Skip to content

docs: migrate userguide, examples, and notebooks to the Water Data API #290

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
thodson-usgs merged 1 commit into from
May 26, 2026
Merged

docs: migrate userguide, examples, and notebooks to the Water Data API #290

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 3 additions & 2 deletions dataretrieval/nldi.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -296,8 +296,9 @@ def get_features_by_data_source(data_source: str) -> gpd.GeoDataFrame:
--------
.. doctest::

>>> # Get features for a feature wqp and feature_id USGS-01031500
>>> gdf = dataretrieval.nldi.get_features_by_data_source(
>>> # "nwissite" returns every NWIS site nationwide, so this example is
>>> # skipped in the doctest build to avoid the (very large) download.
>>> gdf = dataretrieval.nldi.get_features_by_data_source( # doctest: +SKIP
... data_source="nwissite"
... )
"""
Expand Down
18 changes: 11 additions & 7 deletions dataretrieval/nwis.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1125,12 +1125,11 @@ class NWIS_Metadata(BaseMetadata):
Response headers
comments: str | None
Metadata comments, if any
site_info: tuple[pd.DataFrame, NWIS_Metadata] | None
Site information if the query included `site_no`, `sites`, `stateCd`,
`huc`, `countyCd` or `bBox`. `site_no` is preferred over `sites` if
both are present.
variable_info: None
Deprecated. Accessing variable_info via NWIS_Metadata is deprecated.

Notes
-----
``site_info`` and ``variable_info`` are exposed as properties (documented
below) rather than plain attributes.

"""

Expand Down Expand Up @@ -1164,7 +1163,12 @@ def __init__(self, response, **parameters) -> None:

@property
def site_info(self) -> tuple[pd.DataFrame, BaseMetadata] | None:
"""
"""Site information for the query.

Populated when the query included ``site_no``, ``sites``, ``stateCd``,
``huc``, ``countyCd`` or ``bBox`` (``site_no`` is preferred over
``sites`` if both are present); ``None`` otherwise.

Return
------
df: ``pandas.DataFrame``
Expand Down
15 changes: 8 additions & 7 deletions dataretrieval/waterdata/api.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -554,11 +554,11 @@ def get_monitoring_locations(
county_code : string or iterable of strings, optional
The code for the county or county equivalent (parish, borough, etc.) in which
the monitoring location is located. A `list of codes
<https://help.waterdata.usgs.gov/code/county_query?fmt=html>`_ is available.
<https://help.waterdata.usgs.gov/code/county_query?fmt=html>`__ is available.
county_name : string or iterable of strings, optional
The name of the county or county equivalent (parish, borough, etc.) in which
the monitoring location is located. A `list of codes
<https://help.waterdata.usgs.gov/code/county_query?fmt=html>`_ is available.
<https://help.waterdata.usgs.gov/code/county_query?fmt=html>`__ is available.
minor_civil_division_code : string or iterable of strings, optional
Codes for primary governmental or administrative divisions of the county or
county equivalent in which the monitoring location is located.
Expand Down Expand Up @@ -2751,9 +2751,10 @@ def get_channel(
* A date-time: "2018-02-12T23:20:50Z"
* A bounded interval: "2018-02-12T00:00:00Z/2018-03-18T12:31:12Z"
* Half-bounded intervals: "2018-02-12T00:00:00Z/.." or
"../2018-03-18T12:31:12Z"
* Duration objects: "P1M" for data from the past month or "PT36H" for
the last 36 hours
"../2018-03-18T12:31:12Z"
* Duration objects: "P1M" for data from the past month or "PT36H"
for the last 36 hours

channel_name : string or iterable of strings, optional
The channel name.
channel_flow : string or iterable of strings, optional
Expand Down Expand Up @@ -2799,9 +2800,9 @@ def get_channel(
* A date-time: "2018-02-12T23:20:50Z"
* A bounded interval: "2018-02-12T00:00:00Z/2018-03-18T12:31:12Z"
* Half-bounded intervals: "2018-02-12T00:00:00Z/.." or
"../2018-03-18T12:31:12Z"
"../2018-03-18T12:31:12Z"
* Duration objects: "P1M" for data from the past month or "PT36H" for the
last 36 hours
last 36 hours

Only features that have a last_modified that intersects the value of
datetime are selected.
Expand Down
138 changes: 71 additions & 67 deletions demos/R Python Vignette equivalents.ipynb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,9 +20,9 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"The dataRetrieval package was created as a python equivalent to the R dataRetrieval tool.\n",
"The `dataretrieval` Python package was created as an equivalent to the R `dataRetrieval` package.\n",
"\n",
"The following shows python equivalents for methods outlined in the R dataRetrieval Vignette with the equivalent R code in comments"
"The following shows Python equivalents for the methods outlined in the R `dataRetrieval` vignette, with the equivalent R code in comments."
]
},
{
Expand All @@ -36,8 +36,10 @@
"siteNumbers <- c(\"01491000\",\"01645000\")\n",
"siteINFO <- readNWISsite(siteNumbers)\n",
"\"\"\"\n",
"siteNumbers = [\"01491000\", \"01645000\"]\n",
"siteINFO, md = nwis.get_iv(sites=siteNumbers)"
"siteNumbers = [\"USGS-01491000\", \"USGS-01645000\"]\n",
"siteINFO, md = waterdata.get_monitoring_locations(\n",
" monitoring_location_id=siteNumbers, skip_geometry=True\n",
")"
]
},
{
Expand All @@ -52,8 +54,9 @@
"dailyDataAvailable <- whatNWISdata(siteNumbers,\n",
" service=\"dv\", statCd=\"00003\")\n",
"\"\"\"\n",
"\n",
"dailyDataAvailable, md = nwis.get_dv(sites=siteNumbers, statCd=\"00003\")"
"dailyDataAvailable, md = waterdata.get_time_series_metadata(\n",
" monitoring_location_id=siteNumbers, statistic_id=\"00003\", skip_geometry=True\n",
")"
]
},
{
Expand All @@ -66,20 +69,19 @@
"# Choptank River near Greensboro, MD:\n",
"siteNumber <- \"01491000\"\n",
"parameterCd <- \"00060\" # Discharge\n",
"startDate <- \"2009-10-01\" \n",
"endDate <- \"2012-09-30\" \n",
"startDate <- \"2009-10-01\"\n",
"endDate <- \"2012-09-30\"\n",
"\n",
"discharge <- readNWISdv(siteNumber, \n",
" parameterCd, startDate, endDate)\n",
"discharge <- readNWISdv(siteNumber, parameterCd, startDate, endDate)\n",
"\"\"\"\n",
"# Choptank River near Greensboro, MD:\n",
"siteNumber = \"01491000\"\n",
"siteNumber = \"USGS-01491000\"\n",
"parameterCd = \"00060\" # Discharge\n",
"startDate = \"2009-10-01\"\n",
"endDate = \"2012-09-30\"\n",
"\n",
"discharge, md = nwis.get_dv(\n",
" sites=siteNumber, parameterCd=parameterCd, start=startDate, end=endDate\n",
"discharge, md = waterdata.get_daily(\n",
" monitoring_location_id=siteNumber,\n",
" parameter_code=parameterCd,\n",
" time=\"2009-10-01/2012-09-30\",\n",
")"
]
},
Expand All @@ -92,25 +94,21 @@
"\"\"\"\n",
"siteNumber <- \"01491000\"\n",
"parameterCd <- c(\"00010\",\"00060\") # Temperature and discharge\n",
"statCd <- c(\"00001\",\"00003\") # Mean and maximum\n",
"statCd <- c(\"00001\",\"00003\") # Maximum and mean\n",
"startDate <- \"2012-01-01\"\n",
"endDate <- \"2012-05-01\"\n",
"\n",
"temperatureAndFlow <- readNWISdv(siteNumber, parameterCd, \n",
" startDate, endDate, statCd=statCd)\n",
"temperatureAndFlow <- readNWISdv(siteNumber, parameterCd, startDate, endDate, statCd=statCd)\n",
"\"\"\"\n",
"siteNumber = \"01491000\"\n",
"siteNumber = \"USGS-01491000\"\n",
"parameterCd = [\"00010\", \"00060\"] # Temperature and discharge\n",
"statCd = [\"00001\", \"00003\"] # Mean and maximum\n",
"startDate = \"2012-01-01\"\n",
"endDate = \"2012-05-01\"\n",
"statisticId = [\"00001\", \"00003\"] # Maximum and mean\n",
"\n",
"temperatureAndFlow, md = nwis.get_dv(\n",
" sites=siteNumber,\n",
" parameterCd=parameterCd,\n",
" start=startDate,\n",
" end=endDate,\n",
" statCd=statCd,\n",
"temperatureAndFlow, md = waterdata.get_daily(\n",
" monitoring_location_id=siteNumber,\n",
" parameter_code=parameterCd,\n",
" statistic_id=statisticId,\n",
" time=\"2012-01-01/2012-05-01\",\n",
")"
]
},
Expand All @@ -122,17 +120,17 @@
"source": [
"\"\"\"\n",
"parameterCd <- \"00060\" # Discharge\n",
"startDate <- \"2012-05-12\" \n",
"endDate <- \"2012-05-13\" \n",
"dischargeUnit <- readNWISuv(siteNumber, parameterCd, \n",
" startDate, endDate)\n",
"startDate <- \"2012-05-12\"\n",
"endDate <- \"2012-05-13\"\n",
"dischargeUnit <- readNWISuv(siteNumber, parameterCd, startDate, endDate)\n",
"\"\"\"\n",
"siteNumber = \"01491000\"\n",
"siteNumber = \"USGS-01491000\"\n",
"parameterCd = \"00060\" # Discharge\n",
"startDate = \"2012-05-12\"\n",
"endDate = \"2012-05-13\"\n",
"dischargeUnit, md = nwis.get_iv(\n",
" sites=siteNumber, parameterCd=parameterCd, start=startDate, end=endDate\n",
"\n",
"dischargeUnit, md = waterdata.get_continuous(\n",
" monitoring_location_id=siteNumber,\n",
" parameter_code=parameterCd,\n",
" time=\"2012-05-12/2012-05-13\",\n",
")"
]
},
Expand All @@ -147,18 +145,17 @@
"parameterCd <- c(\"00618\",\"71851\")\n",
"startDate <- \"1985-10-01\"\n",
"endDate <- \"2012-09-30\"\n",
"dfLong <- read_USGS_samples(monitoringLocationIdentifier=sprintf(\"USGS-%s\", siteNumber), usgsPCode=parameterCd, \n",
" activityStartDateLower=startDate, activityStartDateUpper=endDate)\n",
"dfLong <- read_USGS_samples(monitoringLocationIdentifier=sprintf(\"USGS-%s\", siteNumber),\n",
" usgsPCode=parameterCd, activityStartDateLower=startDate, activityStartDateUpper=endDate)\n",
"\"\"\"\n",
"siteNumber = \"01491000\"\n",
"siteNumber = \"USGS-01491000\"\n",
"parameterCd = [\"00618\", \"71851\"]\n",
"startDate = \"1985-10-01\"\n",
"endDate = \"2012-09-30\"\n",
"\n",
"dfLong, md = waterdata.get_samples(\n",
" monitoringLocationIdentifier=f\"USGS-{siteNumber}\",\n",
" monitoringLocationIdentifier=siteNumber,\n",
" usgsPCode=parameterCd,\n",
" activityStartDateLower=startDate,\n",
" activityStartDateUpper=endDate,\n",
" activityStartDateLower=\"1985-10-01\",\n",
" activityStartDateUpper=\"2012-09-30\",\n",
")"
]
},
Expand All @@ -172,8 +169,9 @@
"siteNumber <- '01594440'\n",
"peakData <- readNWISpeak(siteNumber)\n",
"\"\"\"\n",
"siteNumber = \"01594440\"\n",
"peakData, md = nwis.get_discharge_peaks(sites=siteNumber)"
"peakData, md = waterdata.get_peaks(\n",
" monitoring_location_id=\"USGS-01594440\", parameter_code=\"00060\"\n",
")"
]
},
{
Expand All @@ -186,7 +184,11 @@
"ratingData <- readNWISrating(siteNumber, \"base\")\n",
"attr(ratingData, \"RATING\")\n",
"\"\"\"\n",
"ratings_data, md = nwis.get_ratings(site=\"01594440\", file_type=\"base\")"
"# get_ratings returns a dict keyed by \"<id>.<file_type>.rdb\"\n",
"ratings_data = waterdata.get_ratings(\n",
" monitoring_location_id=\"USGS-01594440\", file_type=\"base\"\n",
")\n",
"list(ratings_data.keys())"
]
},
{
Expand All @@ -198,10 +200,12 @@
"\"\"\"\n",
"discharge_stats <- readNWISstat(siteNumbers=c(\"02319394\"),\n",
" parameterCd=c(\"00060\"),\n",
" statReportType=\"annual\") \n",
" statReportType=\"annual\")\n",
"\"\"\"\n",
"discharge_stats, md = nwis.get_stats(\n",
" sites=\"02319394\", parameterCd=\"00060\", statReportType=\"annual\", statTypeCd=\"all\"\n",
"discharge_stats, md = waterdata.get_stats_date_range(\n",
" monitoring_location_id=\"USGS-02319394\",\n",
" parameter_code=\"00060\",\n",
" computation_type=\"arithmetic_mean\",\n",
")"
]
},
Expand All @@ -211,14 +215,14 @@
"metadata": {},
"outputs": [],
"source": [
"# '''\n",
"# dischargeWI <- readNWISdata(service=\"dv\",\n",
"# stateCd=\"WI\",\n",
"# parameterCd=\"00060\",\n",
"# drainAreaMin=\"50\",\n",
"# statCd=\"00003\")\n",
"# '''\n",
"# dischargeWI, md = nwis.get_dv(stateCd=\"WI\", parameterCd=\"00060\", drainAreaMin=\"50\", statCd=\"00003\")"
"# R: readNWISdata(service=\"dv\", stateCd=\"WI\", parameterCd=\"00060\",\n",
"# drainAreaMin=\"50\", statCd=\"00003\")\n",
"#\n",
"# The Water Data API serves daily values per monitoring location. To assemble a\n",
"# state-wide set, first find the locations (optionally filtering by drainage\n",
"# area) with waterdata.get_monitoring_locations(state_name=\"Wisconsin\", ...),\n",
"# then pass their ids to waterdata.get_daily(parameter_code=\"00060\",\n",
"# statistic_id=\"00003\")."
]
},
{
Expand Down Expand Up @@ -292,21 +296,21 @@
"source": [
"# Embedded Metadata\n",
"\n",
"All service methods return the DataFrame containing requested data and Metadata as a tuple. Note, a call using get_record will only return the DataFrame to remain compatible with previous usage.\n",
"Most `waterdata` and `wqp` service methods return a tuple of the requested data (a pandas DataFrame) and a metadata object.\n",
"\n",
"`md` is an object with the following attributes:\n",
"\n",
"```\n",
"national, md = nwis.get_water_use()\n",
"Metadata\n",
" url # the URL used to query the service\n",
" query_time # how long the query took\n",
" header # the response headers\n",
"```\n",
"\n",
"md is an object with the following attributes\n",
"Note: USGS *water use* data has no Water Data API equivalent yet, so it remains available only through the deprecated `nwis` module:\n",
"\n",
"```\n",
"Metadata\n",
" url # the resulting url to query usgs\n",
" query_time # the time it took to query usgs\n",
" site_info # a method to call site_info with the site parameters supplied\n",
" header # any headers attached to the response object\n",
"national, md = nwis.get_water_use()\n",
"```"
]
},
Expand Down
Loading