teehr.Fetch.nwm_retrospective_points#

Fetch.nwm_retrospective_points(nwm_version: SupportedNWMRetroVersionsEnum, variable_name: ChannelRtRetroVariableEnum, start_date: str | datetime | Timestamp, end_date: str | datetime | Timestamp, chunk_by: NWMChunkByEnum | None = None, overwrite_output: bool | None = False, domain: SupportedNWMRetroDomainsEnum | None = 'CONUS', timeseries_type: TimeseriesTypeEnum = 'secondary')[source]#

Fetch NWM retrospective point data and load into the TEEHR dataset.

Data is fetched for all secondary location IDs in the locations crosswalk table, and all dates and times within the files and in the cache file names are in UTC.

Parameters:

nwm_version (SupportedNWMRetroVersionsEnum) – NWM retrospective version to fetch. Currently nwm20, nwm21, and nwm30 supported.
variable_name (str) – Name of the NWM data variable to download. (e.g., “streamflow”, “velocity”, …).
start_date (Union[str, datetime, pd.Timestamp]) – Date to begin data ingest. Str formats can include YYYY-MM-DD or MM/DD/YYYY Rounds down to beginning of day.
end_date (Union[str, datetime, pd.Timestamp],) – Last date to fetch. Rounds up to end of day. Str formats can include YYYY-MM-DD or MM/DD/YYYY.
chunk_by (Union[NWMChunkByEnum, None] = None,) – If None (default) saves all timeseries to a single file, otherwise the data is processed using the specified parameter. Can be: ‘week’, ‘month’, or ‘year’.
overwrite_output (bool = False,) – Whether output should overwrite files if they exist. Default is False.
domain (str = "CONUS") – Geographical domain when NWM version is v3.0. Acceptable values are “Alaska”, “CONUS” (default), “Hawaii”, and “PR”. Only relevant when NWM version equals nwm30.
timeseries_type (str) – Whether to consider as the “primary” or “secondary” timeseries. Default is “primary”.

Examples

Here we fetch one days worth of NWM hourly streamflow data. Initially the data is saved to the cache directory, then it is validated and loaded into the TEEHR dataset.

>>> import teehr
>>> ev = teehr.Evaluation()

>>> ev.fetch.nwm_retrospective_points(
>>>     nwm_version="nwm30",
>>>     variable_name="streamflow",
>>>     start_date=datetime(2000, 1, 1),
>>>     end_date=datetime(2000, 1, 2, 23)
>>> )

Note

NWM data can also be fetched outside of a TEEHR Evaluation by calling the method directly.

>>> import teehr.fetching.nwm.retrospective_points as nwm_retro

Fetch and format the data, writing to the specified directory.

>>> nwm_retro.nwm_retro_to_parquet(
>>>     nwm_version="nwm20",
>>>     variable_name="streamflow",
>>>     start_date=Sdatetime(2000, 1, 1),
>>>     end_date=datetime(2000, 1, 2, 23),
>>>     location_ids=[7086109, 7040481],
>>>     output_parquet_dir=Path(Path.home(), "nwm20_retrospective")
>>> )