How ihmeuw-msca/pydisagg works
Project Type and Purpose
• This is a Python library (pyDisagg) for disaggregating aggregated count data under generalized proportionality assumptions.
• It exposes a programmatic API (pydisagg.disaggregate) and implements multiple statistical models (rate-multiplicative, log-modified-odds).
• It includes documentation (Sphinx), example notebooks, unit tests, and CI/CD workflows for build, test, and deployment to PyPI.
File Structure and Architectural Signals
• Top‐level:
• .github/workflows/: CI/CD pipelines (build, deploy) via GitHub Actions
• src/pydisagg/: core library modules
• tests/: unit tests
• docs/: Sphinx documentation source
• examples/: Jupyter notebooks and example scripts
• pyproject.toml, ruff.toml: build and lint configuration
• Inside src/pydisagg/:
• disaggregate.py: main entry point orchestrating data splits
• ihme/: IHME API-specific schema, splitters, validator
• models/: statistical model implementations (RateMultiplicativeModel, LMOModel)
• transformations.py: transformation functions (T and T⁻¹)
• typing.py: shared type definitions
Key Components
a. User & Client Layer
• Users import the disaggregate function or individual model classes.
• Example scripts & notebooks demonstrate usage.
b. Core Library
1. API Layer (pydisagg.disaggregate)
• Receives aggregated data + baseline rates
• Selects/instantiates a model
2. Model Layer (models/)
• RateMultiplicativeModel
• LMOModel
• Each implements T, T⁻¹, fitting β, computing Dᵢ
3. Transformation Layer (transformations.py)
• Mathematical transforms (log, log-odds variants)
4. IHME Schema & Splitters (ihme/)
• Schema validation (schema.py, validator.py)
• Splitter implementations (age, sex, category)
c. Supporting Systems
• Documentation subsystem (Sphinx build) under docs/
• Examples & notebooks under examples/
• Test suite under tests/
• CI/CD pipelines (.github/workflows) triggering:
• Build & test on push
• Deploy to PyPI on tag
Relationships & Data Flows
• Input Data → Schema Validator → Disaggregate API
• Disaggregate API → Transformation functions ↔ Model classes
• Model classes → output per-group estimates → returned to user
• Example scripts & notebooks use the API → illustrate data flow
• CI/CD pipelines trigger tests, docs build, and packaging
Architectural Patterns & Principles
• Separation of Concerns: API, models, transformations, validation are distinct modules
• Modular OOP: each model implements a common interface (fit, transform, estimate)
• Extensibility: new models or splitters can be added by placing modules alongside existing ones
• Documentation as code: Sphinx sources, Makefile, conf.py; keeps docs in sync with code