docs(demos): fix notebook narrative and code inconsistencies

Every docs notebook now executes end-to-end against the live USGS Water
Data API; each fix below was verified against live output before editing.

- DiscreteSamples: `get_codes` returns a `(df, md)` tuple, but five cells
  indexed the tuple with a column list (raising TypeError) and the prose
  claimed it "returns a plain DataFrame". Unpack the tuple and correct the
  claim. (This notebook previously failed to execute.)
- SiteInfo: `state_code="UT"` returned an empty frame under an "all
  locations in a state" heading; `state_code` is a two-digit ANSI code, so
  use "49" (Utah).
- UnitValues: two notes claimed returned timestamps are "in local time" --
  they are tz-aware UTC. Removed a dead duplicate of Example 5.
- Samples: "181 fields" -> the default profile returns 187 columns;
  replaced six references to nonexistent `*_lookup()` helpers with the
  real `get_codes(code_service=...)`.
- GroundwaterLevels: stale comment said partial dates "show up as NaT" in
  the index -- the index is a plain RangeIndex and dates live in a
  normalized UTC `time` column; print that instead. Relabel a y-axis that
  mixed depth-below-surface with NGVD29/NAVD88 elevations.
- Introduction: `get_combined_metadata` joins monitoring-location and
  time-series metadata, not "field-measurement metadata".
- R vignette: `nwis.get_water_use()` is defunct (raises NameError); note
  that instead of presenting it as runnable.
- SiteInventory: Example 3 duplicated Example 2 verbatim -- repurpose it as
  a `skip_geometry=True` demonstration.
- peak_streamflow_trends: the live-data migration (ad4e980) removed the
  CSV-load cell but left narrative cells describing it; rewrite them to
  describe the live `final_df`, and correct the chunker comment (Rhode
  Island's 350 gages return in a single request).
- Disambiguate the two identical `get_field_measurements()` notebook
  titles (Surface-Water vs Groundwater-Level).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: thodson-usgs

demos/R Python Vignette equivalents.ipynb

@@ -307,17 +307,8 @@
     "    header      # the response headers\n",
     "```\n",
     "\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",
-    "national, md = nwis.get_water_use()\n",
-    "```"
+    "Note: USGS *water use* data has no Water Data API equivalent yet. The legacy `nwis.get_water_use()` service has been decommissioned and now raises a \"defunct\" error, so there is currently no runnable way to retrieve water-use data through `dataretrieval`."
    ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": []
   }
  ],
  "metadata": {

demos/USGS_WaterData_DiscreteSamples_Examples.ipynb

@@ -331,8 +331,9 @@
     "## Additional query parameters\n",
     "\n",
     "Several parameters narrow the results further. The allowable values for the\n",
-    "categorical ones come from `get_codes`. Note that `get_codes` returns a plain\n",
-    "`DataFrame` (no metadata tuple).\n",
+    "categorical ones come from `get_codes`, which — like the other `waterdata`\n",
+    "functions — returns a `(DataFrame, metadata)` tuple; we unpack it and keep the\n",
+    "DataFrame.\n",
     "\n",
     "### `siteTypeCode` / `siteTypeName`"
    ]
@@ -344,7 +345,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "site_type_info = waterdata.get_codes(code_service=\"sitetype\")\n",
+    "site_type_info, _ = waterdata.get_codes(code_service=\"sitetype\")\n",
     "site_type_info[[\"typeCode\", \"typeLongName\"]].head(10)"
    ]
   },
