Acute Coronary Syndrome (ACS) Clinical Decision Support System (CDSS)

This repository implements a client-side Clinical Decision Support System (CDSS) and Machine Learning (ML) prediction dashboard for ACS, fully aligned with the 2025 ACC/AHA/ACEP/NAEMSP/SCAI Clinical Guidelines.

---

1. Project Overview

Purpose

The ACS CDSS Dashboard serves as an interactive clinical tool for cardiotranslation and medication safety auditing. It enables clinicians to:

1. Automatically predict patient diagnosis (STEMI vs. NSTE-ACS) using an offline-trained client-side Random Forest model.
2. Evaluate guideline-based treatment strategies (Primary PCI vs. Fibrinolysis vs. Conservative Medical Management) based on hemodynamic and cardiac risk profiles.
3. Track and audit compliance, highlighting guideline deviations, therapeutic omissions (beta-blockers, anticoagulants, RAAS inhibitors), and critical drug-safety contraindications.

Key Features

• Client-Side Machine Learning: Runs an offline-trained Random Forest model directly in the browser via serialized decision trees in JSON.
• Dynamic Diagnosis Prediction: Re-classifies diagnosis (STEMI, NSTEMI, Unstable Angina) automatically in real-time as clinical intake parameters (ECG, Troponins) are updated in the ingestion form.
• 2025 Guidelines Decisions Engine: Implements absolute/relative contraindications for fibrinolysis (Table 14) and routine invasive strategies (Table 15), baseline pharmacotherapy compliance checks, anemia transfusion thresholds, and lipid-lowering therapies.
• Demographics & prevention HTML tables: Outputs a clean, structured print audit report using CSS media queries and structured tables.

Technologies Used

• Frontend Core: HTML5, Vanilla CSS, Vanilla JavaScript (ES6)
• Model Training: Python 3, Scikit-Learn, Joblib, Pandas, NumPy
• Auditing Engine: Pandas Batchdecision logic
• Reference Flowcharts: Interactive SVG HTML, ReportLab PDF generators

---

2. Folder Structure

Pharmacy/
│
├── index.html                           # Main entry point for the clinician dashboard
├── app.js                               # Core application logic & clinical rules engine
├── model_data.js                        # Serialized ML Random Forest trees & scaling constants
├── patients_data.js                     # Synchronized 70-patient registry array (JavaScript format)
├── patients.json                        # Synchronized 70-patient registry array (JSON format)
│
├── train_model.py                       # Retrains the Random Forest classifier and exports model_data.js
├── convert_excel.py                     # Data parsing pipeline to ingest data.json and update registries
├── cdss_engine.py                       # Batch evaluation engine to audit patient registries
├── test_rules.py                        # Rules boundaries validation unit tests
│
├── data.json                            # Raw 70-patient source registry data
├── IHD data entry.xlsx                  # Raw Excel format registry file
├── IHD data entry.xlsx - IHD.csv        # Parsed registry file in CSV format
├── CDSS_Final_Clinical_Audit.csv        # Output audit logs generated by cdss_engine.py
│
├── ihd_diagnosis_model.joblib           # Offline trained Random Forest model (Python format)
├── scaler.joblib                        # Offline standard scaling constants (Python format)
│
├── flowchart.html                       # Reference medical guidelines interactive document
├── flowchart_diagram.html               # Reference medical flowchart interactive schematic
├── generate_flowchart_pdf.py            # PDF generator for reference flowchart
├── generate_diagram_pdf.py              # PDF generator for reference diagram
│
├── ACS_Clinical_Decisions_Flowchart.pdf # 2025 ACS Clinical Flowchart Reference
├── ACS_Patient_Risk_Rules_Flowchart.pdf # 2025 Patient Risk Rules Reference
├── Final.pdf                            # 2025 CDSS Summary Reference
├── rao-et-al-2025-...pdf                # Official ACC/AHA 2025 Guideline Reference PDF
├── guideline_extracts.txt               # Key text passages extracted from official guidelines
│
└── README.md                            # Comprehensive project guide and system documentation

---

3. File-by-File Explanation

Frontend / Client-Side Files

• index.html
  Purpose: Main application entry point. Serves the responsive web layout (sidebar directory, ingestion forms, clinical audit report panels) and defines the @media print style optimizations to support clean page printing.
  Dependencies: Loads patients_data.js, model_data.js, and app.js.

• app.js
  Purpose: Main application controller. Wires frontend event listeners, evaluates patient data against 2025 clinical decision rules, implements the client-side Random Forest classifier and standard scaler, and generates audit reports.
  Dependencies: Directly dependent on elements in index.html and model objects in model_data.js.

• model_data.js
  Purpose: Serialized JavaScript representation of the Random Forest model and scaling constants. Houses feature names, class lists, mean/standard deviations, and estimators.
  Dependencies: Read by app.js during patient evaluation.

• patients_data.js
  Purpose: Serialized registry containing the 70 patients used to pre-populate the directory.
  Dependencies: Read by app.js on application boot.

Machine Learning, Ingestion, and Batch Auditing (Python Backend)

