Skip to content

Results

stormlore.results.PointResult

Bases: Result

Values at one place and time.

to_dataframe

to_dataframe(units: str | None = None) -> pd.DataFrame

One row indexed by valid_time, one column per parameter.

stormlore.results.TimeseriesResult

Bases: Result

Values at one place over time.

to_dataframe

to_dataframe(units: str | None = None) -> pd.DataFrame

Indexed by UTC valid_time, one column per parameter.

plot

plot(
    parameter: str | list[str] | None = None,
    *,
    units: str | None = None,
    palette: Any = None,
    title: str | None = None,
) -> Any

A line per parameter over time: :func:stormlore.viz.timeseries (viz extra).

stormlore.results.RouteResult

Bases: Result

Values along a route, one entry per waypoint.

to_dataframe

to_dataframe(units: str | None = None) -> pd.DataFrame

One row per waypoint: lat, lon, valid_time and one column per parameter.

plot

plot(
    parameter: str | None = None,
    *,
    units: str | None = None,
    palette: Any = None,
    title: str | None = None,
) -> Any

The waypoints on a map: :func:stormlore.viz.route (viz extra).

stormlore.results.AreaResult

Bases: Result

Values over a bounding box at one time, on a regular latitude/longitude grid.

Row 0 is the north edge and column 0 the west edge; both edges are included, so lat[r] = north − r·(north − south)/(height − 1). Missing cells are NaN.

lats property

lats: ndarray

Row latitudes, north first.

lons property

lons: ndarray

Column longitudes, west first.

array

array(parameter: str) -> np.ndarray

parameter as a (height, width) float array, as served (NaN where missing).

to_dataframe

to_dataframe(units: str | None = None) -> pd.DataFrame

Long form: one row per cell, columns lat, lon and one per parameter.

For gridded work, :meth:to_xarray is the better shape.

to_xarray

to_xarray(units: str | None = None) -> Any

An xarray.Dataset with dims (lat, lon), one variable per parameter.

Each variable's attrs["units"] names its units.

Raises:

Type Description
MissingExtraError

xarray is not installed (pip install 'stormlore[xarray]').

plot

plot(
    parameter: str | None = None,
    *,
    units: str | None = None,
    palette: Any = None,
    title: str | None = None,
) -> Any

A heatmap of one parameter: :func:stormlore.viz.heatmap (viz extra).

stormlore.results.WindResult

Bases: Result

Wind at one place and time: speed and direction from the u/v components.

direction is where the wind blows from, in degrees (0 = north).

to_dataframe

to_dataframe(units: str | None = None) -> pd.DataFrame

One row indexed by valid_time: speed, direction, u, v.

stormlore.results.ValueWithUnits

Bases: Result

A value and its units, as the API served them. value is None when missing.

to

to(target: str) -> ValueWithUnits

This value in a system ("metric", "imperial") or a unit ("°F", "kt" …).

Raises:

Type Description
UnitConversionError

The value's units cannot be converted to target.

stormlore.results.ModelList

Bases: Result

The models the API key can use; iterate it, or index it by slug.

to_dataframe

to_dataframe(units: str | None = None) -> pd.DataFrame

One row per model, indexed by slug.

stormlore.results.ModelInfo

Bases: Result

One model the API key can use.

layout is forecast (runs of forecast steps: GFS, HRRR) or analysis (a flat series of observed frames: MRMS). latest_run is "analysis" for the latter.

stormlore.results.ParameterList

Bases: Result

A model's parameters.

to_dataframe

to_dataframe(units: str | None = None) -> pd.DataFrame

One row per parameter, indexed by name.

stormlore.results.RunList

Bases: Result

A model's runs, newest first.

to_dataframe

to_dataframe(units: str | None = None) -> pd.DataFrame

One row per run, newest first.

stormlore.results.Steps

Bases: Result

The serving run's forecast steps (hours after run_time).

For an analysis model run_time is "analysis" and steps is a frame index, not hours: use client.forecast.times() there.

valid_times property

valid_times: list[datetime]

run_time + step for every step (empty for an analysis model).

to_dataframe

to_dataframe(units: str | None = None) -> pd.DataFrame

One row per step: step and valid_time.

stormlore.results.Times

Bases: Result

An analysis model's frame times, oldest first.

to_dataframe

to_dataframe(units: str | None = None) -> pd.DataFrame

