How atrackcs/atrackcs works
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.