Skip to content

USER_GUIDE.md

Latest commit

 

History

History
141 lines (95 loc) · 6.35 KB

USER_GUIDE.md

File metadata and controls

141 lines (95 loc) · 6.35 KB

Clinical User Guide: CardioSense AI (v2.4.0)

CardioSense AI facilitates advanced cardiovascular decision-making through an interactive dashboard and automated clinical reporting.

  1. Dashboard Overview

The CardioSense AI dashboard provides a comprehensive medical interface for risk assessment.

Patient Inputs & Risk Pulse

  • Sidebar: Input traditional cardiovascular risk factors (Age, BP, Cholesterol, etc.).
  • Reliability Score: Active v2.4.0 engine (88.52% Acc) ensures production-grade stability.

Patient Inputs Risk Pulse Gauge

  1. Deep Dive Modules

Diagnosis & Benchmarks

Analyze the underlying drivers of the patient's risk.

Actionable LIME Insights

  • SHAP Waterfall Analysis: Visualizes exactly how many percentage points each vital contributed to the overall risk. Red bars indicate increased risk; blue bars indicate protective factors.
  • LIME Linear Surrogates: Provides a "local linear" view of the model's decision. It shows which features are most sensitive for that specific patient.
  • Patient Benchmarking: Compare your patient's vitals against the Healthy Median.

Risk Optimization Engine (Least Effort Path)

Move beyond simple "What-If" analysis to an AI-driven clinical strategy.

Intervention Simulation Dashboard Risk Optimization & Radar

  1. Strategic Optimization: Select a "Target Risk" percentage and run the solver.
  2. Spider (Radar) Visualization:
    • Blue Shape: The patient's high-risk profile.
    • Green Shape: The AI-calculated "Path to Green."
  3. Treatment Roadmap: A prioritized sequence of lifestyle actions ranked by their risk-reduction ROI relative to effort.
  1. Interpreting the AI "Reasoning"

The SHAP Waterfall plot is the "X-Ray" of the model's decision. It decomposes the 0-100% risk probability into the specific clinical reasons for why a patient was flagged.

  • E[f(X)]: The average model output (the starting baseline).
  • f(X): The final risk probability for this specific patient.
  • Red Features: Clinical factors that pushed the risk Higher.
  • Blue Features: Clinical factors that pushed the risk Lower.
  1. Global Insights & Fairness

Population-Level Feature Importance

Understand dataset-wide summary drivers across all patients.

Population Importance Feature Analysis Correlation Heatmap

Fairness & Equitable Care

CardioSense AI is audited to ensure that the AI model performs reliably across all patient demographics.

Bias and Fairness Assessment

  • Regional Parity: We prioritize high Recall (Sensitivity) in historically marginalized or vulnerable subgroups (e.g., Female and Senior populations) to ensure no high-risk patient is missed due to algorithmic bias.

Model Transparency & Integrity

The System Integrity module validates the underlying statistical performance of the clinical engine.

System Integrity Dashboard

  • Validation Confusion Matrix: Visualizes true/false positives and negatives on the hold-out validation set.
  • Model Calibration Curve: Ensures that the AI's predicted "Risk Pulse" aligns with actual clinical frequencies (Brier Score: 0.0814).
  1. Medical Safety Guardrails

The engine implements a multi-layered safety framework to prevent AI hallucination in high-risk scenarios.

Clinical Overrides (ACC/AHA Alignment)

The system will automatically escalate risk to POSITIVE if critical life-safety thresholds are breached:

  • Hypertensive Crisis: Systolic BP >= 180 mmHg.
  • Multivessel Disease: Number of major vessels (ca) >= 2.
  • Ischemic Severity: ST depression (oldpeak) > 3.0.

Entropy-Based Confidence

Every prediction includes a Confidence Gauge (1.0 - H(p)). These values are now more stable due to the v2.4.0 Robust Preprocessing Pipeline:

  • HIGH: The AI has a clear, focused statistical rationale.
  • MODERATE: Requires physician review.
  • LOW: High entropy/ambiguity. The AI indicates a "Boundary Case."
  1. Generating Clinical PDF Reports

After completing your assessment, generate a professional report for the patient's medical file:

  1. Input clinician observations.
  2. Click "Download Clinical PDF Report".
    • Clinical Audit Hash: cryptographic link for medical records.

Report Preview (Full Clinical Payload)

PDF Page 1 PDF Page 2 PDF Page 3 PDF Page 4 PDF Page 5

  1. Clinical Monitoring & Reliability

The Clinical Monitoring tab allows physicians to monitor the system's "real-world" performance and data stability over time.

Data Drift (Evidently AI)

This module monitors for shifts in the distribution of patient data (e.g., if the incoming population's average cholesterol suddenly spikes).

  • Drift Share: The percentage of clinical features currently showing statistical drift.
  • Dataset Drift: A binary flag indicating if the overall population profile has significantly deviated from the validated training baseline.

Performance Audit (Concept Drift)

By collecting ground-truth feedback from clinicians, the system tracks its Recall Stability.

  • Recall Drop: Measures the decay in sensitivity compared to the 92.86% baseline.
  • Concept Drift Alert: Scalates to clinicians if the model's predictive quality falls below acceptable safety thresholds.

Monitoring Overview Evidently AI Report

The clinical logic and monitoring frameworks in v2.4.0 are designed to ensure long-term model sustainability in dynamic medical environments.