# urbanairproject/nwp_demo_data architecture

> Architecture diagram of the GitHub repository urbanairproject/nwp_demo_data, 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/urbanairproject/nwp_demo_data
- Repository: https://github.com/urbanairproject/nwp_demo_data

## Overview

UrbanAir NWP is a demo and set of tools for discovering, retrieving, inspecting, and visualizing archived weather-model data. Users can download complete datasets from NSC URLs, interactively select fields and download them through the notebook UI, or extract fields using Polytope/FDB; analysis notebooks demonstrate plots such as time-height views. Supporting tools maintain version metadata, scan FDB contents into selection catalogs, and provide an example archive workflow. The UI and several notebook implementations were only partially sampled or not sampled, so their documented capabilities are shown without inferring internal call chains.

Main entry points: [`pt_UI.py`](https://github.com/urbanairproject/nwp_demo_data/blob/main/pt_UI.py) (Interactive selector), [`versions.py`](https://github.com/urbanairproject/nwp_demo_data/blob/main/versions.py) (Version catalog), [`fdb_scan_to_json.py`](https://github.com/urbanairproject/nwp_demo_data/blob/main/fdb_scan_to_json.py) (FDB catalog scan), [`polytope_helper.ipynb`](https://github.com/urbanairproject/nwp_demo_data/blob/main/polytope_helper.ipynb) (Polytope selection)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_catalog["Catalog and metadata"]
  node_versions["Version catalog<br/>[versions.py]"]
  node_versiondata[("Version metadata<br/>[versions.json]")]
  node_paramdata[("Parameter metadata<br/>[para_codes.json]")]
  node_catalogscan["FDB catalog scan"]
  node_catalogjson[("Archive selection catalogs")]
end

subgraph group_retrieval["Data retrieval"]
  node_urlfetch["URL downloader<br/>[download.py]"]
  node_selector["Interactive selector<br/>[pt_UI.py]"]
  node_fileoutput["Downloaded data file"]
  node_polytopeexample["Polytope selection"]
  node_fdbexample["FDB extraction example"]
end

subgraph group_archive["FDB archive tools"]
  node_archivewriter["Archive writer<br/>[fdb_example.py]"]
  node_scanner["FDB scanner<br/>[fdb_scan.py]"]
end

subgraph group_examples["Analysis examples"]
  node_plotexamples["Weather plots"]
  node_subhourplot["Subhour plots"]
  node_earthkitexamples["Earthkit demonstrations"]
end

node_user(("Data user"))
node_nsc["NSC file hosting"]
node_polytope["Polytope API"]
node_fdb[("ECMWF FDB")]

node_user -->|"lists versions"| node_versions
node_versions -->|"loads metadata"| node_versiondata
node_urlfetch -->|"resolves version"| node_versions
node_urlfetch -->|"downloads files"| node_nsc
node_user -->|"requests download"| node_urlfetch
node_user -->|"selects fields"| node_selector
node_selector -->|"loads archive options"| node_versions
node_selector -->|"loads parameter names"| node_paramdata
node_selector -->|"loads archive catalog"| node_catalogjson
node_selector -->|"downloads selection"| node_fileoutput
node_user -->|"explores archive"| node_polytopeexample
node_polytopeexample -.->|"requests data"| node_polytope
node_polytopeexample -->|"explores fields"| node_fdb
node_user -->|"runs extraction"| node_fdbexample
node_fdbexample -->|"extracts fields"| node_fdb
node_user -->|"runs archive example"| node_archivewriter
node_archivewriter -->|"archives data"| node_fdb
node_user -->|"scans archive"| node_scanner
node_scanner -->|"lists archive keys"| node_fdb
node_user -->|"creates catalogs"| node_catalogscan
node_catalogscan -->|"reads archive versions"| node_versions
node_catalogscan -->|"scans fields"| node_fdb
node_catalogscan -->|"writes catalogs"| node_catalogjson
node_user -->|"runs visualization"| node_plotexamples
node_user -->|"runs visualization"| node_subhourplot
node_user -->|"runs demonstration"| node_earthkitexamples

click node_versions "https://github.com/urbanairproject/nwp_demo_data/blob/main/versions.py"
click node_versiondata "https://github.com/urbanairproject/nwp_demo_data/blob/main/json/versions.json"
click node_paramdata "https://github.com/urbanairproject/nwp_demo_data/blob/main/json/para_codes.json"
click node_catalogscan "https://github.com/urbanairproject/nwp_demo_data/blob/main/fdb_scan_to_json.py"
click node_catalogjson "https://github.com/urbanairproject/nwp_demo_data/tree/main/json"
click node_urlfetch "https://github.com/urbanairproject/nwp_demo_data/blob/main/download.py"
click node_selector "https://github.com/urbanairproject/nwp_demo_data/blob/main/pt_UI.py"
click node_polytopeexample "https://github.com/urbanairproject/nwp_demo_data/blob/main/polytope_helper.ipynb"
click node_fdbexample "https://github.com/urbanairproject/nwp_demo_data/blob/main/polytope_fetch.ipynb"
click node_archivewriter "https://github.com/urbanairproject/nwp_demo_data/blob/main/fdb_example.py"
click node_scanner "https://github.com/urbanairproject/nwp_demo_data/blob/main/fdb_scan.py"
click node_plotexamples "https://github.com/urbanairproject/nwp_demo_data/blob/main/paris_time_height_plot.ipynb"
click node_subhourplot "https://github.com/urbanairproject/nwp_demo_data/blob/main/paris_time_height_plot_subhour_200m.ipynb"
click node_earthkitexamples "https://github.com/urbanairproject/nwp_demo_data/blob/main/earthkit_example_paris.ipynb"

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_versions,node_versiondata,node_paramdata,node_catalogscan,node_catalogjson,node_user toneBlue
class node_urlfetch,node_selector,node_fileoutput,node_polytopeexample,node_fdbexample,node_fdb toneAmber
class node_archivewriter,node_scanner,node_polytope toneMint
class node_plotexamples,node_subhourplot,node_earthkitexamples toneRose
class node_nsc toneIndigo
```

## Components

### Catalog and metadata

- [Version catalog](https://github.com/urbanairproject/nwp_demo_data/blob/main/versions.py): `versions.py`
- [Version metadata](https://github.com/urbanairproject/nwp_demo_data/blob/main/json/versions.json): `json/versions.json`
- [Parameter metadata](https://github.com/urbanairproject/nwp_demo_data/blob/main/json/para_codes.json): `json/para_codes.json`
- [FDB catalog scan](https://github.com/urbanairproject/nwp_demo_data/blob/main/fdb_scan_to_json.py): `fdb_scan_to_json.py`
- [Archive selection catalogs](https://github.com/urbanairproject/nwp_demo_data/tree/main/json): `json`

### Data retrieval

- [URL downloader](https://github.com/urbanairproject/nwp_demo_data/blob/main/download.py): `download.py`
- [Interactive selector](https://github.com/urbanairproject/nwp_demo_data/blob/main/pt_UI.py): `pt_UI.py`
- **Downloaded data file**
- [Polytope selection](https://github.com/urbanairproject/nwp_demo_data/blob/main/polytope_helper.ipynb): `polytope_helper.ipynb`
- [FDB extraction example](https://github.com/urbanairproject/nwp_demo_data/blob/main/polytope_fetch.ipynb): `polytope_fetch.ipynb`

### FDB archive tools

- [Archive writer](https://github.com/urbanairproject/nwp_demo_data/blob/main/fdb_example.py): `fdb_example.py`
- [FDB scanner](https://github.com/urbanairproject/nwp_demo_data/blob/main/fdb_scan.py): `fdb_scan.py`

### Analysis examples

- [Weather plots](https://github.com/urbanairproject/nwp_demo_data/blob/main/paris_time_height_plot.ipynb): `paris_time_height_plot.ipynb`
- [Subhour plots](https://github.com/urbanairproject/nwp_demo_data/blob/main/paris_time_height_plot_subhour_200m.ipynb): `paris_time_height_plot_subhour_200m.ipynb`
- [Earthkit demonstrations](https://github.com/urbanairproject/nwp_demo_data/blob/main/earthkit_example_paris.ipynb): `earthkit_example_paris.ipynb`

### Other components

- **Data user**
- **NSC file hosting**
- **Polytope API**
- **ECMWF FDB**

## Connections

- Data user → Version catalog: lists versions (evidence: `README.md`)
- Version catalog → Version metadata: loads metadata (evidence: `versions.py`)
- URL downloader → Version catalog: resolves version (evidence: `download.py`)
- URL downloader → NSC file hosting: downloads files (evidence: `download.py`)
- Data user → URL downloader: requests download (evidence: `README.md`)
- Data user → Interactive selector: selects fields (evidence: `README.md`)
- Interactive selector → Version catalog: loads archive options (evidence: `pt_UI.py`)
- Interactive selector → Parameter metadata: loads parameter names (evidence: `pt_UI.py`)
- Interactive selector → Archive selection catalogs: loads archive catalog (evidence: `pt_UI.py`)
- Interactive selector → Downloaded data file: downloads selection (evidence: `README.md`)
- Data user → Polytope selection: explores archive (evidence: `README.md`)
- Polytope selection → Polytope API: requests data
- Polytope selection → ECMWF FDB: explores fields (evidence: `README.md`)
- Data user → FDB extraction example: runs extraction (evidence: `README.md`)
- FDB extraction example → ECMWF FDB: extracts fields (evidence: `README.md`)
- Data user → Archive writer: runs archive example (evidence: `README.md`)
- Archive writer → ECMWF FDB: archives data (evidence: `fdb_example.py`)
- Data user → FDB scanner: scans archive (evidence: `README.md`)
- FDB scanner → ECMWF FDB: lists archive keys (evidence: `fdb_scan.py`)
- Data user → FDB catalog scan: creates catalogs (evidence: `README.md`)
- FDB catalog scan → Version catalog: reads archive versions (evidence: `fdb_scan_to_json.py`)
- FDB catalog scan → ECMWF FDB: scans fields (evidence: `fdb_scan_to_json.py`)
- FDB catalog scan → Archive selection catalogs: writes catalogs (evidence: `fdb_scan_to_json.py`)
- Data user → Weather plots: runs visualization (evidence: `README.md`)
- Data user → Subhour plots: runs visualization (evidence: `README.md`)
- Data user → Earthkit demonstrations: runs demonstration (evidence: `README.md`)