Skip to content

data.GOESGLM

NASA

Import path: earth2studio.data.GOESGLM

View source on GitHub

Documentation

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

Returns per-event 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 optical event detected by GLM with a sub-second timestamp, latitude/longitude, and the requested measurement (flashe for optical energy in Joules, flashc for a constant 1.0 per detected event 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 events 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 events 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 events on parse and keep time_tolerance bounded.

Note

Output longitudes are normalised to [0, 360) (Earth2Studio convention). Each event's timestamp is computed from the file's event_time_offset variable so per-event precision (~ms) is preserved.

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), ["flashe", "flashc"])

__call__ 

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

Fetch GLM lightning events for a set of timestamps.

Parameters:

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

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

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

    Variable ids defined in earth2studio.lexicon.GOESGLMLexicon ("flashe" and/or "flashc").

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

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

Returns:

  • DataFrame –

    Event-level 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 events.

Parameters:

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

    Timestamps to return events 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 –

    Event-level 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: