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 ( |
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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; |
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. |