How sunlabuiuc/pyhealth works
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).