GHCNHourly#

class earth2studio.data.GHCNHourly(
stations,
time_tolerance=numpy.timedelta64(10, 'm'),
cache=True,
verbose=True,
async_timeout=600,
async_workers=16,
retries=3,
)[source]#
Global

NOAA’s Global Historical Climatology Network Hourly (GHCNh) is a global database of hourly surface observations that supersedes the Integrated Surface Database (ISD). It compiles observations from thousands of stations worldwide into a common data model with consistent CSV encoding.

Parameters:

  • stations (list[str]) – Station IDs in GHCN station format (11 characters), e.g. "USW00013874" for Atlanta Hartsfield-Jackson. Use GHCNHourly.get_stations_bbox() to discover IDs by geographic area.

  • 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’)

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

  • verbose (bool, optional) – Print download progress and missing data warnings, by default True

  • async_timeout (int, optional) – Time in sec after which download will be cancelled if not finished successfully, 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

To help get a list of possible station IDs, this class includes GHCNHourly.get_stations_bbox() which accepts a lat-lon bounding box and will return known station IDs. For more information on the stations, users should consult the ghcnd-stations.txt file accessible via GHCNHourly.get_station_metadata().

Note

Additional information on the data repository can be referenced here:

Example

# Atlanta Hartsfield-Jackson airport
stations = GHCNHourly.get_stations_bbox((33, -85, 34, -84))
ds = GHCNHourly(stations, time_tolerance=timedelta(hours=1))
df = ds(datetime(2024, 1, 1, 12), ["t2m", "ws10m"])
__call__(time, variable, fields=None)[source]#

Function to get data.

Parameters:

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

  • variable (str | list[str] | VariableArray) – String, list of strings or array of strings that refer to variables to return.

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

Returns:

Data frame

Return type:

pd.DataFrame

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

Async function to get data.

Parameters:

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

  • variable (str | list[str] | VariableArray) – String, list of strings or array of strings that refer to variables to return. Must be in the GHCNh lexicon.

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

Returns:

GHCNh data frame

Return type:

pd.DataFrame

classmethod available(time)[source]#

Check if the given date time is available for this data source.

Parameters:

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

Returns:

If date time is available

Return type:

bool