Pipeline Docs

Pipeline Execution Guide

Now that your YAML configuration files are set up, it is time to run the pipeline. The architecture is split into three distinct steps to ensure modularity and reproducibility:

  1. Data Generation (01_generate_data_v2.py): Reads the blueprints and builds the raw, messy hospital database.
  2. Feature Engineering (02_build_features_icare.py): Cleans the messy database, pivots the time-series data, and calculates advanced clinical scores.
  3. Model Evaluation (03_evaluate_scores_v2.py): Tests the accuracy of those clinical scores across different patient subgroups and timeframes.

⚠️ The Golden Rule of Execution

Because the pipeline relies on shared resources (like the src/ directory and the config/ files), you must always run these scripts from the root directory of your project. Furthermore, you must run them as Python modules using the -m flag.

⚙️ Why the -m flag?
If you just run python scripts/01_generate_data_v2.py, Python assumes the scripts/ folder is the center of the universe. It will throw an error saying ModuleNotFoundError: No module named 'src'.

By running python -m scripts.01_generate_data_v2 from the project root, you tell Python: "Hey, load the whole project into memory first, then execute this specific script." This ensures all your relative paths and imports work flawlessly.

Step 1: Running the Data Generator

This script acts as the hospital simulator. It reads your data_config_v2.yaml, generates a cohort of synthetic patients, and builds interconnected relational tables (like Episodes, Pharmacy, and Vitals).

The Command

Open your terminal, ensure you are in the project root folder, and run:

python -m scripts.01_generate_data

What to Expect

When the script runs, it will print a log to your terminal showing you exactly which tables it is building. It automatically creates a new, timestamped directory so you never overwrite old data.

==================================================
🧬 [Step 1] Dynamic Synthetic Data Generation
==================================================

📂 TARGET SAVE DIRECTORY: /your/path/data/synthetic/2026-03-25_103015

Generating configured tables for 100 patients...
 -> Building ICARE_EPISODES_ANON [relational]...
 -> Building ICARE_VITAL_SIGNS_ANON [eav_timeseries]...
 -> Building ICARE_PHARMACY_PRESCRIBING_ANON [relational]...

✅ Success! All data saved dynamically to: data/synthetic/2026-03-25_103015

Step 2: Running the Feature Builder

Once the raw data exists, it's time to engineer the features. This script is highly intelligent: it automatically finds the most recently created folder in your data/synthetic/ directory, loads those raw CSVs, and processes them according to your feature_config.yaml.

The Command

From the project root folder, run:

$ python -m scripts.02_build_features_icare

What to Expect

This script performs a lot of heavy lifting. First, it pivots the long EAV (Entity-Attribute-Value) tables into wide time-series formats. Then, it triggers your Feature Pipeline.

==================================================
⚙️  [Step 2] Feature Engineering: ICARE Edition
==================================================

📂 Loading data from run: 2026-03-25_103015
✅ Raw ICARE tables loaded successfully.
  -> Vitals pivoted. Shape: (1440, 6)
  -> Labs pivoted. Shape: (350, 4)
  -> Combined Time-Series Shape: (1790, 10)
  -> Static (Episodes) rows: 100

🚀 Starting Feature Pipeline...
Processing base features...
  🔍 Computing phenotype: is_aki...
     ✅ is_aki added. Unique values: [0 1]
  🔍 Computing score: charlson_score...
     ✅ charlson_score added. Unique values: [3 unique values]

✨ SUCCESS! Engineered 45 features across 1790 rows.
📍 Saved to: data/processed/2026-03-25_103015/features_engineered_icare.csv

Step 3: Running the Model Evaluator

Finally, we need to test if the scores you generated actually work. This script is driven entirely by eval_config.yaml. It slices your dataset by time (e.g., Admission vs. 48h) and by demographic subgroups (e.g., "Elderly Diabetics") to give you a comprehensive performance report.

The Command

From the project root folder, run:

$ python -m scripts.03_evaluate_scores_v2

What to Expect

The script acts as a "Dumb Dispatcher," executing whatever experiments you defined in the YAML file. It will print its progress as it loops through your specified cohorts and timeframes.

==================================================
📊 [Step 3] Configuration-Driven Model Evaluation
==================================================

🎯 Target Label: 'ground_truth'
🧪 Evaluating Scores: mews_score, pitt_score, increment_esbl_score

🏥 === RUNNING COHORT: ALL PATIENTS (100 Patients) ===
  -> [Admission] Evaluating first clinical record...
  -> [Milestone 24h] Evaluating records near hour 24...

🏥 === RUNNING COHORT: ELDERLY DIABETICS (24 Patients) ===
  -> [Admission] Evaluating first clinical record...
  -> [Milestone 24h] Evaluating records near hour 24...

  📈 Generating AUROC Over Time (up to 168h)...

==================================================
🏆 MASTER EXPERIMENT SUMMARY
==================================================
Strategy                         Score_Name      AUROC  AUPRC
All Patients - Admission         mews_score      0.82   0.65
All Patients - Admission         pitt_score      0.88   0.71
Elderly Diabetics - Admission    mews_score      0.75   0.55

✅ All metrics and plots saved to: outputs

Understanding the Folder Architecture (Outputs)

After running all three scripts successfully, your project's root folder will be beautifully organized. Notice how the system uses identical timestamps for data, and generates a dedicated outputs/ folder for your final metrics.

📦 project_root/
 ┣ 📂 config/
 ┃ ┣ 📜 data_config_v2.yaml                 <-- Recipe for Step 1
 ┃ ┣ 📜 feature_config.yaml                 <-- Recipe for Step 2
 ┃ ┗ 📜 eval_config.yaml                    <-- Recipe for Step 3
 ┣ 📂 data/
 ┃ ┣ 📂 synthetic/
 ┃ ┃ ┗ 📂 2026-03-25_103015/                <-- Output of Step 1 (Raw)
 ┃ ┃   ┣ 📜 icare_episodes_anon.csv
 ┃ ┃   ┗ 📜 icare_vital_signs_anon.csv
 ┃ ┗ 📂 processed/
 ┃   ┗ 📂 2026-03-25_103015/                <-- Output of Step 2 (Engineered)
 ┃     ┗ 📜 features_engineered_icare.csv
 ┣ 📂 outputs/                              <-- Output of Step 3 (Evaluation)
 ┃ ┣ 📂 metrics/
 ┃ ┃ ┣ 📜 master_summary.csv                <-- The ultimate performance table!
 ┃ ┃ ┣ 📜 all_patients_admission_metrics.csv
 ┃ ┃ ┗ 📜 elderly_diabetics_admission_metrics.csv
 ┃ ┗ 📂 plots/
 ┃   ┣ 🖼️ all_patients_admission_roc.png
 ┃   ┗ 🖼️ temporal_auroc.png               <-- Your longitudinal line graph
 ┣ 📂 scripts/
 ┃ ┣ 📜 01_generate_data_v2.py
 ┃ ┣ 📜 02_build_features_icare.py
 ┃ ┗ 📜 03_evaluate_scores_v2.py
 ┗ 📂 src/
🎉 You're Ready for Publication!
The master_summary.csv contains all your stratified metrics, and the plots/ directory holds high-resolution curves ready to be dropped straight into a clinical research paper or dashboard.

On this page

1. Introduction 2. The Golden Rule of Execution 3. Step 1: Data Generation 4. Step 2: Feature Building 5. Step 3: Model Evaluation 6. Understanding Outputs