# azusakou/miranda architecture

> Architecture diagram of the GitHub repository azusakou/miranda, 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/azusakou/miranda
- Repository: https://github.com/azusakou/miranda

## Overview

##### Project Type and Purpose
- The project is a Python-based research and prototype application designed for medication recommendation using causal inference. Its unique approach mimics the learning process of human doctors and relies on counterfactual results.
- It uses clinical datasets like MIMIC III and MIMIC IV, and implements several machine learning models (CNN, RNN, Transformer, etc.) alongside modules for data processing, medical coding (medcode), and tasks (e.g., drug recommendation, readmission prediction).

##### Analyzing the File Structure
- Top-Level Files: Key files include MiranDa.py (the main entry point), cfg.py (configuration with hyperparameters), and the README. These indicate that MiranDa.py is responsible for orchestrating training/inference.
- Directories:
- docs: Contains comprehensive API documentation and guides for different modules such as datasets, models, medcode, metrics, tasks.
- pyhealth: Encapsulates the core domain logic.
▪ pyhealth/data: Data loading and preprocessing scripts.
▪ pyhealth/datasets: Contains various dataset implementations (MIMIC3, MIMIC4, OMOP, etc.) and utility/splitter functions for partitioning data.
▪ pyhealth/medcode: Manages medical coding standards (ICD, ATC, etc.) and any cross-mapping logic.
▪ pyhealth/metrics: Defines evaluation metrics including ones for binary, multiclass, multilabel scenarios.
▪ pyhealth/models: Holds different machine learning model implementations. Notice models such as CNN, RNN, Transformer, etc., and even adversarial/attack variants.
▪ pyhealth/tasks: Houses task-specific implementations (e.g., drug recommendation, length of stay prediction, mortality prediction).
▪ Other modules such as tokenizer, trainer, and utils support data preprocessing, model training, and utility functions.

##### Reading the README
- The README emphasizes key components – the causal inference mechanism, medication recommendation from clinical datasets, and experiments configured with multiple seeds and epochs. This reinforces the need to portray how data flows from raw clinical datasets, through a preprocessing pipeline, into various models, and eventually into task-specific outputs (recommendations and predictions).
- Experimental parameters and hyperparameter configurations (e.g., learning rate, batch size) in cfg.py further hint at the training pipeline design.

a. Main Components:
- Entry Point & Configuration: MiranDa.py and cfg.py.
- Data Input: Clinical datasets (e.g., MIMIC III, MIMIC IV) that are loaded through pyhealth/data and standardized via pyhealth/datasets.
- Medical Coding Module: pyhealth/medcode for mapping and preparing standardized medical codes.
- Model Building: pyhealth/models, illustrating various architectures (CNN, RNN, Transformer, etc.) used for different recommendation and prediction tasks.
- Task Orchestration: pyhealth/tasks, which drives specific outcomes such as drug recommendation and readmission prediction.
- Evaluation & Metrics: pyhealth/metrics for defining and calculating performance measures.
- Training & Inference Layer: Incorporates the trainer (pyhealth/trainer) and any preprocessing/utility functions (pyhealth/utils) that manage the overall flow.

b. Relationships and Interactions:
- From MiranDa.py, the control flow branches out to data ingestion (pyhealth/data) and dataset module (pyhealth/datasets) where raw clinical data is transformed.
- Processed data is then sent to the medcode module to ensure standardized medical terminologies.
- Data flows into the model building modules (pyhealth/models) based on the selected architecture.
- The trainer accompanies these modules for training loops and uses evaluation metrics (pyhealth/metrics) to measure model performance.
- Task modules (pyhealth/tasks) provide specific contextual processing (e.g., predicting length of stay, readmission), using outputs from the models.

c. Architectural Patterns & Design Principles:
- Layered Architecture: The structure follows a clear separation of concerns—from data ingestion, preprocessing, model training, to evaluation.
- Modularity and Extensibility: Each package (data, datasets, medcode, metrics, models, tasks) is self-contained, making it easier to extend or swap components.
- Configuration Driven: The use of cfg.py underscores the emphasis on hyperparameter tuning and experimental reproducibility.

