pygeohydro.nwis#

Accessing NWIS.

Module Contents#

class pygeohydro.nwis.NWIS#

Access NWIS web service.

Notes

More information about query parameters and codes that NWIS accepts can be found at its help webpage.

classmethod get_info(queries, expanded=False, fix_names=True, nhd_info=False)#

Send multiple queries to USGS Site Web Service.

Parameters:

  • queries (dict or list of dict) – A single or a list of valid queries.

  • expanded (bool, optional) – Whether to get expanded site information for example drainage area, default to False.

  • fix_names (bool, optional) – If True, reformat station names and some small annoyances, defaults to True.

  • nhd_info (bool, optional) – If True, get NHD information for each site, defaults to False. This will add four new columns: nhd_comid, nhd_areasqkm, nhd_reachcode, and nhd_measure. Where nhd_id is the NHD COMID of the flowline that the site is located in, nhd_reachcode is the NHD Reach Code that the site is located in, and nhd_measure is the measure along the flowline that the site is located at.

Returns:

geopandas.GeoDataFrame – A correctly typed GeoDataFrame containing site(s) information.

Return type:

geopandas.GeoDataFrame

classmethod get_parameter_codes(keyword)#

Search for parameter codes by name or number.

Notes

NWIS guideline for keywords is as follows:

By default an exact search is made. To make a partial search the term should be prefixed and suffixed with a % sign. The % sign matches zero or more characters at the location. For example, to find all with “discharge” enter %discharge% in the field. % will match any number of characters (including zero characters) at the location.

Parameters:

keyword (str) – Keyword to search for parameters by name of number.

Returns:

pandas.DataFrame – Matched parameter codes as a dataframe with their description.

Return type:

pandas.DataFrame

Examples

>>> from pygeohydro import NWIS
>>> nwis = NWIS()
>>> codes = nwis.get_parameter_codes("%discharge%")
>>> codes.loc[codes.parameter_cd == "00060", "parm_nm"].iloc[0]
'Discharge, cubic feet per second'
classmethod get_streamflow(station_ids: collections.abc.Sequence[str] | str, dates: tuple[str, str], freq: str = 'dv', mmd: bool = False, *, to_xarray: Literal[False] = False) → pandas.DataFrame#
classmethod get_streamflow(station_ids: collections.abc.Sequence[str] | str, dates: tuple[str, str], freq: str = 'dv', mmd: bool = False, *, to_xarray: Literal[True]) → xarray.Dataset

Get mean daily streamflow observations from USGS.

Parameters:

  • station_ids (str, list) – The gage ID(s) of the USGS station.

  • dates (tuple) – Start and end dates as a tuple (start, end).

  • freq (str, optional) – The frequency of the streamflow data, defaults to dv (daily values). Valid frequencies are dv (daily values), iv (instantaneous values). Note that for iv the time zone for the input dates is assumed to be UTC.

  • mmd (bool, optional) – Convert cms to mm/day based on the contributing drainage area of the stations. Defaults to False.

  • to_xarray (bool, optional) – Whether to return a xarray.Dataset. Defaults to False.

Returns:

pandas.DataFrame or xarray.Dataset – Streamflow data observations in cubic meter per second (cms). The stations that don’t provide the requested discharge data in the target period will be dropped. Note that when frequency is set to iv the time zone is converted to UTC.

static retrieve_rdb(url, payloads)#

Retrieve and process requests with RDB format.

Parameters:

  • url (str) – Name of USGS REST service, valid values are site, dv, iv, gwlevels, and stat. Please consult USGS documentation here for more information.

  • payloads (list of dict) – List of target payloads.

Returns:

pandas.DataFrame – Requested features as a pandas’s DataFrame.

Return type:

pandas.DataFrame

pygeohydro.nwis.streamflow_fillna(streamflow, missing_max=5)#

Fill missing data (NAN) in daily streamflow observations.

It drops stations with more than missing_max days missing data per year. Missing data in the remaining stations, are filled with day-of-year average over the entire dataset.

Parameters:

  • streamflow (xarray.DataArray or pandas.DataFrame or pandas.Series) – Daily streamflow observations with at least 10 years of daily data.

  • missing_max (int) – Maximum allowed number of missing daily data per year for filling, defaults to 5.

Returns:

xarray.DataArray or pandas.DataFrame or pandas.Series – Streamflow observations with missing data filled for stations with less than missing_max days of missing data.

Return type:

ArrayLike