# casact/chainladder-python architecture

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

- Interactive diagram: https://gitdiagram.com/casact/chainladder-python
- Repository: https://github.com/casact/chainladder-python

## Overview

##### Project Type and Purpose
- This is an open-source Python library (chainladder) for property and casualty loss reserving.
- It provides data structures (“Triangle”), deterministic and stochastic reserving algorithms, utilities for data I/O/manipulation, and workflow orchestration (grid search, voting).

##### High-Level Architecture Overview
- API Layer:
- Entry points exposed to users (functions like read_triangle, chainladder pipelines).
- Mimics pandas and scikit-learn style.
- Core Engine:
- Data model (“Triangle”) and common operations (slice, display, correlation).
- Central classes and functions in chainladder/core.
- Algorithm Modules:
- Adjustments (berqsherm, bootstrap, parallelogram, trend).
- Development methods (GLM, Munich, Clark, incremental, outstanding, etc.).
- Reserving methods (Mack, Bornhuetter-Ferguson, CapeCod, etc.).
- Tail modeling (exponential, bondy, constant, curve).
- Workflow Orchestration:
- Grid search and voting ensembles under chainladder/workflow.
- Utilities & I/O:
- Data I/O in core/io.
- Data-loading helpers, sparse operations, weighted regression, Dask and CuPy integration in utils.
- Support Components:
- Sample data under utils/data for examples and tests.
- Benchmark suite (benchmarks/benchmarks.py + asv.conf.json).
- Documentation and tutorial notebooks (docs/).
- CI/CD pipelines (.github/workflows, environment yaml files).

##### Relationships & Data Flow
- User script or notebook imports chainladder API
→ calls read_sample or read_triangle → constructs Triangle object.
- Triangle flows into a “method” or “development” algorithm → returns reserves, link ratios, or stochastic simulations.
- Optional tail model step processes output of reserving method → tail curve estimate.
- Workflow module can chain multiple methods (gridsearch/voting)
→ orchestrates the above steps, aggregates results.
- Utilities (Dask/CuPy) accelerate computations under the hood if configured.

