# atrackcs/atrackcs architecture

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

- Interactive diagram: https://gitdiagram.com/atrackcs/atrackcs
- Repository: https://github.com/atrackcs/atrackcs

## Overview

##### Project Type and Purpose
- ATRACKCS is a Python scientific library (and CLI tool) for automated detection and tracking of Mesoscale Convective Systems (MCS) using satellite netCDF data.
- It exposes core functions for ingestion, detection, tracking, and summary, plus Jupyter notebooks for demonstration.

##### File Structure and Architectural Clues
- atrackcs/
- config.py – parameter container (ATRACKCSConfig)
- .py – “read_identify_mcs_parallel” detection pipeline
- tracking.py – “finder_msc” tracking engine
- features.py – “resume_track” summary and feature computation
- setup.py – packaging & install
- atrackcs_env.yml – conda environment
- notebooks/ – Example_ATRACKCS.ipynb, Plot_ATRACKCS.ipynb
- test/WA/{tb,p}/ – sample netCDF inputs (Brightness Temp, Precip)
- test/Results – sample outputs (.pkl, CSV, Figures)
- repo/ – static figures for README

##### Key Components and Responsibilities
A. Data Ingestion Layer
- Reads netCDF4 Tb and P files (xarray + rioxarray)
- Reprojects / resamples to uniform grid and 1-hr time steps
B. Detection Engine
- Module: atrackcs.identify.read_identify_mcs_parallel
- Thresholding (Tb ≤ TB_VALUE), convex hull (shapely), area & precipitation filters (geopandas)
- Parallelized over time slices using multiprocessing
- Output: intermediate storm candidates in a .pkl file
C. Tracking Engine
- Module: atrackcs.tracking.finder_msc
- Overlap‐based linking of polygons between t and t+1
- Enforces one‐to‐one matching, terminates tracks when no overlap
- Parallelized per‐storm or per‐time‐chunk
- Output: in‐memory tracked storm objects
D. Feature & Summary Computation
- Module: atrackcs.features.resume_track
- Computes geometry, area_tb, tb_overshoot, precipitation flags, kinematics (centroids, velocity), durations
- Filters by minimum duration, writes summary CSV to path_results
E. Presentation and Verification
- notebooks/
- Example_ATRACKCS.ipynb – full pipeline demonstration
- Plot_ATRACKCS.ipynb – loading CSV outputs, mapping tracks (matplotlib, geopandas)
F. Configuration
- ATRACKCSConfig centralizes all thresholds and parameters (TB_VALUE, AREA_VALUE, DURATION, etc.)
G. External Dependencies
- geopandas, shapely, xarray, rioxarray, pandas, numpy, multiprocessing

##### Data Flow and Interactions
Raw netCDF Data (tb, p)
↓
[Data Ingestion] → xarray Datasets
↓
[Detection Engine (.identify)] → StormCandidates.pkl
↓
[Tracking Engine (.tracking)] → TrackedStormObjects
↓
[Feature Computation (.features)] → final_summary.csv
↓
[Visualization Notebooks] → Maps & Figures

- ATRACKCSConfig object is passed into each stage to parameterize behavior.
- Intermediate artifacts (.pkl, CSV) are persisted in path_results for reproducibility.

##### Architectural Patterns and Principles
- Pipeline Pattern: linear sequence of stages (ingest → detect → track → summarize).
- Modular Layering: each concern in its own module.
- Stateless Functions: explicit inputs/outputs, side effects only to disk.
- Configuration Injection: single config object drives all thresholds.
- Parallelism: multiprocessing in detection and tracking for scalability.

## Diagram (Mermaid)

```mermaid
flowchart TB
    DataSources["Public Satellite Data<br/>IMERG, CPC"]:::external

    TB["Sample TB Inputs<br/>test/WA/tb/"]:::data
    P["Sample P Inputs<br/>test/WA/p/"]:::data

    DataSources --> Ingestion
    TB --> Ingestion
    P --> Ingestion

    subgraph "ATRACKCS Python Package"
        direction TB
        Ingestion["atrackcs.identify<br/>Data Ingestion"]:::core
        click Ingestion "https://github.com/atrackcs/atrackcs/blob/main/atrackcs/identify.py"

        Config["ATRACKCSConfig"]:::core
        click Config "https://github.com/atrackcs/atrackcs/blob/main/atrackcs/config.py"

        subgraph "Multiprocessing Pool"
            direction TB
            Detection["read_identify_mcs_parallel<br/>(Detection)"]:::core
            click Detection "https://github.com/atrackcs/atrackcs/blob/main/atrackcs/identify.py"
            Tracking["finder_msc<br/>(Tracking)"]:::core
            click Tracking "https://github.com/atrackcs/atrackcs/blob/main/atrackcs/tracking.py"
        end

        Feature["resume_track<br/>(Feature & Summary)"]:::core
        click Feature "https://github.com/atrackcs/atrackcs/blob/main/atrackcs/features.py"
    end

    Ingestion -->|"netCDF4 → xarray Dataset"| Detection
    Detection -->|"StormCandidates.pkl"| PKL
    PKL["StormCandidates.pkl<br/>test/Results/"]:::data
    click PKL "https://github.com/atrackcs/atrackcs/tree/main/test/Results/"
    PKL --> Tracking
    Tracking --> Feature
    Feature -->|"final_summary.csv"| CSV
    CSV["final_summary.csv<br/>test/Results/"]:::data
    click CSV "https://github.com/atrackcs/atrackcs/tree/main/test/Results/"

    CSV --> Notebook1
    CSV --> Notebook2

    Notebook1["Example_ATRACKCS.ipynb"]:::ui
    click Notebook1 "https://github.com/atrackcs/atrackcs/blob/main/notebooks/Example_ATRACKCS.ipynb"
    Notebook2["Plot_ATRACKCS.ipynb"]:::ui
    click Notebook2 "https://github.com/atrackcs/atrackcs/blob/main/notebooks/Plot_ATRACKCS.ipynb"

    CLI["setup.py CLI & Packaging"]:::external
    click CLI "https://github.com/atrackcs/atrackcs/blob/main/setup.py"
    Env["atrackcs_env.yml"]:::external
    click Env "https://github.com/atrackcs/atrackcs/blob/main/atrackcs_env.yml"

    classDef core fill:#cce5ff,stroke:#333,stroke-width:1px;
    classDef data fill:#d4edda,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5;
    classDef ui fill:#ffe5b4,stroke:#333,stroke-width:1px;
    classDef external fill:#e2e3e5,stroke:#333,stroke-width:1px;

    subgraph Legend
        direction LR
        A["Core Modules"]:::core
        B["Data Stores"]:::data
        C["Notebooks / UI"]:::ui
        D["External"]:::external
    end
```
