diff --git a/CONTEXT.md b/CONTEXT.md index f89fb2c4..8acb8bd6 100644 --- a/CONTEXT.md +++ b/CONTEXT.md @@ -123,7 +123,10 @@ service differs. `service=` (`'dv'`, `'peaks'`); WQP names its collections as profiles (`Result`, `Station`, `Activity`). Those parameters are frozen public surface and keep their spelling. Prose says *collection*, including prose about the -adapters that spell it otherwise. +adapters that spell it otherwise — with one exception: deprecated NWIS keeps +`service` in its docstrings as well as its parameters. Describing a parameter +in a term its own module never uses helps nobody, and a module being retired is +not where new vocabulary should land. **Collection family** — A group of collections sharing a shape and therefore a getter signature. Their getters deliberately resemble one another; the diff --git a/dataretrieval/ogc/planning.py b/dataretrieval/ogc/planning.py index 2693327c..c4d28f47 100644 --- a/dataretrieval/ogc/planning.py +++ b/dataretrieval/ogc/planning.py @@ -202,8 +202,9 @@ class _Axis: The args-dict key this axis substitutes back into when a chunk is rendered. atoms : tuple of str - The smallest indivisible units along this axis (one site, one - OR-clause, …). A "chunk" is a contiguous slice of ``atoms``. + The smallest indivisible units along this axis (one monitoring + location, one OR-clause, …). A "chunk" is a contiguous slice of + ``atoms``. joiner : str Separator placed between atoms when they are joined back into URL text — ``","`` for list axes, ``" OR "`` for the filter diff --git a/dataretrieval/waterdata/measurements.py b/dataretrieval/waterdata/measurements.py index ddbe578e..fe5d5acc 100644 --- a/dataretrieval/waterdata/measurements.py +++ b/dataretrieval/waterdata/measurements.py @@ -252,10 +252,11 @@ def get_peaks( ) -> tuple[pd.DataFrame, BaseMetadata]: """Get the annual peak streamflow / stage record for a monitoring location. - Peaks are the largest values observed at a site each water year and are - the standard input to flood-frequency analysis (e.g. log-Pearson Type III - fits). The endpoint returns one row per (monitoring location, parameter, - water year), with the peak ``value`` and the ``time`` it occurred. + Peaks are the largest values observed at a monitoring location each water + year and are the standard input to flood-frequency analysis (e.g. + log-Pearson Type III fits). The endpoint returns one row per (monitoring + location, parameter, water year), with the peak ``value`` and the ``time`` + it occurred. The collection covers both stage (parameter ``"00065"``, ``ft``) and discharge (parameter ``"00060"``, ``ft^3/s``); a typical streamgage has a @@ -338,7 +339,7 @@ def get_peaks( -------- .. code:: - >>> # Full annual peak record at one site (both stage and discharge) + >>> # Full annual peak record at one location (stage and discharge) >>> df, md = dataretrieval.waterdata.get_peaks( ... monitoring_location_id="USGS-02238500" ... ) diff --git a/dataretrieval/waterdata/metadata.py b/dataretrieval/waterdata/metadata.py index 6ab681e2..625cefdf 100644 --- a/dataretrieval/waterdata/metadata.py +++ b/dataretrieval/waterdata/metadata.py @@ -828,7 +828,7 @@ def get_combined_metadata( ... ) >>> # Two-step "what's available?" → "fetch it" workflow: - >>> # 1. inventory the sites in two HUCs + >>> # 1. inventory the monitoring locations in two HUCs >>> hucs, _ = dataretrieval.waterdata.get_combined_metadata( ... hydrologic_unit_code=["11010008", "11010009"], ... site_type="Stream", diff --git a/dataretrieval/waterdata/ratings.py b/dataretrieval/waterdata/ratings.py index 683cdf2c..655dd16f 100644 --- a/dataretrieval/waterdata/ratings.py +++ b/dataretrieval/waterdata/ratings.py @@ -135,9 +135,9 @@ def get_ratings( One feature of the batch failed *deterministically* -- a stale catalog entry (404 on its data asset), a feature with no data asset, a malformed RDB file. That feature is skipped and its id is absent - from the returned dict; the rest of the batch is unaffected. A site - with no published rating never warns -- it matches no feature in the - search, so there is nothing to skip. See + from the returned dict; the rest of the batch is unaffected. A + monitoring location with no published rating never warns -- it + matches no feature in the search, so there is nothing to skip. See :class:`~dataretrieval.exceptions.SkippedItemWarning` for the policy (transients never skip) and the ``filterwarnings`` recipe that makes a skip fatal. diff --git a/dataretrieval/waterdata/samples.py b/dataretrieval/waterdata/samples.py index b73ef3e1..e8e024c8 100644 --- a/dataretrieval/waterdata/samples.py +++ b/dataretrieval/waterdata/samples.py @@ -382,8 +382,8 @@ def get_samples_summary( row per (characteristic group, characteristic, user-supplied characteristic) combination with result and activity counts and the first / most recent activity dates — useful for taking inventory of what discrete-sample data - exists at a site before pulling the underlying observations with - :func:`get_samples`. + exists at a monitoring location before pulling the underlying observations + with :func:`get_samples`. The summary service is single-site only: it accepts exactly one monitoring location per request. diff --git a/dataretrieval/waterdata/time_series.py b/dataretrieval/waterdata/time_series.py index f3c7b572..ee27758e 100644 --- a/dataretrieval/waterdata/time_series.py +++ b/dataretrieval/waterdata/time_series.py @@ -233,11 +233,12 @@ def get_daily( ... last_modified="P7D", ... ) - >>> # Chain queries: pull all stream sites in a state, then their - >>> # daily discharge for the last week. The site list can be hundreds - >>> # of values long — the request is transparently chunked across - >>> # multiple chunks so the URL stays under the server's byte - >>> # limit. Combined output looks like a single query. + >>> # Chain queries: pull all stream monitoring locations in a + >>> # state, then their daily discharge for the last week. The + >>> # location list can be hundreds of values long — the request + >>> # is transparently chunked across multiple chunks so the URL + >>> # stays under the server's byte limit. Combined output looks + >>> # like a single query. >>> sites_df, _ = dataretrieval.waterdata.get_monitoring_locations( ... state="Ohio", ... site_type="Stream", diff --git a/dataretrieval/wqp.py b/dataretrieval/wqp.py index 1d3add97..0c135ea9 100644 --- a/dataretrieval/wqp.py +++ b/dataretrieval/wqp.py @@ -4,7 +4,7 @@ .. todo:: - - implement other services like Organization, Activity, etc. + - implement other collections like Organization, Activity, etc. """ @@ -155,14 +155,14 @@ def _query_wqp( legacy: bool, **kwargs: Any, ) -> tuple[DataFrame, WQP_Metadata]: - """Run one WQP getter query against the selected service. - - Services with a WQX3.0 equivalent (those in :data:`services_wqx3`) use - :func:`wqx3_url` when ``legacy=False`` and :func:`wqp_url` otherwise. - Legacy-only services route through :func:`_legacy_only_url`, which warns - and falls back to the legacy profile. ``dataProfile`` is validated against - :data:`_PROFILE_RULES`, and the CSV response is parsed via - :func:`_read_wqp_csv`. + """Run one WQP getter query against the selected collection. + + Collections with a WQX3.0 equivalent (those in :data:`services_wqx3`, + which keeps its legacy name) use :func:`wqx3_url` when ``legacy=False`` + and :func:`wqp_url` otherwise. Legacy-only collections route through + :func:`_legacy_only_url`, which warns and falls back to the legacy + profile. ``dataProfile`` is validated against :data:`_PROFILE_RULES`, and + the CSV response is parsed via :func:`_read_wqp_csv`. """ kwargs = _check_kwargs(kwargs) kwargs = _resolve_profile(service, legacy, kwargs) @@ -184,7 +184,7 @@ def _query_wqp( ) df = _read_wqp_csv(response.text) # Only get_results documents the appended DateTime columns and the - # activity-start sort, so the other services keep their parsed shape. + # activity-start sort, so the other collections keep their parsed shape. if service == "Result": df = _attach_datetime_columns(df) return df, WQP_Metadata(response, **kwargs)