# jtan1102/nla-mmr_cikm_2024 architecture

> Architecture diagram of the GitHub repository jtan1102/nla-mmr_cikm_2024, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jtan1102/nla-mmr_cikm_2024
- Repository: https://github.com/jtan1102/nla-mmr_cikm_2024

## Overview

##### Project type and purpose
- This is a research codebase (“CIKM2024 submission 53”) implementing a drug-recommendation/multi-medication risk modeling pipeline on the MIMIC-III and MIMIC-IV datasets.
- It is not a full-stack app but an open-source research tool: ingesting raw patient data, constructing datasets, training a GNN-based model, and reporting metrics.

##### File structure
- Top-level:
- data/ — raw Pickle files for MIMIC-III and MIMIC-IV (ATC→SMILES mappings, drug-drug interaction matrices, patient visit records, vocabularies)
- datasets/ — Python scripts that read raw data and produce final, model-ready data splits (e.g., Drug_Rec_pt_new_final.py)
- scripts/ — core training/inference code:
– common_layers.py, util.py (shared utilities)
– gnn/ (custom GNNConv, GNNs, utils)
– main.py (entry point for training & validation)
- No frontend or deployment; focus is on data pipeline, model architecture, and training loop.

##### README
- Confirms the pipeline steps: data download & preparation → code clone → data placement → `python main.py --dataset MIMIC-III|IV --Train`
- Lists environment and dependencies (PyTorch, PyG, Transformers, etc.)
- Logs show training/inference loops with metrics.

a. Main components:
1. Raw Data Store (MIMIC-III/IV raw Pickles)
2. Data Preparation Module (datasets/*.py)
3. DataLoader & Batch Generator (scripts/util.py)
4. Model Definition (scripts/common_layers.py + scripts/gnn/)
5. Training Loop & Loss Computation (scripts/main.py)
6. Checkpointing & Evaluation (scripts/main.py)
7. Output & Metrics Logging
b. Relationships & interactions:
- Raw Data → Data Preparation → Processed Dataset → DataLoader
- DataLoader + Model → Forward Pass → Loss → Backprop → Model Update
- After each epoch: Model → Validation DataLoader → Evaluation Metrics → Logging
c. Architectural patterns & design principles:
- Modular code separation: data prep, model layers, GNN definitions, training script
- Use of custom PyG layers (GNNConv) and PyTorch training loop
- Single-process GPU training with configurable hyperparameters
d. Key technologies/frameworks:
- Python 3.8, PyTorch 2.0.1, torch-geometric (GNNs), Transformers/tokenizers (for possible pre-trained bio_pt embeddings), NumPy, Pandas, Scikit-learn.

##### Elements
- Data flow (→) from raw data to preprocessing to training to evaluation
- Rectangles for code modules
- Rounded rectangles for executables (main.py)
- Parallelograms for outputs/logs

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Data Stores
    RawIII["Raw Pickle Data (MIMIC-III)"]:::dataStore
    RawIV["Raw Pickle Data (MIMIC-IV)"]:::dataStore

    %% Data Preparation
    DataPrepIII["Dataset Builder (MIMIC-III)"]:::module
    DataPrepIV["Dataset Builder (MIMIC-IV)"]:::module

    %% Processed Data
    ProcData["Processed Dataset"]:::dataStore

    %% DataLoader & Batch Generator
    DataLoader["DataLoader & Batch Generator"]:::module

    %% Model Definition
    subgraph "Model Definition"
        CommonLayers["Shared Model Layers"]:::model
        GNNConv["Graph Conv Components"]:::model
        GNNs["Graph Network Architectures"]:::model
        GNNUtils["GNN Utility Functions"]:::model
    end

    %% Main Execution
    Main["Training Loop & Evaluation"]:::exec

    %% Outputs
    Logs["Checkpointing & Metrics Logging"]:::output

    %% Connections
    RawIII -->|"raw .pkl files"| DataPrepIII
    RawIV -->|"raw .pkl files"| DataPrepIV
    DataPrepIII -->|".pkl → torch.Tensor splits"| ProcData
    DataPrepIV -->|".pkl → torch.Tensor splits"| ProcData
    ProcData -->|"batches"| DataLoader
    DataLoader -->|"batches"| Main
    CommonLayers --> Main
    GNNConv --> Main
    GNNs --> Main
    GNNUtils --> Main
    Main -->|"model.ckpt / metrics.json"| Logs

    %% Click Events
    click RawIII "https://github.com/jtan1102/nla-mmr_cikm_2024/tree/cikm_branch/data/MIMIC-III_data/raw"
    click RawIV "https://github.com/jtan1102/nla-mmr_cikm_2024/tree/cikm_branch/data/MIMIC-IV_data/raw"
    click DataPrepIII "https://github.com/jtan1102/nla-mmr_cikm_2024/blob/cikm_branch/datasets/Drug_Rec_pt_new_final.py"
    click DataPrepIV "https://github.com/jtan1102/nla-mmr_cikm_2024/blob/cikm_branch/datasets/Drug_Rec_pt_new_final_iv.py"
    click DataLoader "https://github.com/jtan1102/nla-mmr_cikm_2024/blob/cikm_branch/scripts/util.py"
    click CommonLayers "https://github.com/jtan1102/nla-mmr_cikm_2024/blob/cikm_branch/scripts/common_layers.py"
    click GNNConv "https://github.com/jtan1102/nla-mmr_cikm_2024/blob/cikm_branch/scripts/gnn/GNNConv.py"
    click GNNs "https://github.com/jtan1102/nla-mmr_cikm_2024/blob/cikm_branch/scripts/gnn/GNNs.py"
    click GNNUtils "https://github.com/jtan1102/nla-mmr_cikm_2024/blob/cikm_branch/scripts/gnn/utils.py"
    click Main "https://github.com/jtan1102/nla-mmr_cikm_2024/blob/cikm_branch/scripts/main.py"
    click Logs "https://github.com/jtan1102/nla-mmr_cikm_2024/blob/cikm_branch/scripts/main.py"

    %% Styles
    classDef dataStore fill:#f9f,stroke:#333,stroke-width:1px
    classDef module fill:#bbf,stroke:#333,stroke-width:1px
    classDef model fill:#bfb,stroke:#333,stroke-width:1px
    classDef exec fill:#fbb,stroke:#333,stroke-width:1px
    classDef output fill:#ffb,stroke:#333,stroke-width:1px

    %% Legend
    subgraph Legend
        A["Cylinders: Data Stores"]:::dataStore
        B["Rectangles: Modules"]:::module
        C["Rectangles: Model Components"]:::model
        D(["Rounded: Execution Entry"]):::exec
        E["Parallelogram: Outputs/Logs"]:::output
    end
```
