Skip to content

GOESGLM

NASANOAA

Import path: earth2studio.data.GOESGLM

View source on GitHub

Documentation

NOAA GOES Geostationary Lightning Mapper (GLM) Level 2 Lightning Cluster-Filter Algorithm (LCFA) point lightning data source.

Returns per-detection lightning observations from the GLM instrument on GOES-16/17/18/19, served as point observations in a pandas DataFrame. Each row corresponds to a single detection with a sub-second timestamp, latitude/longitude and the requested measurement.

All three tiers of the GLM detection hierarchy are exposed, and may be mixed freely in one request since they are read from the same files:

  • events (lightning_event_*) — individual illuminated pixels in a single 2 ms frame
  • groups (lightning_group_*) — spatially adjacent events within one frame
  • flashes (lightning_flash_*) — groups clustered in space and time; timestamped by their first constituent event

Each level offers *_energy (optical energy, Joules) and *_count (a constant 1.0 per record, suitable for density aggregation).

Files in the public NOAA AWS bucket are NetCDFs produced at roughly 20 second cadence covering the GOES full-disk field of view. A spatial bounding box can be supplied to restrict detections at parse time and reduce memory usage for large windows.

Parameters:

  • satellite (str, default: 'east' ) –

    Source satellite selector. Pass "east" (default) or "west" to auto-select the active GOES-East / GOES-West platform for each requested timestamp; pass "G16", "G17", "G18" or "G19" to pin a single platform.

  • lat_lon_bbox (tuple[float, float, float, float] | None, default: None ) –

    Bounding box (lat_min, lon_min, lat_max, lon_max) in degrees, applied at parse time. Accepts either [-180, 180) or [0, 360) longitude convention (auto-detected when lon_max >= 180). None (default) returns the full disk. For example, CONUS in the [-180, 180) convention is (24.5, -125.0, 49.5, -66.0).

  • time_tolerance (TimeTolerance, default: timedelta64(2, 'm') ) –

    Time tolerance window for selecting detections around each requested timestamp. Accepts a single value (symmetric ± window) or a tuple (lower, upper) for asymmetric windows, by default np.timedelta64(2, "m").

  • cache (bool, default: True ) –

    Cache downloaded NetCDF files on local disk, by default True.

  • verbose (bool, default: True ) –

    Show download progress bar, by default True.

  • async_timeout (int, default: 600 ) –

    Total timeout in seconds for the entire fetch operation, by default 600.

  • async_workers (int, default: 24 ) –

    Maximum number of concurrent S3 fetch tasks, by default 24.

  • retries (int, default: 3 ) –

    Number of retry attempts per failed fetch task with exponential backoff, by default 3.

Warning

GLM produces hundreds of files per hour. Large time windows can download tens to hundreds of gigabytes of NetCDFs. Use lat_lon_bbox to discard out-of-region detections on parse and keep time_tolerance bounded.

Note

Output longitudes are normalised to [0, 360) (Earth2Studio convention). Each record's timestamp is computed from the file's per-level time offset variable so sub-second precision (~ms) is preserved.

Note

The pre-0.19 variable ids flashe and flashc are deprecated aliases of lightning_event_energy and lightning_event_count. They still select the correct measurement and are echoed back in the output variable column, but emit a FutureWarning and will be removed in a future release.

Note

Additional information on the data repository:

Example 
from datetime import datetime
import numpy as np
from earth2studio.data import GOESGLM

ds = GOESGLM(
    satellite="east",
    lat_lon_bbox=(24.5, -125.0, 49.5, -66.0),  # CONUS
    time_tolerance=np.timedelta64(5, "m"),
)
df = ds(
    datetime(2024, 6, 1, 18, 0),
    ["lightning_event_energy", "lightning_event_count"],
)

__call__ 

__call__(
    time: datetime | list[datetime] | TimeArray,
    variable: str | list[str] | VariableArray,
    fields: str | list[str] | Schema | None = None,
) -> DataFrame

Fetch GLM lightning detections for a set of timestamps.

Parameters:

  • time (datetime | list[datetime] | TimeArray) –

    Timestamps to return detections for (UTC). Timezone-aware datetimes are converted to UTC automatically.

  • variable (str | list[str] | VariableArray) –

    Variable ids defined in earth2studio.lexicon.GOESGLMLexicon, e.g. "lightning_event_energy" or "lightning_flash_count". Event-, group- and flash-level ids may be mixed.

  • fields (str | list[str] | Schema | None, default: None ) –

    Output column subset. None (default) returns all schema fields.

Returns:

  • DataFrame –

    Long-format lightning observations with columns matching the resolved schema.

fetch async 

fetch(
    time: datetime | list[datetime] | TimeArray,
    variable: str | list[str] | VariableArray,
    fields: str | list[str] | Schema | None = None,
) -> DataFrame

Async function to fetch GLM detections.

Parameters:

  • time (datetime | list[datetime] | TimeArray) –

    Timestamps to return detections for (UTC).

  • variable (str | list[str] | VariableArray) –

    Variable ids defined in GOESGLMLexicon.

  • fields (str | list[str] | Schema | None, default: None ) –

    Output column subset. None (default) returns all schema fields.

Returns:

  • DataFrame –

    Long-format lightning observations.

available classmethod 

available(time: datetime | datetime64) -> bool

Check whether data is available for a given time.

Offline check against the GLM archive window; per-slot platform cutovers are enforced when the source is called.

Parameters:

Returns: