Skip to content

mostlyright.weather.satellite

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

Section titled “mostlyright.weather.satellite(station=None, satellite=None, product=None, , lat=None, lon=None, site_id=None, tz_override=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] | None) – Single ICAO/NWS code or a list, resolved against the settlement registry first and then the full packaged station catalog. Unknown codes are skipped with a logged warning (partial list -> partial DataFrame). Mutually exclusive with lat/lon: exactly one of the two identity forms must be supplied.
    • lat (float | None) – Latitude of a coordinate site, in decimal degrees. Given together with lon, addresses an arbitrary point that need not exist in any registry or catalog; its identity is the derived site id (40.7789, -73.9692 -> "N4078W07397"), which is what selects the cache partition, the object-store key, and the row’s station value. Supplying only one of lat/lon raises.
    • lon (float | None) – Longitude of a coordinate site, in decimal degrees (negative = west). See lat.
    • site_id (str | None) – Override the derived identity of a coordinate site. Coordinate mode only. It cannot claim an allocated station’s identifier (nor a merely ICAO-shaped one) unless the supplied coordinates are that station’s own grid cell — identity selects which partition receives rows, so an accepted site_id="KNYC" beside arbitrary coordinates would write non-KNYC pixels into the KNYC settlement-feeding namespace.
    • tz_override (str | None) – Override a coordinate site’s timezone, which otherwise comes from the nearest packaged-catalog station (precomputed at build time — no runtime geo dependency). Coordinate mode only.
    • satellite (str | None) – A native-ring satellite id, or None (the default) to auto-route by the station’s coverage region — GOES for the Americas/Pacific, Himawari for Asia-Pacific, Meteosat for Europe/Africa/Indian Ocean (needs a Data Store key only for the live fetch), and VIIRS for the poles and any band no supported 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, needs a key): "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. 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 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 rather than compared as a string.
    • delivery (str) – "live" (default) 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 records the channel, not source identity). Hosted is opt-in via those two environment variables; 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 temporal 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 matching id for each other native-ring source).
  • Raises:
    • ContractError – the identity arguments conflict — station given beside lat/lon, only one of lat/lon, neither form, or a coordinate-only override (site_id/tz_override) in station mode. Raised before any I/O.
    • 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, or a coordinate that is out of range / not finite, or a site_id that claims a reserved identifier.
    • SourceUnavailableError – the [satellite] optional extra is absent.