Skip to content
Mostly Right

mostlyright.weather

mostlyright.weather — direct public-API access for AWC, IEM, GHCNh, NWS CLI.

Local-first; no hosted backend; no API keys. The parsers (_awc / _iem / _climate / _ghcnh) are byte-faithful lifts from mostlyright==0.14.1 (namespace rename only); the HTTP fetchers and the parquet cache are net-new so the SDK can run without the v0.14.1 ingest service. _bounds lives under mostlyright._internal.

Parsers are a byte-faithful lift from the mostlyright monorepo v0.14.1 tag (source SHA 514fcda); the 0.14.1 oracle is no longer reachable — the parity fixtures in tests/fixtures/parity/ are the ground truth.

The public surface stays stable for the existing mostlyright==0.14.1 workflow: raw_metar is preserved on observation rows so a MetPy re-parse keeps working without preprocessing in v0.1.0.

mostlyright.weather.climate(station, from_date, to_date, , source=None, backend=‘pandas’, return_type=‘dataframe’)

Section titled “mostlyright.weather.climate(station, from_date, to_date, , source=None, backend=‘pandas’, return_type=‘dataframe’)”

Return NWS CLI daily settlement labels for station over [from_date, to_date].

The settlement source for Kalshi NHIGH/NLOW markets: the official NWS CLI daily high/low, merged via the frozen dedup policy (highest report_type_priority with STRICT > — overnight final wins).

  • Parameters:
    • station (str) – ICAO code (e.g. "KNYC") or 3-letter NWS code.
    • from_date (str) – ISO date strings (YYYY-MM-DD), inclusive bounds.
    • to_date (str) – ISO date strings (YYYY-MM-DD), inclusive bounds.
    • source ( {None , “iem” , “cli” , “cli.archive”} , keyword-only , default None) – Provenance selector. A degenerate single-authority axis: IEM CLI is the sole live provider, so every accepted value resolves to the same fetch. None means best-available (== "iem"). "acis" raises ValueError — there is no ACIS leg in this code path.
    • backend ( {“pandas” , “polars”} , keyword-only , default “pandas”) – Output frame type. "polars" requires return_type="wrapper" (polars frames carry no df.attrs for provenance).
    • return_type ( {“dataframe” , “wrapper” , “list”} , keyword-only , default “dataframe”) –
      • "dataframe" (default): a pandas.DataFrame with provenance on df.attrs.
      • "list": a plain list[dict] of rows.
      • "wrapper": a ProvenancedFrame.
  • Returns: One row per CLI settlement day with the public column contract: station, local_standard_date, daily_summary_temp_high_f, daily_summary_temp_low_f, daily_summary_report_type plus provenance source (per-row endpoint tag "iem") and issued_at_utc. Frame identity df.attrs["source"] == "cli.archive".
  • Return type: pd.DataFrame | list[dict]
  • Raises: ValueError – If source is not in {None, "iem", "cli", "cli.archive"}, if from_date/to_date are not ISO dates, or if the backend/return_type pair is incoherent (e.g. backend="polars", return_type="dataframe").

Notes

Section titled “Notes”
  • CLI is a daily batch product — climate() has NO grain axis and NO live surface (class 1: re-fetchable upstream).
  • This wraps the LOCAL CLI fetcher only; it makes NO hosted call.

Examples

Section titled “Examples”
>>> from mostlyright.weather import climate
>>> df = climate("KNYC", "2026-01-01", "2026-01-03")
>>> df.attrs["source"]
'cli.archive'

mostlyright.weather.forecasts(station, from_date=None, to_date=None, , source=‘model_output_statistics’, models=None)

Section titled “mostlyright.weather.forecasts(station, from_date=None, to_date=None, , source=‘model_output_statistics’, models=None)”

Return the settlement-day forecast frame for station over [from_date, to_date].

  • Parameters:
    • station (str) – The station id to fetch forecasts for.
    • from_date (DateLike | None) – Inclusive ISO start date (YYYY-MM-DD). Required.
    • to_date (DateLike | None) – Inclusive ISO end date (YYYY-MM-DD). Required.
    • source (str) – The forecast engine — "model_output_statistics" (alias "mos", default), "open_meteo", or "numerical_weather_prediction" (alias "nwp").
    • models (str | list[str] | None) – Product(s) WITHIN source. A str or single-item list for MOS/Open-Meteo; a list for raw NWP. Ambiguous multi-model MOS selections raise.
  • Return type: pd.DataFrame
  • Returns: The eager fcst_* frame keyed by station + settlement date.
  • Raises: ContractError – from_date/to_date is missing or the window is inverted (raised before any I/O); or source/models is invalid or ambiguous.