@@ -365,7 +366,8 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "waterdata.get_codes(code_service=\"samplemedia\")[\"activityMedia\"].tolist()"
+    "media, _ = waterdata.get_codes(code_service=\"samplemedia\")\n",
+    "media[\"activityMedia\"].tolist()"
    ]
   },
   {
@@ -386,7 +388,8 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "waterdata.get_codes(code_service=\"characteristicgroup\")[\"characteristicGroup\"].tolist()"
+    "char_groups, _ = waterdata.get_codes(code_service=\"characteristicgroup\")\n",
+    "char_groups[\"characteristicGroup\"].tolist()"
    ]
   },
   {
@@ -407,7 +410,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "characteristic_info = waterdata.get_codes(code_service=\"characteristics\")\n",
+    "characteristic_info, _ = waterdata.get_codes(code_service=\"characteristics\")\n",
     "print(\"unique characteristic names:\")\n",
     "print(characteristic_info[\"characteristicName\"].drop_duplicates().head().tolist())\n",
     "print(\"\\nexample USGS parameter codes:\")\n",
@@ -432,7 +435,8 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "waterdata.get_codes(code_service=\"observedproperty\")[\"observedProperty\"].head().tolist()"
+    "observed, _ = waterdata.get_codes(code_service=\"observedproperty\")\n",
+    "observed[\"observedProperty\"].head().tolist()"
    ]
   },
   {

demos/USGS_WaterData_Introduction_Examples.ipynb

@@ -237,9 +237,11 @@
    "source": [
     "### Time series & combined metadata\n",
     "\n",
-    "`get_combined_metadata` merges time-series metadata\n",
-    "(`get_time_series_metadata`) and field-measurement metadata by site, telling you\n",
-    "which time series a site offers and the span of each."
+    "`get_combined_metadata` joins the monitoring-location catalog\n",
+    "(`get_monitoring_locations`) with the time-series metadata\n",
+    "(`get_time_series_metadata`), returning one row per available time series with\n",
+    "both the site attributes and the series' period of record — a convenient \"what\n",
+    "data is available\" view."
    ]
   },
   {

demos/hydroshare/USGS_WaterData_GroundwaterLevels_Examples.ipynb

@@ -4,7 +4,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# USGS dataretrieval Python Package `get_field_measurements()` Examples\n",
+    "# USGS dataretrieval Python Package Groundwater-Level `get_field_measurements()` Examples\n",
     "\n",
     "This notebook provides examples of using the Python dataretrieval package to retrieve groundwater level field measurements for a United States Geological Survey (USGS) monitoring location. The dataretrieval package provides a collection of functions to get data from the USGS Water Data API and other online sources of hydrology and water quality data."
    ]
@@ -152,9 +152,11 @@
    "metadata": {},
    "outputs": [],
    "source": [
+    "# This site reports several quantities (depth below land surface as well as\n",
+    "# water-surface elevations above NGVD29/NAVD88), so use a datum-neutral label.\n",
     "ax = data[0][[\"time\", \"value\"]].plot(x=\"time\", y=\"value\", style=\".\")\n",
     "ax.set_xlabel(\"Date\")\n",
-    "ax.set_ylabel(\"Water Level (feet below land surface)\")"
+    "ax.set_ylabel(\"Water level (ft)\")"
    ]
   },
   {
@@ -233,9 +235,11 @@
     "data3 = waterdata.get_field_measurements(monitoring_location_id=\"USGS-425957088141001\")\n",
     "print(\"Retrieved \" + str(len(data3[0])) + \" data values.\")\n",
     "\n",
-    "# Print the date/time index values, which show up as NaT because\n",
-    "# the dates can't be converted to a date/time data type\n",
-    "print(data3[0].index)"
+    "# Observation dates live in the 'time' column (the data frame uses a plain\n",
+    "# integer index). Where the original record gave only a year or a year and\n",
+    "# month, the Water Data API normalizes the value to a UTC timestamp with the\n",
+    "# missing day/time defaulted, so these appear as ordinary timestamps.\n",
+    "print(data3[0][\"time\"].head(10))"
    ]
   },
   {

demos/hydroshare/USGS_WaterData_Measurements_Examples.ipynb

@@ -4,7 +4,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# USGS dataretrieval Python Package `get_field_measurements()` Examples\n",
+    "# USGS dataretrieval Python Package Surface-Water `get_field_measurements()` Examples\n",
     "\n",
     "This notebook provides examples of using the Python dataretrieval package to retrieve surface water field measurement data for a United States Geological Survey (USGS) monitoring location. The dataretrieval package provides a collection of functions to get data from the USGS Water Data API and other online sources of hydrology and water quality data."
    ]

demos/hydroshare/USGS_WaterData_Samples_Examples.ipynb

