# yerevann/mimic3-benchmarks architecture

> Architecture diagram of the GitHub repository yerevann/mimic3-benchmarks, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/yerevann/mimic3-benchmarks
- Repository: https://github.com/yerevann/mimic3-benchmarks

## Overview

Based on your project’s file tree and README, this repository is a benchmark suite designed to generate, process, and evaluate machine learning datasets from the MIMIC-III clinical database. In other words, it provides tools to both construct (via scripts) and use (via readers and baseline models) datasets for key clinical prediction tasks such as in-hospital mortality, decompensation, length of stay forecasting, and phenotype classification.

- Benchmark Dataset Pipeline (mimic3benchmark):
– Data Extraction & Preprocessing: Represent components that extract subjects and episodes from the raw MIMIC-III CSV data. This includes scripts such as extract_subjects.py, extract_episodes_from_subjects.py, and preprocessing.py.
– Data Validation & Splitting: Include modules for validating events and splitting data into train/test sets (e.g., validate_events.py and split_train_and_test.py). Also note the tool for creating per-task datasets (the various create_*.py scripts).
– Data Readers: Highlight the central role of mimic3benchmark/readers.py and its task-specific reader classes for properly loading the benchmark datasets.
– Evaluation: Represent the evaluation scripts (stored under mimic3benchmark/evaluation) that take model outputs (predictions) and produce performance metrics.

- Baseline Models & Training Framework (mimic3models):
– Model Implementations: Divide this into sub-components corresponding to each clinical task (decompensation, in-hospital mortality, length-of-stay, phenotyping, and multitask learning), shown as separate modules or clusters.
– Model Types: Within each task’s directory, distinguish the neural network architectures (Keras models in mimic3models/keras_models, multitask architectures in mimic3models/multitask, etc.) versus simpler classical methods (e.g., logistic regression scripts in the various logistic subdirectories).
– Supporting Utilities: Include components like normalization (normalizer state creations), feature extraction (feature_extractor.py), metric computation (metrics.py), and preprocessing utilities (preprocessing.py) within the baseline models package.
– Training/Validation: Represent the setup for train/validation splits (e.g., split_train_val script) and the pipelines for training respective models (as illustrated in the README commands).

- Supporting Artifacts:
– Test Scripts and Validation Files: Note the tests directory (mimic3benchmark/tests) that checks dataset creation, file consistency, and correctness of extracted data.
– Resources and Configuration Data: Include resources such as YAML definitions and CSV maps that define variable ranges and item-to-variable maps. Also point to JSON config files under mimic3models/resources.

– Follow with the data ingestion pipeline in the “Benchmark Dataset Pipeline” component: raw data is funneled through extraction, then cleaning/validation, and finally split into per-task directories.
– Show that these readers feed into the “Baseline Models & Training Framework” where tools (either deep learning via Keras or logistic regression models) are trained.
– Finally, represent the flow from model predictions to “Evaluation Scripts” where the evaluation is performed and metrics are reported.

##### Architectural Patterns & Technologies
– The architecture follows a pipeline or staged data processing design: from raw CSVs, through cleaning and transformation, to generation of task-specific benchmark datasets.
– The modular separation (mimic3benchmark for dataset construction versus mimic3models for modeling) shows a separation of concerns.
– Emphasize that the baseline models implement both classical machine learning (logistic regression with grid search options) and deep learning techniques (using Keras models).
– Specify that Python (with libraries such as numpy, pandas, scikit-learn, and Keras) is the backbone for the implementation. Also note the dependency on conda environments for reproducibility.

##### Final Advice
– Be as detailed as possible by breaking down the project into its logical sub-components.
– Include annotations that explain how each part interacts with the others (for example, “Extracts patient episodes” or “Feeds predictions into evaluation script”).
– Remember that clarity is key—the ultimate goal is to convey how data flows from one component to another and how the repository’s modules collaborate to support the benchmark creation and modeling tasks.

Happy diagramming!

## Diagram (Mermaid)

