IBTrACS#

class earth2studio.data.IBTrACS(
region='ALL',
time_tolerance=numpy.timedelta64(0),
cache=True,
verbose=True,
async_timeout=600,
async_workers=4,
retries=3,
)[source]#
Global

International Best Track Archive for Climate Stewardship (IBTrACS) data source.

IBTrACS provides global tropical cyclone best track data compiled from various regional agencies (NHC, JTWC, JMA, etc.) into a standardized format. This source returns track observations as a DataFrame with storm metadata.

Parameters:

  • region (str | list[str]) –

    IBTrACS region code(s) to fetch. Valid codes: - Basin codes: "NA" (North Atlantic), "EP" (Eastern Pacific),

    "WP" (Western Pacific), "SP" (South Pacific), "NI" (North Indian), "SI" (South Indian), "SA" (South Atlantic)

    • Combined datasets: "ALL" (all basins), "since1980" (satellite era), "last3years" (recent storms), "ACTIVE" (currently active)

  • time_tolerance (TimeTolerance, optional) – Time tolerance window for filtering observations. Accepts a single value (symmetric +/- window) or a tuple (lower, upper) for asymmetric windows, by default np.timedelta64(0)

  • cache (bool, optional) – Cache data source on local memory, by default True

  • verbose (bool, optional) – Print download progress and missing data warnings, by default True

  • async_timeout (int, optional) – Time in sec after which download will be cancelled if not finished successfully, by default 600

  • async_workers (int, optional) – Maximum number of concurrent async fetch tasks, by default 4

  • retries (int, optional) – 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 "ALL" region file is ~23 MB.

Note

IBTrACS files are updated frequently (especially "ACTIVE"). This source checks the server’s Last-Modified header and re-downloads when the remote file is newer than the cached version.

Note

Additional information on the data repository can be referenced here:

Example

from datetime import datetime, timedelta
from earth2studio.data import IBTrACS

# Fetch North Atlantic and Eastern Pacific storms
ds = IBTrACS(region=["NA", "EP"], time_tolerance=timedelta(days=1))
df = ds(datetime(2024, 9, 1), ["tcwnd", "mslp"])

# Get active storms
ds_active = IBTrACS(region="ACTIVE")
df_active = ds_active(datetime.utcnow(), ["tcwnd", "mslp"])
__call__(time, variable, fields=None)[source]#

Retrieve tropical cyclone track observations.

Parameters:

  • time (datetime | list[datetime] | TimeArray) – Timestamps to return data for (UTC).

  • variable (str | list[str] | VariableArray) – Variable names from the IBTrACS lexicon.

  • fields (str | list[str] | pa.Schema | None, optional) – Fields to include in output, by default None (all fields).

Returns:

IBTrACS track observations with columns matching the schema.

Return type:

pd.DataFrame

async fetch(time, variable, fields=None)[source]#

Async function to get tropical cyclone track data.

Parameters:

  • time (datetime | list[datetime] | TimeArray) – Timestamps to return data for (UTC).

  • variable (str | list[str] | VariableArray) – Variable names from the IBTrACS lexicon.

  • fields (str | list[str] | pa.Schema | None, optional) – Fields to include in output, by default None (all fields).

Returns:

IBTrACS track observations.

Return type:

pd.DataFrame

classmethod available(time)[source]#

Check if given date time is available.

Parameters:

time (datetime | np.datetime64) – Date time to check.

Returns:

If date time is available.

Return type:

bool