mostlyright.weather.forecast_nwp

Public NWP-forecast surface (live HRRR/GFS/NBM).

End-to-end pipeline:

1. Validate (model, mirror) against the closed enums in mostlyright.weather._fetchers._nwp_archive. Reserved ECMWF models raise NWPModelNotAvailableError.
2. Resolve cycle (default: latest cycle whose lead time covers the requested fxx).
3. For each mirror in the fallback chain: fetch the .idx text (Content-Length HEAD issued lazily, only when the file’s final record is needed), parse + filter to the model’s VARIABLE_MAP records, fetch each record via Range: bytes=.., write the concatenated bytes to a one-message-per-file GRIB2 in a temp directory, decode with cfgrib, extract per-station values with the cached BallTree, populate the canonical DataFrame.
4. Run inline physics-bounds QC; tag each row with qc_status ∈ {clean, flagged, suspect}.
5. Validate the assembled DataFrame against schema.forecast.nwp.v1.

If all wired mirrors fail, raise NoLiveForNWPError carrying the mirror chain. If any byte-range fetch returns bytes that fail GRIB2 structural checks, raise GRIBIntegrityError.

This module imports cfgrib / xarray / sklearn lazily inside forecast_nwp() so the module imports cleanly even without the [nwp] extra installed. The optional-extra hint is surfaced via SourceUnavailableError.

Functions

forecast_nwp(station, model, *[, cycle, …])	Fetch NWP forecast values for one or more stations from NOAA BDP.

mostlyright.weather.forecast_nwp.forecast_nwp(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).