# ksanjivy/swac_global_potential_dataset architecture

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

- Interactive diagram: https://gitdiagram.com/ksanjivy/swac_global_potential_dataset
- Repository: https://github.com/ksanjivy/swac_global_potential_dataset

## Overview

This repo is **not an online service**; it’s a **reproducible geospatial data-processing + publication dataset** for assessing **SWAC (Sea Water Air Conditioning) potential** globally.

Its core purpose/pipeline:
1. Start from **input climatology** (NetCDF seawater temperature; plus UTCI heat-stress dataset).
2. Derive **isotherm depth grids** for intake temperature thresholds (MATLAB `.mat` matrices).
3. Combine those depths with **cross‑shore bathymetric profiles** to compute **pipeline length** from coastal points to reach target isotherm depths (TXT outputs).

##### What the file tree tells you about architecture
Top-level directories map cleanly to pipeline stages and published artifacts:

- `climatology/` — **inputs** (NetCDF)
- `seawater_intake_depth/` — **derived intermediate products** (MATLAB `.mat` isotherm depth matrices)
- `bathymetric_profile/` — **inputs** for distance computation (TXT profiles split in parts)
- `pipeline_length/` — **derived outputs** per temperature (TXT per threshold)
- `metrics/` — **aggregations** (CSV summaries)
- `maps/` — **visualization outputs** grouped by region (world/us/europe/asia)
- `scripts/` — **processing & plotting implementation** (MATLAB + Python), relative-path execution

This structure implies a *batch/offline* workflow with **repeatable regeneration** of all outputs if the large data files are present (downloaded from Zenodo).

##### Zenodo archive download
→ extracted into local repo directories (climatology, bathymetric_profile, etc.)

##### `climatology/seawater_temperature_climatology_2000_2020.nc`
→ (MATLAB) `compute_seawater_isotherm_depth.m`
→ `seawater_intake_depth/iso_<T>_matrix.mat` for each T

3. `seawater_intake_depth/iso_<T>_matrix.mat` + `bathymetric_profile/bathymetric_profiles_part*.txt`
→ (MATLAB) `compute_swac_pipeline_length.m` (+ `haversine.m`)
→ `pipeline_length/pipeline_length_<T>.txt`

##### `pipeline_length/pipeline_length_<T>.txt` (for all T)
→ (MATLAB) `compute_swac_metrics.m`
→ `metrics/swac_*_summary.csv`

→ (Python) `plot_world_map.py`, `plot_zoom_maps.py`
→ `maps/<region>/*_map_<T>.png`

##### `maps/<region>/*_map_<T>.png` series
→ (Python) `generate_all_gifs.py`
→ `maps/<region>/*_map_all.gif`

*parameterization dimension*:
- A loop/iteration marker: “For each intake temperature threshold T (5.0–15.0 step 0.5)”.

