# jakorostami/expectation architecture

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

- Interactive diagram: https://gitdiagram.com/jakorostami/expectation
- Repository: https://github.com/jakorostami/expectation

## Overview

##### Project type and purpose
- **Type**: A Python library for sequential testing and monitoring using e-values.
- **Purpose**: Provide a simple API (`SequentialTest`) to run valid, anytime-valid statistical tests (means, proportions, quantiles, variance, conformal, confseq, etc.) on streaming or batch data.

##### File structure
- **Top-level**
- `expectation/` – core package
- `examples/` – demonstration notebooks
- `tests/` – automated test suites
- `docs/`, `assets/` – documentation and images
- CI config under `.github/`
- **Submodules inside `expectation/`**
- `conformal/` – adaptive thresholds, cusum, conformal tests
- `confseq/` – confidence sequences, config, implementation
- `modules/` – building blocks: boundaries, martingales, e-power, hypothesis testing, order statistics, quantile tests
- `parametric/` – generic t-test implementations
- `seqtest/` – sequential e-testing orchestration (`SequentialTest`)
- `utils/` – helper functions

##### README for additional insights
- **Key API**: `SequentialTest(test_type, null_value, alternative)`
- **Workflow**:
1. Instantiate test
2. Call `.update(data_batch)` repeatedly
3. Obtain `e_value`, `reject_null`, and `e_process` (cumulative evidence)
- **Features**: Always-valid inference, multiple test types, streaming support, easy extension

##### Main components
a. **Client Code / User**
– Jupyter notebooks, Python scripts importing `expectation.SequentialTest`
b. **API Layer**
– `SequentialTest` class in `expectation/seqtest`
c. **Test-Type Modules**
– Conformal (`expectation/conformal`)
– Confidence sequences (`expectation/confseq`)
– Parametric tests (`expectation/parametric`)
d. **Core Engine / Modules**
– Martingales, boundaries, e-power, hypothesis tests, order statistics, quantile tests (`expectation/modules`)
e. **Utilities**
– Helper functions (`expectation/utils`)
f. **External Dependencies**
– NumPy, SciPy, Pandas (as specified in `requirements.txt`)
g. **Examples & Tests**
– Example notebooks (`examples/`)
– Automated tests (`tests/`)
h. **CI / Docs** (optional)
– GitHub Actions, documentation site

##### Relationships and interactions
- **Data flow**:
User → API Layer (`SequentialTest`) → selects appropriate Test-Type Module → uses Core Engine modules → computes e-values and e-process → returns results to User
- **Extensibility**:
New test types plug into the API by implementing the same interface in `expectation/modules` or a new subpackage
- **Utilities**:
Shared by all modules for common tasks (random number generation, boundary computation)

##### Architectural patterns & design principles
- **Modular design**: each statistical test is its own subpackage
- **Strategy pattern**: `SequentialTest` dispatches to different test modules based on `test_type`
- **Single Responsibility**: modules focus on one statistical method or utility
- **Plug-in architecture**: easy to add new tests without touching core API

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Layer
    User["Client Code / User"]:::support
    click User "https://github.com/jakorostami/expectation/tree/develop/examples/"

    %% API Layer
    SequentialTest["SequentialTest"]:::api
    click SequentialTest "https://github.com/jakorostami/expectation/blob/develop/expectation/seqtest/sequential_e_testing.py"

    %% Test Modules Layer
    subgraph "Test-Type Modules"
        direction TB
        Conformal["Conformal Module"]:::core
        click Conformal "https://github.com/jakorostami/expectation/tree/develop/expectation/conformal/"
        ConfidenceSeq["Confidence Sequence Module"]:::core
        click ConfidenceSeq "https://github.com/jakorostami/expectation/tree/develop/expectation/confseq/"
        Parametric["Parametric Test Module"]:::core
        click Parametric "https://github.com/jakorostami/expectation/tree/develop/expectation/parametric/"
    end

    %% Core Engine Layer
    subgraph "Core Engine / Modules"
        direction TB
        Boundaries["Boundaries"]:::core
        click Boundaries "https://github.com/jakorostami/expectation/blob/develop/expectation/modules/boundaries.py"
        Martingales["Martingales"]:::core
        click Martingales "https://github.com/jakorostami/expectation/blob/develop/expectation/modules/martingales.py"
        EPower["E-Power"]:::core
        click EPower "https://github.com/jakorostami/expectation/blob/develop/expectation/modules/epower.py"
        Hypothesis["Hypothesis Testing"]:::core
        click Hypothesis "https://github.com/jakorostami/expectation/blob/develop/expectation/modules/hypothesistesting.py"
        OrderStats["Order Statistics"]:::core
        click OrderStats "https://github.com/jakorostami/expectation/blob/develop/expectation/modules/orderstatistics.py"
        Quantile["Quantile Tests"]:::core
        click Quantile "https://github.com/jakorostami/expectation/blob/develop/expectation/modules/quantiletest.py"
    end

    %% Utilities
    Utils["Utilities"]:::core
    click Utils "https://github.com/jakorostami/expectation/blob/develop/expectation/utils/helper_functions.py"

    %% External Dependencies
    subgraph "External Dependencies"
        direction TB
        NumPy["NumPy"]:::external
        SciPy["SciPy"]:::external
        Pandas["Pandas"]:::external
        click NumPy "https://github.com/jakorostami/expectation/blob/develop/requirements.txt"
        click SciPy "https://github.com/jakorostami/expectation/blob/develop/requirements.txt"
        click Pandas "https://github.com/jakorostami/expectation/blob/develop/requirements.txt"
    end

    %% Supporting Artifacts
    Examples["Examples Notebooks"]:::support
    click Examples "https://github.com/jakorostami/expectation/tree/develop/examples/"
    Tests["Automated Tests"]:::support
    click Tests "https://github.com/jakorostami/expectation/tree/develop/tests/"
    CI["CI Configuration"]:::support
    click CI "https://github.com/jakorostami/expectation/blob/develop/.github/workflows/run-tests.yml"
    Docs["Documentation"]:::support
    click Docs "https://github.com/jakorostami/expectation/tree/develop/docs/"

    %% Relationships
    User -->|import| SequentialTest
    SequentialTest -->|dispatch to| Conformal
    SequentialTest -->|dispatch to| ConfidenceSeq
    SequentialTest -->|dispatch to| Parametric
    Conformal -->|uses| Boundaries
    Conformal -->|uses| Martingales
    ConfidenceSeq -->|uses| Boundaries
    ConfidenceSeq -->|uses| EPower
    Parametric -->|uses| Hypothesis
    Parametric -->|uses| OrderStats
    Parametric -->|uses| Quantile
    Boundaries -->|call| Utils
    Martingales -->|call| Utils
    EPower -->|call| Utils
    Hypothesis -->|call| Utils
    OrderStats -->|call| Utils
    Quantile -->|call| Utils
    SequentialTest -->|requires| NumPy
    SequentialTest -->|requires| SciPy
    SequentialTest -->|requires| Pandas
    Examples -->|demo| SequentialTest
    Tests -->|validate| Conformal
    Tests -->|validate| ConfidenceSeq
    Tests -->|validate| Parametric
    CI -->|runs| Tests
    Docs -->|reference| SequentialTest

    %% Styles
    classDef core fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef api fill:#90EE90,stroke:#000,stroke-width:1px
    classDef external fill:#FFA500,stroke:#000,stroke-width:1px
    classDef support fill:#D3D3D3,stroke:#000,stroke-width:1px
```
