# wateraccounting/waporwa architecture

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

- Interactive diagram: https://gitdiagram.com/wateraccounting/waporwa
- Repository: https://github.com/wateraccounting/waporwa

## Overview

This repository supports rapid WaPOR-based water accounting across five river basins. The principal workflow is to retrieve time- and area-selected WaPOR data, prepare raster inputs, then create NetCDF and GRACE storage-change inputs, run the soil-moisture-balance model, and calculate water-accounting sheet fluxes. The README describes the notebook workflow; its detailed notebook-to-module calls are not shown in the sampled source, so those links are marked unverified. The sampled downloader code does show API retrieval, raster correction, and GIS helper use.

Main entry points: [`modules/WaPOR/AET_dekadal.py`](https://github.com/wateraccounting/waporwa/blob/master/modules/WaPOR/AET_dekadal.py) (Period raster downloads), [`notebooks/0_Collect_Prepare_data.ipynb`](https://github.com/wateraccounting/waporwa/blob/master/notebooks/0_Collect_Prepare_data.ipynb) (Collect and prepare), [`notebooks/2_GRACE_dS.ipynb`](https://github.com/wateraccounting/waporwa/blob/master/notebooks/2_GRACE_dS.ipynb) (GRACE storage change), [`notebooks/1_Create_NetCDF.ipynb`](https://github.com/wateraccounting/waporwa/blob/master/notebooks/1_Create_NetCDF.ipynb) (Create NetCDF)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Analysis workflow"]
  node_collect["Collect and prepare"]
  node_netcdf["Create NetCDF"]
  node_grace_nb["GRACE storage change<br/>[2_GRACE_dS.ipynb]"]
  node_run_model["Run SM balance"]
  node_sheet_nb["Calculate sheet fluxes"]
end

subgraph group_download["WaPOR data access"]
  node_wa_api["WaPOR API client<br/>[WaporAPI.py]"]
  node_period_downloads["Period raster downloads<br/>[AET_dekadal.py]"]
  node_other_downloads["Other WaPOR products"]
  node_progress["Progress display<br/>[WaitbarConsole.py]"]
end

subgraph group_prepare["Input preparation"]
  node_raster_gis["Raster GIS tools<br/>[GIS_functions.py]"]
  node_wa_gis["Water-accounting GIS<br/>[GIS_functions.py]"]
  node_rasterize["Rasterize basin shapes"]
  node_landcover["Land-cover mapping<br/>[LCC_to_LUWA.py]"]
  node_netcdf_create["NetCDF creation<br/>[create_NC.py]"]
  node_grace["GRACE dS processing<br/>[dS_from_grace.py]"]
  node_grace_nc["GRACE NetCDF processing"]
  node_basin_data["Basin data files<br/>[pickle_basin.py]"]
end

subgraph group_account["Water accounting"]
  node_balance["SM balance model<br/>[model_SMBalance.py]"]
  node_sheet["Sheet 1 fluxes<br/>[sheet1.py]"]
  node_average["Average by land use<br/>[average_by_LU.py]"]
end

node_analyst(("Analyst"))
node_api_service{{"WaPOR API service"}}

node_analyst -->|"starts"| node_collect
node_collect -.->|"prepares for"| node_netcdf
node_netcdf -.->|"prepares for"| node_grace_nb
node_grace_nb -.->|"prepares for"| node_run_model
node_run_model -.->|"prepares for"| node_sheet_nb
node_collect -.->|"uses"| node_period_downloads
node_period_downloads -->|"queries"| node_wa_api
node_period_downloads -->|"downloads from"| node_api_service
node_wa_api -->|"sends requests"| node_api_service
node_period_downloads -->|"corrects rasters"| node_raster_gis
node_period_downloads -->|"updates"| node_progress
node_other_downloads -.->|"queries"| node_wa_api
node_collect -.->|"may use"| node_other_downloads
node_netcdf -.->|"uses"| node_netcdf_create
node_grace_nb -.->|"uses"| node_grace
node_grace_nb -.->|"may use"| node_grace_nc
node_run_model -.->|"uses"| node_balance
node_sheet_nb -.->|"uses"| node_sheet
node_sheet -.->|"may use"| node_average
node_landcover -->|"imports"| node_rasterize
node_landcover -->|"imports"| node_wa_gis

click node_collect "https://github.com/wateraccounting/waporwa/blob/master/notebooks/0_Collect_Prepare_data.ipynb"
click node_netcdf "https://github.com/wateraccounting/waporwa/blob/master/notebooks/1_Create_NetCDF.ipynb"
click node_grace_nb "https://github.com/wateraccounting/waporwa/blob/master/notebooks/2_GRACE_dS.ipynb"
click node_run_model "https://github.com/wateraccounting/waporwa/blob/master/notebooks/3_RunSMBalance.ipynb"
click node_sheet_nb "https://github.com/wateraccounting/waporwa/blob/master/notebooks/4_calc_Sheet1_fluxes.ipynb"
click node_wa_api "https://github.com/wateraccounting/waporwa/blob/master/modules/WaPOR/WaporAPI.py"
click node_period_downloads "https://github.com/wateraccounting/waporwa/blob/master/modules/WaPOR/AET_dekadal.py"
click node_other_downloads "https://github.com/wateraccounting/waporwa/tree/master/modules/WaPOR"
click node_progress "https://github.com/wateraccounting/waporwa/blob/master/modules/WaPOR/WaitbarConsole.py"
click node_raster_gis "https://github.com/wateraccounting/waporwa/blob/master/modules/WaPOR/GIS_functions.py"
click node_wa_gis "https://github.com/wateraccounting/waporwa/blob/master/modules/WA/GIS_functions.py"
click node_rasterize "https://github.com/wateraccounting/waporwa/blob/master/modules/WA/rasterize_shapefile.py"
click node_landcover "https://github.com/wateraccounting/waporwa/blob/master/modules/WA/LCC_to_LUWA.py"
click node_netcdf_create "https://github.com/wateraccounting/waporwa/blob/master/modules/WA/create_NC.py"
click node_grace "https://github.com/wateraccounting/waporwa/blob/master/modules/WA/dS_from_grace.py"
click node_grace_nc "https://github.com/wateraccounting/waporwa/blob/master/modules/WA/dS_from_grace_nc.py"
click node_balance "https://github.com/wateraccounting/waporwa/blob/master/modules/WA/model_SMBalance.py"
click node_sheet "https://github.com/wateraccounting/waporwa/blob/master/modules/WA/sheet1.py"
click node_average "https://github.com/wateraccounting/waporwa/blob/master/modules/WA/average_by_LU.py"
click node_basin_data "https://github.com/wateraccounting/waporwa/blob/master/modules/WA/pickle_basin.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_collect,node_netcdf,node_grace_nb,node_run_model,node_sheet_nb toneBlue
class node_wa_api,node_period_downloads,node_other_downloads,node_progress toneAmber
class node_raster_gis,node_wa_gis,node_rasterize,node_landcover,node_netcdf_create,node_grace,node_grace_nc,node_basin_data,node_api_service toneMint
class node_balance,node_sheet,node_average toneRose
class node_analyst toneIndigo
```

## Components

### Analysis workflow

- [Collect and prepare](https://github.com/wateraccounting/waporwa/blob/master/notebooks/0_Collect_Prepare_data.ipynb): `notebooks/0_Collect_Prepare_data.ipynb`
- [Create NetCDF](https://github.com/wateraccounting/waporwa/blob/master/notebooks/1_Create_NetCDF.ipynb): `notebooks/1_Create_NetCDF.ipynb`
- [GRACE storage change](https://github.com/wateraccounting/waporwa/blob/master/notebooks/2_GRACE_dS.ipynb): `notebooks/2_GRACE_dS.ipynb`
- [Run SM balance](https://github.com/wateraccounting/waporwa/blob/master/notebooks/3_RunSMBalance.ipynb): `notebooks/3_RunSMBalance.ipynb`
- [Calculate sheet fluxes](https://github.com/wateraccounting/waporwa/blob/master/notebooks/4_calc_Sheet1_fluxes.ipynb): `notebooks/4_calc_Sheet1_fluxes.ipynb`

### WaPOR data access

- [WaPOR API client](https://github.com/wateraccounting/waporwa/blob/master/modules/WaPOR/WaporAPI.py): `modules/WaPOR/WaporAPI.py`
- [Period raster downloads](https://github.com/wateraccounting/waporwa/blob/master/modules/WaPOR/AET_dekadal.py): `modules/WaPOR/AET_dekadal.py`
- [Other WaPOR products](https://github.com/wateraccounting/waporwa/tree/master/modules/WaPOR): `modules/WaPOR`
- [Progress display](https://github.com/wateraccounting/waporwa/blob/master/modules/WaPOR/WaitbarConsole.py): `modules/WaPOR/WaitbarConsole.py`

### Input preparation

- [Raster GIS tools](https://github.com/wateraccounting/waporwa/blob/master/modules/WaPOR/GIS_functions.py): `modules/WaPOR/GIS_functions.py`
- [Water-accounting GIS](https://github.com/wateraccounting/waporwa/blob/master/modules/WA/GIS_functions.py): `modules/WA/GIS_functions.py`
- [Rasterize basin shapes](https://github.com/wateraccounting/waporwa/blob/master/modules/WA/rasterize_shapefile.py): `modules/WA/rasterize_shapefile.py`
- [Land-cover mapping](https://github.com/wateraccounting/waporwa/blob/master/modules/WA/LCC_to_LUWA.py): `modules/WA/LCC_to_LUWA.py`
- [NetCDF creation](https://github.com/wateraccounting/waporwa/blob/master/modules/WA/create_NC.py): `modules/WA/create_NC.py`
- [GRACE dS processing](https://github.com/wateraccounting/waporwa/blob/master/modules/WA/dS_from_grace.py): `modules/WA/dS_from_grace.py`
- [GRACE NetCDF processing](https://github.com/wateraccounting/waporwa/blob/master/modules/WA/dS_from_grace_nc.py): `modules/WA/dS_from_grace_nc.py`
- [Basin data files](https://github.com/wateraccounting/waporwa/blob/master/modules/WA/pickle_basin.py): `modules/WA/pickle_basin.py`

### Water accounting

- [SM balance model](https://github.com/wateraccounting/waporwa/blob/master/modules/WA/model_SMBalance.py): `modules/WA/model_SMBalance.py`
- [Sheet 1 fluxes](https://github.com/wateraccounting/waporwa/blob/master/modules/WA/sheet1.py): `modules/WA/sheet1.py`
- [Average by land use](https://github.com/wateraccounting/waporwa/blob/master/modules/WA/average_by_LU.py): `modules/WA/average_by_LU.py`

### Other components

- **Analyst**
- **WaPOR API service**

## Connections

- Analyst → Collect and prepare: starts (evidence: `README.md`)
- Collect and prepare → Create NetCDF: prepares for
- Create NetCDF → GRACE storage change: prepares for
- GRACE storage change → Run SM balance: prepares for
- Run SM balance → Calculate sheet fluxes: prepares for
- Collect and prepare → Period raster downloads: uses
- Period raster downloads → WaPOR API client: queries (evidence: `modules/WaPOR/AET_dekadal.py`)
- Period raster downloads → WaPOR API service: downloads from (evidence: `modules/WaPOR/AET_dekadal.py`)
- WaPOR API client → WaPOR API service: sends requests (evidence: `modules/WaPOR/WaporAPI.py`)
- Period raster downloads → Raster GIS tools: corrects rasters (evidence: `modules/WaPOR/AET_dekadal.py`)
- Period raster downloads → Progress display: updates (evidence: `modules/WaPOR/AET_dekadal.py`)
- Other WaPOR products → WaPOR API client: queries (evidence: `modules/WaPOR/__init__.py`)
- Collect and prepare → Other WaPOR products: may use
- Create NetCDF → NetCDF creation: uses
- GRACE storage change → GRACE dS processing: uses
- GRACE storage change → GRACE NetCDF processing: may use
- Run SM balance → SM balance model: uses
- Calculate sheet fluxes → Sheet 1 fluxes: uses
- Sheet 1 fluxes → Average by land use: may use
- Land-cover mapping → Rasterize basin shapes: imports (evidence: `modules/WA/LCC_to_LUWA.py`)
- Land-cover mapping → Water-accounting GIS: imports (evidence: `modules/WA/LCC_to_LUWA.py`)