# yeh-tc/python_project-thermal_displacement architecture

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

- Interactive diagram: https://gitdiagram.com/yeh-tc/python_project-thermal_displacement
- Repository: https://github.com/yeh-tc/python_project-thermal_displacement

## Overview

##### Project type and purpose
- This is a scientific data-processing pipeline implemented in Python.
- Its goal is to calculate “thermal displacement by marine heatwaves” using NOAA OISST (sea-surface temperature) data.

##### File structure
Top-level Python scripts correspond to discrete pipeline stages:
- 00_download_data.py – Ingest raw OISST data from NOAA
- 01_calculate_monthly_average.py – Compute monthly climatology
- apply_oisst_masks.py – Apply spatial masks (land/sea, regions)
- 02_make_mask.py – Create custom masks (e.g., marine heatwave domains)
- 03_calculate_an.py – Calculate anomalies relative to climatology
- 04_defineheatwaves.py – Identify marine heatwave events
- update_monthly.py – Update monthly summaries with new data
- 05_oisst_distance.py – Compute distance metrics from heatwave centroids
- 06_thermal_displacement.py – Derive final thermal displacement statistics
Configuration occurs implicitly via script defaults or command-line arguments; there are no separate config files.

##### Key insights from the README
- Data source: daily OISST v2.1 from NOAA
- Methodology follows Jacox et al. (2020)
- Pure Python implementation (likely uses xarray, numpy, netCDF4 under the hood)

a. Main components
- External Data Source (NOAA OISST)
- Ingestion Module
- Preprocessing Module
- Analysis Module
- Computation Module
- Data Store (intermediate NetCDF/CSV outputs)
- Final Output / Reporting

b. Relationships & data flow
1. External Data Source → (00_download_data.py) → Raw Data Store
2. Raw Data Store → (01_calculate_monthly_average.py) → Climatology Store
3. Raw Data Store + Climatology Store → (apply_oisst_masks.py & 02_make_mask.py) → Masked Data Store
4. Masked Data Store + Climatology Store → (03_calculate_an.py) → Anomaly Store
5. Anomaly Store → (04_defineheatwaves.py) → Heatwave Event Store
6. Heatwave Event Store → (05_oisst_distance.py) → Distance Metrics Store
7. Distance Metrics Store → (06_thermal_displacement.py) → Final Results

c. Architectural patterns & design principles
- Pipeline pattern: each script is a stage that reads inputs and emits outputs
- Single responsibility per script (modularity)
- Stateless processing: each stage writes to disk and can be re-run independently
- Data provenance: intermediate files document each step

d. Technologies & libraries
- Python 3.x
- xarray / netCDF4 for multi-dimensional data
- numpy / pandas for array and tabular operations
- Possible use of Dask for parallelization (if data volumes demand it)

##### Final advice
- Every script as its own component to reflect the pipeline’s modularity.
- Intermediate data stores clearly; these are critical for reproducing results.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Source
    ExternalData["NOAA OISST"]:::external

    %% Ingestion
    Download["00_download_data.py\nDownload OISST"]:::ingestion
    RawStore[(Raw Data Store .nc)]:::datastore

    %% Preprocessing: Monthly Climatology
    MonthlyAvg["01_calculate_monthly_average.py\nCompute Monthly Climatology"]:::ingestion
    ClimatologyStore[(Climatology Store .nc)]:::datastore

    %% Preprocessing: Spatial Masks
    ApplyMask["apply_oisst_masks.py\nApply Spatial Masks"]:::ingestion
    MakeMask["02_make_mask.py\nCreate Custom Masks"]:::ingestion
    MaskedStore[(Masked Data Store .nc)]:::datastore

    %% Analysis: Anomaly Calculation
    AnomalyCalc["03_calculate_an.py\nCalculate Anomalies"]:::analysis
    AnomalyStore[(Anomaly Store .nc)]:::datastore

    %% Computation: Heatwave Identification
    DefineHW["04_defineheatwaves.py\nDefine Heatwaves"]:::analysis
    HWStore[(Heatwave Event Store .nc)]:::datastore

    %% Computation: Distance Metrics
    DistanceCalc["05_oisst_distance.py\nCompute Distance Metrics"]:::analysis
    DistanceStore[(Distance Metrics Store .nc/.csv)]:::datastore

    %% Computation: Thermal Displacement
    Displacement["06_thermal_displacement.py\nThermal Displacement Stats"]:::analysis
    FinalResults[(Final Results .csv)]:::datastore

    %% Auxiliary Update
    UpdateMonthly["update_monthly.py\nIncremental Monthly Updates"]:::aux
    README["README.md"]:::aux

    %% Data Flow
    ExternalData -->|".nc"| Download
    Download -->|".nc"| RawStore
    RawStore -->|".nc"| MonthlyAvg
    MonthlyAvg -->|".nc"| ClimatologyStore
    RawStore -->|".nc"| ApplyMask
    ClimatologyStore --> ApplyMask
    ApplyMask --> MaskedStore
    ClimatologyStore --> MakeMask
    MakeMask --> MaskedStore
    MaskedStore -->|".nc"| AnomalyCalc
    AnomalyCalc -->|".nc"| AnomalyStore
    AnomalyStore -->|".nc"| DefineHW
    DefineHW -->|".nc"| HWStore
    HWStore -->|".nc"| DistanceCalc
    DistanceCalc -->|".csv"| DistanceStore
    DistanceStore -->|".csv"| Displacement
    Displacement -->|".csv"| FinalResults

    %% Auxiliary Flow
    RawStore -->|".nc"| UpdateMonthly
    UpdateMonthly -->|".nc"| ClimatologyStore

    %% Documentation
    ExternalData --- README

    %% Click Events
    click Download "https://github.com/yeh-tc/python_project-thermal_displacement/blob/main/00_download_data.py"
    click MonthlyAvg "https://github.com/yeh-tc/python_project-thermal_displacement/blob/main/01_calculate_monthly_average.py"
    click ApplyMask "https://github.com/yeh-tc/python_project-thermal_displacement/blob/main/apply_oisst_masks.py"
    click MakeMask "https://github.com/yeh-tc/python_project-thermal_displacement/blob/main/02_make_mask.py"
    click AnomalyCalc "https://github.com/yeh-tc/python_project-thermal_displacement/blob/main/03_calculate_an.py"
    click DefineHW "https://github.com/yeh-tc/python_project-thermal_displacement/blob/main/04_defineheatwaves.py"
    click DistanceCalc "https://github.com/yeh-tc/python_project-thermal_displacement/blob/main/05_oisst_distance.py"
    click Displacement "https://github.com/yeh-tc/python_project-thermal_displacement/blob/main/06_thermal_displacement.py"
    click UpdateMonthly "https://github.com/yeh-tc/python_project-thermal_displacement/blob/main/update_monthly.py"
    click README "https://github.com/yeh-tc/python_project-thermal_displacement/blob/main/README.md"

    %% Styles
    classDef external fill:#ffe082,stroke:#bf360c,color:#000
    classDef ingestion fill:#81d4fa,stroke:#0277bd,color:#000
    classDef analysis fill:#a5d6a7,stroke:#1b5e20,color:#000
    classDef datastore fill:#e0e0e0,stroke:#424242,color:#000
    classDef aux fill:#ffcc80,stroke:#e65100,color:#000
```
