# realrate/causing architecture

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

- Interactive diagram: https://gitdiagram.com/realrate/causing
- Repository: https://github.com/realrate/causing

## Overview

1.  The user-facing entry points (examples CLI, Python API)
2.  The core modules (model definition & processing, graph construction, utilities)
3.  Data-flow paths (input CSV/JSON → model computations → JSON results → Graphviz → SVG output)
4.  External dependencies (SymPy, Graphviz, file system)

––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––
##### Main components
- CLI / Python API (causing/examples/__main__.py, user’s scripts)
- Model Builder & Evaluator (causing/model.py)
- Graph Constructor (causing/graph.py)
- Utility Layer (causing/utils.py)
- Data Store (input CSV/JSON under data/ or causing/examples/input/)
- Results Store (intermediate graphs.json under output/)
- Renderer (Graphviz engine invoked by causing/graph.py)
- Packaging & Tests (setup.py, Makefile, .github/workflows, tests/)

##### Interactions and data flow
1.  User invokes “python -m causing.examples example” or uses Python API.
2.  Examples loader reads dataset (CSV/JSON) → passes to Model Builder.
3.  Model Builder (model.py)
– Defines SymPy symbols and equations
– Calculates endogenous variables per individual observation
– Calls Utility functions (utils.py) for data normalization, derivative computations
– Outputs a structural representation (adjacency, weights) to Graph Constructor
4.  Graph Constructor (graph.py)
– Converts structural representation → internal graph object
– Splits total effects into mediation effects per edge
– Serializes per-individual IME graph(s) into JSON under output/…/graphs.json
– Calls Graphviz to render JSON → SVG/EPS output in output/…
5.  Final graph files are stored under output/education, output/example*, etc.

##### Architectural patterns and design principles
- Modular design: clear separation of model logic, graph logic, utilities, CLI
- Data-driven flow: pipelines for input → compute → intermediate JSON → render → output
- External-tool integration: Graphviz as rendering back-end, SymPy for symbolic math
- Small-data, in-memory processing; no long-running services or microservices
- Test harness: unit tests for model estimation (tests/test_estimate.py), utils, examples

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Entry Points
    subgraph "User Entry Points"
        CLI["CLI / Python API"]:::internal
        ExampleModels["Example Models"]:::internal
    end

    %% Input Data Stores
    subgraph "Input Data Stores" 
        direction TB
        In1[(education.csv)]:::datastore
        In2[(example.json)]:::datastore
        In3[(example2.json)]:::datastore
        In4[(example3.json)]:::datastore
        In5[(data/education.csv)]:::datastore
        In6[(data/xdat.csv)]:::datastore
        In7[(data/ymdat.csv)]:::datastore
    end

    %% Core Modules
    subgraph "Core Modules"
        direction TB
        ModelBuilder["Model Builder & Evaluator"]:::internal
        Util["Utility Layer"]:::internal
        GraphConstructor["Graph Constructor"]:::internal
    end

    %% Intermediate/Result Store
    subgraph "Intermediate Results"
        JSONStore[(graphs.json)]:::datastore
    end

    %% Rendered Output
    subgraph "Rendered Output"
        SVGOut[(SVG/EPS files)]:::datastore
    end

    %% External Tools
    subgraph "External Dependencies"
        direction TB
        SymPy["SymPy"]:::external
        Graphviz["Graphviz"]:::external
    end

    %% Developer Toolchain
    subgraph "Developer Toolchain"
        direction TB
        Setup["setup.py"]:::devtool
        Makefile["Makefile"]:::devtool
        PreCommit[".github/workflows/pre-commit.yml"]:::devtool
        Publish[".github/workflows/publish-to-pypi.yml"]:::devtool
        Test1["tests/test_estimate.py"]:::devtool
        Test2["tests/utils.py"]:::devtool
        Test3["tests/examples/models.py"]:::devtool
    end

    %% Data Flow
    CLI --> ExampleModels
    ExampleModels --> In1
    ExampleModels --> In2
    ExampleModels --> In3
    ExampleModels --> In4
    In1 --> ModelBuilder
    In2 --> ModelBuilder
    In3 --> ModelBuilder
    In4 --> ModelBuilder
    In5 --> ModelBuilder
    In6 --> ModelBuilder
    In7 --> ModelBuilder

    ModelBuilder --> Util
    ModelBuilder -->|"structure"| GraphConstructor
    ModelBuilder --> SymPy
    GraphConstructor -->|"JSON"| JSONStore
    GraphConstructor --> Graphviz
    Graphviz --> SVGOut

    %% Click Events
    click CLI "https://github.com/realrate/causing/blob/develop/causing/examples/__main__.py"
    click ExampleModels "https://github.com/realrate/causing/blob/develop/causing/examples/models.py"
    click ModelBuilder "https://github.com/realrate/causing/blob/develop/causing/model.py"
    click Util "https://github.com/realrate/causing/blob/develop/causing/utils.py"
    click GraphConstructor "https://github.com/realrate/causing/blob/develop/causing/graph.py"
    click In1 "https://github.com/realrate/causing/blob/develop/causing/examples/input/education.csv"
    click In2 "https://github.com/realrate/causing/blob/develop/causing/examples/input/example.json"
    click In3 "https://github.com/realrate/causing/blob/develop/causing/examples/input/example2.json"
    click In4 "https://github.com/realrate/causing/blob/develop/causing/examples/input/example3.json"
    click In5 "https://github.com/realrate/causing/blob/develop/data/education.csv"
    click In6 "https://github.com/realrate/causing/blob/develop/data/xdat.csv"
    click In7 "https://github.com/realrate/causing/blob/develop/data/ymdat.csv"
    click JSONStore "https://github.com/realrate/causing/blob/develop/output/education/graphs.json"
    click JSONStore "https://github.com/realrate/causing/blob/develop/output/example/graphs.json"
    click JSONStore "https://github.com/realrate/causing/blob/develop/output/example2/graphs.json"
    click JSONStore "https://github.com/realrate/causing/blob/develop/output/example3/graphs.json"
    click JSONStore "https://github.com/realrate/causing/blob/develop/output/heaviside/graphs.json"
    click Setup "https://github.com/realrate/causing/blob/develop/setup.py"
    click Makefile "https://github.com/realrate/causing/tree/develop/Makefile"
    click PreCommit "https://github.com/realrate/causing/blob/develop/.github/workflows/pre-commit.yml"
    click Publish "https://github.com/realrate/causing/blob/develop/.github/workflows/publish-to-pypi.yml"
    click Test1 "https://github.com/realrate/causing/blob/develop/tests/test_estimate.py"
    click Test2 "https://github.com/realrate/causing/blob/develop/tests/utils.py"
    click Test3 "https://github.com/realrate/causing/blob/develop/tests/examples/models.py"

    %% Styles
    classDef internal fill:#cce5ff,stroke:#004085,color:#004085;
    classDef datastore fill:#d4edda,stroke:#155724,color:#155724;
    classDef external fill:#ffe5b4,stroke:#ff8c00,color:#8b4513;
    classDef devtool fill:#f5c6cb,stroke:#721c24,color:#721c24;
```
