Skip to content

data.IBTrACS

Global

Import path: earth2studio.data.IBTrACS

View source on GitHub

Documentation

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], default: 'ALL' ) –

    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, default: timedelta64(0) ) –

    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, 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

  • async_workers (int, default: 4 ) –

    Maximum number of concurrent async fetch tasks, by default 4

  • 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 "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__ 

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

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] | Schema | None, default: None ) –

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

Returns:

  • DataFrame –

    IBTrACS track observations with columns matching the 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 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] | Schema | None, default: None ) –

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

Returns:

  • DataFrame –

    IBTrACS track observations.

available classmethod 

available(time: datetime | datetime64) -> bool

Check if given date time is available.

Parameters:

Returns:

  • bool –

    If date time is available.