usdata
Follow an analysis from its source datasets to saved results, or start with a small manifest. Every example includes code you can run yourself.
Set up and run examplesNotebook · saved results
Compare twelve months at Oklahoma City's airport with 1991–2020 station normals, including temperature-unit checks and monthly anomaly plots.
Monthly station climate · 30-year station climate normals
Notebook · saved results
Connect one Storm Events report to nearby NEXRAD and GOES observations, with explicit time matching and a plotted event context.
Storm Events details · NEXRAD radar scans · GOES CONUS imagery
Notebook · saved results
Fetch NOAA and USGS observations with one manifest, inspect the tables, and verify and restore the exact inputs.
Daily station weather · Daily water observations
Notebook · saved results
Download four sea-surface-temperature grid cells, inspect their units, and plot the selected area.
Sea-surface temperature
Notebook · saved results
Read monthly station observations, compare temperature and precipitation in two plots, and verify the source manifest.
Monthly station climate
Notebook · saved results
Filter an annual Storm Events archive locally, plot report counts and damage ratings, and account for reporting limitations.
Storm Events details
Notebook · saved results
Open a NEXRAD Level II volume, inspect its sweeps and reflectivity units, and plot a selected sweep.
NEXRAD radar scans
Notebook · saved results
Decode a GOES CONUS scene, inspect quality flags and scan coordinates, and plot brightness temperatures.
GOES CONUS imagery
Manifest walkthrough
Fetch complete-year station summaries and read annual temperature and precipitation with a reproducible manifest.
Annual station climate
Manifest walkthrough
Read 1991–2020 monthly temperature and precipitation normals and select a month for comparison.
30-year station climate normals
Manifest walkthrough
Inspect three six-minute coastal observations, their reference datum, quality flags, and source provenance.
Coastal water levels
Manifest walkthrough
Read the whole Atlantic best-track file, identify hurricane-intensity landfall records, and inspect peak winds and historical coverage limits.
Tropical cyclone best tracks
From the repository root, with uv and just installed:
just notebooks
This launches JupyterLab with the optional examples dependency group, which
includes pandas, plotting, and notebook tools. The commands also install the
optional radar and netcdf extras. Notebook tools are development dependencies;
installing base usdata does not install them or the scientific reader extras. Select a notebook and use the Python 3
kernel. In an IDE, select this checkout's .venv interpreter after the environment
has been installed. Use Restart Kernel and Run All Cells to check that a notebook
works without hidden state. Each notebook works from its own folder or the repo root.
The first run needs access to NOAA and/or USGS. Interactive runs use the normal
usdata cache (USDATA_CACHE_DIR overrides it). The manifest examples retain
their dataset.yaml files; a first pull creates an ignored dataset.lock.json
beside the manifest. When changing a locked manifest deliberately, use
pull(manifest, force=True) to resolve and lock the new inputs.
just check-notebooks # offline checks of committed notebook outputs
just run-notebooks # live execution, without changing committed outputs
just run-notebooks --write # live execution, then save all successful results
The runner starts each notebook in a fresh kernel with temporary manifests,
lockfiles, and caches. It uses the same interpreter as the examples environment;
it does not install a global kernel. A failure leaves the committed notebooks
untouched. The scheduled Integration workflow runs the live notebook check
separately from the existing adapter tests. Regular just check validates the
saved notebooks offline.
Saved outputs are snapshots, not promises about future upstream responses. Each notebook records its execution time, package versions, source retrieval times, source URLs, and full input checksums. Preserve both the manifest and lockfile in your own analysis project, and keep cached bytes for long-lived reproducibility.
Commit compact executed outputs: short tables, small static plots, and relevant provenance. The runner removes execution timing and widget metadata while keeping the visible outputs. Review the notebook diff before committing a refresh; upstream revisions can change both observations and checksums. The notebooks are the tutorial source; equivalent analysis scripts are not maintained alongside them.
A small coastal water-level manifest demonstrates CO-OPS datum, units, quality flags, and local CSV reading (available since v0.10.0).