Skip to content

Forecasts

A historical forecast is useful only when you know when the run became available. Mostly Right keeps issuance and valid time attached so you can compare each run with the decision cutoff.

Local-standard-day forecasts

Section titled “Local-standard-day forecasts”

weather.forecasts() is the stable, eager read. Both inclusive dates are required:

from mostlyright import weather


mos = weather.forecasts(
    "KNYC",
    "2025-01-01",
    "2025-01-31",
)

The default source is "model_output_statistics" (alias "mos"). Other supported source families are "open_meteo" and "numerical_weather_prediction" (alias "nwp").

Use models= to choose a product within that source:

nbm = weather.forecasts(
    "KNYC",
    "2025-01-01",
    "2025-01-31",
    source="model_output_statistics",
    models="nbm",
)


gfs_and_hrrr = weather.forecasts(
    "KNYC",
    "2025-01-01",
    "2025-01-31",
    source="numerical_weather_prediction",
    models=["gfs", "hrrr"],
)

The result is keyed to the station’s local-standard-day calendar and exposes forecast feature columns with the fcst_* prefix.

Join forecasts to a target

Section titled “Join forecasts to a target”

Read forecasts explicitly and join them with pandas, Polars, or your own TypeScript code. Keep issued_at_utc beside each row and require it to be at or before the simulated decision cutoff. Do not replace an unknown availability time with the forecast’s target time.

Raw cycle-grain NWP in Python

Section titled “Raw cycle-grain NWP in Python”

weather.nwp.forecasts() fetches a model cycle and forecast hour:

from datetime import datetime, timezone
from mostlyright.weather import nwp


raw = nwp.forecasts(
    "KNYC",
    "hrrr",
    cycle=datetime(2025, 1, 6, 6, tzinfo=timezone.utc),
    forecast_hour=12,
)

forecast_hour is the 2.0 keyword. The old fxx name is gone.

Install the optional decoder packages when you use raw GRIB2:

Terminal window
pip install "mostlyrightmd-weather[nwp]"

NCEP models including HRRR, GFS, NBM, RAP, RTMA, URMA, GEFS, and CFS have wired Python paths. Other names may be reserved, live-only, or unavailable; typed errors explain the model’s status rather than substituting a different run.

Use cycle_range_start and cycle_range_end for a series of runs, and member= for member-capable ensembles.

TypeScript

Section titled “TypeScript”

TypeScript supports IEM MOS. Raw gridded NWP remains a typed stub because the runtime does not ship a production GRIB2 decoder:

import { forecastNwp } from "@mostlyrightmd/weather";
import { NwpNotAvailableError } from "@mostlyrightmd/core";


try {
  await forecastNwp("KNYC", "hrrr");
} catch (error) {
  if (error instanceof NwpNotAvailableError) {
    console.warn(error.hint);
  } else {
    throw error;
  }
}

Use the TypeScript MOS read for station-level work, or run Python NWP behind your own service.

Daily-summary gaps

Section titled “Daily-summary gaps”

weather.daily_summary_gaps() reports dates whose CLI cache year is absent:

from mostlyright import weather


missing = weather.daily_summary_gaps(
    "KNYC",
    "2024-11-01",
    "2025-04-30",
)

This is a coarse cache-coverage signal, not proof that every row in a cached year exists. For row-level label coverage, compare the returned daily-summary rows with the expected settlement dates.

The TypeScript dailySummaryGaps() lane is deferred.

Score with time in view

Section titled “Score with time in view”

Compare forecasts to the settlement label, not to a later revised proxy:

error = (
    frame["fcst_high_f_nwp_gfs"]
    - frame["daily_summary_temp_high_f"]
).abs().mean()

Keep these rules:

  1. Split chronologically.
  2. Select only forecast runs issued before the decision cutoff.
  3. Recompute rolling features within each fold.
  4. Compare against the label the target venue actually uses.

Errors

Section titled “Errors”
  • ContractError for missing/inverted windows or invalid source/model selections
  • NWPModelNotAvailableError for reserved Python models
  • HistoricalDepthError for a model without the requested archive depth
  • SourceUnavailableError when the Python [nwp] extra is missing
  • NoLiveForNWPError when every configured mirror is unavailable

See also

Section titled “See also”