# starmpcc/remed architecture

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

- Interactive diagram: https://gitdiagram.com/starmpcc/remed
- Repository: https://github.com/starmpcc/remed

## Overview

##### Main Components
- Data Sources & Preprocessing:
– External EHR Data (e.g., MIMIC-IV, eICU, MEDS dataset) and cohort inputs (from ACES).
– Integration with the external Integrated-EHR-Pipeline for initial data extraction.
– Scripts under “scripts/meds/” (e.g., process_meds.py) show the preprocessing phase.
- Event Encoding:
– A separately pre-trained event encoder (using modules from src/models, for example, the “eventencoder” and kernel modules in src/models/kernels).
– The encoding phase is separately handled by scripts such as encode_events.sh and corresponding Python commands.
- Model Training:
– The core REMed model (implemented across src/models, with different variants like mega, rmt, s4, etc.) is trained by drivers in main.py and various trainers under src/trainer (including models like remed.py, bioclinicalbert_encode.py, long.py, short.py).
– Training configurations and distributed training settings (using accelerate launch, DeepSpeed, FSDP configs from config/) need to be highlighted.
- Inference / Prediction:
– A dedicated prediction stage (using predict.sh scripts and testing routines also reflected in main.py) and a “standalone_remed.py” module for lightweight single-instance prediction.
- Supporting Components:
– Utility functions (src/utils) for miscellaneous trainer operations.
– Build and configuration: configuration files in config directory and build scripts for kernel compilation (using setup.py in src/models/kernels).
– Logging and experiment tracking integration via wandb.

##### Relationships & Data Flow
– Start with External Data Sources (EHR databases, MEDS dataset) feeding into the Preprocessing component.
– Preprocessed data (in .h5 and .tsv formats) feeds into the Event Encoding stage where the pretrained encoder processes the raw events.
– The encoded data then becomes input to the REMed training module, which uses various trainer scripts to update model weights.
– Once the model is trained, the prediction/inference block (either within the full pipeline or standalone) accepts new event sequences and returns predictions.
– Highlight the control flow managed through main.py and configuration files (that link to training, encoding, and prediction processes).

##### Architectural Patterns & Design Principles
– Modularity: clear separation between preprocessing (scripts/meds), model code (src/models), training logic (src/trainer) and utility functions.
– Extensibility: multiple training types (short, remed, long, etc.) and support for both a full pipeline and a standalone prediction mode.
– Accelerated execution: integration with GPU-based computation (CUDA kernels, deepspeed and FSDP configs) shown by the specialized kernel implementations.
– Pipeline orchestration: use of “accelerate launch” for distributed training and inference, as indicated by command-line examples in the README.

##### Relevant Technologies & Frameworks
– PyTorch & related deep learning libraries (e.g., transformers, accelerate).
– CUDA (with dedicated C++ and .cu kernel files in src/models/kernels).
– Dependency management and configurations (e.g., conda and pip install commands in the README).
– Potential logging/experiment tracking using wandb.

##### Elements
– Include configuration nodes (point to files in the config directory) to indicate how runtime behavior is controlled.
– Optionally, add annotations to show external integrations (e.g., integration with wandb for logging or CUDA for acceleration).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Sources
    subgraph "Data Sources"
        A("Raw EHR Data"):::external
        B("MEDS Dataset"):::external
        C("ACES Cohort Inputs"):::external
        D0("Integrated EHR Pipeline"):::external
    end

    %% Preprocessing Layer
    subgraph "Preprocessing Layer"
        D("Preprocessing (process_meds.py)"):::processing
    end

    %% Event Encoding Layer
    subgraph "Event Encoding Layer"
        E("Encode Events (encode_events.sh)"):::processing
        F("Event Encoder (eventencoder.py)"):::model
    end

    %% Model Training Layer
    subgraph "Model Training Layer"
        G("Training Orchestration (main.py)"):::training
        H("Trainer Modules (src/trainer)"):::training
        I("Configurations (config)"):::config
    end

    %% Kernel & Retrieval
    subgraph "Kernel & Retrieval"
        J("Kernel Modules & Acceleration (src/models/kernels)"):::kernel
    end

    %% Inference Layer
    subgraph "Inference Layer"
        K("Prediction (predict.sh)"):::inference
        L("Standalone Prediction (standalone_remed.py)"):::inference
    end

    %% Utilities
    subgraph "Utilities"
        M("Utility Functions (trainer_utils.py)"):::util
    end

    %% Data flow connections
    A --> D
    B --> D
    C --> D
    D0 --> D

    D --> E
    D --> F

    E --> G
    F --> G

    I --> G

    G --> H
    H --> M
    H --> J

    G --> K
    G --> L

    %% Click Events
    click D "https://github.com/starmpcc/remed/blob/main/scripts/meds/process_meds.py"
    click E "https://github.com/starmpcc/remed/blob/main/scripts/meds/encode_events.sh"
    click F "https://github.com/starmpcc/remed/blob/main/src/models/eventencoder.py"
    click G "https://github.com/starmpcc/remed/blob/main/main.py"
    click H "https://github.com/starmpcc/remed/tree/main/src/trainer/"
    click I "https://github.com/starmpcc/remed/tree/main/config/"
    click J "https://github.com/starmpcc/remed/tree/main/src/models/kernels/"
    click K "https://github.com/starmpcc/remed/blob/main/scripts/meds/predict.sh"
    click L "https://github.com/starmpcc/remed/blob/main/standalone_remed.py"
    click M "https://github.com/starmpcc/remed/blob/main/src/utils/trainer_utils.py"

    %% Styles
    classDef external fill:#AED6F1,stroke:#1F618D,color:#1F618D,stroke-width:2px;
    classDef processing fill:#A9DFBF,stroke:#196F3D,color:#145A32,stroke-width:2px;
    classDef model fill:#A9DFBF,stroke:#196F3D,color:#145A32,stroke-width:2px;
    classDef training fill:#F9E79F,stroke:#B9770E,color:#7D6608,stroke-width:2px;
    classDef config fill:#F5B7B1,stroke:#922B21,color:#641E16,stroke-width:2px;
    classDef kernel fill:#FAD7A0,stroke:#D35400,color:#873600,stroke-width:2px;
    classDef inference fill:#D2B4DE,stroke:#6C3483,color:#4A235A,stroke-width:2px;
    classDef util fill:#D5F5E3,stroke:#117864,color:#0E6251,stroke-width:2px;
```