##### Architectural patterns / design principles to call out
- **Offline batch pipeline** (file-based interfaces between stages)
- **Deterministic, reproducible processing** (relative paths; fixed naming conventions)
- **Artifact versioning by filename convention** (`<T>` encoded with one decimal)
- **Separation of concerns**:
- MATLAB for numeric/geo computations
- Python for visualization/automation of map products
- **Dataset publication workflow** (raw inputs → derived products → aggregated metrics → figures)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% =========================
    %% External / Upstream
    %% =========================
    ZENODO(("ZenodoArchive<br/>(large_files_not_in_git)")):::external
    OCEAN(("OceanTempClimatology<br/>2000-2020")):::external
    ERA5(("ERA5-HEAT_UTCI<br/>(context_dataset)")):::external

    %% =========================
    %% Local Repo + Docs
    %% =========================
    README["README.md<br/>(reproducible_pipeline_docs)"]:::doc

    subgraph "LocalRepository(offline_file_based_pipeline)"
        direction TB

        NOTE["Notes<br/>-Run_scripts_from_scripts/<br/>-Relative_paths_assumed<br/>-T_in_[5.0,15.0]_step_0.5<br/>-Artifacts_keyed_by_<T>"]:::note

        subgraph "Inputs"
            direction TB
            CLIM[(climatology/<br/>NetCDF_inputs)]:::input
            CLIMDOC["climatology/README.md"]:::doc

            BATHY[(bathymetric_profile/<br/>TXT_profiles_part*.txt)]:::input
            BATHYDOC["bathymetric_profile/README.md"]:::doc
        end

        subgraph "Stage1_IsothermDepth(MATLAB)"
            direction TB
            ISO_SCRIPT["compute_seawater_isotherm_depth.m"]:::script
            ISO_STORE[(seawater_intake_depth/<br/>iso_<T>_matrix.mat)]:::intermediate
            ISODOC["seawater_intake_depth/README.md"]:::doc
        end

        subgraph "Stage2_PipelineLength(MATLAB)"
            direction TB
            PL_SCRIPT["compute_swac_pipeline_length.m"]:::script
            HAV["haversine.m<br/>(geodesic_helper)"]:::script
            PL_STORE[(pipeline_length/<br/>pipeline_length_<T>.txt)]:::derived
            PLDOC["pipeline_length/README.md"]:::doc
        end

        subgraph "Stage3_Metrics(MATLAB)"
            direction TB
            MET_SCRIPT["compute_swac_metrics.m"]:::script
            MET_STORE[(metrics/<br/>CSV_summaries)]:::metrics
            METDOC["metrics/README.md"]:::doc
            MET1["swac_metrics_summary.csv"]:::metrics
            MET2["swac_coastal_points_summary.csv"]:::metrics
        end

        subgraph "Stage4_Maps(Python)"
            direction TB
            WORLD_PLOT["plot_world_map.py"]:::script
            ZOOM_PLOT["plot_zoom_maps.py"]:::script

            subgraph "MapsOutputs"
                direction TB
                MAPS[(maps/)]:::viz
                WORLD[(maps/world/)]:::viz
                US[(maps/us/)]:::viz
                EUR[(maps/europe/)]:::viz
                ASIA[(maps/asia/)]:::viz
            end

            GIF_SCRIPT["generate_all_gifs.py"]:::script
            GIFS[(maps/<region>/<br/>*_map_all.gif)]:::viz
        end
    end

    SCRIPTS_DOC["scripts/README.md<br/>(execution_notes)"]:::doc

    %% =========================
    %% Dataflow
    %% =========================
    ZENODO -->|"download_and_extract"| CLIM
    ZENODO -->|"download_and_extract"| BATHY
    ZENODO -->|"download_and_extract"| MAPS

    OCEAN -->|"source_of"| CLIM
    ERA5 -->|"optional_context_for"| MET_SCRIPT

    README -->|"describes_workflow"| NOTE
    SCRIPTS_DOC -->|"run_from_scripts/"| NOTE
    CLIMDOC -->|"documents_inputs"| CLIM
    BATHYDOC -->|"documents_inputs"| BATHY

    CLIM -->|"NetCDF(.nc)"| ISO_SCRIPT
    ISO_SCRIPT -->|"MATLAB_output:iso_<T>_matrix.mat"| ISO_STORE
    ISODOC -->|"documents_products"| ISO_STORE

    ISO_STORE -->|"MAT(.mat)"| PL_SCRIPT
    BATHY -->|"TXT_profiles_part*.txt"| PL_SCRIPT
    HAV -->|"helper_used_by"| PL_SCRIPT
    PL_SCRIPT -->|"TXT_output:pipeline_length_<T>.txt"| PL_STORE
    PLDOC -->|"documents_outputs"| PL_STORE

    PL_STORE -->|"all_T_series"| MET_SCRIPT
    MET_SCRIPT -->|"CSV_outputs"| MET_STORE
    MET_STORE -->|"includes"| MET1
    MET_STORE -->|"includes"| MET2
    METDOC -->|"documents_tables"| MET_STORE

    PL_STORE -->|"pipeline_length_<T>.txt"| WORLD_PLOT
    PL_STORE -->|"pipeline_length_<T>.txt"| ZOOM_PLOT
    WORLD_PLOT -->|"PNG:*_map_<T>.png"| WORLD
    ZOOM_PLOT -->|"PNG:*_map_<T>.png"| US
    ZOOM_PLOT -->|"PNG:*_map_<T>.png"| EUR
    ZOOM_PLOT -->|"PNG:*_map_<T>.png"| ASIA

    WORLD -->|"png_series_for_all_T"| GIF_SCRIPT
    US -->|"png_series_for_all_T"| GIF_SCRIPT
    EUR -->|"png_series_for_all_T"| GIF_SCRIPT
    ASIA -->|"png_series_for_all_T"| GIF_SCRIPT
    GIF_SCRIPT -->|"GIF_output:*_map_all.gif"| GIFS

    %% =========================
    %% Click events (component_mapping)
    %% =========================
    click README "https://github.com/ksanjivy/swac_global_potential_dataset/blob/main/README.md"
    click CLIM "https://github.com/ksanjivy/swac_global_potential_dataset/tree/main/climatology/"
    click CLIMDOC "https://github.com/ksanjivy/swac_global_potential_dataset/blob/main/climatology/README.md"
    click BATHY "https://github.com/ksanjivy/swac_global_potential_dataset/tree/main/bathymetric_profile/"
    click BATHYDOC "https://github.com/ksanjivy/swac_global_potential_dataset/blob/main/bathymetric_profile/README.md"
    click ISO_SCRIPT "https://github.com/ksanjivy/swac_global_potential_dataset/blob/main/scripts/compute_seawater_isotherm_depth.m"
    click ISO_STORE "https://github.com/ksanjivy/swac_global_potential_dataset/tree/main/seawater_intake_depth/"
    click ISODOC "https://github.com/ksanjivy/swac_global_potential_dataset/blob/main/seawater_intake_depth/README.md"
    click PL_SCRIPT "https://github.com/ksanjivy/swac_global_potential_dataset/blob/main/scripts/compute_swac_pipeline_length.m"
    click HAV "https://github.com/ksanjivy/swac_global_potential_dataset/blob/main/scripts/haversine.m"
    click PL_STORE "https://github.com/ksanjivy/swac_global_potential_dataset/tree/main/pipeline_length/"
    click PLDOC "https://github.com/ksanjivy/swac_global_potential_dataset/blob/main/pipeline_length/README.md"
    click MET_SCRIPT "https://github.com/ksanjivy/swac_global_potential_dataset/blob/main/scripts/compute_swac_metrics.m"
    click MET_STORE "https://github.com/ksanjivy/swac_global_potential_dataset/tree/main/metrics/"
    click MET1 "https://github.com/ksanjivy/swac_global_potential_dataset/blob/main/metrics/swac_metrics_summary.csv"
    click MET2 "https://github.com/ksanjivy/swac_global_potential_dataset/blob/main/metrics/swac_coastal_points_summary.csv"
    click METDOC "https://github.com/ksanjivy/swac_global_potential_dataset/blob/main/metrics/README.md"
    click WORLD_PLOT "https://github.com/ksanjivy/swac_global_potential_dataset/blob/main/scripts/plot_world_map.py"
    click ZOOM_PLOT "https://github.com/ksanjivy/swac_global_potential_dataset/blob/main/scripts/plot_zoom_maps.py"
    click MAPS "https://github.com/ksanjivy/swac_global_potential_dataset/tree/main/maps/"
    click WORLD "https://github.com/ksanjivy/swac_global_potential_dataset/tree/main/maps/world/"
    click US "https://github.com/ksanjivy/swac_global_potential_dataset/tree/main/maps/us/"
    click EUR "https://github.com/ksanjivy/swac_global_potential_dataset/tree/main/maps/europe/"
    click ASIA "https://github.com/ksanjivy/swac_global_potential_dataset/tree/main/maps/asia/"
    click GIF_SCRIPT "https://github.com/ksanjivy/swac_global_potential_dataset/blob/main/scripts/generate_all_gifs.py"
    click SCRIPTS_DOC "https://github.com/ksanjivy/swac_global_potential_dataset/blob/main/scripts/README.md"

    %% =========================
    %% Styles (color-coded)
    %% =========================
    classDef external fill:#e6f2ff,stroke:#2b6cb0,stroke-width:1.5px,color:#0b2545
    classDef input fill:#dbeafe,stroke:#1d4ed8,stroke-width:1.5px,color:#0b2545
    classDef intermediate fill:#efe7ff,stroke:#6d28d9,stroke-width:1.5px,color:#2a0a4a
    classDef derived fill:#ffedd5,stroke:#c2410c,stroke-width:1.5px,color:#3b1d0b
    classDef metrics fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#052e16
    classDef viz fill:#ffe4e6,stroke:#be123c,stroke-width:1.5px,color:#4a0b1b
    classDef script fill:#e5e7eb,stroke:#374151,stroke-width:1.5px,color:#111827
    classDef doc fill:#fff7ed,stroke:#9a3412,stroke-width:1.5px,color:#431407
    classDef note fill:#fef9c3,stroke:#a16207,stroke-width:1.5px,color:#422006
```
