docs: copy-edit guides and fix demo-notebook narrative/code inconsistencies

CONTRIBUTING.md

@@ -36,7 +36,7 @@ however writing code is not the only way to contribute.
 
 ### Reporting Bugs
 
-Report bugs at https://github.com/USGS-python/dataretrieval/issues.
+Report bugs at https://github.com/DOI-USGS/dataretrieval-python/issues.
 
 When reporting a bug, please include:
 
@@ -49,7 +49,7 @@ When reporting a bug, please include:
 
 ### Fixing Bugs
 
-Look through the GitHub [issues](https://github.com/USGS-python/dataretrieval/issues)
+Look through the GitHub [issues](https://github.com/DOI-USGS/dataretrieval-python/issues)
 for known and unresolved bugs. Any issues labeled "bug" that are unassigned,
 are open for resolution. You are welcome to comment in the relevant issue to
 state your intention to resolve the bug, which will help ensure there is no
@@ -68,7 +68,7 @@ your fork, to the original upstream repository.
 
 ### Implementing Features
 
-Look through the GitHub [issues](https://github.com/USGS-python/dataretrieval/issues)
+Look through the GitHub [issues](https://github.com/DOI-USGS/dataretrieval-python/issues)
 for outstanding feature requests. Anything tagged with "enhancement"
 and "please-help" is open to whomever wants to implement it.
 
@@ -83,8 +83,8 @@ Before you submit a pull request, check that it meets these guidelines:
 2. If the pull request adds or modifies functionality, the documentation should
    be updated. To do so, either add or modify a functions docstring which will
    automatically become part of the API documentation
-3. The pull request should work for Python 3.7, 3.8, 3.9, 3.10 - refer to the
-   [python-package.yml file](https://github.com/USGS-python/dataretrieval/blob/master/.github/workflows/python-package.yml)
+3. The pull request should work for Python 3.9 and later - refer to the
+   [python-package.yml file](https://github.com/DOI-USGS/dataretrieval-python/blob/main/.github/workflows/python-package.yml)
    for the latest versions of Python being tested by the continuous integration
    pipelines. This will be checked automatically by the CI pipelines once the
    pull request is opened.
@@ -98,7 +98,7 @@ via any automated processes or pipelines.
 #### Style
 
 * Attempt to write code following the [PEP8 style guidelines](https://peps.python.org/pep-0008/) as much as possible
-* The public interace should emphasize functions over classes; however, classes
+* The public interface should emphasize functions over classes; however, classes
   can and should be used internally and in tests
 * Functions for downloading data from a specific web portal must be grouped
   within their own submodule
@@ -202,7 +202,7 @@ will need to do the following (in a separate branch of the repository):
 ### Submitting Feedback
 
 The best way to send feedback is to open an issue at
-https://github.com/USGS-python/dataretrieval/issues.
+https://github.com/DOI-USGS/dataretrieval-python/issues.
 
 Please be as clear as possible in your feedback, if you are reporting a bug
 refer to [Reporting Bugs](#reporting-bugs).
@@ -211,7 +211,7 @@ refer to [Reporting Bugs](#reporting-bugs).
 ### Feature Requests
 
 To request or propose a new feature, open an issue at
-https://github.com/USGS-python/dataretrieval/issues.
+https://github.com/DOI-USGS/dataretrieval-python/issues.
 
 Please be sure to:
 * Explain in detail how it would work, possibly with pseudo-code or an example

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": {