noawclg (Rust)
Rust port of the noawclg Python
package: download, analyse and visualise NOAA atmospheric (GFS) and ocean
(GODAS / ERSST) data, no API key required.
This crate mirrors the Python package module-for-module. See Module map below for the exact correspondence.
Feature flags
| Feature | Adds | System requirement |
|---|---|---|
| (default) | catalogue, coordinate helpers, GFS GRIB2 download & caching, Zarr save/load, all ENSO/ocean math | none |
grib |
Decodes downloaded GRIB2 files into datasets, via the pure-Rust gribberish crate |
none (builds a vendored JPEG2000/PNG decoder) |
netcdf-io |
GODAS/ERSST access over OPeNDAP + NetCDF4 save/load, via the netcdf crate |
system libnetcdf built with DAP support (e.g. apt install libnetcdf-dev) |
full |
both of the above | both of the above |
This split matters because, exactly like the Python library (which needs a
system eccodes/libnetcdf install and documents it explicitly), the parts
of this crate that talk to real weather/ocean data formats have a real
system dependency. cargo build/cargo test with no features succeeds
anywhere and exercises 100% of the pure logic (all 38 unit tests, matching
the intent of the Python test suite, run without network or system libs).
Data freshness — always resolve dates dynamically
NOMADS only serves a rolling window of recent GFS runs — treat anything
older than 3 days back as unavailable. Every example below resolves its
date from "now" via auto_date, never a hardcoded date. If you write your
own code against this crate, do the same — a date more than a few days old
will 404. This is exactly why auto_date's lag_days parameter exists:
auto_date(1) targets yesterday's run, which is reliably published by the
time you'd read this.
Examples
All examples below are ported directly from the
Python README and exercised
in tests/readme_examples_tests.rs (offline, against synthetic/in-memory
data standing in for a real download or OPeNDAP fetch — see that file's
module doc for exactly which Python example each test corresponds to).
tests/integration_live_tests.rs additionally hits the real NOMADS
service for the download step (run with cargo test -- --ignored).
GFS weather forecasts
auto_date — pick the latest available GFS cycle
use auto_date;
let = auto_date;
// date -> "30/07/2026" (DD/MM/YYYY — always this format)
// cycle -> "12" (00 / 06 / 12 / 18)
load — quick download as a GfsDataset
Requires the grib feature to actually decode the downloaded GRIB2 files.
There are no lat=/lon= parameters — to query a single point, use
GetNoaaData::get_data_from_point
instead.
use ;
let = auto_date;
let ds = load?;
println!;
Pre-defined hour sequences
use ;
let ds = load?;
| Constant | Range | Step |
|---|---|---|
HOURS_5DAYS_1H |
0–120 h | 1 h |
HOURS_10DAYS_3H |
0–240 h | 3 h |
HOURS_16DAYS_3H |
0–384 h | 3 h |
HOURS_16DAYS |
0–120 h @ 6 h + 123–384 h @ 3 h | mixed |
GfsDatasetManager — full control over download and storage
GfsDatasetManager takes date in YYYYMMDD format (auto_date
returns DD/MM/YYYY; convert with noawclg::coords::parse_date).
use ;
let = auto_date;
let mgr = new?;
let hours: = .step_by.collect;
// One variable -> build_dataset
let ds_t = mgr.build_dataset?; // needs `grib`
// Multiple variables at once -> build_multi_dataset
let ds = mgr.build_multi_dataset?; // needs `grib`
// Persist and reload
save_zarr?;
let ds2 = load_zarr?;
save_netcdf?; // needs `netcdf-io`
let ds3 = load_netcdf?; // needs `netcdf-io`
GetNoaaData — query by coordinates or place name
Date format is DD/MM/YYYY, same as auto_date's output.
use ;
let = auto_date;
let gfs = new?; // needs `grib`
// Query by coordinates -> DatasetView
let view = gfs.get_data_from_point?;
let table = view.to_table; // Vec<BTreeMap<String, f64>>, one row per forecast hour
// Query by place name (geocoded automatically via Nominatim)
let view2 = gfs.get_data_from_place?;
// Complete time series for one variable at a grid point
let t2m_series = gfs.get_time_series?;
// List all loaded variables
println!;
// Access the raw dataset
let raw = gfs.dataset;
Mathematical analysis examples
All examples below assume a dataset loaded as in the load example, plus a
single grid point selected — the same shape of computation the Python
README does with numpy/pandas/scipy, translated to plain Rust +
ndarray (this crate's numeric dependency, no extra math crate required).
A few Python examples that lean on scipy.signal/scipy.ndimage
(find_peaks, gaussian_filter, FFT dominant-period detection) are not
ported — they'd need rustfft/an image-filtering crate, which is outside
noawclg's own scope in either language (the Python versions are usage
demos, not part of the noawclg package either).
Temperature — heat index, anomaly, trend
// Heat index (Rothfusz equation, °C in -> °C out)
// Anomaly relative to the 0-h (analysis) step
let t2m_anom: = t2m.iter.map.collect;
// Linear trend across the forecast window (simple least squares)
let hours_f: = hours.iter.map.collect;
let = linregress;
println!;
Dew-point depression and relative humidity check
// Dew-point depression (dry-bulb minus dew-point, °C)
let depression: = t2m.iter.zip.map.collect;
// Magnus formula: recompute RH from T and Td to cross-check
const A: f64 = 17.625;
const B: f64 = 243.04;
let rh_check: = t2m.iter.zip.map.collect;
Wind — speed, direction, stress, gusts
// Scalar wind speed and meteorological direction (from, 0°=N)
let wspd: = u10.iter.zip.map.collect;
let wdir: = u10.iter.zip.map.collect;
// Wind stress (bulk formula, air density rho ~ 1.225 kg/m3, Cd ~ 1.3e-3)
const RHO: f64 = 1.225;
const CD: f64 = 1.3e-3;
let tau_x: = wspd.iter.zip.map.collect;
let tau_y: = wspd.iter.zip.map.collect;
// Normalised gust factor (gust / sustained)
let gust_factor: = gust.iter.zip
.map
.collect;
// Beaufort scale
Pressure — gradient and tendency
use Array3; // prmsl: (time, lat, lon), hPa
// Central-difference gradient (hPa / grid-cell), NumPy `np.gradient` style
// Pressure tendency (hPa / 3h) at one point — central differences in time
let tendency = gradient_1d; // already spaced 3 h apart per `hours`
// Anomaly from the first step
let p_anom: = prmsl_point.iter.map.collect;
Precipitation — accumulation, exceedance
// prate is kg/m^2/s == mm/s; * 3600 -> mm/h, then * timestep(h) to accumulate
let dt_hours = 3.0;
let precip_rate_mm_h: = prate.iter.map.collect;
let mut precip_accum_mm = Vecwith_capacity;
let mut running = 0.0;
for r in &precip_rate_mm_h
// Probability of exceeding 5 mm/h, spatial domain at each timestep
// prate_all: Array3<f64> (time, lat, lon)
let prob_5mm: = prate_all.outer_iter.map.collect;
CAPE — instability classification
// cape_now: Array2<f64> (lat, lon), J/kg, at one forecast hour
// Area fraction with extreme instability (CAPE > 2500 J/kg) per timestep
// cape_all: Array3<f64> (time, lat, lon)
let frac_extreme: = cape_all.outer_iter.map.collect;
Upper-air multi-level variables — vertical profiles
let ds_ua = load?;
// levels, T_prof, gh_prof, u_prof, v_prof extracted from `ds_ua` at one
// point / one forecast hour (via GetNoaaData::get_data_from_point instead,
// then index into the "level" dim of the returned SelectedVariable).
const R: f64 = 287.05;
const G: f64 = 9.81;
for i in 0..levels.len - 1
// Wind shear (m/s per hPa) between levels
let shear_u: = u_prof.windows.zip
.map
.collect;
GFS variable catalogue
use ;
println!; // all 47 keys
println!; // single-level keys
println!; // multi-level keys
for in VARIABLES.iter
Ocean data — GODAS & ERSST
All ocean data is served via OPeNDAP — nothing is downloaded to disk;
access is lazy. Requires the netcdf-io feature.
use ;
let field = open_godas?;
let Surface = field else ;
println!; // °C, (time=12, lat, lon)
use get_godas;
// All 2020-2024 temperature at 200 m
let da = get_godas?; // 5 years concatenated
use ;
let t200 = get_ocean_temp?; // °C
let t5 = get_ocean_temp?; // surface temperature
let sal = get_salinity?; // PSU
let curr = get_currents?; // ucur, vcur, speed
println!;
let ssh = get_ssh?; // m, (time=12, lat, lon)
let ssh5 = get_ssh?; // 5 years concatenated
use ;
// Nino 3.4 box, 1950-2024
let sst = open_ersst?; // °C
use get_sst_series;
let sst_godas = get_sst_series?; // 1980+
let sst_ersst = get_sst_series?; // 1854+, longer climatology
ENSO diagnostics
use ;
// SST anomaly relative to a 1991-2020 climatology
let anom = get_nino_anomaly?;
// Oceanic Nino Index (3-month running mean of the anomaly)
let oni = get_oni?;
// Phase classification (CPC ONI rule: >= 5 consecutive seasons)
let phase = classify_enso; // Vec<String> of "El Niño"/"La Niña"/"Neutral"
use enso_summary;
let rows = enso_summary?;
for row in rows.iter.rev.take
Thermocline depth (D20) and Warm Water Volume:
use ;
let d20 = get_thermocline_depth?;
let wwv = get_warm_water_volume?;
Plotting
Not ported — see Known limitations.
Module map ↔ Python equivalent
| Rust module | Python module | Notes |
|---|---|---|
catalog |
noawclg/catalog.py |
VARIABLES (47 entries — the Python README says 43 but undercounts its own catalog.py), HOURS_* |
coords |
noawclg/coords.py |
BoundingBox, auto_date, find_dim, normalize_lon, parse_date |
http |
noawclg/http.py |
NOMADS grib-filter URL builder + HTTP client |
gfs_dataset |
noawclg/gfs_dataset.py |
Download/cache always on; decoding (build_dataset/build_multi_dataset) needs grib |
grib_decode |
(cfgrib calls inside gfs_dataset.py) |
GRIB2 → array decoding via gribberish, only compiled with grib |
persistence |
noawclg/persistence.py |
Zarr v2 (always on, self-contained writer/reader); NetCDF4 needs netcdf-io |
ocean |
noawclg/ocean.py |
Split into pure math (masking, region/depth selection, ENSO indices — always on) and live OPeNDAP fetch (needs netcdf-io) |
query |
noawclg/query.py |
GetNoaaData, Nominatim geocoding (plain HTTP, no geopy needed) |
view |
noawclg/view.py |
DatasetView |
load |
noawclg/load.py |
load() one-liner |
plots.py and enso_forecast.py in the Python repo live outside the
noawclg package itself (they're top-level scripts, not part of the
importable library), so they're out of scope for this port — there is no
Rust equivalent of matplotlib/cartopy plotting here.
Known limitations / honesty notes
- GRIB2 decoding (
gribfeature) usesgribberishinstead of thecfgrib/eccodescombo the Python library uses. The decode path (src/grib_decode.rs) is written against gribberish's documentedMessageAPI and compiles cleanly, but has not been exercised against a real downloaded GFS file in this environment (no network egress to NOMADS from the sandbox this was built in). Treat it as a solid starting point, not a guarantee — if a real file decodes incorrectly, the likely culprit is level-matching ingrib_decode::match_level(isobaric level units aren't 100% pinned down by gribberish's docs) or message ordering. netcdf-iofeature requireslibnetcdf-dev/libhdf5-dev(or the condanetcdf4package) to even compile, exactly like the Python library needslibeccodes-dev/netCDF4. It was not build-tested in this environment because those system packages aren't installed here and installing them requiressudo.- No plotting. See above — out of scope by design, not an oversight.
- DataFrame equivalent. Rust has no
pandas/xarray.TimeSeries(aVec<NaiveDate>+Vec<f64>) stands in forpd.Series;DatasetView::to_table()stands in for.to_dataframe()for the common case of single-level variables.
Testing
Two layers, mirroring the Python tests/ suite one file at a time:
| Rust | Ports (Python) | How |
|---|---|---|
src/**/*.rs #[cfg(test)] mod tests (38 tests) |
— | Unit tests with access to private internals (e.g. cache_path, mask_and_convert) |
tests/catalog_tests.rs |
test_gfs_dataset.py::TestConstants |
Public API only |
tests/gfs_dataset_tests.rs |
test_gfs_dataset.py::TestInit/TestHelpers/TestDownloadHours/TestEdgeCases |
Public API + common::FakeFetcher |
tests/query_view_tests.rs |
test_main.py |
Public API + GetNoaaData::from_dataset |
tests/ocean_tests.rs |
test_ocean.py (index math) |
Public API only |
tests/persistence_tests.rs |
test_gfs_dataset.py::TestZarr |
Public API, real on-disk round trip |
The Python suite mocks network calls with unittest.mock.patch.object(mgr._session, "get", ...). The Rust port achieves the same thing with a real seam
instead of monkeypatching: GfsDatasetManager is generic over an
http::Fetcher trait, and tests/common/mod.rs::FakeFetcher implements it
in-memory (canned status/body per call, or a queue for retry scenarios),
recording every URL requested so tests can assert on it — e.g.
gfs_dataset_tests.rs::var_params_shared_level_token_deduplicated checks
the exact grib-filter query string download_hours builds, without that
method needing to be pub. No test in this crate opens a socket.
License
GPL-3.0-or-later, matching the original Python package.