# iamconsortium/pyam architecture

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

- Interactive diagram: https://gitdiagram.com/iamconsortium/pyam
- Repository: https://github.com/iamconsortium/pyam

## Overview

##### Main Components and Architecture

a) Core Framework Layer:
- IamDataFrame (core data structure)
- Data Processing Engine
- Validation System

b) Input/Output Layer:
- Data Readers (IAMC template, Excel, CSV)
- Database Connectors (IIASA, World Bank, UNFCCC)
- NetCDF Handler

c) Analysis Layer:
- Computation Module
- Statistical Operations
- Time Series Processing
- Aggregation Engine

d) Visualization Layer:
- Plotting Engine
- Figure Generation
- Style Management

##### Component Relationships

**[Data Sources] → [I/O Layer] → [Core Framework] ↔ [Analysis Layer]**
- ↓
- [Visualization Layer]

##### Detailed Component Breakdown

a) Data Processing Components (Rectangle):
- Data validation (pyam/validation.py)
- Time series operations (pyam/timeseries.py)
- Computing functions (pyam/compute.py)

b) Interface Components (Hexagon):
- IIASA database connector (pyam/iiasa.py)
- World Bank connector (pyam/worldbank.py)
- UNFCCC connector (pyam/unfccc.py)

c) Visualization Components (Oval):
- Plotting functions (pyam/plotting.py)
- Figure generation (pyam/figures.py)
- Style management (pyam/_style.py)

##### Implementation Details

Technical aspects:

a) Core Dependencies:
- Pandas for data manipulation
- Matplotlib for visualization
- NumPy for numerical operations

b) Extension Points:
- Custom data formats
- Plugin system for new analyses
- Visualization customization

##### Notes for Implementation

- Maintain a clear hierarchy of components
- Data flow between modules
- Extension points
- Version compatibility (Python ≥3.10,<3.14)
- External integrations

This architecture emphasizes pyam's role as a scientific computing tool with strong data processing and visualization capabilities, while maintaining extensibility for different data formats and analysis methods.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Styles and classes
    classDef core fill:#e1f5fe,stroke:#01579b
    classDef io fill:#fff3e0,stroke:#ff6f00
    classDef analysis fill:#f3e5f5,stroke:#7b1fa2
    classDef viz fill:#e8f5e9,stroke:#2e7d32
    classDef data fill:#fbe9e7,stroke:#bf360c
    classDef external fill:#f5f5f5,stroke:#424242

    %% Legend
    subgraph Legend
        L1[Core Components]:::core
        L2[I/O Components]:::io
        L3[Analysis Components]:::analysis
        L4[Visualization Components]:::viz
        L5[Data Processing]:::data
    end

    %% Core Framework Layer
    subgraph CoreFramework
        IamDF["IamDataFrame"]:::core
        Validation["Validation System"]:::core
        DataProc["Data Processing Engine"]:::core
    end

    %% I/O Layer
    subgraph IOLayer
        IIASA["IIASA Connector"]:::io
        WorldBank["World Bank Connector"]:::io
        UNFCCC["UNFCCC Connector"]:::io
        NetCDF["NetCDF Handler"]:::io
    end

    %% Analysis Layer
    subgraph AnalysisLayer
        Compute["Computation Module"]:::analysis
        Stats["Statistical Operations"]:::analysis
        TimeSeries["Time Series Processing"]:::analysis
        Aggregation["Aggregation Engine"]:::analysis
    end

    %% Visualization Layer
    subgraph VizLayer
        Plot["Plotting Engine"]:::viz
        Figures["Figure Generation"]:::viz
        Style["Style Management"]:::viz
    end

    %% Data Processing Components
    subgraph DataProcessing
        Filter["Data Filtering"]:::data
        Units["Unit Handling"]:::data
        Index["Index Management"]:::data
        Ops["Operations Handler"]:::data
    end

    %% External Dependencies
    subgraph Dependencies
        Pandas["Pandas"]:::external
        Matplotlib["Matplotlib"]:::external
        Numpy["NumPy"]:::external
    end

    %% Relationships
    IOLayer --> CoreFramework
    CoreFramework <--> AnalysisLayer
    CoreFramework --> VizLayer
    DataProcessing --> CoreFramework
    Dependencies --> CoreFramework

    %% Click events
    click IamDF "https://github.com/IAMconsortium/pyam/blob/main/pyam/core.py"
    click Validation "https://github.com/IAMconsortium/pyam/blob/main/pyam/validation.py"
    click IIASA "https://github.com/IAMconsortium/pyam/blob/main/pyam/iiasa.py"
    click WorldBank "https://github.com/IAMconsortium/pyam/blob/main/pyam/worldbank.py"
    click UNFCCC "https://github.com/IAMconsortium/pyam/blob/main/pyam/unfccc.py"
    click NetCDF "https://github.com/IAMconsortium/pyam/blob/main/pyam/netcdf.py"
    click Compute "https://github.com/IAMconsortium/pyam/blob/main/pyam/compute.py"
    click Stats "https://github.com/IAMconsortium/pyam/blob/main/pyam/statistics.py"
    click TimeSeries "https://github.com/IAMconsortium/pyam/blob/main/pyam/timeseries.py"
    click Aggregation "https://github.com/IAMconsortium/pyam/blob/main/pyam/aggregation.py"
    click Plot "https://github.com/IAMconsortium/pyam/blob/main/pyam/plotting.py"
    click Figures "https://github.com/IAMconsortium/pyam/blob/main/pyam/figures.py"
    click Style "https://github.com/IAMconsortium/pyam/blob/main/pyam/_style.py"
    click Filter "https://github.com/IAMconsortium/pyam/blob/main/pyam/filter.py"
    click Units "https://github.com/IAMconsortium/pyam/blob/main/pyam/units.py"
    click Index "https://github.com/IAMconsortium/pyam/blob/main/pyam/index.py"
    click Ops "https://github.com/IAMconsortium/pyam/blob/main/pyam/_ops.py"
```