@@ -51,7 +51,7 @@
    "source": [
     "### Basic Usage\n",
     "\n",
-    "The dataretrieval package has several functions that allow you to retrieve data from different web services. This example uses the `get_samples()` function to retrieve water quality sample data for USGS monitoring locations from Samples. The following arguments are supported:\n",
+    "The dataretrieval package has several functions that allow you to retrieve data from different web services. This example uses the `get_samples()` function to retrieve water quality sample data for USGS monitoring locations from Samples. The allowable values for the categorical arguments below come from `waterdata.get_codes()` (see the *Discrete water-quality samples* notebook). The following arguments are supported:\n",
     "\n",
     "* **ssl_check** : boolean, optional\n",
     "        Check the SSL certificate.\n",
@@ -72,8 +72,7 @@
     "        organizations - \"organization\", \"count\"\n",
     "* **activityMediaName** : string or list of strings, optional\n",
     "        Name or code indicating environmental medium in which sample was taken.\n",
-    "        Check the `activityMediaName_lookup()` function in this module for all\n",
-    "        possible inputs.\n",
+    "        Use `get_codes(code_service=\"samplemedia\")` for all possible inputs.\n",
     "        Example: \"Water\".\n",
     "* **activityStartDateLower** : string, optional\n",
     "        The start date if using a date range. Takes the format YYYY-MM-DD.\n",
@@ -90,16 +89,16 @@
     "        Example: \"Sample-Routine, regular\".\n",
     "* **characteristicGroup** : string or list of strings, optional\n",
     "        Characteristic group is a broad category of characteristics\n",
-    "        describing one or more results. Check the `characteristicGroup_lookup()`\n",
-    "        function in this module for all possible inputs.\n",
+    "        describing one or more results. Use\n",
+    "        `get_codes(code_service=\"characteristicgroup\")` for all possible inputs.\n",
     "        Example: \"Organics, PFAS\"\n",
     "* **characteristic** : string or list of strings, optional\n",
     "        Characteristic is a specific category describing one or more results.\n",
-    "        Check the `characteristic_lookup()` function in this module for all\n",
-    "        possible inputs.\n",
+    "        Use `get_codes(code_service=\"characteristics\")` for all possible inputs.\n",
     "        Example: \"Suspended Sediment Discharge\"\n",
     "* **characteristicUserSupplied** : string or list of strings, optional\n",
     "        A user supplied characteristic name describing one or more results.\n",
+    "        Use `get_codes(code_service=\"observedproperty\")` for all possible inputs.\n",
     "* **boundingBox**: list of four floats, optional\n",
     "        Filters on the the associated monitoring location's point location\n",
     "        by checking if it is located within the specified geographic area. \n",
@@ -116,27 +115,22 @@
     "* **countryFips** : string or list of strings, optional\n",
     "        Example: \"US\" (United States)\n",
     "* **stateFips** : string or list of strings, optional\n",
-    "        Check the `stateFips_lookup()` function in this module for all\n",
-    "        possible inputs.\n",
     "        Example: \"US:15\" (United States: Hawaii)\n",
     "* **countyFips** : string or list of strings, optional\n",
-    "        Check the `countyFips_lookup()` function in this module for all\n",
-    "        possible inputs.\n",
     "        Example: \"US:15:001\" (United States: Hawaii, Hawaii County)\n",
     "* **siteTypeCode** : string or list of strings, optional\n",
-    "        An abbreviation for a certain site type. Check the `siteType_lookup()`\n",
-    "        function in this module for all possible inputs.\n",
+    "        An abbreviation for a certain site type. Use\n",
+    "        `get_codes(code_service=\"sitetype\")` for all possible inputs.\n",
     "        Example: \"GW\" (Groundwater site)\n",
     "* **siteTypeName** : string or list of strings, optional\n",
-    "        A full name for a certain site type. Check the `siteType_lookup()`\n",
-    "        function in this module for all possible inputs.\n",
+    "        A full name for a certain site type. Use\n",
+    "        `get_codes(code_service=\"sitetype\")` for all possible inputs.\n",
     "        Example: \"Well\"\n",
     "* **usgsPCode** : string or list of strings, optional\n",
     "        5-digit number used in the US Geological Survey computerized\n",
     "        data system, National Water Information System (NWIS), to\n",
-    "        uniquely identify a specific constituent. Check the \n",
-    "        `characteristic_lookup()` function in this module for all possible\n",
-    "        inputs.\n",
+    "        uniquely identify a specific constituent. Use\n",
+    "        `get_codes(code_service=\"characteristics\")` for all possible inputs.\n",
     "        Example: \"00060\" (Discharge, cubic feet per second)\n",
     "* **hydrologicUnit** : string or list of strings, optional\n",
     "        Max 12-digit number used to describe a hydrologic unit.\n",
@@ -300,7 +294,7 @@
    "source": [
     "#### Example 4: Retrieve water quality sample data for one site and convert to a wide format\n",
     "\n",
-    "Note that the USGS Samples database returns multiple parameters in a \"long\" format: each row in the resulting table represents a single observation of a single parameter. Furthermore, every observation has 181 fields of metadata. However, if you wanted to place your water quality data into a \"wide\" format, where each column represents a water quality parameter code, the code below details one solution."
+    "Note that the USGS Samples database returns multiple parameters in a \"long\" format: each row in the resulting table represents a single observation of a single parameter. Furthermore, every observation comes with more than 180 fields of metadata (the default `fullphyschem` profile returns 187 columns). However, if you wanted to place your water quality data into a \"wide\" format, where each column represents a water quality parameter code, the code below details one solution."
    ]
   },
   {

demos/hydroshare/USGS_WaterData_SiteInfo_Examples.ipynb

@@ -172,8 +172,9 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "# Get the site information for a state\n",
-    "siteINFO_state = waterdata.get_monitoring_locations(state_code=\"UT\")\n",
+    "# Get the site information for a state. state_code is a two-digit ANSI code;\n",
+    "# 49 is Utah. (The postal abbreviation \"UT\" returns no results.)\n",
+    "siteINFO_state = waterdata.get_monitoring_locations(state_code=\"49\")\n",
     "display(siteINFO_state[0])"
    ]
   },