##### Key Architectural Patterns
- Modular plug-in structure: each reserving method and adjustment is its own module, shares common base classes.
- Pipeline pattern: analogous to scikit-learn pipelines (see core/base.py and workflow/Pipeline).
- Separation of concerns:
- core for data structures and basic ops,
- methods/adjustments/tails for domain algorithms,
- utils for performance and I/O,
- workflow for orchestration.
- Testing is co-located with modules under tests subdirectories.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% API Layer
    subgraph "API Layer"
        direction TB
        API_Entry["Entry Points"]:::core
        API_Pipeline["Pipeline Base"]:::core
    end

    %% Core Engine
    subgraph "Core Engine" 
        direction TB
        Core_Triangle["Triangle Model"]:::core
        Core_Common["Common Utilities"]:::core
        Core_IO["I/O Utilities"]:::core
        Core_Corr["Correlation"]:::core
        Core_Display["Display"]:::core
        Core_Slice["Slice"]:::core
        Core_Pandas["Pandas Integration"]:::core
    end

    %% Algorithm Modules
    subgraph "Algorithm Modules"
        direction TB
        subgraph "Adjustments" 
            direction TB
            Adj_Berq["Berq-Sherman"]:::alg
            Adj_Boot["Bootstrap"]:::alg
            Adj_Para["Parallelogram"]:::alg
            Adj_Trend["Trend"]:::alg
        end
        subgraph "Development Methods"
            direction TB
            Dev_GLM["GLM"]:::alg
            Dev_Munich["Munich"]:::alg
            Dev_Clark["Clark"]:::alg
            Dev_Incr["Incremental"]:::alg
            Dev_Out["Outstanding"]:::alg
            Dev_Barn["Barnzehn"]:::alg
            Dev_Const["Constant Dev"]:::alg
        end
        subgraph "Reserving Methods"
            direction TB
            Res_Chain["Chainladder"]:::alg
            Res_Mack["Mack"]:::alg
            Res_Benkt["Benktander"]:::alg
            Res_Born["Bornhuetter-Ferguson"]:::alg
            Res_Cape["CapeCod"]:::alg
            Res_ExpLoss["Expected Loss"]:::alg
        end
        subgraph "Tail Modeling"
            direction TB
            Tail_Exp["Exponential"]:::alg
            Tail_Bond["Bondy"]:::alg
            Tail_ConstTail["Constant Tail"]:::alg
            Tail_Curve["Curve Tail"]:::alg
        end
    end

    %% Workflow Orchestrator
    subgraph "Workflow Orchestrator"
        direction TB
        WF_Grid["Grid Search"]:::workflow
        WF_Vote["Voting Ensemble"]:::workflow
    end

    %% Utilities & I/O
    subgraph "Utilities & I/O"
        direction TB
        Util_Dask["Dask"]:::util
        Util_Cupy["CuPy"]:::util
        Util_Sparse["Sparse Ops"]:::util
        Util_Weight["Weighted Regression"]:::util
        Util_Help["Data Helpers"]:::util
        Util_Data["Sample Data"]:::util
    end

    %% Support Components
    subgraph "Support"
        direction TB
        Supp_Bench["Benchmarks"]:::support
        Supp_CI["CI/CD Pipelines"]:::support
        Supp_Docs["Documentation & Tutorials"]:::support
    end

    %% External Dependencies
    subgraph "External Dependencies"
        direction TB
        Ext_Pandas["pandas"]:::external
        Ext_Numpy["numpy"]:::external
        Ext_Scipy["scipy"]:::external
        Ext_Dask["dask"]:::external
        Ext_CuPy["cupy"]:::external
    end

    %% Connections
    API_Entry -->|"calls"| Core_Triangle
    API_Pipeline -->|"constructs"| Core_Triangle
    Core_Triangle -->|"Flow to algorithms"| Adj_Berq
    Core_Triangle --> Dev_GLM
    Dev_GLM --> Res_Chain
    Res_Chain --> Tail_Exp
    WF_Grid --> Adj_Berq
    WF_Grid --> Dev_GLM
    WF_Grid --> Res_Chain
    WF_Vote --> Res_Chain
    Core_Common -.-> Util_Help
    Adj_Berq -.-> Util_Dask
    Dev_GLM -.-> Util_Cupy
    Res_Chain -.-> Util_Weight
    Core_IO -.-> Util_Data
    Core_Triangle -->|"uses"| Ext_Pandas
    Core_Common --> Ext_Numpy
    Dev_GLM --> Ext_Scipy
    Util_Dask --> Ext_Dask
    Util_Cupy --> Ext_CuPy

    %% Click Events
    click API_Entry "https://github.com/casact/chainladder-python/blob/master/chainladder/__init__.py"
    click API_Pipeline "https://github.com/casact/chainladder-python/blob/master/chainladder/core/base.py"
    click Core_Triangle "https://github.com/casact/chainladder-python/blob/master/chainladder/core/triangle.py"
    click Core_Common "https://github.com/casact/chainladder-python/blob/master/chainladder/core/common.py"
    click Core_IO "https://github.com/casact/chainladder-python/blob/master/chainladder/core/io.py"
    click Core_Corr "https://github.com/casact/chainladder-python/blob/master/chainladder/core/correlation.py"
    click Core_Display "https://github.com/casact/chainladder-python/blob/master/chainladder/core/display.py"
    click Core_Slice "https://github.com/casact/chainladder-python/blob/master/chainladder/core/slice.py"
    click Core_Pandas "https://github.com/casact/chainladder-python/blob/master/chainladder/core/pandas.py"
    click Adj_Berq "https://github.com/casact/chainladder-python/blob/master/chainladder/adjustments/berqsherm.py"
    click Adj_Boot "https://github.com/casact/chainladder-python/blob/master/chainladder/adjustments/bootstrap.py"
    click Adj_Para "https://github.com/casact/chainladder-python/blob/master/chainladder/adjustments/parallelogram.py"
    click Adj_Trend "https://github.com/casact/chainladder-python/blob/master/chainladder/adjustments/trend.py"
    click Dev_GLM "https://github.com/casact/chainladder-python/blob/master/chainladder/development/glm.py"
    click Dev_Munich "https://github.com/casact/chainladder-python/blob/master/chainladder/development/munich.py"
    click Dev_Clark "https://github.com/casact/chainladder-python/blob/master/chainladder/development/clark.py"
    click Dev_Incr "https://github.com/casact/chainladder-python/blob/master/chainladder/development/incremental.py"
    click Dev_Out "https://github.com/casact/chainladder-python/blob/master/chainladder/development/outstanding.py"
    click Dev_Barn "https://github.com/casact/chainladder-python/blob/master/chainladder/development/barnzehn.py"
    click Dev_Const "https://github.com/casact/chainladder-python/blob/master/chainladder/development/constant.py"
    click Res_Chain "https://github.com/casact/chainladder-python/blob/master/chainladder/methods/chainladder.py"
    click Res_Mack "https://github.com/casact/chainladder-python/blob/master/chainladder/methods/mack.py"
    click Res_Benkt "https://github.com/casact/chainladder-python/blob/master/chainladder/methods/benktander.py"
    click Res_Born "https://github.com/casact/chainladder-python/blob/master/chainladder/methods/bornferg.py"
    click Res_Cape "https://github.com/casact/chainladder-python/blob/master/chainladder/methods/capecod.py"
    click Res_ExpLoss "https://github.com/casact/chainladder-python/blob/master/chainladder/methods/expectedloss.py"
    click Tail_Exp "https://github.com/casact/chainladder-python/blob/master/chainladder/tails/exponential.py"
    click Tail_Bond "https://github.com/casact/chainladder-python/blob/master/chainladder/tails/bondy.py"
    click Tail_ConstTail "https://github.com/casact/chainladder-python/blob/master/chainladder/tails/constant.py"
    click Tail_Curve "https://github.com/casact/chainladder-python/blob/master/chainladder/tails/curve.py"
    click WF_Grid "https://github.com/casact/chainladder-python/blob/master/chainladder/workflow/gridsearch.py"
    click WF_Vote "https://github.com/casact/chainladder-python/blob/master/chainladder/workflow/voting.py"
    click Util_Dask "https://github.com/casact/chainladder-python/blob/master/chainladder/utils/dask.py"
    click Util_Cupy "https://github.com/casact/chainladder-python/blob/master/chainladder/utils/cupy.py"
    click Util_Sparse "https://github.com/casact/chainladder-python/blob/master/chainladder/utils/sparse.py"
    click Util_Weight "https://github.com/casact/chainladder-python/blob/master/chainladder/utils/weighted_regression.py"
    click Util_Help "https://github.com/casact/chainladder-python/blob/master/chainladder/utils/utility_functions.py"
    click Util_Data "https://github.com/casact/chainladder-python/tree/master/chainladder/utils/data/"
    click Supp_Bench "https://github.com/casact/chainladder-python/blob/master/benchmarks/benchmarks.py"
    click Supp_CI "https://github.com/casact/chainladder-python/blob/master/.github/workflows/pytest.yml"
    click Supp_Docs "https://github.com/casact/chainladder-python/tree/master/docs/"

    %% Styles
    classDef core fill:#bbdefb,stroke:#1976d2,color:#000;
    classDef alg fill:#c8e6c9,stroke:#388e3c,color:#000;
    classDef workflow fill:#ffe0b2,stroke:#f57c00,color:#000;
    classDef util fill:#e0e0e0,stroke:#757575,color:#000;
    classDef external fill:#f5f5f5,stroke:#9e9e9e,color:#000;
    classDef support fill:#d1c4e9,stroke:#7e57c2,color:#000;
```
