feat(waterdata): add waterdata.xarray module returning CF datasets

Add dataretrieval.waterdata.xarray, optional-dependency wrappers that
mirror the Water Data time-series getters but return CF-conventions
xarray.Dataset objects instead of bare DataFrames.

- Ragged (CF contiguous ragged array) layout by default; pass dense=True
  for the NaN-filled (monitoring_location_id, time) grid with one named
  variable per parameter.
- CF metadata is derived from columns the getters already return
  (unit_of_measure -> units, statistic_id -> cell_methods,
  parameter_code -> standard_name/vertical_datum), plus a cached
  parameter-name lookup; sites carry cf_role=timeseries_id with lon/lat.
- Coverage: get_daily, get_continuous, get_latest_continuous,
  get_latest_daily, get_nearest_continuous, get_peaks,
  get_field_measurements, get_samples, and preliminary
  get_stats_por / get_stats_date_range.
- xarray is an optional extra (pip install dataretrieval[xarray]); the
  core package never imports it. Hash-valued ID columns are dropped
  inside the xarray builders, so the plain getters are left untouched.

CF vocabulary maps live in waterdata.types (xarray-free, plain data).
Adds a demo notebook + docs entry and offline converter unit tests.

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

Author: thodson-usgs

dataretrieval/waterdata/types.py

@@ -74,3 +74,62 @@
         "count",
     ],
 }
+
+
+# --- CF / xarray vocabulary mappings ---------------------------------------
+# Lookup tables used by :mod:`dataretrieval.waterdata.xarray` to translate
+# USGS terms into CF-conventions metadata. Each is intentionally partial:
+# anything not listed falls back to a sensible default (raw unit string kept
+# verbatim; no standard_name emitted) rather than guessing a wrong CF term.
+# They are plain data, so they live here rather than in the (xarray-optional)
+# converter module and can be extended without importing xarray.
+
+# USGS unit strings -> UDUNITS / CF-canonical form.
+CF_UNIT_MAP = {
+    "ft^3/s": "ft3 s-1",
+    "ft3/s": "ft3 s-1",
+    "ft": "ft",
+    "in": "in",
+    "degC": "degC",
+    "deg C": "degC",
+    "uS/cm": "uS/cm",
+    "mg/l": "mg L-1",
+    "mg/L": "mg L-1",
+    # UDUNITS 'ton' is the US short ton; 'short_ton' is not a valid UDUNITS name.
+    "tons/day": "ton day-1",
+    "%": "percent",
+}
+
+# USGS statistic_id -> the operator in a CF ``cell_methods`` string.
+CF_CELL_METHODS = {
+    "00001": "maximum",
+    "00002": "minimum",
+    "00003": "mean",
+    "00006": "sum",
+    "00008": "median",
+    "00011": "point",  # instantaneous
+}
+
+# USGS 5-digit parameter code -> CF standard_name. Deliberately conservative;
+# codes without a confident match are left without a standard_name.
+CF_STANDARD_NAMES = {
+    "00060": "water_volume_transport_in_river_channel",
+    # 00010 (water temperature) is intentionally omitted: ``water_temperature``
+    # is NOT a CF standard name, and the only valid CF water-temperature name,
+    # ``sea_water_temperature``, is wrong-domain for USGS freshwater/groundwater.
+    # Leaving it unmapped keeps the variable's ``long_name`` without emitting an
+    # invalid or misleading ``standard_name``.
+    "00065": "water_surface_height_above_reference_datum",
+    "63160": "water_surface_height_above_reference_datum",
+    "00045": "lwe_thickness_of_precipitation_amount",
+}
+
+# USGS parameter code -> vertical reference datum, attached as a
+# ``vertical_datum`` attribute. The two water-surface-height parameters share
+# the CF standard_name water_surface_height_above_reference_datum, so the datum
+# distinguishes them: gage height (00065) is measured from a local site (gage)
+# datum, while stream water level (63160) is referenced to NAVD88.
+CF_VERTICAL_DATUM = {
+    "00065": "local site datum",
+    "63160": "NAVD88",
+}