Skip to content

data.CFS_Reforecast_FX

Global

Import path: earth2studio.data.CFS_Reforecast_FX

View source on GitHub

Documentation

NCEP CFSv2 6-hourly 9-month reforecast (pressure-level product).

The CFS reforecast is a 30-year offline integration of CFSv2 produced by NCEP to support training and bias-correction of the operational system. Cycles are launched every 5 days from 1981-12-12 to 2011-03-27; each 5-day cycle directory contains four 6-hourly initial conditions (00/06/12/18 UTC) integrated forward to roughly 9 months in 6-hour steps. Only ensemble member 01 of the operational 1-4 set is published in this 9-month series.

This class exposes the pressure-level (pgbf) product on the same 1 degree regular lat-lon grid (181 x 360) as the operational [CFS_FX][earth2studio.data.CFS_FX]. Variable definitions are taken verbatim from [CFSLexicon][earth2studio.lexicon.CFSLexicon], which the grib2 inventories match.

Parameters:

  • cache (bool, default: True ) –

    Cache data source on local memory, by default True. Cached files are large (~22 MB per (IC, lead) pgbf file) and are reused across variable requests for the same file.

  • 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: 16 ) –

    Maximum number of concurrent async fetch tasks, by default 16. Each task downloads one whole grib file.

  • 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. Unlike the operational archive, the reforecast bucket has no .idx companions; every variable request triggers a full grib-file download (~22 MB) if not already cached.

Note

The reforecast 9-month series only publishes ensemble member 01; no member constructor argument is exposed.

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 reforecast 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, 0 to ~9 months).

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

    Variable identifier(s). Must be in the source's lexicon.

Returns:

  • DataArray –

    CFS reforecast 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 fetch of CFS reforecast data.

Parameters:

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

    Initial-condition timestamps (UTC).

  • lead_time (timedelta | list[timedelta] | LeadTimeArray) –

    Forecast lead times.

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

    Variable identifier(s). Must be in the source's lexicon.

Returns:

  • DataArray –

    CFS reforecast data array.

available classmethod 

available(time: datetime | datetime64) -> bool

Check whether a CFS reforecast initial condition is available.

Performs offline validity checks (6-hour cycle, history range); the every-5-days cycle calendar is not enforced here because it shifts slightly across leap-year boundaries. Off-schedule requests are surfaced as FileNotFoundError at fetch time.

Parameters:

Returns:

  • bool –

    Whether the offline checks pass.