• train_model.py
  Purpose: offline model training utility. Ingests patient CSV data, trains a RandomForestClassifier to map clinical variables to ACS diagnoses, and writes scaler variables and decision nodes to model_data.js.
  Dependencies: Outputs model_data.js, ihd_diagnosis_model.joblib, and scaler.joblib.

• convert_excel.py
  Purpose: Data parser utility. Ingests raw data from data.json and parses drug compliance variables and relative contraindications before writing outputs.
  Dependencies: Generates patients.json, patients_data.js, and IHD data entry.xlsx - IHD.csv.

• cdss_engine.py
  Purpose: Batch decisions auditor. Reads the intermediate registry CSV using pandas and runs the patient registry against CDSS rules, outputting compliance statistics to a log.
  Dependencies: Generates CDSS_Final_Clinical_Audit.csv.

• test_rules.py
  Purpose: Automated unit validator. Contains explicit test assertions representing patient boundary cases (e.g., age overrides, hypoxemia, DAPT combinations, contraindications) to guarantee clinical compliance.

Reference flowcharts and documentation

• flowchart.html & flowchart_diagram.html
  Purpose: Documentation files containing guideline references, dosing parameters, risk score sheets, and interactive medical diagrams.
• generate_flowchart_pdf.py & generate_diagram_pdf.py
  Purpose: Utilities to render reference flowcharts into print-ready PDF layouts.
• guideline_extracts.txt
  Purpose: Extracted guidelines reference files capturing tables 14, 15, and clinical criteria.

---

4. Feature Documentation

🔑 Clinician Login

• Responsible Files: index.html (DOM Overlay), app.js (Event Handlers)
• How it works: Locks access to the database behind a glassmorphic login screen. For clinical simulation, typing any non-blank username and password grants access, updating application state (state.isLoggedIn) and blurring out the login modal.

📊 Patient Directory Dashboard

• Responsible Files: index.html, app.js (DOM Rendering)
• How it works: Displays statistics (Ingested Patients count, High Ischemic Risk count, HBR count, and overall Guideline Compliance Score). An active search bar and dropdown filter (by diagnosis or risk level) enable immediate subset directories.

📝 Add / Modify Patient Record

• Responsible Files: index.html (Forms), app.js (State validation and submission)
• How it works: Validates inputs (valid Hospital ID, positive age constraints, numeric boundaries on SBP, HR, and SpO2). Ingests patient variables into the registry arrays and updates statistics.

🧠 Dynamic Patient Prediction

• Responsible Files: app.js (predictRF()), model_data.js (ML Model weights)
• How it works: Triggered dynamically in the form during patient entry. When inputs like ECG or Troponin are changed, the app runs the patient data through a Z-score scaler and traverses the Random Forest decision trees, updating the Primary Diagnosis automatically in the dropdown.

🧬 ACS Flowchart Rules Engine

• Responsible Files: app.js (evaluateClinicalRules()), cdss_engine.py, test_rules.py
• How it works: Processes 12 input features to:
  • Check oxygenation status (alerts if SpO2 < 90%).
  • Map reperfusion strategy vs. P2Y12 antiplatelet guidelines (flags potent antiplatelets under fibrinolysis).
  • Verify contraindications to routine invasive strategy (Table 15) and fibrinolysis (Table 14).
  • Track medication gaps for Anticoagulants, Beta-Blockers, and RAAS inhibitors.
  • Assess anemia and transfusions requirements (Hb < 11 g/dL target Hb of 10 g/dL without active bleeding).
  • Check secondary lipid prevention compliance.

🖨️ Professional Report Generation & Printing

• Responsible Files: index.html (Stylesheets), app.js (renderSelectedPatient())
• How it works: Renders Block I patient demographics and Prevention Metrics inside clean, structured HTML tables. When the user clicks Print Audit, a custom CSS print media query hides dashboard headers, menus, and forms, formatting the report for print or PDF export.

---

5. System Architecture & Module Dependencies

The clinical CDSS pipeline is structured as follows:

Raw Registry Excel/JSON
  │
  ▼ [convert_excel.py] Ingestion Pipeline
Parsed CSV & JSON Dataset
  │
  ▼ [train_model.py] Model Training
Joblib & JS Serialized RF Model (model_data.js)
  │
  ▼ Loading client-side scripts
HTML5 Dashboard (index.html, app.js, model_data.js)
  │
  ├── [Form Interaction] -> Ingest Patient -> Dynamic ML Prediction -> State Update
  ▼
Block Report Generation -> Tables Display -> Print Layout CSS -> PDF Audit Output

---

6. Execution Instructions

Retraining the Model & Updating Registries

To run the automated data ingestion, retrain the classifier, and update the client-side model weights:

# 1. Parse Excel data and generate CSV registries
python convert_excel.py

# 2. Retrain machine learning classifier and export JS estimators
python train_model.py

# 3. Run the batch auditing engine across the cohort
python cdss_engine.py

# 4. Execute unit validation tests
python test_rules.py

Launching the Dashboard locally

To launch the dashboard application:

# Start Python's built-in web server
python -m http.server 8000

Open your browser and navigate to: http://localhost:8000/index.html