One row per frame: time.

stormlore.results.Tile

Bases: Result

One 256 × 256 PNG data tile and the range its pixels encode.

For grey8: value = value_min + R / 255 · (value_max − value_min); for rg16: value = value_min + (R·256 + G) / 65535 · (value_max − value_min). A pixel with alpha 0 is missing.

save

save(path: str) -> None

Write the PNG to path.

to_dataframe

to_dataframe(units: str | None = None) -> pd.DataFrame

The tile's description as one row (the PNG bytes left out).

stormlore.results.TileMetadata

Bases: Result

How to decode a parameter's tiles back to values.

stormlore.results.ObservationPage

Bases: CursorPage

One page of observations or storm reports; iterate it, or index it.

to_dataframe

to_dataframe(units: str | None = None) -> pd.DataFrame

One row per feature.

Columns: id, observed_at, lat, lon, source, station_id, station_name, station_state, station_country, distance_m, then one per key of values, attributes and the other properties (top level only: a nested value stays an object in its cell). A key that would take a name already used is named values.<key>, attributes.<key> or properties.<key>. An empty page gives an empty frame with the fixed columns.

Raises:

Type Description
ValueError

units was given (observations are served as written).

plot

plot(
    kind: str | None = None,
    parameter: str | None = None,
    *,
    title: str | None = None,
) -> Any

A map (:func:stormlore.viz.observations) or a line per station over time (:func:stormlore.viz.observation_timeseries); viz extra.

kind=None picks "timeseries" when every row is one station at more than one time, else "map".

Raises:

Type Description
ValueError

kind is not "map", "timeseries" or None.

stormlore.results.Observation

Bases: Result

One observation or storm report (a GeoJSON point Feature, flattened).

Attributes:

Name Type Description
values dict[str, Any]

A customer source's numeric readings, {name: value}.

units dict[str, str]

The unit of each of values, when the source declared one.

attributes dict[str, str]

A customer source's text attributes, {name: text}.

properties dict[str, Any]

Everything else the source wrote, untouched (a platform source such as METAR or a storm report keeps its readings here).

distance_m float | None

Metres from the query point (observations.near only).

to_dataframe

to_dataframe(units: str | None = None) -> pd.DataFrame

One row: the fixed columns, then one column per value, attribute and property.

stormlore.results.StationList

Bases: Result

Stations (not paged: the API clamps the list by limit).

to_dataframe

to_dataframe(units: str | None = None) -> pd.DataFrame

One row per station: station_id, name, state, country, elevation_m, lat, lon, source, then any extra metadata.

plot

plot(*, title: str | None = None) -> Any

The stations on a map: :func:stormlore.viz.stations (viz extra).

stormlore.results.Station

Bases: Result

One observing station; properties holds any other metadata the source wrote.

stormlore.results.AreaPage

Bases: CursorPage

One page of area observations; iterate it, or index it.

to_dataframe

to_dataframe(units: str | None = None) -> pd.DataFrame

One row per area: id, source, start, end, the values, attributes and other properties (named as for observations), and geometry last (the GeoJSON mapping).

stormlore.results.Area

Bases: Result

One area observation (a polygon Feature); geometry is the GeoJSON mapping.

stormlore.results.SourceCatalog

Bases: Result

The observation sources your key can read; iterate it, or index it by source.

to_dataframe

to_dataframe(units: str | None = None) -> pd.DataFrame

One row per source: source, name, kind, category, earliest, latest, row_count, owner.

stormlore.results.StormReportCatalog

Bases: SourceCatalog

The storm report sources, and the report_types they carry.

stormlore.results.SourceCoverage

Bases: Result

One observation source and the span of data it holds.

kind is points or polygons; owner is true for your organisation's own sources.

stormlore.results.CountyRollups

Bases: Result

Storm report counts per county.

to_dataframe

to_dataframe(units: str | None = None) -> pd.DataFrame

One row per county: fips, county, state, total, then one column per year (0 where a county had none that year).

stormlore.results.CountyRollup

Bases: Result

Storm report counts for one county; by_year maps a year to its count.

stormlore.results.CursorPage

Bases: Page

One page of a cursor-paged listing.

next_cursor is None on the last page; otherwise pass it as cursor= to the same call for the next page (or use the matching iter_* method).

next property

next: str | None