```mermaid
graph TD
    %% External Data Source
    DataSource["Raw MIMIC-III CSV Data"]:::external

    %% Benchmark Dataset Pipeline
    subgraph "Benchmark Dataset Pipeline"
        direction TB
        subgraph "Data Extraction & Preprocessing"
            direction TB
            ES["extract_subjects.py"]:::pipeline
            EE["extract_episodes_from_subjects.py"]:::pipeline
            BP_Pre["preprocessing.py"]:::pipeline
        end
        subgraph "Data Validation & Splitting & Dataset Creation"
            direction TB
            VE["validate_events.py"]:::pipeline
            ST["split_train_and_test.py"]:::pipeline
            CD["create_decompensation.py"]:::pipeline
            CIHM["create_in_hospital_mortality.py"]:::pipeline
            CLS["create_length_of_stay.py"]:::pipeline
            CM["create_multitask.py"]:::pipeline
            CP["create_phenotyping.py"]:::pipeline
        end
        DR["readers.py"]:::pipeline
        Eval["Evaluation Scripts"]:::pipeline
    end

    %% Baseline Models & Training Framework
    subgraph "Baseline Models & Training Framework"
        direction TB
        subgraph "Model Implementations"
            direction TB
            Decomp["Decompensation Models"]:::model
            IHM["In-Hospital Mortality Models"]:::model
            LOS["Length of Stay Models"]:::model
            Pheno["Phenotyping Models"]:::model
            Multi["Multitask Models"]:::model
            Keras["Keras Models"]:::model
        end
        subgraph "Supporting Utilities & Training Setup"
            direction TB
            CU["common_utils.py"]:::model
            FE["feature_extractor.py"]:::model
            Met["metrics.py"]:::model
            BP_Model["preprocessing.py"]:::model
            STV["split_train_val.py"]:::model
            NS["create_normalizer_state.py"]:::model
            KU["keras_utils.py"]:::model
            PU["parse_utils.py"]:::model
        end
    end

    %% Supporting Artifacts
    subgraph "Supporting Artifacts"
        direction TB
        Tests["Test Scripts"]:::artifact
        BenchRes["Benchmark Resources"]:::artifact
        ModelsRes["Models Resources"]:::artifact
    end

    %% Data Flow Connections
    DataSource -->|"ingests"| ES
    DataSource --> EE
    DataSource --> BP_Pre

    BP_Pre --> VE
    ES --> VE
    EE --> VE

    VE --> ST
    ST --> CD
    ST --> CIHM
    ST --> CLS
    ST --> CM
    ST --> CP

    CP --> DR

    DR -->|"loads data for"| Decomp
    DR --> IHM
    DR --> LOS
    DR --> Pheno
    DR --> Multi
    DR --> Keras

    %% Utilities connected to Model Implementations
    CU --- Decomp
    FE --- IHM
    Met --- LOS
    BP_Model --- Pheno
    STV --- Multi
    NS --- Keras
    KU --- Decomp
    PU --- IHM

    %% Model Predictions flow into Evaluation
    Keras -->|"produces predictions"| Eval
    Decomp --> Eval
    IHM --> Eval
    LOS --> Eval
    Pheno --> Eval
    Multi --> Eval

    %% Supporting Artifacts Connections (dotted lines indicate support/config dependency)
    VE -.-> BenchRes
    ST -.-> BenchRes
    DR -.-> BenchRes
    CU -.-> ModelsRes
    FE -.-> ModelsRes
    Met -.-> ModelsRes
    Tests -.-> VE

    %% Click Events for Benchmark Dataset Pipeline – Data Extraction & Preprocessing
    click ES "https://github.com/yerevann/mimic3-benchmarks/blob/master/mimic3benchmark/scripts/extract_subjects.py"
    click EE "https://github.com/yerevann/mimic3-benchmarks/blob/master/mimic3benchmark/scripts/extract_episodes_from_subjects.py"
    click BP_Pre "https://github.com/yerevann/mimic3-benchmarks/blob/master/mimic3benchmark/preprocessing.py"

    %% Click Events for Benchmark Dataset Pipeline – Data Validation & Splitting & Dataset Creation
    click VE "https://github.com/yerevann/mimic3-benchmarks/blob/master/mimic3benchmark/scripts/validate_events.py"
    click ST "https://github.com/yerevann/mimic3-benchmarks/blob/master/mimic3benchmark/scripts/split_train_and_test.py"
    click CD "https://github.com/yerevann/mimic3-benchmarks/blob/master/mimic3benchmark/scripts/create_decompensation.py"
    click CIHM "https://github.com/yerevann/mimic3-benchmarks/blob/master/mimic3benchmark/scripts/create_in_hospital_mortality.py"
    click CLS "https://github.com/yerevann/mimic3-benchmarks/blob/master/mimic3benchmark/scripts/create_length_of_stay.py"
    click CM "https://github.com/yerevann/mimic3-benchmarks/blob/master/mimic3benchmark/scripts/create_multitask.py"
    click CP "https://github.com/yerevann/mimic3-benchmarks/blob/master/mimic3benchmark/scripts/create_phenotyping.py"

    %% Click Event for Data Readers
    click DR "https://github.com/yerevann/mimic3-benchmarks/blob/master/mimic3benchmark/readers.py"

    %% Click Event for Evaluation Scripts
    click Eval "https://github.com/yerevann/mimic3-benchmarks/tree/master/mimic3benchmark/evaluation"

    %% Click Events for Baseline Models – Model Implementations
    click Decomp "https://github.com/yerevann/mimic3-benchmarks/tree/master/mimic3models/decompensation"
    click IHM "https://github.com/yerevann/mimic3-benchmarks/tree/master/mimic3models/in_hospital_mortality"
    click LOS "https://github.com/yerevann/mimic3-benchmarks/tree/master/mimic3models/length_of_stay"
    click Pheno "https://github.com/yerevann/mimic3-benchmarks/tree/master/mimic3models/phenotyping"
    click Multi "https://github.com/yerevann/mimic3-benchmarks/tree/master/mimic3models/multitask"
    click Keras "https://github.com/yerevann/mimic3-benchmarks/tree/master/mimic3models/keras_models"

    %% Click Events for Baseline Models – Supporting Utilities & Training Setup
    click CU "https://github.com/yerevann/mimic3-benchmarks/blob/master/mimic3models/common_utils.py"
    click FE "https://github.com/yerevann/mimic3-benchmarks/blob/master/mimic3models/feature_extractor.py"
    click Met "https://github.com/yerevann/mimic3-benchmarks/blob/master/mimic3models/metrics.py"
    click BP_Model "https://github.com/yerevann/mimic3-benchmarks/blob/master/mimic3models/preprocessing.py"
    click STV "https://github.com/yerevann/mimic3-benchmarks/blob/master/mimic3models/split_train_val.py"
    click NS "https://github.com/yerevann/mimic3-benchmarks/blob/master/mimic3models/create_normalizer_state.py"
    click KU "https://github.com/yerevann/mimic3-benchmarks/blob/master/mimic3models/keras_utils.py"
    click PU "https://github.com/yerevann/mimic3-benchmarks/blob/master/mimic3models/parse_utils.py"

    %% Click Events for Supporting Artifacts
    click Tests "https://github.com/yerevann/mimic3-benchmarks/tree/master/mimic3benchmark/tests"
    click BenchRes "https://github.com/yerevann/mimic3-benchmarks/tree/master/mimic3benchmark/resources"
    click ModelsRes "https://github.com/yerevann/mimic3-benchmarks/tree/master/mimic3models/resources"

    %% Styles
    classDef external fill:#FFB6C1,stroke:#000,stroke-width:2px;
    classDef pipeline fill:#FFD700,stroke:#000,stroke-width:2px;
    classDef model fill:#87CEFA,stroke:#000,stroke-width:2px;
    classDef artifact fill:#90EE90,stroke:#000,stroke-width:2px;
```
