Skip to content

data.ISD

NA

Import path: earth2studio.data.ISD

View source on GitHub

Documentation

NOAA's Integrated Surface Database (ISD) is a global database that consists of hourly and synoptic surface observations compiled from numerous sources into a common data model.

Parameters:

  • stations (list[str]) –

    Station IDs as the concatenation of USAF (6 chars) and WBAN (5 digits) to attempt to fetch data from.

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

    Time tolerance window for filtering observations. Accepts a single value (symmetric ± window) or a tuple (lower, upper) for asymmetric windows, by default np.timedelta64(10, 'm')

  • cache (bool, default: True ) –

    Cache data source on local memory, by default True

  • verbose (bool, default: True ) –

    Print download progress and missing data warnings, by default True

  • async_timeout (int, default: 600 ) –

    Time in sec after which download will be cancelled if not finished successfully, by default 600

Warning

This is a remote data source and can potentially download a large amount of data to your local machine for large requests.

Note

To help get a list of possible station IDs, this class includes ISD.get_stations_bbox which accepts a lat-lon bounding box and will return known historical stations IDs. For more information on the stations, users should consult the isd-history.csv which can easily accessed with ISD.get_station_history

Note

Additional information on the data repository can be referenced here:

Example 
# Bay area, lat lon bounding box (lat min, lon min, lat max, lon max)
stations = ISD.get_stations_bbox((36, -124, 40, -120))
ds = ISD(stations, time_tolerance=timedelta(hours=2))
df = ds(datetime(2024, 1, 1, 20), ["t2m", "ws10m"])

__call__ 

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

Function to get data

Parameters:

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

    Timestamps to return data for (UTC).

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

    String, list of strings or array of strings that refer to variables to return. Must be in the ISD lexicon.

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

    Fields to include in output, by default None (all fields).

Returns:

fetch async 

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

Async function to get data

Parameters:

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

    Timestamps to return data for (UTC).

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

    String, list of strings or array of strings that refer to variables (column ids) to return. Must be in the ISD lexicon.

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

    Fields to include in output, by default None (all fields).

Returns: