CFS_FX#

class earth2studio.data.CFS_FX(
member=1,
source='nomads',
cache=True,
verbose=True,
async_timeout=600,
async_workers=16,
retries=3,
)[source]#
Global

NCEP Climate Forecast System v2 (CFSv2) pressure-level forecast source.

CFSv2 is NCEP’s operational coupled atmosphere-ocean-land-cryosphere forecast system. Each 6-hour cycle launches four ensemble members (1-4) that integrate forward in 6-hour steps; member 1 of selected cycles runs out to roughly 9 months. This data source exposes the pgbf product (pressure-level atmosphere, 1 degree regular lat-lon, 181 x 360).

Parameters:

  • member (int, optional) – CFS ensemble member, one of {1, 2, 3, 4}, by default 1.

  • source (str, optional) – Backing store: "nomads" (default; NCEP’s official real-time distribution, rolling ~7-day window) or "aws" (NOAA Big Data Program mirror at s3://noaa-cfs-pds/, anonymous, archive back to 2023-04-22).

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

  • verbose (bool, optional) – Print download progress, by default True.

  • async_timeout (int, optional) – Total timeout in seconds for the entire fetch operation, by default 600.

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

  • 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.

Note

The NOMADS rolling window keeps roughly the last seven days of cycles online; for older initial conditions use source="aws". Members 2-4 integrate to substantially shorter lead times than member 1; the lead-time validator caps requests at 180 days regardless of member, but requests past a given member’s actual horizon will raise FileNotFoundError at fetch time.

Note

Additional information on the data repository:

__call__(time, lead_time, variable)[source]#

Retrieve CFS forecast data.

Parameters:

  • time (datetime | list[datetime] | TimeArray) – Initial-condition timestamps to return data for (UTC).

  • lead_time (timedelta | list[timedelta] | LeadTimeArray) – Forecast lead times to fetch (6-hour increments).

  • variable (str | list[str] | VariableArray) – Variable identifier(s). Must be in the source’s lexicon.

Returns:

CFS forecast data array with dimensions [time, lead_time, variable, lat, lon].

Return type:

xr.DataArray

async fetch(time, lead_time, variable)[source]#

Async function to get CFS forecast data.

Parameters:

  • time (datetime | list[datetime] | TimeArray) – Initial-condition timestamps to return data for (UTC).

  • lead_time (timedelta | list[timedelta] | LeadTimeArray) – Forecast lead times to fetch (6-hour increments).

  • variable (str | list[str] | VariableArray) – Variable identifier(s). Must be in the source’s lexicon.

Returns:

CFS forecast data array.

Return type:

xr.DataArray

classmethod available(time, member=1)[source]#

Check whether a given CFS initial condition is available on AWS.

Uses the public AWS PDS bucket (the most complete public archive) rather than NOMADS, so this works regardless of the rolling-window cutoff on the NCEP server.

Parameters:

  • time (datetime | np.datetime64) – Initial-condition date time to check.

  • member (int, optional) – CFS member to check, by default 1.

Returns:

Whether the cycle directory exists in the AWS bucket.

Return type:

bool