noaaplotter

A python package to create fancy plots with NOAA weather data (stations) and ERA5 reanalysis (by coordinates).

📚 Docs & API reference: initze.github.io/noaaplotter

Install: pip install noaaplotter

Install

PyPI (recommended for end users)

pip install noaaplotter

From source (development)

uv venv
uv pip install -e .          # install this package + all dependencies
# or from GitHub:
uv pip install git+https://github.com/initze/noaaplotter.git

Requirements

matplotlib, numpy, pandas, requests, joblib, tqdm, polars, pyarrow, plotly, python-dotenv, typer (all listed in pyproject.toml and installed automatically).

Quick start (3 steps)

# 1. Download data (no token needed — NOAA data comes from the public
#    NCEI Access Data Service)
noaaplotter download-data -o data/kotzebue.parquet -sid USW00026616 -start 1970-01-01 -end 2021-12-31

# 2. Create a daily plot (temperature vs. climate + precipitation, incl. 7-day rolling sum)
noaaplotter plot-daily -infile data/kotzebue.parquet -start 1992-01-01 -end 1992-12-31 -t_range -45 25 -p_range 50 -save_plot figures/kotzebue_1992.png

# 3. ...or an interactive HTML plot
noaaplotter plot-daily -infile data/kotzebue.parquet -start 1992-01-01 -end 1992-12-31 --engine plotly -save_plot figures/kotzebue_1992.html

Command Line Interface (CLI)

Unified command line interface: noaaplotter <command> [OPTIONS]. Every command supports -h / --help for detailed usage.

noaaplotter download-data

Download weather data to a parquet file.

# NOAA station (no token needed — public NCEI service)
noaaplotter download-data -o data/kotzebue.parquet -sid USW00026616 -start 1970-01-01 -end 2021-12-31

# ERA5 reanalysis by coordinates (open_meteo, no token needed)
noaaplotter download-data -o data/potsdam.parquet --source open_meteo -lat 52.4 -lon 13.05 -start 1980-01-01 -end 2021-12-31

Data files are cached: re-running only fetches the missing dates.

The ERA5-backed sources (--source open_meteo / cds) additionally return daily wind columns: WSPD (daily mean 10 m wind speed, m/s) and WDIR (daily dominant direction in degrees, meteorological convention — the direction the wind blows FROM; 0 = north). NOAA station data has no equivalent, so both stay null for --source noaa.

noaaplotter plot-daily

Daily temperature (observed vs. climate mean ± 1σ, with anomaly fills) + precipitation (bars + 7-day rolling sum).

noaaplotter plot-daily -infile data/kotzebue.parquet -start 1992-01-01 -end 1992-12-31 -t_range -45 25 -p_range 50 -save_plot figures/kotzebue_1992.png
noaaplotter plot-daily -infile data/kotzebue.parquet -start 2017-07-01 -end 2018-06-30 --snow_acc --engine plotly -save_plot figures/kotzebue_winter.html

noaaplotter plot-monthly

Monthly bar chart of temperature or precipitation, with anomaly and trailing mean.

# Absolute values
noaaplotter plot-monthly -infile data/kotzebue.parquet -start 1980-01-01 -end 2021-08-31 -type Temperature -trail 12 -save_plot figures/kotzebue_t.png

# Anomaly from climate (1981-2010)
noaaplotter plot-monthly -infile data/kotzebue.parquet -start 1980-01-01 -end 2021-08-31 -type Precipitation -trail 12 -anomaly -save_plot figures/kotzebue_p_anomaly.png

noaaplotter plot-stripes

Warming stripes (Ed Hawkins style): one vertical bar per period, coloured by temperature anomaly (cool-blue → white → warm-red).

noaaplotter plot-stripes -infile data/kotzebue.parquet -type Temperature -start 1980-01-01 -end 2018-12-31 -save_plot figures/kotzebue_stripes.png

noaaplotter plot-heatmap

Activity heatmap (GitHub-style matrix): months on x, one row per year (latest on top).

noaaplotter plot-heatmap -infile data/kotzebue.parquet -type Temperature -scale anomaly -save_plot figures/kotzebue_heatmap_anomaly.png

Examples

Download data

Option 1 — NOAA Daily Summaries via CLI (Kotzebue, 1970-2021)

• No token required — served by the public NCEI Access Data Service.

noaaplotter download-data -o data/kotzebue.parquet -sid USW00026616 -start 1970-01-01 -end 2021-12-31

Option 2 — NOAA Daily Summaries via browser CSV files of "daily summaries" (https://www.ncdc.noaa.gov/cdo-web/search), values: metric, file type: csv.

Option 3 — ERA5 via CLI (Potsdam, 13.05°E / 52.4°N, 1980-2021 — no token) noaaplotter download-data -o data/potsdam.parquet --source open_meteo -lat 52.4 -lon 13.05 -start 1980-01-01 -end 2021-12-31

Daily Mean Temperature and Precipitation vs. Climate

Entire year 1 January until 31 December (e.g. 1992):

noaaplotter plot-daily -infile data/kotzebue.parquet -start 1992-01-01 -end 1992-12-31 -t_range -45 25 -p_range 50 -save_plot figures/kotzebue_daily_1992.png

Monthly aggregates

Temperature, absolute (12-month trailing mean):

noaaplotter plot-monthly -infile data/kotzebue.parquet -start 1980-01-01 -end 2021-08-31 -type Temperature -trail 12 -save_plot figures/kotzebue_monthly_t.png

Temperature, anomaly from climate (1981-2010):

noaaplotter plot-monthly -infile data/kotzebue.parquet -start 1980-01-01 -end 2021-08-31 -type Temperature -trail 12 -anomaly -save_plot figures/kotzebue_monthly_t_anomaly.png

Precipitation, absolute (12-month trailing mean):

noaaplotter plot-monthly -infile data/kotzebue.parquet -start 1980-01-01 -end 2021-08-31 -type Precipitation -trail 12 -save_plot figures/kotzebue_monthly_p.png

Warming stripes

One bar per year, coloured by the monthly-mean temperature anomaly (ed Hawkins style):

noaaplotter plot-stripes -infile data/kotzebue.parquet -type Temperature -start 1980-01-01 -end 2018-12-31 -save_plot figures/kotzebue_stripes.png

Activity heatmap (months × years)

Anomaly from the climate mean, red↔white↔blue (white in the centre):

noaaplotter plot-heatmap -infile data/kotzebue.parquet -type Temperature -scale anomaly -save_plot figures/kotzebue_heatmap_anomaly.png

Precipitation (absolute, Blues palette — blue for wet months):

noaaplotter plot-heatmap -infile data/kotzebue.parquet -type Precipitation -scale absolute -save_plot figures/kotzebue_heatmap_precip.png

Advanced Usage

Get help for any command

noaaplotter --help
noaaplotter download-data --help
noaaplotter plot-daily --help
noaaplotter plot-monthly --help

Interactive (plotly) plots

Use --engine plotly and save to .html to get interactive plots (zoom, hover, range slider). Daily plots also show a 7-day rolling sum of precipitation.

Python API

The package is a normal Python library as well:

from noaaplotter import NOAAPlotter

n = NOAAPlotter("data/kotzebue.parquet", location="Kotzebue", climate_filtersize=7)
fig = n.plot_weather_series(start_date="1992-01-01", end_date="1992-12-31",
                            show_plot=False, return_plot=True, engine="plotly")
fig.write_html("figures/kotzebue_1992.html")