Skip to content

Charts and maps

Results that have a shape worth drawing have .plot(); the functions behind it live in stormlore.viz, which also has the two charts no single result owns (meteogram, wind rose). Every one returns a plotly Figure: interactive in Jupyter, fig.show() elsewhere, fig.write_html("chart.html") to share.

pip install 'stormlore[viz]'     # plotly

Without the extra, .plot() raises MissingExtraError naming that install line; import stormlore never needs plotly.

from stormlore import Client, viz

client = Client()
series = client.forecast.timeseries("gfs", (41.26, -95.94), ["temperature_2m", "dewpoint_2m"])
series.plot(units="imperial")            # the same as viz.timeseries(series, units="imperial")

The charts below are drawn from recorded sample responses when this site is built; hover, zoom and toggle legend entries as you would in a notebook.

What every chart shares

  • title= sets the figure's title.
  • Values come from the result's own to_dataframe(units), so units= ("metric", "imperial", "native") converts as there, and the client's units= default applies when it is omitted. Observations, storm reports, advisories and scores are drawn as served and take no units.
  • A parameter that is not in the result raises ValueError listing those that are.
  • An empty result gives an empty figure with its title, never an error.
  • palette= (forecast charts) takes a stormlore.viz.palette palette; the default is picked from the parameter's name (NWS colour scales). A palette's fixed range is written in the units the API serves (temperature in kelvin) and converts with the values, so units="imperial" keeps the full colour scale.
  • A y-axis shared by several parameters is titled by their unit; observation rows with no station (storm reports) are drawn as points, never joined by a line.

Forecast at a place

viz.timeseries(result, parameter=None): one line per parameter (all of them by default), one y-axis per unit.

series = client.forecast.timeseries(
    "gfs", (41.26, -95.94), ["temperature_2m", "dewpoint_2m", "wind_speed_gust_surface"]
)
series.plot(units="imperial", title="GFS at Omaha")

viz.meteogram(result): one stacked panel per parameter, sharing the time axis.

viz.meteogram(series, units="imperial")

viz.wind_rose(result, u_parameter="u_component_of_wind_10m", v_parameter="v_component_of_wind_10m"): how often the wind blows from each of 16 directions, stacked by speed. Ask the timeseries for both components; a missing one raises ValueError.

wind = client.forecast.timeseries(
    "gfs", (41.26, -95.94), ["u_component_of_wind_10m", "v_component_of_wind_10m"]
)
viz.wind_rose(wind, units="imperial")    # speed bins in mph

Over an area and along a route

viz.heatmap(result, parameter=None) (AreaResult.plot()): one parameter over the grid, the first by default. An area that crosses 180° keeps an increasing longitude axis.

area = client.forecast.area("hrrr", (43.0, 40.0, -95.3, -104.1), "temperature_2m")
area.plot(units="imperial")

viz.route(result, parameter=None) (RouteResult.plot()): the waypoints on a map, coloured by one parameter.

trip = client.forecast.route("gfs", [(41.26, -95.94, "2026-11-13T18Z"), (40.7, -99.08, "2026-11-14T00Z")],
                             "temperature_2m")
trip.plot(units="imperial")

Maps

The maps use OpenStreetMap tiles, which need no token: the browser showing the figure fetches them. Without a network the data still draws, on a blank background.

viz.stations(result) (StationList.plot()): one colour per source; hover names the id, name and source.

client.observations.stations(source="madis_metar", bounds=(42, 40, -95, -98)).plot()

viz.observations(result, parameter=None) (ObservationPage.plot()): observations or storm reports, one colour per source, or coloured by a numeric reading when parameter names one. A page of 10,000 rows is one trace per source, never one per row.

page = client.observations.points((42, 40, -95, -98), start="2026-11-13T12Z")
page.plot()                          # by source
page.plot(parameter="temperature_c") # by value

viz.observation_timeseries(result, parameter=None): one line per station over observed_at. parameter may be left out when the page has a single numeric reading.

ObservationPage.plot() picks this chart by itself when every row is one station at more than one time; force either with kind="map" or kind="timeseries".

client.observations.timeseries("KOMA", source="madis_metar", start="2026-11-12T17Z").plot()

Radar

viz.radar(result, parameter=None) (RadarSeries.plot()): one line per parameter over the MRMS frames. A missed sweep (a gap wider than 1.5 × the usual spacing) breaks the line instead of joining across it.

client.radar.point((41.26, -95.94), "merged_reflectivity_qc_composite_500m_amsl").plot()

Advisories

viz.advisories(result, color_by="severity") (AdvisoryPage.plot(), AdvisoryDetail.plot()): the shapes on a map, one legend entry per severity (or per event with color_by="event"); hover shows the event, headline and expiry.

The page must be asked with geometry=True, or the call raises ValueError saying so. Advisories defined by zones alone have no shape: they are left off and counted in the title. A browser cannot draw a whole country of shapes, so more than max_shapes=500 shapes or max_vertices=200_000 vertices raises: filter by place, or raise the cap.

client.advisories.list("68102", geometry=True).plot()

Scores

viz.score_history(result) (ScoreHistory.plot()): the monthly score with its confidence band; provisional months are circled.

client.scores.history("gfs").plot()

Region scores and the monthly ranking are tables, not charts: use to_dataframe().

Static images

Figures export to PNG, SVG or PDF with plotly's fig.write_image(...), which needs pip install kaleido and a Chrome on the machine; it is not part of the viz extra.