Example

Section titled “Example”
>>> from mostlyright.weather import forecasts
>>> df = forecasts("KNYC", "2025-01-01", "2025-01-07")

mostlyright.weather.observations(station, from_date=None, to_date=None, , source=None, backend=‘pandas’, return_type=‘dataframe’, timezone=None, quality_control=False)

Section titled “mostlyright.weather.observations(station, from_date=None, to_date=None, , source=None, backend=‘pandas’, return_type=‘dataframe’, timezone=None, quality_control=False)”

Return merged per-report observation rows for station over [from_date, to_date].

  • Parameters:
    • station (str | list[str] | tuple[str, …]) – ICAO code (e.g. "KNYC"), 3-letter NWS code, or a list/tuple of them (concatenated in input order).
    • from_date (DateLike | None) – Inclusive ISO start date (YYYY-MM-DD). Required.
    • to_date (DateLike | None) – Inclusive ISO end date (YYYY-MM-DD). Required.
    • source (Source | None) – If set, only that source ("iem" / "ghcnh" / "awc") is queried; otherwise every source whose coverage can reach the window is merged by priority (the GHCNh leg is skipped for window slices inside the station’s current LST month — NCEI’s publication lag — and for non-US stations).
    • backend (str) – Output frame backend ("pandas" / "polars").
    • return_type (str) – Output shape ("dataframe" / "list" / "wrapper").
    • timezone (str | None) – IANA timezone override for stations outside the registry.
    • quality_control (bool) – Attach QC status to returned rows.
  • Return type: pd.DataFrame | list[dict]
  • Returns: The merged per-report rows, each carrying event_time_utc, the bare parser source tag, raw_metar, and the LST local_standard_date. Shape follows return_type.
  • Raises:
    • ContractError – from_date or to_date is missing, or the window is inverted (raised before any I/O).
    • ValueError – source is not in its allowed set.
    • HttpError – a queried upstream failed in transport or with a non-404 HTTP status — never a raw httpx exception, and never a silently thinner frame.

Example

Section titled “Example”
>>> from mostlyright.weather import observations
>>> rows = observations("KNYC", "2024-03-01", "2024-03-31")

mostlyright.weather.satellite(station, satellite=None, product=None, , variable=None, from_time, to_time, as_of=None, delivery=‘live’, backend=‘pandas’, return_type=‘dataframe’)

Section titled “mostlyright.weather.satellite(station, satellite=None, product=None, , variable=None, from_time, to_time, as_of=None, delivery=‘live’, backend=‘pandas’, return_type=‘dataframe’)”

Fetch native-L2 satellite single-pixel values for one or more stations.

  • Parameters:
    • station (str | list[str]) – Single ICAO/NWS code or a list. Unknown codes are skipped with a logged warning (partial list -> partial DataFrame).
    • satellite (str | None) – A native-ring satellite id, or None (the default) to auto-route by the station’s coverage region (Wave 5) — GOES for the Americas/Pacific, Himawari for Asia-Pacific, Meteosat for Europe/Africa/Indian-Ocean (landed Wave 6; needs a Data-Store key only for the live fetch), and VIIRS for the poles and any band no landed geostationary source covers. Explicit values: GOES (all noaa_goes): "goes16"/"goes19" (GOES-East, CONUS) and "goes18" (operational GOES-West) / "goes17" (GOES-West archive) — West “C” covers PACUS (Pacific incl. Hawaii). Himawari (jma_himawari): "himawari8"/"himawari9". VIIRS (noaa_viirs): "viirs-npp"/"viirs-n20"/"viirs-n21". Meteosat (eumetsat_meteosat, KEYED): "meteosat-0deg"/"meteosat-iodc". When auto-routing, a single (source, satellite, product) triple is picked from the FIRST resolved station and applied to the whole call (MODEST routing). Cross-region caveat: auto-routing a station list that SPANS regions (e.g. ["KNYC", "RJTT"]) fetches every station on the first station’s source, so stations outside that footprint silently return no rows (off-disk -> dropped; leakage-safe but a partial frame). A WARNING is logged naming the divergent stations; prefer per-region calls or an explicit satellite= for mixed lists.
    • product (str | None) – Product id, or None (the default) to use the resolved source’s cheap default product (GOES "ABI-L2-ACMC", Himawari "AHI-L2-FLDK-Clouds", VIIRS "VIIRS-JRR-CloudMask", Meteosat "MSG-CLM"). "ABI-L2-DSRF" emits a one-time gating warning (D6) on the live path.
    • variable (str | None) – Optional single-variable filter; None keeps every registered variable of product.
    • from_time (datetime) – Event-time window start (UTC, tz-aware recommended). Typed datetime — sub-day times are honored (the window is filtered back precisely after the day-grain fetch).
    • to_time (datetime) – Event-time window end. to_time < from_time raises ValueError. A midnight (date-granular) bound means “through the end of that UTC day”.
    • as_of (Any) – Knowledge-time cutoff. TimePoint | datetime | None. Filters in-process on typed datetimes via KnowledgeView; a naive datetime is rejected loudly (NOT a lexical string snapshot, D4).
    • delivery (str) – "live" (default) self-parses public data directly and makes NO hosted call; "hosted" fetches the deployed weather serving endpoint ${MOSTLYRIGHT_WEATHER_HOSTED_URL}/satellite with the MOSTLYRIGHT_API_KEY header and returns rows byte-identical to delivery="live" (delivery is informational lineage, not source identity). Hosted is OPT-IN via the two env seams; the default live path never touches it.
    • backend (str) – "pandas" (default) or "polars".
    • return_type (str) – "dataframe" (default) or "wrapper".
  • Return type: DataFrame
  • Returns: pd.DataFrame carrying the satellite rows plus the leakage overlay columns (source/event_time/knowledge_time/retrieved_at/ delivery) and qc_status, with df.attrs["source"] set to the resolved per-source identity (noaa_goes for GOES, and the other native-ring sources forward as their adapters land).
  • Raises:
    • ValueError – satellite/product/delivery not in their enums (or product not registered for satellite’s source), or to_time < from_time, or a naive as_of datetime.
    • SourceUnavailableError – the [satellite] optional extra is absent.

