Add waterdata.get_peaks for the annual peak-streamflow OGC collection

[thodson-usgs]

Adds a thin wrapper around the new /ogcapi/v0/collections/peaks collection. Returns the annual peak record for a monitoring location — one row per (location, parameter, water year) — which is the standard input to flood-frequency analysis (log-Pearson Type III, etc.).

The collection covers stage (parameter 00065) and discharge (00060); typical streamgages have a series for each.

Implementation

A thin parameter declaration plus a single call to the existing service-agnostic get_ogc_data(args, output_id, service):

• service = "peaks"
• output_id = "peak_id" — the API's id field is renamed for users, matching the project's other get_* functions.

R has no equivalent yet; the docstring was written from scratch following the project's existing get_* style.

Live API examples (verified)

from dataretrieval.waterdata import get_peaks

# Full annual record (both stage and discharge)
df, md = get_peaks(monitoring_location_id="USGS-02238500")
# 135 rows, parameter codes ['00060', '00065']

# Discharge peaks only
df, md = get_peaks(monitoring_location_id="USGS-02238500", parameter_code="00060")

# Multi-site over a water-year window
df, md = get_peaks(
    monitoring_location_id=["USGS-07069000", "USGS-07064000", "USGS-07068000"],
    parameter_code="00060",
    water_year=[2020, 2021, 2022, 2023],
)

Test plan

• test_get_peaks — single-site happy path; asserts peak_id, value, water_year columns and a clean parameter-code subset.
• test_get_peaks_water_year_filter — exercises the water_year filter.
• Live verification: monitoring_location_id="USGS-02238500" returns 135 rows, parameter codes {"00060", "00065"}.

Related

Part of the v1.1.4 release-staging series; will be linked from a tracking issue.

[thodson-usgs]

Tracked in the v1.1.4 release-staging issue: #270.

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated no new comments.

[ldecicco-USGS]

Do you have deprecation messages in all the NWIS modules? I think with peaks and ratings, all NWIS functions should now have a waterdata replacement.

[thodson-usgs]

Here's Claude's survey:

nwis function	status	waterdata replacement
get_qwdata	defunct (raises)	waterdata.get_samples
get_discharge_measurements	defunct (raises)	waterdata.get_field_measurements
get_gwlevels	defunct (raises)	waterdata.get_field_measurements
get_pmcodes	defunct (raises)	waterdata.get_reference_table("parameter-codes")
get_water_use	defunct (raises)	(no equivalent; service retired upstream)
get_discharge_peaks	active, no warning	waterdata.get_peaks (this PR, #267)
get_ratings	active, no warning	waterdata.get_ratings (#269)
get_stats	active, no warning	waterdata.get_stats_por / get_stats_date_range
get_dv	active, no warning	waterdata.get_daily
get_iv	active, no warning	waterdata.get_continuous
get_info	active, no warning	waterdata.get_monitoring_locations
what_sites	active, no warning	waterdata.get_monitoring_locations
query_waterdata	active, no warning	low-level; superseded by direct waterdata.get_* calls
query_waterservices	active, no warning	low-level; superseded by direct waterdata.get_* calls
get_record	active, no warning	dispatcher; replace with the appropriate waterdata.get_*

So once #267 (peaks) and #269 (ratings) merge, every NWIS function has a waterdata replacement (except get_water_use, whose upstream service was retired) and the 9 still-active ones are eligible for DeprecationWarning.

I'll follow up with the warnings in a separate PR