Add source parameter to CONUS hydrology + arctic hydrology endpoints

[Joshdpaul]

Summary

Both the CONUS hydrology and arctic hydrology stats coverages in Rasdaman have been updated (conus_hydro_segments_stats_combined and ak_hydro_segments_stats_combined) to include a source dimension encoding three variants of the data. This branch wires up that new dimension as a ?source= query parameter and simplifies the conus_hydrology/stats/{stream_id} and arctic_hydrology/stats/{stream_id} endpoints by moving the historical baseline adjustment math out of inline application code and into the coverage itself.

Changes:

• New ?source= parameter on /conus_hydrology/stats/{stream_id}, arctic_hydrology/stats/{stream_id}, /conus_hydrology/modeled_climatology/{stream_id}, and /arctic_hydrology/modeled_climatology/{stream_id}. Accepted values are:
  • gcm_diff_applied_to_maurer (default for conus hydrology): GCM-projected changes applied to the Maurer historical baseline
  • gcm_diff_applied_to_cheng (default for arctic hydrology): GCM-projected changes applied to the Cheng historical baseline
  • original_gcm: raw GCM output
  • gcm_diff: ratio/absolute difference between projected and historical GCM (for stats endpoint only; not valid for climatology)
• Hidden hydroviz app /conus_hydrology/hydroviz/{stream_id} and /arctic_hydrology/hydroviz/{stream_id} endpoints are simplified: the historical baseline adjustment calculation previously done inline is now handled by calculate_and_apply_gcm_diffs_to_maurer_climatology() or calculate_and_apply_gcm_diffs_to_cheng_climatology(), and is called from the modeled climatology endpoint when source is "gcm_diff_applied_to_maurer" (the conus default) or "gcm_diff_applied_to_cheng" (the arctic default). Note that this math is now optional depending on the choice of source: the user can get an un-adjusted hydrograph too by using source="original_gcm", if that's what they want.
• ma99 removed from client-side calculation: annual mean flow is now stored in the coverage, so calculate_and_populate_annual_mean_flow() is deleted.
• Source notes in metadata: variable descriptions in JSON and CSV output include a brief note describing what the values represent for the selected source. For the JSON, notes were included in each variable description to be very explicit about what data the user is getting. I did this because I don't think it's safe to assume anyone is reading a JSON completely top to bottom - they might be accessing only certain parts and so the redundancy might be useful. For the CSV, the note is included near the top of the metadata as I expect users will read the notes at the top before accessing values.
• Application-level validation: ?source= values are validated via marshmallow in application.py.
• Documentation: ?source= options and parameter chaining documented for both endpoints.

Note that the source notes (in variable metadata descriptions and CSV headers) and their documentation wording are first drafts. The language describing what each source mode means should be revised if there is a better way to clearly communicate the data provenance. Any ideas here are welcome, or we could workshop it with the rest of the team later.

XREF: ua-snap/hydroviz#184
XREF: ua-snap/rasdaman-ingest#157

XREF: ua-snap/arctic_rivers#4
XREF: ua-snap/rasdaman-ingest#158

[Copilot]

Pull request overview

This PR updates the CONUS hydrology API to support a new Rasdaman “source” dimension by exposing it as a ?source= query parameter, while simplifying hydroviz logic by moving Maurer-adjustment math out of inline endpoint code and into shared processing.

Changes:

• Add ?source= support for /conus_hydrology/stats/{stream_id} and /conus_hydrology/modeled_climatology/{stream_id} (with gcm_diff_applied_to_maurer as default).
• Update Rasdaman stats coverage wiring to conus_hydro_segments_stats_combined and add WCS subsetting for the source axis.
• Add “source notes” into JSON variable descriptions and CSV metadata output; remove client-side ma99 derivation.

Reviewed changes

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

Show a summary per file

File	Description
templates/documentation/conus_hydrology.html	Documents ?source= options for stats and modeled climatology endpoints.
routes/conus_hydrology.py	Implements source handling, updates stats coverage, adds Maurer adjustment helper, and simplifies hydroviz aggregation.
generate_requests.py	Adds optional SUBSET=source(...) to CONUS hydrology WCS request generation.
csv_functions.py	Adds source-specific notes to CSV metadata and adds None-skipping in CSV row construction.
application.py	Adds global marshmallow validation for source query parameter values.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[cstephen]

I kicked the tires on this quite a bit, downloading the JSON data for each source from each endpoint, doing a diff of the different source values to make sure they differed in the way I expected. I also tested the hydroviz webapp against this endpoint and made a few tweaks in PR #722 to make this more compatible with the webapp. The documentation and CSVs look great, too! Approved!