# sunlabuiuc/pyhealth architecture

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

- Interactive diagram: https://gitdiagram.com/sunlabuiuc/pyhealth
- Repository: https://github.com/sunlabuiuc/pyhealth

## Overview

##### Main Components and Their Roles
- Core Library (“pyhealth”): This is the heart of the project. It’s organized into multiple submodules:
- Datasets: Handles ingestion and pre-processing of various electronic health record (EHR) datasets (e.g., MIMIC-III, MIMIC-IV, eICU, OMOP, etc.). Illustrate how raw input data gets transformed into a structured multi-level dictionary.
- Tasks: Contains functionality for defining healthcare predictive tasks (e.g., readmission prediction, drug recommendation, mortality prediction, length of stay forecasting). This module transforms processed datasets into task-specific samples.
- Models: Provides a suite of deep learning models (e.g., CNN, RNN, Transformer, RETAIN, and many more specialized models) that can be interchanged within the pipeline.
- Trainer: Manages training, hyperparameter configuration, checkpointing, and saving the best model.
- Metrics: Evaluates the predictive performance using different evaluation metrics (e.g., ROC-AUC, PR-AUC).
- Medcode, Code Mapping, and Tokenizer: Offer utilities for mapping medical codes and tokenizing clinical texts and codes so that they can seamlessly integrate into the ML pipeline.
- Calibration (pyhealth/calib): Provides modules for calibrating model predictions.

- Auxiliary Components:
- Chat-Assistant: A subproject (with its own Dockerfile, ingestion and prompt files) that likely acts as an interface or an extension tool that leverages the main PyHealth library to interact with users, perhaps using an API key for OpenAI integration.
- Docs: A documentation suite that includes a Sphinx-based documentation website, guides, API reference, and example tutorials.
- Examples & Leaderboard: These components provide illustrative notebooks, scripts, and evaluation scripts so users can quickly see and benchmark the toolkit in action.
- Testing/CI: Elements like the .github workflows and unit test files (pyhealth/unittests) that support continuous integration and maintainability.

##### Interactions and Data Flow
- Raw EHR data arrives from various input sources (filesystem, URLs, or synthetic datasets). This data is handled by modules from pyhealth.datasets.
- Task Definition:
- Once the data is structured, the pyhealth.tasks module processes the dataset to generate task-specific samples.
- Model Invocation:
- These samples are then fed to one of the many supported models (in pyhealth.models) for training or inference.
- Training & Evaluation:
- The pyhealth.trainer module coordinates training sessions, iterates over batches, and updates model weights.
- After training, the pyhealth.metrics module computes various performance metrics to evaluate the model.
- Utility Modules:
- Medcode and Tokenizer modules operate alongside the primary pipeline, supporting code mappings, lookups, and token conversions.
- Integration with Chat-Assistant:
- The chat-assistant subproject encapsulates a Dockerized service that may wrap around some of the above functionalities to allow an interactive conversational interface (using prompt files and an API key).
- External Services:

##### Architectural Patterns and Design Principles
- Modular Design & Separation of Concerns:
- How each functional unit (datasets, tasks, models, trainer, metrics) is isolated and interchangeable, making the toolkit highly customizable.
- Pipeline-based Processing:
- “five-stage pipeline” (data processing, task generation, modeling, training, and evaluation) mentioned in the README.
- Extensibility:
- That modules such as medcode and tokenizer are built to work independently, demonstrating how the toolkit can be extended or integrated with other systems.

##### Relevant Technologies and Frameworks
- Python and its ecosystem (with modules and packages).
- Docker (from the chat-assistant’s Dockerfile).
- CI/CD tools (GitHub actions workflows, Travis CI, Appveyor).
- Documentation tools (Sphinx, ReadTheDocs).

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "PyHealth Core Library"
        subgraph "Data Layer"
            DatasetsNode["Datasets"]:::datalayer
            MedcodeNode["Medcode"]:::datalayer
            TokenizerNode["Tokenizer"]:::datalayer
            CalibrationNode["Calibration"]:::datalayer
        end
        subgraph "Processing Layer"
            TasksNode["Tasks"]:::processing
        end
        subgraph "Model Layer"
            ModelsNode["Models"]:::modellayer
        end
        subgraph "Training & Evaluation Layer"
            TrainerNode["Trainer"]:::training
            MetricsNode["Metrics"]:::training
        end
    end

    subgraph "Integration Layer"
        ChatAssistantNode["Chat-Assistant"]:::integration
    end

    subgraph "Support & Utility Layer"
        DocsNode["Docs"]:::support
        ExamplesNode["Examples & Leaderboard"]:::support
        TestingNode["Testing & CI"]:::support
    end

    %% Core pipeline connections
    DatasetsNode -->|"data_ingestion"| TasksNode
    MedcodeNode -->|"supports"| TasksNode
    TokenizerNode -->|"supports"| TasksNode
    TasksNode -->|"task_generation"| ModelsNode
    ModelsNode -->|"model_invocation"| TrainerNode
    CalibrationNode -->|"calibrates"| TrainerNode
    TrainerNode -->|"evaluation"| MetricsNode

    %% Integration connection
    ChatAssistantNode -->|"wraps_pipeline"| TasksNode

    %% Support connections
    TrainerNode -->|"documented_in"| DocsNode
    ModelsNode -->|"documented_in"| DocsNode
    ExamplesNode -->|"showcases"| TasksNode
    TestingNode -->|"validates"| TrainerNode

    %% Click Events
    click DatasetsNode "https://github.com/sunlabuiuc/pyhealth/tree/master/pyhealth/datasets/"
    click MedcodeNode "https://github.com/sunlabuiuc/pyhealth/tree/master/pyhealth/medcode/"
    click TokenizerNode "https://github.com/sunlabuiuc/pyhealth/blob/master/pyhealth/tokenizer.py"
    click CalibrationNode "https://github.com/sunlabuiuc/pyhealth/tree/master/pyhealth/calib/"
    click TasksNode "https://github.com/sunlabuiuc/pyhealth/tree/master/pyhealth/tasks/"
    click ModelsNode "https://github.com/sunlabuiuc/pyhealth/tree/master/pyhealth/models/"
    click TrainerNode "https://github.com/sunlabuiuc/pyhealth/blob/master/pyhealth/trainer.py"
    click MetricsNode "https://github.com/sunlabuiuc/pyhealth/tree/master/pyhealth/metrics/"
    click ChatAssistantNode "https://github.com/sunlabuiuc/pyhealth/tree/master/chat-assistant/"
    click DocsNode "https://github.com/sunlabuiuc/pyhealth/tree/master/docs/"
    click ExamplesNode "https://github.com/sunlabuiuc/pyhealth/tree/master/examples/"
    click TestingNode "https://github.com/sunlabuiuc/pyhealth/tree/master/.github/workflows/"

    %% Styles
    classDef datalayer fill:#ccf2ff,stroke:#1f78b4,stroke-width:2px;
    classDef processing fill:#d0f0c0,stroke:#33a02c,stroke-width:2px;
    classDef modellayer fill:#ffe6cc,stroke:#ff7f0e,stroke-width:2px;
    classDef training fill:#ffffcc,stroke:#ffd700,stroke-width:2px;
    classDef integration fill:#e6ccff,stroke:#6a3d9a,stroke-width:2px;
    classDef support fill:#f2f2f2,stroke:#b2b2b2,stroke-width:2px;
```
