NomadsGDASObsConv#

class earth2studio.data.NomadsGDASObsConv(
time_tolerance=numpy.timedelta64(10, 'm'),
max_workers=4,
decode_workers=8,
cache=True,
verbose=True,
async_timeout=600,
retries=3,
)[source]#
Global

Real-time GDAS conventional observations from NOAA NOMADS.

Provides near-real-time access to quality-controlled conventional (in-situ) observations from the NOAA Global Data Assimilation System (GDAS). Data is sourced from merged PrepBUFR and separate GPSRO files on NOMADS, updated 4 times daily (00z, 06z, 12z, 18z) with approximately 6-10 hours latency.

Observation types include radiosondes (ADPUPA), surface stations (ADPSFC), aircraft (AIRCAR/AIRCFT), ships and buoys (SFCSHP), wind profilers (PROFLR), satellite-derived winds (SATWND), and GPS precipitable water (GPSIPW). The gps variable reads only the combined ionosphere-corrected bending-angle observation from the separate GPSRO dump.

GPSRO rows use the shared columns with product-specific meanings: type is receiver SAID, station combines receiver/transmitter identifiers, quality is the QFRO flag table, pres is null, and elev is impact parameter minus Earth radius of curvature.

The output schema matches UFSObsConv with additional PrepBUFR quality, pressure_quality, and level_cat metadata.

Parameters:

  • 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(10, “m”).

  • max_workers (int, optional) – Maximum concurrent async download tasks, by default 4.

  • decode_workers (int, optional) – Number of parallel processes for BUFR message decoding. Higher values speed up decoding of large PrepBUFR files at the cost of more memory. Set to 1 to disable multiprocessing, by default 8.

  • cache (bool, optional) – Cache downloaded observation files locally, by default True.

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

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

  • retries (int, optional) – Number of retry attempts per failed download 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. Each 6-hourly PrepBUFR file is approximately 60-100 MB; GPSRO is downloaded only when gps is requested.

Note

Additional information on the data:

Data is retained on the NOMADS production server for approximately 2 days. Older data should be retrieved from the UFS GEFSv13 Replay dataset via UFSObsConv.

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

Fetch conventional observation data.

Parameters:

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

  • variable (str | list[str] | VariableArray) – Variables to return. Must be in GDASObsConvLexicon.

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

Returns:

Observation data matching the requested time/variable window.

Return type:

pd.DataFrame

Raises:

  • KeyError – If a variable is not found in the lexicon.

  • ValueError – If requested time is out of valid range.

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

Async fetch of conventional observation data.

Parameters:

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

  • variable (str | list[str] | VariableArray) – Variables to return.

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

Returns:

Observation data.

Return type:

pd.DataFrame

classmethod available(time)[source]#

Check if date time is available on NOMADS.

Parameters:

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

Returns:

True if the time falls within the NOMADS retention window.

Return type:

bool