Skip to content
Mostly Right

mostlyright.weather.satellite

mostlyright.weather.satellite

Section titled “mostlyright.weather.satellite”

mostlyright.weather.satellite(station, satellite=None, product=None, , variable=None, start, end, qc=‘clean’, as_of=None, mirror=‘aws’, delivery=‘live’, cache=True, max_workers=8, backend=‘pandas’, return_type=‘dataframe’)

Section titled “mostlyright.weather.satellite(station, satellite=None, product=None, , variable=None, start, end, qc=‘clean’, as_of=None, mirror=‘aws’, delivery=‘live’, cache=True, max_workers=8, 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.
    • start (datetime) – Event-time window start (UTC, tz-aware recommended).
    • end (datetime) – Event-time window end. end < start raises ValueError.
    • qc (str) – Reserved qc-filter knob (annotate-never-drop — no row is dropped).
    • 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).
    • mirror (str) – "aws" (default) or "gcp" — the D9 TRANSPORT selector. Validated with a loud ValueError BEFORE any I/O. Mirror is transport-only: the source identity stays "noaa_goes" and there is NO mirror row column.
    • delivery (str) – "live" (default) self-parses public data directly and makes NO hosted call; "hosted" (28-31) fetches the deployed weather serving endpoint ${WEATHER_HOSTED_URL}/satellite with the MOSTLYRIGHT_API_KEY header and returns rows byte-identical to delivery="live" (D-28.2 — delivery is informational lineage, not source identity). Hosted is OPT-IN via the two env seams; the default live path never touches it.
    • cache (bool) – Reserved cache toggle (per-partition parquet tier, 25-03).
    • max_workers (int) – Reserved thread fan-out width (documented UNTUNED, D10).
    • backend (str) – "pandas" (default) or "polars".
    • return_type (str) – "dataframe" (default) or "result".
  • 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/mirror/delivery not in their enums (or product not registered for satellite’s source), or end < start, or a naive as_of datetime.
    • SourceUnavailableError – the [satellite] optional extra is absent.