d. Technologies & Frameworks:
- Python forms the backbone of the project.
- The project leverages the PyHealth framework (from the acknowledgement in README) to interface with healthcare data.
- Models could be built with deep learning frameworks (e.g., PyTorch or TensorFlow) though not explicitly mentioned, they are implicit in the implementation of CNNs, RNNs, etc.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Entry & Configuration"
        CFG["cfg.py"]:::config
        EP["MiranDa.py"]:::config
    end

    subgraph "Data Ingestion & Preprocessing"
        DP["Data Loading & Preprocessing (pyhealth/data)"]:::data
        DS["Dataset Implementations (pyhealth/datasets)"]:::data
    end

    subgraph "Medical Coding"
        MC["Medical Coding Logic (pyhealth/medcode)"]:::coding
        CS["Code Standards (pyhealth/medcode/codes)"]:::coding
    end

    subgraph "Model Building"
        MI["Model Implementations (pyhealth/models)"]:::model
        AM["Adversarial Models (pyhealth/models/attack)"]:::model
        BM["Base Model & Utilities (pyhealth/models/base_model & pyhealth/models/utils)"]:::model
    end

    subgraph "Task Orchestration"
        TO["Task Handlers (pyhealth/tasks)"]:::task
    end

    subgraph "Training & Inference"
        TR["Training Module (pyhealth/trainer)"]:::training
        TK["Tokenizer (pyhealth/tokenizer)"]:::training
        UT["Utility Functions (pyhealth/utils)"]:::training
    end

    EM["Evaluation Metrics (pyhealth/metrics)"]:::evaluation

    %% Connections
    CFG --> EP
    EP --> DP
    EP --> DS
    DP --> MC
    DS --> MC
    MC --> CS
    MC --> MI
    MI --> BM
    MI --> AM
    MI --> TR
    TR --> TK
    TR --> UT
    TR --> TO
    TR --> EM
    TO --> EM

    %% Click Events
    click CFG "https://github.com/azusakou/miranda/blob/main/cfg.py"
    click EP "https://github.com/azusakou/miranda/blob/main/MiranDa.py"
    click DP "https://github.com/azusakou/miranda/blob/main/pyhealth/data/data.py"
    click DS "https://github.com/azusakou/miranda/tree/main/pyhealth/datasets/"
    click MC "https://github.com/azusakou/miranda/tree/main/pyhealth/medcode/"
    click CS "https://github.com/azusakou/miranda/tree/main/pyhealth/medcode/codes/"
    click MI "https://github.com/azusakou/miranda/tree/main/pyhealth/models/"
    click AM "https://github.com/azusakou/miranda/tree/main/pyhealth/models/attack/"
    click BM "https://github.com/azusakou/miranda/blob/main/pyhealth/models/base_model.py"
    click TO "https://github.com/azusakou/miranda/tree/main/pyhealth/tasks/"
    click TR "https://github.com/azusakou/miranda/blob/main/pyhealth/trainer.py"
    click TK "https://github.com/azusakou/miranda/blob/main/pyhealth/tokenizer.py"
    click UT "https://github.com/azusakou/miranda/blob/main/pyhealth/utils.py"
    click EM "https://github.com/azusakou/miranda/tree/main/pyhealth/metrics/"

    %% Styles
    classDef config fill:#add8e6,stroke:#333,stroke-width:2px;
    classDef data fill:#90ee90,stroke:#333,stroke-width:2px;
    classDef coding fill:#ffa500,stroke:#333,stroke-width:2px;
    classDef model fill:#ffdead,stroke:#333,stroke-width:2px;
    classDef task fill:#dda0dd,stroke:#333,stroke-width:2px;
    classDef training fill:#ff7f7f,stroke:#333,stroke-width:2px;
    classDef evaluation fill:#ffb6c1,stroke:#333,stroke-width:2px;
```
