Skip to content

Charts and maps

pip install 'stormlore[viz]'; see the guide for every chart drawn.

stormlore.viz.timeseries

timeseries(
    result: TimeseriesResult,
    parameter: str | Sequence[str] | None = None,
    *,
    units: str | None = None,
    palette: Palette | None = None,
    title: str | None = None,
) -> Any

One line per parameter over valid time; one y-axis per unit.

Parameters:

Name Type Description Default
result TimeseriesResult

A forecast timeseries (client.forecast.timeseries).

required
parameter str | Sequence[str] | None

A name or a list of names; all of the result's parameters by default.

None
units str | None

"metric", "imperial" or "native"; the client's default if omitted.

None
palette Palette | None

Line colour(s); the parameter's own palette by default.

None
title str | None

The figure's title.

None

Raises:

Type Description
ValueError

A parameter is not in the result.

MissingExtraError

plotly is not installed.

stormlore.viz.meteogram

meteogram(
    result: TimeseriesResult,
    *,
    units: str | None = None,
    title: str | None = None,
) -> Any

One stacked panel per parameter, sharing the time axis.

Raises:

Type Description
MissingExtraError

plotly is not installed.

stormlore.viz.wind_rose

wind_rose(
    result: TimeseriesResult,
    *,
    u_parameter: str = "u_component_of_wind_10m",
    v_parameter: str = "v_component_of_wind_10m",
    units: str | None = None,
    title: str | None = None,
) -> Any

How often the wind blows from each of 16 directions, stacked by speed.

The result must carry both wind components (ask for them in the timeseries).

Raises:

Type Description
ValueError

A component is not in the result.

MissingExtraError

plotly is not installed.

stormlore.viz.heatmap

heatmap(
    result: AreaResult,
    parameter: str | None = None,
    *,
    units: str | None = None,
    palette: Palette | None = None,
    title: str | None = None,
) -> Any

One parameter over the area's latitude/longitude grid.

parameter defaults to the first in the result. Longitudes that cross 180° are unwrapped (170 … 190) so the axis keeps increasing. A palette's fixed range is in the units the API serves and converts with the values (one that holds none of them is dropped).

Raises:

Type Description
ValueError

parameter is not in the result.

MissingExtraError

plotly is not installed.

stormlore.viz.route

route(
    result: RouteResult,
    parameter: str | None = None,
    *,
    units: str | None = None,
    palette: Palette | None = None,
    title: str | None = None,
) -> Any

The route's waypoints on a tile map, coloured by one parameter (the first by default).

Raises:

Type Description
ValueError

parameter is not in the result.

MissingExtraError

plotly is not installed.

stormlore.viz.stations

stations(
    result: StationList, *, title: str | None = None
) -> Any

Stations on a tile map, one colour per source; hover names the id, name and source.

Raises:

Type Description
MissingExtraError

plotly is not installed.

stormlore.viz.observations

observations(
    result: ObservationPage,
    parameter: str | None = None,
    *,
    title: str | None = None,
) -> Any

Observations or storm reports on a tile map.

Coloured by parameter (a numeric reading) when given, else one colour per source. Drawn as served (no units); the colour bar names the unit where the source declared one. Rows without the reading are left off.

Raises:

Type Description
ValueError

parameter is not a numeric reading on the page.

MissingExtraError

plotly is not installed.

stormlore.viz.observation_timeseries

observation_timeseries(
    result: ObservationPage,
    parameter: str | None = None,
    *,
    title: str | None = None,
) -> Any

One line per station over observed_at; rows with no station (storm reports) are points, grouped by source, never joined by a line.

Observations are drawn as served (no units); the axis names the unit where the source declared one. parameter defaults to the page's only numeric reading.

Raises:

Type Description
ValueError

parameter is not a numeric reading, or none was given and the page has several (or none).

MissingExtraError

plotly is not installed.

stormlore.viz.radar

radar(
    result: RadarSeries,
    parameter: str | Sequence[str] | None = None,
    *,
    units: str | None = None,
    title: str | None = None,
) -> Any

One line per parameter over the MRMS frames, one y-axis per unit; a missed sweep breaks the line.

A gap wider than 1.5 × the median frame spacing is drawn as a break, not a straight line across.

Raises:

Type Description
ValueError

A parameter is not in the result.

MissingExtraError

plotly is not installed.

stormlore.viz.advisories

advisories(
    result: AdvisoryPage | AdvisoryDetail,
    *,
    color_by: str = "severity",
    max_shapes: int = 500,
    max_vertices: int = 200000,
    title: str | None = None,
) -> Any

Advisory shapes on a tile map, one legend entry per severity (or event).

The page must have been asked with geometry=True. Advisories without a shape (zone only) are skipped and counted in the title. A full active set is too much for a browser, so more than max_shapes shapes or max_vertices vertices is refused: filter by place first.

Raises:

Type Description
ValueError

geometry was not asked for; too many shapes or vertices; color_by is not "severity" or "event".

MissingExtraError

plotly is not installed.

stormlore.viz.score_history

score_history(
    result: ScoreHistory, *, title: str | None = None
) -> Any

The monthly score with its confidence band; provisional months are marked.

Raises:

Type Description
MissingExtraError

plotly is not installed.

stormlore.viz.palette

Color palettes for weather data visualization.

All default palettes use NWS (National Weather Service) standard colors — the same color conventions used on weather.gov, AWIPS, and NWS forecast products.

Usage

from stormlore.viz.palette import temperature, for_parameter, create

Built-in NWS palette

pal = temperature

Auto-detect from parameter name

pal = for_parameter("temperature_surface")

Custom palette

pal = create("severity", colors=["#2166ac", "#f7f7f7", "#b2182b"], range=(0, 100))

Palette dataclass

A reusable color scale for visualizations.

Attributes:

Name Type Description
name str

Human-readable name.

colors list[str]

List of hex color strings (#RRGGBB).

range tuple[float, float] | None

Optional fixed value range (min, max). None means auto-scale from data.

create

create(
    name: str,
    colors: list[str],
    range: tuple[float, float] | None = None,
) -> Palette

Create a custom reusable palette.

Parameters:

Name Type Description Default
name str

Palette name.

required
colors list[str]

List of hex color strings (#RRGGBB).

required
range tuple[float, float] | None

Optional fixed value range (min, max).

None

Returns:

Type Description
Palette

A new Palette instance.

Raises:

Type Description
ValueError

If colors is empty or contains invalid hex strings.

for_parameter

for_parameter(parameter_name: str) -> Palette

Auto-detect the best NWS palette for a parameter name.

Parameters:

Name Type Description Default
parameter_name str

Storm Glass parameter name (e.g., "temperature_surface").

required

Returns:

Type Description
Palette

The most appropriate built-in palette. Falls back to viridis for unknown parameters.