# google/empirical_calibration architecture

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

- Interactive diagram: https://gitdiagram.com/google/empirical_calibration
- Repository: https://github.com/google/empirical_calibration

## Overview

##### Main Components Identification
- Library Core Component:
- Main package “empirical_calibration”. Inside this module, the key file is core.py (which likely implements the core calibration routines) and its counterpart core_test.py for unit testing.
- Data Submodule:
- “data” subdirectory as an additional component responsible for handling or generating calibration dataset examples. It contains scripts such as kang_schafer.py, kang_schafer_test.py, and lalonde.py.
- Notebook Examples:
- “notebooks” folder which contains several Jupyter notebooks. These notebooks serve as the user-facing demonstration of how to use the library for survey calibration and causal inference (e.g., notebooks for the Kang-Schafer method, Lalonde study, and simulation examples).
- Setup and Build Infrastructure:
- A component for project configuration, represented by files like setup.py (installation and dependency configurations) and BUILD files in both the root and inside empirical_calibration/data. These indicate build or packaging scripts which can be related to continuous integration or automated deployment.

##### Relationships and Data Flow
- Dependency between the core processing logic (in core.py) and data handling routines (in the data submodule). Indicate that core.py uses or references functionalities or data available in the “data” folder.
- That the setup and BUILD components are part of the project's build and deployment pipeline.

##### Architectural Patterns or Design Principles
- Modularity: Highlight that the library is separated into well-defined modules (core functionality vs. data handling) with tests included at the same level (core_test.py, kang_schafer_test.py).
- Extensibility: Point out that by separating examples (notebooks) from the core library, the design supports both interactive experimentation and integration into other projects.
- Testing / Validation: Acknowledge the presence of unit tests in the file tree which suggests that testing is a first-class citizen in the design.

##### Relevant Technologies and Frameworks
- Python 3.6+ is required.
- The convex optimization technique is likely built on established Python libraries for numerical computation (although not directly visible, it might be implied via dependencies in setup.py or within the code itself).
- Jupyter/Google Colab: Notebooks suggest interactive execution environments, so if applicable, indicate integration with these platforms.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Top Layer: User / Client Code
    user["User/Client Code\n(import empirical_calibration as ec)"]:::client

    %% Middle Layer: Empirical Calibration Library
    subgraph "Empirical Calibration Library"
        direction TB
        core["Core Module (core.py)"]:::core
        coretest["Core Tests (core_test.py)"]:::test
        data["Data Module"]:::data
        kang["Kang-Schafer Data (kang_schafer.py)"]:::data
        kangtest["Kang-Schafer Tests (kang_schafer_test.py)"]:::test
        lalonde["Lalonde Data (lalonde.py)"]:::data
    end

    %% Middle Layer: Example Notebooks
    subgraph "Example Notebooks"
        direction TB
        n1["Kang-Schafer Method (causal_inference_kang_schafer.ipynb)"]:::notebook
        n2["Lalonde Study (causal_inference_lalonde.ipynb)"]:::notebook
        n3["Kang-Schafer Population Mean (kang_schafer_population_mean.ipynb)"]:::notebook
        n4["Survey Calibration CVXR (survey_calibration_cvxr.ipynb)"]:::notebook
        n5["Survey Calibration Simulated (survey_calibration_simulated.ipynb)"]:::notebook
    end

    %% Bottom Layer: Build & Deployment
    subgraph "Build & Deployment"
        direction TB
        setup["Setup (setup.py)"]:::build
        buildCore["Core BUILD (empirical_calibration/BUILD)"]:::build
        buildData["Data BUILD (empirical_calibration/data/BUILD)"]:::build
    end

    %% Connections
    user -->|"imports"| core
    core -->|"uses"| data
    data ---|"supplies data"| kang
    data ---|"supplies data"| lalonde
    core -->|"validated by"| coretest
    kang ---|"tested by"| kangtest

    n1 -->|"invokes"| core
    n2 -->|"invokes"| core
    n3 -->|"invokes"| core
    n4 -->|"invokes"| core
    n5 -->|"invokes"| core

    buildCore -->|"builds"| core
    buildData -->|"builds"| data
    setup -->|"configures"| core

    %% Click Events for Library Core Component
    click core "https://github.com/google/empirical_calibration/blob/master/empirical_calibration/core.py"
    click coretest "https://github.com/google/empirical_calibration/blob/master/empirical_calibration/core_test.py"

    %% Click Events for Data Submodule
    click data "https://github.com/google/empirical_calibration/tree/master/empirical_calibration/data"
    click kang "https://github.com/google/empirical_calibration/blob/master/empirical_calibration/data/kang_schafer.py"
    click kangtest "https://github.com/google/empirical_calibration/blob/master/empirical_calibration/data/kang_schafer_test.py"
    click lalonde "https://github.com/google/empirical_calibration/blob/master/empirical_calibration/data/lalonde.py"

    %% Click Events for Notebook Examples
    click n1 "https://github.com/google/empirical_calibration/blob/master/notebooks/causal_inference_kang_schafer.ipynb"
    click n2 "https://github.com/google/empirical_calibration/blob/master/notebooks/causal_inference_lalonde.ipynb"
    click n3 "https://github.com/google/empirical_calibration/blob/master/notebooks/kang_schafer_population_mean.ipynb"
    click n4 "https://github.com/google/empirical_calibration/blob/master/notebooks/survey_calibration_cvxr.ipynb"
    click n5 "https://github.com/google/empirical_calibration/blob/master/notebooks/survey_calibration_simulated.ipynb"

    %% Click Events for Build and Deployment
    click setup "https://github.com/google/empirical_calibration/blob/master/setup.py"
    click buildCore "https://github.com/google/empirical_calibration/tree/master/empirical_calibration/BUILD"
    click buildData "https://github.com/google/empirical_calibration/tree/master/empirical_calibration/data/BUILD"

    %% Styles
    classDef client fill:#FFEB99,stroke:#333,stroke-width:2px;
    classDef core fill:#B3E5FC,stroke:#333,stroke-width:2px;
    classDef test fill:#C8E6C9,stroke:#333,stroke-width:2px;
    classDef data fill:#FFE0B2,stroke:#333,stroke-width:2px;
    classDef notebook fill:#D1C4E9,stroke:#333,stroke-width:2px;
    classDef build fill:#FFAB91,stroke:#333,stroke-width:2px;
```
