Skip to content

data.CFS_FX

Global

Import path: earth2studio.data.CFS_FX

View source on GitHub

Documentation

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, default: 1 ) –

    CFS ensemble member, one of {1, 2, 3, 4}, by default 1.

  • source (str, default: 'nomads' ) –

    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, default: True ) –

    Cache data source on local memory, by default True.

  • verbose (bool, default: True ) –

    Print download progress, by default True.

  • async_timeout (int, default: 600 ) –

    Total timeout in seconds for the entire fetch operation, by default 600.

  • async_workers (int, default: None ) –

    Maximum number of concurrent downloads. By default None, which autoscales to the number of download tasks (capped at 64).

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

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__ 

__call__(
    time: datetime | list[datetime] | TimeArray,
    lead_time: timedelta | list[timedelta] | LeadTimeArray,
    variable: str | list[str] | VariableArray,
) -> DataArray

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:

  • DataArray –

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

fetch async 

fetch(
    time: datetime | list[datetime] | TimeArray,
    lead_time: timedelta | list[timedelta] | LeadTimeArray,
    variable: str | list[str] | VariableArray,
) -> DataArray

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:

  • DataArray –

    CFS forecast data array.

available classmethod 

available(
    time: datetime | datetime64, member: int = 1
) -> bool

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 | datetime64) –

    Initial-condition date time to check.

  • member (int, default: 1 ) –

    CFS member to check, by default 1.

Returns:

  • bool –

    Whether the cycle directory exists in the AWS bucket.