demos/hydroshare/USGS_WaterData_SiteInventory_Examples.ipynb

@@ -148,7 +148,9 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "#### Example 3: Retrieve information for a single monitoring location"
+    "#### Example 3: Retrieve a single monitoring location without geometry\n",
+    "\n",
+    "Pass `skip_geometry=True` to get a plain `pandas.DataFrame` (no `geometry` column) instead of a `geopandas.GeoDataFrame`."
    ]
   },
   {
@@ -157,8 +159,11 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "oneSite = waterdata.get_monitoring_locations(monitoring_location_id=\"USGS-05114000\")\n",
-    "display(oneSite[0])"
+    "oneSite_nogeom = waterdata.get_monitoring_locations(\n",
+    "    monitoring_location_id=\"USGS-05114000\", skip_geometry=True\n",
+    ")\n",
+    "print(\"geometry column present:\", \"geometry\" in oneSite_nogeom[0].columns)\n",
+    "display(oneSite_nogeom[0])"
    ]
   },
   {

demos/hydroshare/USGS_WaterData_UnitValues_Examples.ipynb

@@ -181,7 +181,7 @@
     "\n",
     "#### Example 2: Get unit values for an individual monitoring location and parameter between a start and end date.\n",
     "\n",
-    "NOTE: By default, start and end date are evaluated as local time, and the result is returned with the timestamps in the local time of the monitoring location."
+    "NOTE: By default, the start and end dates are interpreted in the monitoring location's local time. Regardless of the input time zone, the returned `time` column is tz-aware UTC (see Example 4 for supplying UTC input explicitly)."
    ]
   },
   {
@@ -228,7 +228,7 @@
    "source": [
     "#### Example 4: Retrieve data using UTC times\n",
     "\n",
-    "NOTE: Adding 'Z' to the input time parameters indicates that they are in UTC rather than local time. The time stamps associated with the data returned are still in the local time of the USGS monitoring location."
+    "NOTE: Adding 'Z' to the input time parameters indicates that they are in UTC rather than local time. The returned timestamps are tz-aware UTC in either case."
    ]
   },
   {
@@ -267,29 +267,6 @@
     "print(\"Retrieved \" + str(len(discharge_multisite[0])) + \" data values.\")\n",
     "display(discharge_multisite[0])"
    ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "The following example requests the same two-location data as the previous example."
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "discharge_multisite = waterdata.get_continuous(\n",
-    "    monitoring_location_id=[\"USGS-04024430\", \"USGS-04024000\"],\n",
-    "    parameter_code=parameterCode,\n",
-    "    time=\"2013-10-01/2013-10-01\",\n",
-    "    \n",
-    ")\n",
-    "print(\"Retrieved \" + str(len(discharge_multisite[0])) + \" data values.\")\n",
-    "display(discharge_multisite[0])"
-   ]
   }
  ],
  "metadata": {

demos/peak_streamflow_trends.ipynb

@@ -8,7 +8,7 @@
     "\n",
     "## Introduction\n",
     "\n",
-    "This notebook demonstrates a slightly more advanced application of the `dataretrieval.waterdata` module: assembling a dataset of historical annual peak streamflow and regressing peak discharge against time to look for trends \u2014 not at a single station, but across many."
+    "This notebook demonstrates a slightly more advanced application of the `dataretrieval.waterdata` module: assembling a dataset of historical annual peak streamflow and regressing peak discharge against time to look for trends — not at a single station, but across many."
    ]
   },
   {
@@ -151,7 +151,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "To run the analysis for all states since 1970, one would only need to uncomment and run the following lines. However, pulling all that data from the Water Data API takes time and could put a burden on resources."
+    "Running the analysis for every state since 1970 would pull a large amount of data from the Water Data API and could burden the service. To keep this demo light, we run a single small state — Rhode Island — below."
    ]
   },
   {
@@ -160,10 +160,10 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "# Download peak discharge for every stream gage in Rhode Island and run\n",
-    "# the trend regression on each. The async chunker (default concurrency 16)\n",
-    "# fans the ``get_peaks`` call across all sites in a single pool; the full\n",
-    "# run completes in roughly two seconds.\n",
+    "# Download peak discharge for every stream gage in Rhode Island and run the\n",
+    "# trend regression on each. For larger states the async chunker (default\n",
+    "# concurrency 16) automatically fans the ``get_peaks`` call across many sites;\n",
+    "# Rhode Island is small enough to return in a single request.\n",
     "start = \"1970-01-01\"\n",
     "states = [\"Rhode Island\"]\n",
     "final_df = peak_trend_analysis(state_names=states, start_date=start)\n",
@@ -174,22 +174,22 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Instead, let's quickly load some pre-generated results bundled with this notebook. (This example dataset was produced by an earlier run of the analysis and retains the column names from that run.)"
+    "The cell above ran the full analysis for a single small state (Rhode Island) and returned `final_df` — one row per gage whose peak-discharge trend is statistically significant (`p_value < 0.05`), carrying the regression slope, intercept, p-value, and standard error."
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Notice how the data has been transformed. In addition to statistics about the peak streamflow trends, the analysis joined monitoring-location metadata to add latitude and longitude for each station."
+    "`final_df` pairs each station's trend statistics with its monitoring-location metadata (`monitoring_location_id`, `state_name`, `site_type_code`, …). Because `peak_trend_analysis` requests the locations with `skip_geometry=True`, `final_df` carries no coordinate columns; drop that argument if you want the `geometry` for mapping."
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
     "## Plotting the results\n",
-    "Finally we'll use `basemap` and `matplotlib`, along with the location information from the Water Data API, to plot the results on a map (shown below). Monitoring locations with increasing peak annual discharge are shown in red, and those with decreasing peaks in blue."
+    "The commented cell below sketches how one might map the results with `basemap` and `matplotlib`, coloring monitoring locations with increasing peak annual discharge in red and decreasing peaks in blue. It is left commented because `basemap` is awkward to install on a remote machine. Note that it refers to a pre-generated national result set using the legacy NWIS coordinate columns (`dec_lat_va` / `dec_long_va`) rather than the Rhode Island `final_df` computed above; to map `final_df` directly, rerun `peak_trend_analysis` without `skip_geometry=True` and use the resulting `geometry` column."
    ]
   },
   {