Skip to content
Mostly Right

mostlyright.weather.nwp

mostlyright.weather.nwp — raw cycle-grain NWP forecasts.

weather.nwp.forecasts(station, model, ...) is the raw, cycle-addressed NWP capability (live HRRR/GFS/NBM + the wider NCEP family): frames are keyed by model run cycle + forecast hour, GRIB2-derived, and validated against schema.forecast.nwp.v1. This is the ONLY public route to cycle-grain forecast frames — distinct from the settlement-day weather.forecasts() verb, which returns one row per LST settlement day.

The implementation lives in mostlyright.weather.forecast_nwp; this namespace re-exports it under the clean forecasts name.

mostlyright.weather.nwp.forecasts(station, model, , cycle=None, cycle_range_start=None, cycle_range_end=None, forecast_hour=None, member=None, client=None, backend=‘pandas’, return_type=‘dataframe’)

Section titled “mostlyright.weather.nwp.forecasts(station, model, , cycle=None, cycle_range_start=None, cycle_range_end=None, forecast_hour=None, member=None, client=None, backend=‘pandas’, return_type=‘dataframe’)”

Fetch NWP forecast values for one or more stations from NOAA BDP.

  • Parameters:
    • station (str | list[str]) – Single ICAO/NWS code or a list of them. Unknown codes are skipped with a logged warning (not raised) so a partial list still returns a partial DataFrame.
    • model (str) – One of SUPPORTED_NWP_MODELS ("hrrr", "gfs", "nbm"). ECMWF Tier-2 values raise NWPModelNotAvailableError.
    • cycle (datetime | None) – Model run cycle (UTC, tz-aware). Default: the most recent cycle whose run + forecast_hour clears a 90-minute upload backoff.
    • forecast_hour (int | None) – Forecast hour ahead of cycle. Default 1 (next hour); 0 for the rtma/urma analysis products (no forecast hour). The emitted frame carries the matching forecast_hour output column, so input and output share one word.
    • member (str | None) – Ensemble member id — only valid for the member-capable models GEFS (e.g. "p05", default "c00") and CFS ("01"..“”04”, default ``"01"). None (the default) keeps the path-builder default and is byte-identical to pre-issue-#74 behavior. Threaded to the GEFS/CFS path builder only when non-None.
    • client (Client | None) – Reuse an httpx.Client for connection pooling. A fresh client is created (and closed) per call if omitted.
    • cycle_range_start (datetime | None)
    • cycle_range_end (datetime | None)
    • backend (str)
    • return_type (str)
  • Return type: DataFrame
  • Returns: pd.DataFrame matching schema.forecast.nwp.v1 — one row per (station, variable subset) for the given cycle/forecast_hour. Empty DataFrame (with the canonical columns) if every requested station is unknown OR the model variable map matches no records in the upstream .idx (genuinely missing variables).
  • Raises:
    • NWPModelNotAvailableError – model is reserved (ECMWF Tier-2).
    • ValueError – model is not in the supported set; forecast_hour is negative; cycle is naive; member is set for a non-member model, or is not a valid member of the requested model’s ensemble (GEFS/CFS).
    • SourceUnavailableError – the [nwp] optional extra (cfgrib + xarray + sklearn) is not installed.
    • NoLiveForNWPError – every wired mirror failed (typically while the upstream is still uploading a cycle).
    • GRIBIntegrityError – at least one fetched record decoded with structural failures (Pitfall 1 territory — cfgrib raises for a truncated final-record byte range).