docs: clean up Water Data API vignettes

- Rename `daily_modern`/`field_modern` → `daily_data`/`field_data` (the
  "_modern" suffix was a leftover NWIS-vs-modern comparison artifact)
- Rename `what_huc_sites` → `huc_sites`, `sites_information` → `sites_info`,
  `site_1`/`site_2` → `renamed`/`raw_id`, and `site1` → `site` in the daily
  statistics notebook (no `site2` ever existed)
- Fix broken intra-notebook anchor `#General-retrieval-and-CQL2`
  → `#general-retrieval-and-cql2`
- Simplify the daily-values facet plot by dropping the unnecessary
  `squeeze=False` + axes-indexing workaround
- Clean up the `map_sites` helper in the samples notebook to use the
  conventional `fig, ax = plt.subplots(...)` unpacking and a docstring

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

Author: thodson-usgs

demos/USGS_WaterData_DailyStatistics_Examples.ipynb

@@ -41,7 +41,7 @@
     "\n",
     "%matplotlib inline\n",
     "\n",
-    "site1 = \"USGS-02037500\""
+    "site = \"USGS-02037500\""
    ]
   },
   {
@@ -66,7 +66,7 @@
    "outputs": [],
    "source": [
     "jan_por_mean, _ = waterdata.get_stats_por(\n",
-    "    monitoring_location_id=site1,\n",
+    "    monitoring_location_id=site,\n",
     "    parameter_code=\"00060\",\n",
     "    computation_type=\"arithmetic_mean\",\n",
     "    start_date=\"01-01\",\n",
@@ -126,7 +126,7 @@
    "outputs": [],
    "source": [
     "full_por_percentiles, _ = waterdata.get_stats_por(\n",
-    "    monitoring_location_id=site1,\n",
+    "    monitoring_location_id=site,\n",
     "    parameter_code=\"00060\",\n",
     "    computation_type=[\"minimum\", \"maximum\", \"percentile\"],\n",
     "    start_date=\"01-01\",\n",
@@ -210,7 +210,7 @@
    "outputs": [],
    "source": [
     "daily, _ = waterdata.get_daily(\n",
-    "    monitoring_location_id=site1,\n",
+    "    monitoring_location_id=site,\n",
     "    parameter_code=\"00060\",\n",
     "    statistic_id=\"00003\",\n",
     "    time=[\"2024-01-01\", \"2025-12-31\"],\n",
@@ -259,7 +259,7 @@
    "outputs": [],
    "source": [
     "jan_daterange_mean, _ = waterdata.get_stats_date_range(\n",
-    "    monitoring_location_id=site1,\n",
+    "    monitoring_location_id=site,\n",
     "    parameter_code=\"00060\",\n",
     "    computation_type=\"arithmetic_mean\",\n",
     "    start_date=\"2024-01-01\",\n",
@@ -287,7 +287,7 @@
    "outputs": [],
    "source": [
     "multiyear, _ = waterdata.get_stats_date_range(\n",
-    "    monitoring_location_id=site1,\n",
+    "    monitoring_location_id=site,\n",
     "    parameter_code=\"00060\",\n",
     "    computation_type=\"arithmetic_mean\",\n",
     "    start_date=\"2023-09-30\",\n",
@@ -338,7 +338,7 @@
    "outputs": [],
    "source": [
     "monthly_raw, _ = waterdata.get_stats_date_range(\n",
-    "    monitoring_location_id=site1,\n",
+    "    monitoring_location_id=site,\n",
     "    parameter_code=\"00060\",\n",
     "    computation_type=\"arithmetic_mean\",\n",
     ")\n",

demos/USGS_WaterData_DiscreteSamples_Examples.ipynb

@@ -43,12 +43,11 @@
     "plt.rcParams[\"figure.figsize\"] = (7, 4)\n",
     "\n",
     "\n",
-    "# Scatter plot of sample-site locations (a static map; use folium for an\n",
-    "# interactive version).\n",
     "def map_sites(df, title=\"\"):\n",
+    "    \"\"\"Static scatter plot of sample-site locations. Use folium for interactive.\"\"\"\n",
     "    lon = pd.to_numeric(df[\"Location_Longitude\"], errors=\"coerce\")\n",
     "    lat = pd.to_numeric(df[\"Location_Latitude\"], errors=\"coerce\")\n",
-    "    ax = plt.subplots(figsize=(7, 5))[1]\n",
+    "    fig, ax = plt.subplots(figsize=(7, 5))\n",
     "    ax.scatter(lon, lat, s=10, color=\"red\", alpha=0.7)\n",
     "    ax.set_xlabel(\"Longitude\")\n",
     "    ax.set_ylabel(\"Latitude\")\n",
@@ -528,12 +527,21 @@
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "Python 3",
+   "display_name": "Python 3 (ipykernel)",
    "language": "python",
    "name": "python3"
   },
   "language_info": {
-   "name": "python"
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.12.10"
   }
  },
  "nbformat": 4,

demos/USGS_WaterData_Introduction_Examples.ipynb

@@ -97,7 +97,7 @@
    "outputs": [],
    "source": [
     "# Ask for just a few columns instead of the full ~40-column record.\n",
-    "site_info, _ = waterdata.get_monitoring_locations(\n",
+    "sites_info, _ = waterdata.get_monitoring_locations(\n",
     "    monitoring_location_id=\"USGS-01491000\",\n",
     "    properties=[\n",
     "        \"monitoring_location_id\",\n",
@@ -106,7 +106,7 @@
     "        \"monitoring_location_name\",\n",
     "    ],\n",
     ")\n",
-    "site_info.drop(columns=\"geometry\")"
+    "sites_info.drop(columns=\"geometry\")"
    ]
   },
   {
@@ -126,7 +126,7 @@
     "\n",
     "The APIs accept [CQL2](https://www.loc.gov/standards/sru/cql/) expressions for\n",
     "complex queries through the `filter` / `filter_lang` arguments. See the\n",
-    "[General retrieval and CQL2](#General-retrieval-and-CQL2) section below.\n",
+    "[General retrieval and CQL2](#general-retrieval-and-cql2) section below.\n",
     "\n",
     "### Simple features\n",
     "\n",
@@ -176,11 +176,11 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "sites_information, _ = waterdata.get_monitoring_locations(\n",
+    "sites_info, _ = waterdata.get_monitoring_locations(\n",
     "    monitoring_location_id=\"USGS-01491000\"\n",
     ")\n",
-    "print(f\"{sites_information.shape[1]} columns returned\")\n",
-    "sites_information.drop(columns=\"geometry\").T"
+    "print(f\"{sites_info.shape[1]} columns returned\")\n",
+    "sites_info.drop(columns=\"geometry\").T"
    ]
   },
   {
@@ -299,13 +299,13 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "daily_modern, _ = waterdata.get_daily(\n",
+    "daily_data, _ = waterdata.get_daily(\n",
     "    monitoring_location_id=\"USGS-01491000\",\n",
     "    parameter_code=[\"00060\", \"00010\"],\n",
     "    statistic_id=\"00003\",\n",
     "    time=[\"2023-10-01\", \"2024-09-30\"],\n",
     ")\n",
-    "daily_modern[[\"time\", \"parameter_code\", \"value\", \"approval_status\"]].head()"
+    "daily_data[[\"time\", \"parameter_code\", \"value\", \"approval_status\"]].head()"
    ]
   },
   {
@@ -324,11 +324,10 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "params = sorted(daily_modern[\"parameter_code\"].unique())\n",
-    "fig, axes = plt.subplots(len(params), 1, figsize=(7, 5), sharex=True, squeeze=False)\n",
-    "axes = axes[:, 0]  # squeeze=False -> always a 2-D array, even for one param\n",
+    "params = sorted(daily_data[\"parameter_code\"].unique())\n",
+    "fig, axes = plt.subplots(len(params), 1, figsize=(7, 5), sharex=True)\n",
     "for ax, pcode in zip(axes, params):\n",
-    "    sub = daily_modern[daily_modern[\"parameter_code\"] == pcode]\n",
+    "    sub = daily_data[daily_data[\"parameter_code\"] == pcode]\n",
     "    ax.scatter(sub[\"time\"], sub[\"value\"], s=4)\n",
     "    ax.set_ylabel(pcode)\n",
     "axes[0].set_title(\"Daily values at USGS-01491000 (water year 2024)\")\n",
@@ -386,14 +385,14 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "field_modern, _ = waterdata.get_field_measurements(\n",
+    "field_data, _ = waterdata.get_field_measurements(\n",
     "    monitoring_location_id=[\n",
     "        \"USGS-451605097071701\",\n",
     "        \"USGS-263819081585801\",\n",
     "    ],\n",
     "    time=[\"2023-10-01\", \"2024-09-30\"],\n",
     ")\n",
-    "field_modern[[\"time\", \"monitoring_location_id\", \"parameter_code\", \"value\"]].head()"
+    "field_data[[\"time\", \"monitoring_location_id\", \"parameter_code\", \"value\"]].head()"
    ]
   },
   {
@@ -404,7 +403,7 @@
    "outputs": [],
    "source": [
     "fig, ax = plt.subplots(figsize=(7, 4))\n",
-    "for site, sub in field_modern.groupby(\"monitoring_location_id\"):\n",
+    "for site, sub in field_data.groupby(\"monitoring_location_id\"):\n",
     "    ax.scatter(sub[\"time\"], sub[\"value\"], s=12, label=site)\n",
     "ax.set_ylabel(\"value\")\n",
     "ax.set_title(\"Field measurements\")\n",
@@ -499,12 +498,12 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "what_huc_sites, _ = waterdata.get_monitoring_locations(\n",
+    "huc_sites, _ = waterdata.get_monitoring_locations(\n",
     "    filter=\"hydrologic_unit_code LIKE '02070010%'\",\n",
     "    filter_lang=\"cql-text\",\n",
     ")\n",
-    "print(f\"{len(what_huc_sites)} sites in HUC 02070010\")\n",
-    "ax = what_huc_sites.plot(markersize=2, figsize=(7, 5))\n",
+    "print(f\"{len(huc_sites)} sites in HUC 02070010\")\n",
+    "ax = huc_sites.plot(markersize=2, figsize=(7, 5))\n",
     "ax.set_title(\"Sites within HUC 02070010\")\n",
     "plt.show()"
    ]
@@ -620,16 +619,16 @@
    "outputs": [],
    "source": [
     "site = \"USGS-02238500\"\n",
-    "site_1, _ = waterdata.get_monitoring_locations(\n",
+    "renamed, _ = waterdata.get_monitoring_locations(\n",
     "    monitoring_location_id=site,\n",
     "    properties=[\"monitoring_location_id\", \"state_name\", \"country_name\"],\n",
     ")\n",
-    "site_2, _ = waterdata.get_monitoring_locations(\n",
+    "raw_id, _ = waterdata.get_monitoring_locations(\n",
     "    monitoring_location_id=site,\n",
     "    properties=[\"id\", \"state_name\", \"country_name\"],\n",
     ")\n",
-    "print(\"renamed:\", [c for c in site_1.columns if c != \"geometry\"])\n",
-    "print(\"raw id :\", [c for c in site_2.columns if c != \"geometry\"])"
+    "print(\"renamed:\", [c for c in renamed.columns if c != \"geometry\"])\n",
+    "print(\"raw id :\", [c for c in raw_id.columns if c != \"geometry\"])"
    ]
   },
   {
@@ -647,12 +646,21 @@
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "Python 3",
+   "display_name": "Python 3 (ipykernel)",
    "language": "python",
    "name": "python3"
   },
   "language_info": {
-   "name": "python"
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.12.10"
   }
  },
  "nbformat": 4,