mostlyright.weather.training_table(station, from_date, to_date, , label=‘cli’, **_unsupported)

Section titled “mostlyright.weather.training_table(station, from_date, to_date, , label=‘cli’, **_unsupported)”

A built-in supervised-table example: features -> label rows.

Returns one row per station-settlement-day — the label="cli" settlement target (Kalshi NHIGH/NLOW ground truth) beside the observation feature aggregates. The recipe keeps its cutoff fields visible and applies the timing metadata available from its sources. The label="cli" default is EXPLICIT and contractually stable (no FutureWarning, no deprecation path). Two positional dates, inclusive ends. label="daily_extremes" swaps in the Polymarket WU/NOAA-WRH target.

Example

Section titled “Example”
>>> from datetime import date
>>> from mostlyright import weather
>>> table = weather.training_table(
...     "KNYC", date(2025, 1, 6), date(2025, 1, 12)
... )
  • Parameters:
    • station (str | list[str] | tuple[str, …]) – A station id (or a list -> a long-format panel).
    • from_date (DateLike) – YYYY-MM-DD inclusive start.
    • to_date (DateLike) – YYYY-MM-DD inclusive end.
    • label (Label) – The settlement label recipe — "cli" (default) or "daily_extremes".
    • _unsupported (object)
  • Return type: pd.DataFrame
  • Returns: The training table (the settlement y columns + the obs_* observation feature aggregates), one row per station-settlement-day.
  • Raises:
    • TypeError – an unsupported keyword was passed — training_table() is capped. For anything beyond the capped surface, compose the raw weather.observations() / weather.forecasts() sources yourself and join them per the feature-engineering doc; the message names that path, never an internal API.
    • HttpError – an upstream fetch (label or observations) failed in transport or with an HTTP error status — never a raw httpx exception.

Modules

Section titled “Modules”
cacheLocal parquet cache for mostlyright weather observations and climate.
catalogWeather catalog package.
climate(station, from_date, to_date, *[, …])Return NWS CLI daily settlement labels for station over [from_date, to_date].
cwopmostlyright.weather.cwop — standalone CWOP (Citizen Weather Observer Program) live adapter.
forecast_nwpPublic NWP-forecast surface (live HRRR/GFS/NBM).
forecasts(station[, from_date, to_date, …])Return the settlement-day forecast frame for station over [from_date, to_date].
labelweather.label.* — the .label.-registered weather spine FACTORIES (04).
nwpmostlyright.weather.nwp — raw cycle-grain NWP forecasts.
qcWeather QC rules + per-model NWP physics-bounds registry.
qc_sidecarObservation QC sidecar writer.
satellite(station[, satellite, product, …])Fetch native-L2 satellite single-pixel values for one or more stations.
spineInternal per-settlement-day weather spine constructor.
stationsmostlyright.weather.stations — the canonical home for the station catalog.
training_table(station, from_date, to_date, *)A built-in supervised-table example: features -> label rows.