pyGWRetrieval v0.2.0.post1

pyGWRetrieval v0.2.0.post1

📦 First archived, citable release — pyGWRetrieval is now on Zenodo with a permanent DOI.

This is a post-release of v0.2.0: no code or API changes. It exists to mint the
Zenodo archive and wire the DOI into the project metadata.

What's changed

• Archived the release on Zenodo with a citable concept DOI (10.5281/zenodo.21272166)
  that always resolves to the latest version.
• Added the Zenodo DOI badge and a doi field to the BibTeX citation across the
  README and documentation.

How to cite

@software{pyGWRetrieval,
  author = {Sayantan Majumdar},
  title  = {pyGWRetrieval: Scalable Retrieval and Analysis of USGS Groundwater Level Data},
  year   = {2026},
  doi    = {10.5281/zenodo.21272166},
  url    = {https://doi.org/10.5281/zenodo.21272166}
}

pyGWRetrieval v0.2.0

pyGWRetrieval v0.2.0

This release migrates pyGWRetrieval to the modern USGS Water Data OGC API and adds a water-table depth interpolation subsystem. It includes breaking changes — see below.

Highlights

• 🌐 Modern USGS backend. All retrieval now uses the USGS Water Data OGC API (dataretrieval >= 1.2.0): get_monitoring_locations, get_daily, get_continuous, and get_field_measurements. This restores field-measurement (gwlevels) retrieval — the deprecated NWIS endpoint had started returning an HTML notice instead of data — and adds native large-area request chunking. The legacy NWIS endpoints remain only as an automatic fallback.
• 🗺️ Water-table depth maps. New WaterTableInterpolator turns point observations into gridded rasters for a chosen window (period='all'|'monthly'|'annual'|'custom') at a resolution you set in meters. Methods: idw (core), kriging (pykrige), and linear/cubic/nearest/rbf (scipy). Results support .plot(), .to_geotiff(), and .to_xarray(). Also adds idw_at_points (scattered-point IDW with leave-one-out cross-validation).
• 💧 Aquifer filtering. get_aquifer_info() returns each well's aqfr_type_cd ('U' unconfined, 'C' confined, 'M' mixed) so you can restrict to unconfined wells before mapping water-table depth.

Added

• WaterTableInterpolator, InterpolationResult, and idw_at_points, plus the optional dependency group installed with pip install pyGWRetrieval[interp] (scipy, pykrige, rasterio, xarray). Delaunay methods can backfill beyond the wells' convex hull via fill_outside='nearest'.
• GroundwaterRetrieval.get_aquifer_info() for aquifer type / well-depth attributes.
• A parameter_cd column identifying the USGS parameter behind each value — filter with data['parameter_cd'] == '72019' to keep wells on the same footing (depth vs. elevation).
• Upper Colorado River Basin example (examples/ucrc/): a 1 km mean water-table depth map with a five-method interpolation comparison and an unconfined-aquifer gap-fill.
• New documentation: a Water-Table Depth Interpolation guide and expanded API reference.

Fixed

• Field-measurement (gwlevels) retrieval, which previously returned an HTML notice instead of data.
• get_data_by_state now maps two-letter USPS codes (e.g. NV) to the full state name required by the OGC API; it previously returned no wells.
• CLI --version now reports the installed package version (was hardcoded to 0.1.0).

⚠️ Breaking changes

• site_no now carries the full monitoring-location id (e.g. USGS-393000119000001) instead of the bare site number.
• Default data_sources is now 'dv' (daily values) instead of 'all'. Pass data_sources='gwlevels', 'iv', 'all', or a list to override (Python API and CLI).
• Retrieved-data schema changed. Records are standardized to site_no, datetime, value/lev_va, and parameter_cd across all sources; NWIS-only columns (lev_tm, lev_acy_cd, lev_src_cd, lev_meth_cd, lev_status_cd) are no longer present.
• Minimum Python is now 3.10 (was 3.8) and dataretrieval >= 1.2.0 is required.

Install

pip install --upgrade pyGWRetrieval — or with interpolation support: pip install --upgrade "pyGWRetrieval[interp]"

Full changelog: https://github.com/montimaj/pyGWRetrieval/blob/main/CHANGELOG.md

pyGWRetrieval v0.1.0

pyGWRetrieval v0.1.0 is a Python package for scalable retrieval and analysis of USGS groundwater level data from the National Water Information System (NWIS). It supports flexible queries by zip code, shapefile, GeoJSON, state code, or site numbers with configurable buffer distances, and retrieves data from field measurements, daily values, and instantaneous values. Key features include multi-format export (CSV, Parquet, GeoJSON), built-in caching, and a full command-line interface. The package provides comprehensive analysis capabilities including regional trend analysis with statistical significance testing, change point detection, sustainability index computation, and future projections. Documentation includes a case study analyzing 9 major U.S. metropolitan areas with 15 publication-ready visualizations covering ~8 million groundwater records from 33,000+ wells spanning 55 years.