How azusakou/miranda works
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.