next_cursor.

stormlore.results.RadarSeries

Bases: Result

Every MRMS frame at one place within [start, end), oldest first.

A missed radar sweep is not an error: it is simply one frame fewer. parameters names what was asked for, so an empty window still has its columns.

to_dataframe

to_dataframe(units: str | None = None) -> pd.DataFrame

Indexed by UTC valid_time, one column per parameter.

Zero frames give an empty frame with the parameter columns. units converts as the forecast results do; attrs["units"] names each column's units.

plot

plot(
    parameter: str | list[str] | None = None,
    *,
    units: str | None = None,
    title: str | None = None,
) -> Any

A line per parameter over the frames: :func:stormlore.viz.radar (viz extra).

stormlore.results.RadarFrame

Bases: Result

One raw MRMS frame: its time and the value of each parameter (None when missing).

stormlore.results.Score

Bases: Result

A model's current Shyft Score.

shyft_score (and value) is None when the API has no score stored for the model: that is an absence, not a zero.

value property

value: float | None

The score, or None when none is stored.

to_dataframe

to_dataframe(units: str | None = None) -> pd.DataFrame

One row (model, window_kind, methodology_version, value, ci_lower, ci_upper, provisional, n_components, reference, model_version, lanes_used, window_end), or zero rows with the same columns when no score is stored.

stormlore.results.ShyftScore

Bases: Result

A composite Shyft Score with its confidence interval.

stormlore.results.ScoreHistory

Bases: Result

A model's score, one point per calendar month; iterate it for the months.

unreadable counts stored months the API could not read and left out.

to_dataframe

to_dataframe(units: str | None = None) -> pd.DataFrame

