# qingltc/pyrosync architecture

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

- Interactive diagram: https://gitdiagram.com/qingltc/pyrosync
- Repository: https://github.com/qingltc/pyrosync

## Overview

PyroSync is a fire-activity harmonization pipeline and Streamlit calendar. Its main workflow turns NASA FIRMS archives into filtered detections, comparable cell-day counts, calibrated MODIS-equivalent estimates, and processed tables that users explore by area and time. The map preserves both ratio and machine-learning approaches, their validation, and calendar analytics. Relationships are limited to calls and data transfers visible in excerpts or documented in the README; some app interactions and unsampled implementation details are therefore represented only at subsystem level.

Main entry points: [`scripts/build_dataset.py`](https://github.com/qingltc/pyrosync/blob/main/scripts/build_dataset.py) (Dataset pipeline), [`app.py`](https://github.com/qingltc/pyrosync/blob/main/app.py) (Streamlit calendar app), [`pyrosync/grid.py`](https://github.com/qingltc/pyrosync/blob/main/pyrosync/grid.py) (Fire cell-days), [`pyrosync/series.py`](https://github.com/qingltc/pyrosync/blob/main/pyrosync/series.py) (Area time series)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Ingestion and gridding"]
  node_settings["Pipeline settings<br/>[config.py]"]
  node_ingest_filter["Read and filter detections<br/>[io.py]"]
  node_cell_days["Fire cell-days<br/>[grid.py]"]
  node_monthly_grid["Monthly coarse grid<br/>[grid.py]"]
  node_dataset_pipeline["Dataset pipeline<br/>[build_dataset.py]"]
end

subgraph group_harmonize["Calibration and validation"]
  node_ratio_fit["Layer A ratio<br/>[calibrate.py]"]
  node_sensor_chain["NOAA-20 chain<br/>[calibrate.py]"]
  node_ml_model["Layer B model<br/>[calibrate.py]"]
  node_validation["Hold-out validation<br/>[calibrate.py]"]
end

subgraph group_data["Processed data"]
  node_processed_tables[("Processed tables")]
end

subgraph group_experience["Calendar experience"]
  node_streamlit_app["Streamlit calendar app<br/>[app.py]"]
  node_area_series["Area time series<br/>[series.py]"]
  node_calendar_analysis["Calendar and anomalies<br/>[series.py]"]
end

node_user(("Area and period user"))
node_firms["FIRMS archives"]

node_firms -->|"reads archives"| node_ingest_filter
node_dataset_pipeline -->|"loads detections"| node_ingest_filter
node_dataset_pipeline -->|"counts cell-days"| node_cell_days
node_cell_days -->|"aggregates monthly"| node_monthly_grid
node_dataset_pipeline -->|"builds grid"| node_monthly_grid
node_dataset_pipeline -->|"fits factors"| node_ratio_fit
node_dataset_pipeline -->|"applies chain"| node_sensor_chain
node_dataset_pipeline -->|"fits and predicts"| node_ml_model
node_dataset_pipeline -->|"validates methods"| node_validation
node_dataset_pipeline -->|"writes outputs"| node_processed_tables
node_user -->|"selects area"| node_streamlit_app
node_streamlit_app -->|"loads tables"| node_processed_tables
node_streamlit_app -->|"queries series"| node_area_series
node_streamlit_app -->|"shows season story"| node_calendar_analysis
node_area_series -.->|"derives calendar"| node_calendar_analysis

click node_settings "https://github.com/qingltc/pyrosync/blob/main/pyrosync/config.py"
click node_ingest_filter "https://github.com/qingltc/pyrosync/blob/main/pyrosync/io.py"
click node_cell_days "https://github.com/qingltc/pyrosync/blob/main/pyrosync/grid.py"
click node_monthly_grid "https://github.com/qingltc/pyrosync/blob/main/pyrosync/grid.py"
click node_dataset_pipeline "https://github.com/qingltc/pyrosync/blob/main/scripts/build_dataset.py"
click node_ratio_fit "https://github.com/qingltc/pyrosync/blob/main/pyrosync/calibrate.py"
click node_sensor_chain "https://github.com/qingltc/pyrosync/blob/main/pyrosync/calibrate.py"
click node_ml_model "https://github.com/qingltc/pyrosync/blob/main/pyrosync/calibrate.py"
click node_validation "https://github.com/qingltc/pyrosync/blob/main/pyrosync/calibrate.py"
click node_processed_tables "https://github.com/qingltc/pyrosync/tree/main/data/processed"
click node_streamlit_app "https://github.com/qingltc/pyrosync/blob/main/app.py"
click node_area_series "https://github.com/qingltc/pyrosync/blob/main/pyrosync/series.py"
click node_calendar_analysis "https://github.com/qingltc/pyrosync/blob/main/pyrosync/series.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_settings,node_ingest_filter,node_cell_days,node_monthly_grid,node_dataset_pipeline,node_user toneBlue
class node_ratio_fit,node_sensor_chain,node_ml_model,node_validation toneAmber
class node_processed_tables toneMint
class node_streamlit_app,node_area_series,node_calendar_analysis toneRose
class node_firms toneIndigo
```

## Components

### Ingestion and gridding

- [Pipeline settings](https://github.com/qingltc/pyrosync/blob/main/pyrosync/config.py): `pyrosync/config.py`
- [Read and filter detections](https://github.com/qingltc/pyrosync/blob/main/pyrosync/io.py): `pyrosync/io.py`
- [Fire cell-days](https://github.com/qingltc/pyrosync/blob/main/pyrosync/grid.py): `pyrosync/grid.py`
- [Monthly coarse grid](https://github.com/qingltc/pyrosync/blob/main/pyrosync/grid.py): `pyrosync/grid.py`
- [Dataset pipeline](https://github.com/qingltc/pyrosync/blob/main/scripts/build_dataset.py): `scripts/build_dataset.py`

### Calibration and validation

- [Layer A ratio](https://github.com/qingltc/pyrosync/blob/main/pyrosync/calibrate.py): `pyrosync/calibrate.py`
- [NOAA-20 chain](https://github.com/qingltc/pyrosync/blob/main/pyrosync/calibrate.py): `pyrosync/calibrate.py`
- [Layer B model](https://github.com/qingltc/pyrosync/blob/main/pyrosync/calibrate.py): `pyrosync/calibrate.py`
- [Hold-out validation](https://github.com/qingltc/pyrosync/blob/main/pyrosync/calibrate.py): `pyrosync/calibrate.py`

### Processed data

- [Processed tables](https://github.com/qingltc/pyrosync/tree/main/data/processed): `data/processed`

### Calendar experience

- [Streamlit calendar app](https://github.com/qingltc/pyrosync/blob/main/app.py): `app.py`
- [Area time series](https://github.com/qingltc/pyrosync/blob/main/pyrosync/series.py): `pyrosync/series.py`
- [Calendar and anomalies](https://github.com/qingltc/pyrosync/blob/main/pyrosync/series.py): `pyrosync/series.py`

### Other components

- **Area and period user**
- **FIRMS archives**

## Connections

- FIRMS archives → Read and filter detections: reads archives (evidence: `README.md`)
- Dataset pipeline → Read and filter detections: loads detections (evidence: `scripts/build_dataset.py`)
- Dataset pipeline → Fire cell-days: counts cell-days (evidence: `scripts/build_dataset.py`)
- Fire cell-days → Monthly coarse grid: aggregates monthly (evidence: `pyrosync/grid.py`)
- Dataset pipeline → Monthly coarse grid: builds grid (evidence: `scripts/build_dataset.py`)
- Dataset pipeline → Layer A ratio: fits factors (evidence: `scripts/build_dataset.py`)
- Dataset pipeline → NOAA-20 chain: applies chain (evidence: `scripts/build_dataset.py`)
- Dataset pipeline → Layer B model: fits and predicts (evidence: `scripts/build_dataset.py`)
- Dataset pipeline → Hold-out validation: validates methods (evidence: `scripts/build_dataset.py`)
- Dataset pipeline → Processed tables: writes outputs (evidence: `scripts/build_dataset.py`)
- Area and period user → Streamlit calendar app: selects area (evidence: `README.md`)
- Streamlit calendar app → Processed tables: loads tables (evidence: `app.py`)
- Streamlit calendar app → Area time series: queries series (evidence: `README.md`)
- Streamlit calendar app → Calendar and anomalies: shows season story (evidence: `app.py`)
- Area time series → Calendar and anomalies: derives calendar (evidence: `pyrosync/series.py`)