MeteosatLI

EUAFEUMETSAT

Import path: earth2studio.data.MeteosatLI

View source on GitHub

Documentation

EUMETSAT MTG-I LI Level-2 pointed lightning data source.

Returns per-detection lightning observations from the Meteosat Third Generation (MTG) Lightning Imager (LI), served as point observations in a pandas DataFrame. The Level-2 processing clusters optical detections into a three-level hierarchy, each published as a separate EUMETSAT Data Store collection:

• LFL Lightning Flashes, the coarsest level (lightning_flash_* variables)
• LGR Lightning Groups, detections clustered per integration frame (lightning_group_* variables)
• LEF Lightning Events Filtered, individual pixel detections that were retained by the flash clustering (lightning_event_* variables)

The collection a request reads from is determined by the requested variables, so only the products actually needed are downloaded. Each row carries the detection time, latitude/longitude and the requested measurement, with radiance reported in mW m-2 sr-1. The lightning_*_count variables are a constant 1.0 per record, suitable for density aggregation.

Parameters:

• 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 the [-180, 180) or the [0, 360) longitude convention (auto-detected when lon_max >= 180). None (default) returns the full disk. For example, Europe in the [-180, 180) convention is (35.0, -12.0, 60.0, 30.0).

• time_tolerance (TimeTolerance, default: timedelta64(5, '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(5, "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: 8 ) –

  Maximum number of concurrent Data Store fetch tasks, by default 8

• retries (int, default: 3 ) –

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

Warning

This is a remote data source and can potentially download a large amount of data to your local machine for large requests. The LEF product contains hundreds of thousands of detections per 10 minute granule; prefer lightning_flash_* variables and a bounded time_tolerance for large time windows.

Note

Requires EUMETSAT Data Store credentials. Set the following environment variables:

• EUMETSAT_CONSUMER_KEY: Your EUMETSAT API consumer key
• EUMETSAT_CONSUMER_SECRET: Your EUMETSAT API consumer secret

Register at eoportal.eumetsat.int/ to obtain credentials.

Note

Output longitudes are normalised to [0, 360) (Earth2Studio convention). Detection times are decoded from each product's native seconds since 2000-01-01 encoding, so sub-second precision is preserved. Products are archived as 10 minute granules; a granule is downloaded whenever it overlaps a requested tolerance window.

Note

Additional information on the data repository:

• user.eumetsat.int/resources/user-guides/mtg-li-level-2-data-guide
• data.eumetsat.int/product/EO:EUM:DAT:0691
• user.eumetsat.int/s3/eup-strapi-media/MTG_LI_Level_2_Format_Specification_12c067c926.pdf

Example

from datetime import datetime
import numpy as np
from earth2studio.data import MeteosatLI

ds = MeteosatLI(
    lat_lon_bbox=(35.0, -12.0, 60.0, 30.0),  # Europe
    time_tolerance=np.timedelta64(5, "m"),
)
df = ds(
    datetime(2025, 6, 15, 12, 0),
    ["lightning_flash_radiance", "lightning_flash_count"],
)

__call__

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

Fetch LI lightning detections for a set of timestamps.

Parameters:

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

  Timestamps to return detections for (UTC).

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

  Variable ids defined in earth2studio.lexicon.MeteosatLILexicon.

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

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

Returns:

• DataFrame –

  Detection-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 LI lightning detections.

Parameters:

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

  Timestamps to return detections for (UTC).

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

  Variable ids defined in MeteosatLILexicon.

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

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

Returns:

• DataFrame –

  Detection-level lightning observations.

available classmethod

available(time: datetime | datetime64) -> bool

Check whether data is available for a given time.

Offline check against the LI Level-2 archive window.

Parameters:

• time (datetime | datetime64) –

  Date-time to check.

Returns:

• bool –

  Whether the requested date time is available.