One row per month, indexed by month (a UTC DatetimeIndex at the month's start). Columns: value, ci_lower, ci_upper, provisional, n_components, reference, methodology_version, model_version, window_start, window_end, provenance.

plot

plot(*, title: str | None = None) -> Any

The monthly score and its band: :func:stormlore.viz.score_history (viz extra).

stormlore.results.ScoreMonth

Bases: Result

One calendar month of a model's score history; month is YYYY-MM.

stormlore.results.RegionScores

Bases: Result

A model's score in each of the nine NCEI climate regions; iterate it for them.

to_dataframe

to_dataframe(units: str | None = None) -> pd.DataFrame

One row per region: region, code, name, value, ci_lower, ci_upper, provisional, n_components, reference, methodology_version, model_version, window_end.

stormlore.results.RegionScore

Bases: Result

A model's score in one NCEI climate region (code 101–109).

stormlore.results.MonthRanking

Bases: Result

Every model you can see, ranked by its score for one month; iterate it for them.

incomplete is true when a model's visibility could not be determined, truncated when the list was cut short, and unreadable counts stored scores left out.

to_dataframe

to_dataframe(units: str | None = None) -> pd.DataFrame

One row per model in the API's order, rank (1-based) first.

stormlore.results.RankedScore

Bases: Result

One model's score in a month's ranking.

stormlore.results.ModelBadges

Bases: Result

A model's badges, best first; headline is the first one's id (or None).

to_dataframe

to_dataframe(units: str | None = None) -> pd.DataFrame

One row per badge: id, family, label_key, window, first_month, last_month, rivals (the number of rivals; Badge.rivals keeps the detail).

stormlore.results.BadgeHeadlines

Bases: Result

The headline badge of every model that holds one; iterate it for them.

to_dataframe

to_dataframe(units: str | None = None) -> pd.DataFrame

One row per model: model, badge_count, then the headline badge's columns.

stormlore.results.ModelHeadline

Bases: Result

A model's headline badge and how many distinct badges it holds.

stormlore.results.Badge

Bases: Result

A slice a model beats its published rivals on (overall, a season, a region …).

first_month/last_month are YYYY-MM, None on a rolling badge.

stormlore.results.BadgeRival

Bases: Result

A rival compared on a badge's slice: ratio is its error over this model's.

stormlore.results.Scorecard

Bases: Result

A model's per-slice verification scores; iterate it for the entries.

truncated is true when the API capped the entries (at 5,000): narrow the filters. available lists what each filter can take.

to_dataframe

to_dataframe(units: str | None = None) -> pd.DataFrame

One row per entry: parameter, lead_time_hours, truth_source, region, metric, metric_qualifier, baseline_model, value, ci_lower, ci_upper, n_valid_times, n_samples_total, provisional, methodology_version, model_version, window_start, window_end.

stormlore.results.ScoreEntry

Bases: Result

One scorecard entry: a metric for one parameter, lead time, truth source and region.

stormlore.results.AppliedFilters

Bases: Result

The filters the API applied (default_regions: regions it chose for you).

stormlore.results.AvailableDimensions

Bases: Result

Every value each scorecard filter can take for this model.

stormlore.results.AdvisoryPage

Bases: Page, _GeometryAsked

One page of active advisories; iterate it, or index it.

count is the number of advisories on this page. next_offset is None on the last page; otherwise pass it as offset= for the next (or use iter_list).

next property

next: int | None

next_offset.

to_dataframe

to_dataframe(units: str | None = None) -> pd.DataFrame

One row per advisory.

Columns: id, event, severity, certainty, urgency, headline, area_desc, sent, effective, onset, expires, ends, source, provider, status, message_type, category, sender_name, description, instruction, ugc, zcta, zcta_status (ugc/zcta stay lists in the cell; times are UTC), then geometry whenever it was asked for (rows or not), then one column per key of a customer source's values and attributes. An attribute repeating a fixed column with the same value is dropped; a key that would take a name already used is named values.<key> or attributes.<key>. An empty page gives an empty frame with the fixed columns.

Raises:

Type Description
ValueError

units was given (advisories are served as written).

plot

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

The shapes on a map: :func:stormlore.viz.advisories (viz extra; ask with geometry=True).

stormlore.results.Advisory

Bases: Result

One active advisory.

Attributes:

Name Type Description
geometry dict[str, Any] | None

The GeoJSON shape, only when it was asked for (geometry=True); None for an advisory defined by zones alone.

ugc list[str]

The NWS zones it covers; zcta: the ZIP codes (ZCTAs) it covers.

values dict[str, Any]

A customer source's numeric readings, {name: value} (empty for NWS).

units dict[str, str]

The unit of each of values, when the source declared one.

attributes dict[str, str]

A customer source's text attributes (empty for NWS).

has_geometry property

has_geometry: bool

Whether the API sent geometry (it does only when asked, even if null).

to_dataframe

to_dataframe(units: str | None = None) -> pd.DataFrame

One row, with the columns of AdvisoryPage.to_dataframe().

stormlore.results.AdvisoryDetail

Bases: _GeometryAsked

One advisory, with as_of (when the active set was last refreshed) and active.

to_dataframe

to_dataframe(units: str | None = None) -> pd.DataFrame

One row, with the columns of AdvisoryPage.to_dataframe().

plot

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

The shapes on a map: :func:stormlore.viz.advisories (viz extra; ask with geometry=True).

stormlore.results.AdvisoryTypes

Bases: Result

The event names of the active advisories, with counts; iterate it for them.

to_dataframe

to_dataframe(units: str | None = None) -> pd.DataFrame

One row per event name, in the API's order: event, count.

stormlore.results.AdvisoryType

Bases: Result

An event name and how many active advisories carry it.

stormlore.results.ZipLookup

Bases: Result

The ZIP codes looked up; iterate it, or index it by ZIP code.

unknown lists the codes the reference data has no ZCTA for (data, not an error).

to_dataframe

to_dataframe(units: str | None = None) -> pd.DataFrame

One row per ZIP: zip, state, lat, lon, zones (the zones' UGC codes, a list in the cell; ZipInfo.zones keeps their type and name), same.

stormlore.results.ZipInfo

Bases: Result

One ZIP code: its state, a point inside it, its NWS zones and its SAME codes.

stormlore.results.ZipZone

Bases: Result

An NWS zone a ZIP overlaps; type is forecast, fire, county or marine.

stormlore.results.ZipVintage

Bases: Result

The reference data the answer came from (advisory zcta lists use the same).

stormlore.results.Page

Bases: Result

One page of a paged listing: next is what to ask for the next page with.

next property

next: Any

The cursor or offset of the next page; None on the last page.

has_more property

has_more: bool

Whether there is a next page.

stormlore.results.Health

Bases: Result

The API's health. status is healthy, empty or loading.

ok property

ok: bool

True when the API can serve (healthy or empty).

stormlore.results.VersionInfo

Bases: Result

What build of the API is running.