Skip to content

Commit c03267f

Browse files
thodson-usgsclaude
thodson-usgs
and
claude
committed
docs(examples): port readme & siteinfo examples to the Water Data API
Rewrite the two getting-started example pages off the deprecated nwis module onto waterdata: get_continuous (instantaneous values), get_monitoring_locations (site metadata), and get_time_series_metadata (the data-availability catalog that replaces the legacy seriesCatalogOutput switch). Output captured from live calls. Switched to illustrative .. code:: blocks matching the waterdata docstrings, which also clears the last 4 output-drift doctest failures: the doctest suite is now green (0 failures). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
1 parent 527963d commit c03267f

2 files changed

Lines changed: 89 additions & 82 deletions

File tree

‎docs/source/examples/readme_examples.rst‎

Lines changed: 45 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -1,40 +1,49 @@
11

2-
Examples from the Readme file on retrieving NWIS data
3-
-----------------------------------------------------
2+
Retrieving USGS water data with the ``waterdata`` module
3+
--------------------------------------------------------
44

55
.. note::
66

7-
NWIS stands for the National Water Information System
8-
9-
10-
.. doctest::
11-
12-
>>> # first import the functions for downloading data from NWIS
13-
>>> import dataretrieval.nwis as nwis
14-
15-
>>> # specify the USGS site code for which we want data.
16-
>>> site = '03339000'
17-
18-
>>> # get instantaneous values (iv)
19-
>>> df = nwis.get_record(sites=site, service='iv', start='2017-12-31', end='2018-01-01')
20-
21-
>>> df.head()
22-
00010 00010_cd site_no 00060 00060_cd ... 63680_ysi), [discontinued 10/5/21_cd 63680_hach 63680_hach_cd 99133 99133_cd
23-
datetime ...
24-
2017-12-31 06:00:00+00:00 1.0 A 03339000 140.0 A ... A 3.6 A 4.61 A
25-
2017-12-31 06:15:00+00:00 1.0 A 03339000 138.0 A ... A 3.6 A 4.61 A
26-
2017-12-31 06:30:00+00:00 1.0 A 03339000 139.0 A ... A 3.4 A 4.61 A
27-
2017-12-31 06:45:00+00:00 1.0 A 03339000 139.0 A ... A 3.4 A 4.61 A
28-
2017-12-31 07:00:00+00:00 1.0 A 03339000 139.0 A ... A 3.5 A 4.61 A
29-
<BLANKLINE>
30-
[5 rows x 21 columns]
31-
32-
33-
>>> # get basic info about the site
34-
>>> df3 = nwis.get_record(sites=site, service='site')
35-
36-
>>> print(df3)
37-
agency_cd site_no station_nm site_tp_cd lat_va long_va ... aqfr_cd aqfr_type_cd well_depth_va hole_depth_va depth_src_cd project_no
38-
0 USGS 03339000 VERMILION RIVER NEAR DANVILLE, IL ST 400603 873550 ... NaN NaN NaN NaN NaN 100
39-
<BLANKLINE>
40-
[1 rows x 42 columns]
7+
The ``waterdata`` module accesses the USGS `Water Data API`_ and is the
8+
recommended way to retrieve USGS water data. The legacy ``nwis`` module
9+
remains available but is deprecated.
10+
11+
.. _Water Data API: https://api.waterdata.usgs.gov/
12+
13+
.. code:: python
14+
15+
>>> # import the waterdata module
16+
>>> from dataretrieval import waterdata
17+
18+
>>> # a USGS monitoring location id joins the agency code and the site
19+
>>> # number with a hyphen
20+
>>> site = "USGS-05427718"
21+
22+
>>> # get continuous (instantaneous) streamflow — parameter code 00060 —
23+
>>> # over a one-day window
24+
>>> df, md = waterdata.get_continuous(
25+
... monitoring_location_id=site,
26+
... parameter_code="00060",
27+
... time="2024-03-01/2024-03-02",
28+
... )
29+
30+
>>> df[["time", "value", "unit_of_measure", "approval_status"]].head()
31+
time value unit_of_measure approval_status
32+
0 2024-03-01 00:00:00+00:00 18.7 ft^3/s Approved
33+
1 2024-03-01 00:15:00+00:00 18.5 ft^3/s Approved
34+
2 2024-03-01 00:30:00+00:00 18.5 ft^3/s Approved
35+
3 2024-03-01 00:45:00+00:00 18.5 ft^3/s Approved
36+
4 2024-03-01 01:00:00+00:00 18.3 ft^3/s Approved
37+
38+
>>> # get descriptive metadata about the monitoring location itself
39+
>>> info, md = waterdata.get_monitoring_locations(
40+
... monitoring_location_id=site,
41+
... skip_geometry=True,
42+
... )
43+
44+
>>> info[["monitoring_location_name", "state_name", "site_type", "drainage_area"]].T
45+
0
46+
monitoring_location_name YAHARA RIVER AT WINDSOR, WI
47+
state_name Wisconsin
48+
site_type Stream
49+
drainage_area 73.6

‎docs/source/examples/siteinfo_examples.rst‎

Lines changed: 44 additions & 46 deletions
Original file line numberDiff line numberDiff line change
@@ -2,49 +2,47 @@
22
Retrieving site information
33
---------------------------
44

5-
By default ``dataretrieval`` fetches the so-called "expanded" site date from
6-
the NWIS web service. However there is an optional keyword parameter called
7-
``seriesCatalogOutput`` that can be set to "True" if you wish to retrieve the
8-
detailed period of record information for a site instead. Refer to the
9-
`NWIS water services documentation`_ for additional information. The below
10-
example illustrates the use of the ``seriesCatalogOutput`` switch and displays
11-
the resulting column names for the output dataframes (example prompted by
12-
`GitHub Issue #34`_).
13-
14-
.. _NWIS water services documentation: https://waterservices.usgs.gov/docs/site-service/site-service-details/
15-
16-
.. _GitHub Issue #34: https://github.com/DOI-USGS/dataretrieval-python/issues/34
17-
18-
.. doctest::
19-
20-
# first import the functions for downloading data from NWIS
21-
>>> import dataretrieval.nwis as nwis
22-
23-
# fetch data from a major HUC basin with seriesCatalogOutput set to True
24-
>>> df = nwis.get_record(huc='20', parameterCd='00060',
25-
... service='site', seriesCatalogOutput='True')
26-
27-
>>> print(df.columns)
28-
Index(['agency_cd', 'site_no', 'station_nm', 'site_tp_cd', 'dec_lat_va',
29-
'dec_long_va', 'coord_acy_cd', 'dec_coord_datum_cd', 'alt_va',
30-
'alt_acy_va', 'alt_datum_cd', 'huc_cd', 'data_type_cd', 'parm_cd',
31-
'stat_cd', 'ts_id', 'loc_web_ds', 'medium_grp_cd', 'parm_grp_cd',
32-
'srs_id', 'access_cd', 'begin_date', 'end_date', 'count_nu'],
33-
dtype='object')
34-
35-
# repeat the same query with seriesCatalogOutput set as False
36-
>>> df = nwis.get_record(huc='20', parameterCd='00060',
37-
... service='site', seriesCatalogOutput='False')
38-
39-
>>> print(df.columns)
40-
Index(['agency_cd', 'site_no', 'station_nm', 'site_tp_cd', 'lat_va', 'long_va',
41-
'dec_lat_va', 'dec_long_va', 'coord_meth_cd', 'coord_acy_cd',
42-
'coord_datum_cd', 'dec_coord_datum_cd', 'district_cd', 'state_cd',
43-
'county_cd', 'country_cd', 'land_net_ds', 'map_nm', 'map_scale_fc',
44-
'alt_va', 'alt_meth_cd', 'alt_acy_va', 'alt_datum_cd', 'huc_cd',
45-
'basin_cd', 'topo_cd', 'instruments_cd', 'construction_dt',
46-
'inventory_dt', 'drain_area_va', 'contrib_drain_area_va', 'tz_cd',
47-
'local_time_fg', 'reliability_cd', 'gw_file_cd', 'nat_aqfr_cd',
48-
'aqfr_cd', 'aqfr_type_cd', 'well_depth_va', 'hole_depth_va',
49-
'depth_src_cd', 'project_no'],
50-
dtype='object')
5+
The ``waterdata`` module distinguishes a monitoring location's *descriptive*
6+
metadata from the *catalog* of data available at it.
7+
8+
Use ``get_monitoring_locations`` for descriptive metadata — name, location,
9+
site type, drainage area, hydrologic unit, and so on.
10+
11+
.. code:: python
12+
13+
>>> from dataretrieval import waterdata
14+
15+
>>> info, md = waterdata.get_monitoring_locations(
16+
... monitoring_location_id="USGS-05427718",
17+
... skip_geometry=True,
18+
... )
19+
20+
>>> info[["monitoring_location_name", "site_type", "drainage_area", "hydrologic_unit_code"]].T
21+
0
22+
monitoring_location_name YAHARA RIVER AT WINDSOR, WI
23+
site_type Stream
24+
drainage_area 73.6
25+
hydrologic_unit_code 070900020504
26+
27+
To discover *what data are available* at a location — the period-of-record
28+
catalog that the legacy ``seriesCatalogOutput`` switch used to provide — use
29+
``get_time_series_metadata``. Each row is one time series; the ``begin`` and
30+
``end`` columns give its period of record.
31+
32+
.. code:: python
33+
34+
>>> series, md = waterdata.get_time_series_metadata(
35+
... monitoring_location_id="USGS-05427718",
36+
... skip_geometry=True,
37+
... )
38+
39+
>>> len(series) # number of available time series
40+
22
41+
42+
>>> series[["parameter_code", "parameter_name", "computation_period_identifier"]].head()
43+
parameter_code parameter_name computation_period_identifier
44+
0 00045 Precipitation Points
45+
1 91060 Orthophosphate, diss Daily
46+
2 91057 NH3+orgN, wu as N Daily
47+
3 00060 Discharge Points
48+
4 80155 Suspnd sedmnt disch Daily

0 commit comments

Comments
 (0)