Skip to content
Mostly Right

Guides

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.

Compose with a target

Section titled “Compose with a target”

weather.training_table() intentionally contains only the default observation features. When you need forecasts, read the source explicitly and join it with your normal dataframe tooling. Apply knowledge_time <= decision_time only when the source carries a reliable knowledge timestamp.

The experimental align() helper accepts DeferredSource values or explicit (DataFrame, SourceContract) pairs. It does not accept bare eager frames. align() is semver-exempt; the raw domain reads are stable.

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.

Climate gaps

Section titled “Climate gaps”

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

from mostlyright import weather


missing = weather.climate_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, diff the returned climate rows against the expected settlement dates.

The TypeScript climateGaps() 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”