# ihmeuw-msca/pydisagg architecture

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

- Interactive diagram: https://gitdiagram.com/ihmeuw-msca/pydisagg
- Repository: https://github.com/ihmeuw-msca/pydisagg

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Entities
    User((User)):::external
    DataInput["Aggregated Data + Baseline Rates"]:::external
    PyPI((PyPI)):::external
    GitHubActions((GitHub Actions)):::cicd

    %% User Layer
    User -->|"imports disaggregate() or model classes"| DisaggAPI
    subgraph "Core Library"
        direction TB
        %% Validation Layer
        Validator["IHME Schema Validator"]:::core
        Validator -->|"validated data"| DisaggAPI

        %% API Layer
        DisaggAPI["Disaggregate API"]:::core
        DisaggAPI -->|"selects model & data"| Models
        DisaggAPI -->|"calls transform() / inv_transform()"| Transformations

        %% Transformation Layer
        Transformations["Transformations (T, T⁻¹)"]:::core
        Transformations -->|"transformed data"| Models

        %% Model Layer
        subgraph "Model Layer"
            direction TB
            BaseModel["Base Model Interface"]:::core
            RateModel["RateMultiplicativeModel"]:::core
            LMOModel["LMOModel"]:::core
            LogOddsModel["LogOddsModel"]:::core
            BaseModel --> RateModel
            BaseModel --> LMOModel
            BaseModel --> LogOddsModel
            Models(("Models")):::core
            Models --> BaseModel
            RateModel -->|"fit & estimate Dᵢ"| Models
            LMOModel -->|"fit & estimate Dᵢ"| Models
            LogOddsModel -->|"fit & estimate Dᵢ"| Models
        end

        %% Output back to User
        Models -->|"group estimates"| User
    end

    %% Data Flow Start
    DataInput -->|"input data"| Validator

    %% Supporting Systems
    subgraph "Supporting Systems"
        direction TB
        Docs["Documentation (Sphinx)"]:::support
        Examples["Examples & Notebooks"]:::support
        Tests["Test Suite (pytest)"]:::support
    end

    %% CI/CD Pipeline
    GitHubActions -->|"run tests"| Tests
    GitHubActions -->|"build docs"| Docs
    GitHubActions -->|"package & deploy"| PyPI

    %% Examples flow
    Examples -->|"demonstrate API"| DisaggAPI

    %% Click Events
    click Validator "https://github.com/ihmeuw-msca/pydisagg/blob/main/src/pydisagg/ihme/schema.py"
    click Validator "https://github.com/ihmeuw-msca/pydisagg/blob/main/src/pydisagg/ihme/validator.py"
    click DisaggAPI "https://github.com/ihmeuw-msca/pydisagg/blob/main/src/pydisagg/disaggregate.py"
    click Transformations "https://github.com/ihmeuw-msca/pydisagg/blob/main/src/pydisagg/transformations.py"
    click BaseModel "https://github.com/ihmeuw-msca/pydisagg/blob/main/src/pydisagg/models/disagg_model.py"
    click RateModel "https://github.com/ihmeuw-msca/pydisagg/blob/main/src/pydisagg/models/rate_multiplicative_model.py"
    click LMOModel "https://github.com/ihmeuw-msca/pydisagg/blob/main/src/pydisagg/models/lmo_model.py"
    click LogOddsModel "https://github.com/ihmeuw-msca/pydisagg/blob/main/src/pydisagg/models/log_odds_model.py"
    click Examples "https://github.com/ihmeuw-msca/pydisagg/tree/main/examples/"
    click Docs "https://github.com/ihmeuw-msca/pydisagg/tree/main/docs/"
    click Tests "https://github.com/ihmeuw-msca/pydisagg/tree/main/tests/"
    click GitHubActions "https://github.com/ihmeuw-msca/pydisagg/blob/main/.github/workflows/build.yml"
    click GitHubActions "https://github.com/ihmeuw-msca/pydisagg/blob/main/.github/workflows/deploy.yml"
    click PyPI "https://github.com/ihmeuw-msca/pydisagg/blob/main/pyproject.toml"

    %% Styling
    classDef core fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef support fill:#90EE90,stroke:#333,stroke-width:1px
    classDef cicd fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef external fill:#FFE4B5,stroke:#333,stroke-width:1px
```
