# jhartford/deepiv architecture

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

- Interactive diagram: https://gitdiagram.com/jhartford/deepiv
- Repository: https://github.com/jhartford/deepiv

## Overview

##### Project type and purpose
- DeepIV is an open‐source Python package implementing the Deep IV (instrumental variables) method on top of Keras.
- It provides a two‐stage neural‐network procedure (treatment model + response model) for counterfactual prediction.

##### File structure
Top‐level directories and files:
- deepiv/         ← core library code
– architectures.py    (network‐building blocks)
– custom_gradients.py (IV‐specific gradient logic)
– densities.py        (density estimation helpers)
– models.py           (DeepIVModel class, main API)
– samplers.py         (Monte Carlo samplers for stage 2)
- experiments/    ← example pipelines demonstrating usage
- docs/           ← Sphinx documentation sources
- tests/          ← unit tests for core functionality
- setup.py, setup.cfg, Makefile, requirements_dev.txt, tox.ini, travis_pypi_setup.py ← build, CI, and packaging

##### README for additional insights
- Two‐stage procedure:
1. Fit the Treatment network
2. Fit the Response network, which consumes Treatment’s fitted distribution
- Built as a subclass of Keras’ Model class—drop‐in replacement for standard Keras models
- Example scripts under experiments/ illustrate both simple feedforward and convolutional variants

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Experiments
    subgraph "Experiments (Example Pipelines)" 
        direction TB
        EX1["data_generator.py"]:::examples
        EX2["demand_simulation.py"]:::examples
        EX3["demand_simulation_mnist.py"]:::examples
        EX4["linear.py"]:::examples
        EX5["nonpar.py"]:::examples
        EX6["twosls.py"]:::examples
    end

    %% Core DeepIV modules
    subgraph "DeepIV Core" 
        direction TB
        ARCH["Architectures (deepiv/architectures.py)"]:::core
        CUSTG["Custom Gradients (deepiv/custom_gradients.py)"]:::core
        DENS["Densities (deepiv/densities.py)"]:::core
        TM["Treatment Model"]:::core
        SAM["Sampler"]:::core
        RM["Response Model"]:::core
        API["DeepIVModel Class"]:::core
    end

    %% External frameworks
    subgraph "External Frameworks" 
        direction TB
        KERAS["Keras 2.0.6"]:::external
        TF["TensorFlow Backend"]:::external
        NP["NumPy/SciPy"]:::external
    end

    %% Tests
    subgraph "Unit Tests" 
        direction TB
        TEST["test_deepiv.py"]:::tests
    end

    %% Documentation
    subgraph "Documentation (Sphinx)" 
        direction TB
        DOC1["index.rst"]:::docs
        DOC2["usage.rst"]:::docs
        DOC3["installation.rst"]:::docs
    end

    %% Data and flow
    DATA["Input Data"]:::external
    OUT["Counterfactual Predictions"]:::external

    %% Connections: Experiments drive data
    EX1 -->|imports deepiv| API
    EX2 -->|imports deepiv| API
    EX3 -->|imports deepiv| API
    EX4 -->|imports deepiv| API
    EX5 -->|imports deepiv| API
    EX6 -->|imports deepiv| API

    API -->|uses architectures| ARCH
    API -->|uses custom gradients| CUSTG
    API -->|uses densities| DENS
    API -->|builds Stage1| TM
    TM -->|outputs distribution| SAM
    SAM -->|samples treatment| RM
    RM -->|predicts outcome| OUT

    %% Dependencies on external frameworks
    TM -->|built with| KERAS
    RM -->|built with| KERAS
    KERAS -->|backend| TF
    API -->|uses numeric| NP

    %% Tests and docs depend on core
    TEST -->|validates| API
    DOC1 -->|documents| API
    DOC2 -->|documents| API
    DOC3 -->|documents| API

    %% Click Events
    click TM "https://github.com/jhartford/deepiv/blob/master/deepiv/models.py"
    click RM "https://github.com/jhartford/deepiv/blob/master/deepiv/models.py"
    click SAM "https://github.com/jhartford/deepiv/blob/master/deepiv/samplers.py"
    click CUSTG "https://github.com/jhartford/deepiv/blob/master/deepiv/custom_gradients.py"
    click ARCH "https://github.com/jhartford/deepiv/blob/master/deepiv/architectures.py"
    click DENS "https://github.com/jhartford/deepiv/blob/master/deepiv/densities.py"
    click API "https://github.com/jhartford/deepiv/blob/master/deepiv/models.py"
    click EX1 "https://github.com/jhartford/deepiv/blob/master/experiments/data_generator.py"
    click EX2 "https://github.com/jhartford/deepiv/blob/master/experiments/demand_simulation.py"
    click EX3 "https://github.com/jhartford/deepiv/blob/master/experiments/demand_simulation_mnist.py"
    click EX4 "https://github.com/jhartford/deepiv/blob/master/experiments/linear.py"
    click EX5 "https://github.com/jhartford/deepiv/blob/master/experiments/nonpar.py"
    click EX6 "https://github.com/jhartford/deepiv/blob/master/experiments/twosls.py"
    click TEST "https://github.com/jhartford/deepiv/blob/master/tests/test_deepiv.py"
    click DOC1 "https://github.com/jhartford/deepiv/blob/master/docs/index.rst"
    click DOC2 "https://github.com/jhartford/deepiv/blob/master/docs/usage.rst"
    click DOC3 "https://github.com/jhartford/deepiv/blob/master/docs/installation.rst"

    %% Styles
    classDef core fill:#eef,stroke:#036,color:#000
    classDef external fill:#fdf,stroke:#630,color:#000
    classDef examples fill:#efe,stroke:#060,color:#000
    classDef tests fill:#fee,stroke:#600,color:#000
    classDef docs fill:#ffe,stroke:#aa0,color:#000
```
