gagely

gagely provides Python utilities for retrieving US weather, streamflow, rainfall, and related gage data from services such as Contrail and USGS, with helpers for writing time-series data to HEC-DSS through pydsstools.

The Python import package is named gagely.

Installation

Install from a local checkout:

python -m pip install .

For development:

python -m pip install -e ".[dev]"

Versioning

Package versions are derived from git tags with setuptools-scm.

Use tags such as:

git tag 0.1.0

Then build/install from that tagged checkout.

Basic Usage

USGS

The USGS package wraps dataretrieval.waterdata and adds DSS-write helpers. Set the personal access token once per process, then go through the daily or continuous submodule:

from gagely.usgs import configure_usgs, daily, continuous

configure_usgs("YOUR_USGS_API_KEY")

Daily values to DSS (period-mean, written as a regular 1DAY series — each row is shifted to the period-end timestamp DSS expects):

daily.flow_to_dss(
    output="flow.dss",
    site_id="08354900",
    sdate="2000-01-01",
)

Continuous (instantaneous) values to DSS (sampling interval is inferred per site from the data, e.g. 15MIN for a typical 15-minute gage; internal time gaps are filled with the no-data sentinel UNDEFINED):

continuous.to_dss(
    output="iv.dss",
    site_id="12362500",
    param="flow",
    sdate="2026-01-01",
)

Returning a DataFrame instead of writing to DSS:

df_daily = daily.get_flow("08354900", sdate="2020-01-01")
df_iv    = continuous.get_flow("12362500", sdate="2026-01-01")

site_id accepts a single id, a list, or a dict mapping label → id (the dict keys become the DSS APART). Bare USGS ids ("08354900") and prefixed ones ("USGS-08354900") are both accepted.

Each submodule exposes the same helper set: get_flow, get_stage, to_dss, flow_to_dss, stage_to_dss, plus the canonical endpoint-name function (get_daily or get_continuous) for arbitrary parameter / statistic combinations. The endpoint-name functions are also re-exported at the package level: from gagely.usgs import get_daily, get_continuous.

Contrail

from gagely.contrail import configure_contrail, fetch_to_dss

configure_contrail(url="https://contrail.example.com", system_key="YOUR_KEY")
fetch_to_dss(
    output="rainfall.dss",
    sensor_class=10,
    sdate="2000-01-01",
    or_site_id=200,
)

Resolve gage names to Contrail or_site_id values before fetching:

from gagely.contrail import get_site_metadata, validate_gages

site_meta = get_site_metadata()
gage_to_or_id = validate_gages(
    ["Station 2", "City Hall"],
    site_meta,
)

Site and sensor metadata can also be queried directly, filtered by site_id or or_site_id (and, for sensors, sensor_class):

from gagely.contrail import get_site_metadata, get_sensor_metadata

# Omit site_id / or_site_id to get metadata for every site/sensor
# accessible under the configured URL/system key.
site_meta = get_site_metadata(or_site_id="200")
sensor_meta = get_sensor_metadata(or_site_id="200", sensor_class=10)

Both return a list of dicts, one per <row> in the XML response (each dict maps child-element tag → text).

Contributing

Bug reports, feature requests, and pull requests are welcome — see CONTRIBUTING.md for guidelines. This project follows the Code of Conduct.

License

gagely is licensed under the MIT License.