{"id":31531540,"url":"https://github.com/hyriver/hydrosignatures","last_synced_at":"2025-10-04T02:13:18.837Z","repository":{"id":60694476,"uuid":"544479858","full_name":"hyriver/hydrosignatures","owner":"hyriver","description":"A suite of tools for computing hydrological signatures","archived":false,"fork":false,"pushed_at":"2025-06-25T20:11:11.000Z","size":475,"stargazers_count":11,"open_issues_count":1,"forks_count":3,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-08-31T22:09:49.217Z","etag":null,"topics":["hydrological-data-analysis","hydrology","python"],"latest_commit_sha":null,"homepage":"https://docs.hyriver.io/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hyriver.png","metadata":{"files":{"readme":"README.rst","changelog":"HISTORY.rst","contributing":"CONTRIBUTING.rst","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.rst","threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":"AUTHORS.rst","dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":["cheginit"]}},"created_at":"2022-10-02T15:33:33.000Z","updated_at":"2025-08-21T16:35:41.000Z","dependencies_parsed_at":"2023-11-29T19:26:02.397Z","dependency_job_id":"2d008f4f-dda5-48d4-a71d-9a7fd44c3b7b","html_url":"https://github.com/hyriver/hydrosignatures","commit_stats":{"total_commits":233,"total_committers":3,"mean_commits":77.66666666666667,"dds":0.03862660944206009,"last_synced_commit":"091ae7de79715d2ac74e755bd34a7d7a71e91d63"},"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"purl":"pkg:github/hyriver/hydrosignatures","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyriver%2Fhydrosignatures","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyriver%2Fhydrosignatures/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyriver%2Fhydrosignatures/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyriver%2Fhydrosignatures/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hyriver","download_url":"https://codeload.github.com/hyriver/hydrosignatures/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyriver%2Fhydrosignatures/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278254466,"owners_count":25956604,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-04T02:00:05.491Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["hydrological-data-analysis","hydrology","python"],"created_at":"2025-10-04T02:13:17.848Z","updated_at":"2025-10-04T02:13:18.831Z","avatar_url":"https://github.com/hyriver.png","language":"Python","funding_links":["https://github.com/sponsors/cheginit"],"categories":[],"sub_categories":[],"readme":".. image:: https://raw.githubusercontent.com/hyriver/HyRiver-examples/main/notebooks/_static/hydrosignatures_logo.png\n    :target: https://github.com/hyriver/HyRiver\n\n|\n\n.. image:: https://joss.theoj.org/papers/b0df2f6192f0a18b9e622a3edff52e77/status.svg\n    :target: https://joss.theoj.org/papers/b0df2f6192f0a18b9e622a3edff52e77\n    :alt: JOSS\n\n|\n\n.. |pygeohydro| image:: https://github.com/hyriver/pygeohydro/actions/workflows/test.yml/badge.svg\n    :target: https://github.com/hyriver/pygeohydro/actions/workflows/test.yml\n    :alt: Github Actions\n\n.. |pygeoogc| image:: https://github.com/hyriver/pygeoogc/actions/workflows/test.yml/badge.svg\n    :target: https://github.com/hyriver/pygeoogc/actions/workflows/test.yml\n    :alt: Github Actions\n\n.. |pygeoutils| image:: https://github.com/hyriver/pygeoutils/actions/workflows/test.yml/badge.svg\n    :target: https://github.com/hyriver/pygeoutils/actions/workflows/test.yml\n    :alt: Github Actions\n\n.. |pynhd| image:: https://github.com/hyriver/pynhd/actions/workflows/test.yml/badge.svg\n    :target: https://github.com/hyriver/pynhd/actions/workflows/test.yml\n    :alt: Github Actions\n\n.. |py3dep| image:: https://github.com/hyriver/py3dep/actions/workflows/test.yml/badge.svg\n    :target: https://github.com/hyriver/py3dep/actions/workflows/test.yml\n    :alt: Github Actions\n\n.. |pydaymet| image:: https://github.com/hyriver/pydaymet/actions/workflows/test.yml/badge.svg\n    :target: https://github.com/hyriver/pydaymet/actions/workflows/test.yml\n    :alt: Github Actions\n\n.. |pygridmet| image:: https://github.com/hyriver/pygridmet/actions/workflows/test.yml/badge.svg\n    :target: https://github.com/hyriver/pygridmet/actions/workflows/test.yml\n    :alt: Github Actions\n\n.. |pynldas2| image:: https://github.com/hyriver/pynldas2/actions/workflows/test.yml/badge.svg\n    :target: https://github.com/hyriver/pynldas2/actions/workflows/test.yml\n    :alt: Github Actions\n\n.. |async| image:: https://github.com/hyriver/async-retriever/actions/workflows/test.yml/badge.svg\n    :target: https://github.com/hyriver/async-retriever/actions/workflows/test.yml\n    :alt: Github Actions\n\n.. |signatures| image:: https://github.com/hyriver/hydrosignatures/actions/workflows/test.yml/badge.svg\n    :target: https://github.com/hyriver/hydrosignatures/actions/workflows/test.yml\n    :alt: Github Actions\n\n================ ====================================================================\nPackage          Description\n================ ====================================================================\nPyNHD_           Navigate and subset NHDPlus (MR and HR) using web services\nPy3DEP_          Access topographic data through National Map's 3DEP web service\nPyGeoHydro_      Access NWIS, NID, WQP, eHydro, NLCD, CAMELS, and SSEBop databases\nPyDaymet_        Access daily, monthly, and annual climate data via Daymet\nPyGridMET_       Access daily climate data via GridMET\nPyNLDAS2_        Access hourly NLDAS-2 data via web services\nHydroSignatures_ A collection of tools for computing hydrological signatures\nAsyncRetriever_  High-level API for asynchronous requests with persistent caching\nPyGeoOGC_        Send queries to any ArcGIS RESTful-, WMS-, and WFS-based services\nPyGeoUtils_      Utilities for manipulating geospatial, (Geo)JSON, and (Geo)TIFF data\n================ ====================================================================\n\n.. _PyGeoHydro: https://github.com/hyriver/pygeohydro\n.. _AsyncRetriever: https://github.com/hyriver/async-retriever\n.. _PyGeoOGC: https://github.com/hyriver/pygeoogc\n.. _PyGeoUtils: https://github.com/hyriver/pygeoutils\n.. _PyNHD: https://github.com/hyriver/pynhd\n.. _Py3DEP: https://github.com/hyriver/py3dep\n.. _PyDaymet: https://github.com/hyriver/pydaymet\n.. _PyGridMET: https://github.com/hyriver/pygridmet\n.. _PyNLDAS2: https://github.com/hyriver/pynldas2\n.. _HydroSignatures: https://github.com/hyriver/hydrosignatures\n\nHydroSignatures: Tools for computing hydrological signatures\n------------------------------------------------------------\n\n.. image:: https://img.shields.io/pypi/v/hydrosignatures.svg\n    :target: https://pypi.python.org/pypi/hydrosignatures\n    :alt: PyPi\n\n.. image:: https://img.shields.io/conda/vn/conda-forge/hydrosignatures.svg\n    :target: https://anaconda.org/conda-forge/hydrosignatures\n    :alt: Conda Version\n\n.. image:: https://codecov.io/gh/hyriver/hydrosignatures/branch/main/graph/badge.svg\n    :target: https://codecov.io/gh/hyriver/hydrosignatures\n    :alt: CodeCov\n\n.. image:: https://img.shields.io/pypi/pyversions/hydrosignatures.svg\n    :target: https://pypi.python.org/pypi/hydrosignatures\n    :alt: Python Versions\n\n.. image:: https://static.pepy.tech/badge/hydrosignatures\n    :target: https://pepy.tech/project/hydrosignatures\n    :alt: Downloads\n\n|\n\n.. image:: https://www.codefactor.io/repository/github/hyriver/hydrosignatures/badge\n   :target: https://www.codefactor.io/repository/github/hyriver/hydrosignatures\n   :alt: CodeFactor\n\n.. image:: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json\n    :target: https://github.com/astral-sh/ruff\n    :alt: Ruff\n\n.. image:: https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit\u0026logoColor=white\n    :target: https://github.com/pre-commit/pre-commit\n    :alt: pre-commit\n\n.. image:: https://mybinder.org/badge_logo.svg\n    :target: https://mybinder.org/v2/gh/hyriver/HyRiver-examples/main?urlpath=lab/tree/notebooks\n    :alt: Binder\n\n|\n\nFeatures\n--------\n\nHydroSignatures is a suite of tools for computing hydrological signatures\nand a part of `HyRiver \u003chttps://github.com/hyriver/HyRiver\u003e`__ software stack.\nThis package includes the following functions:\n\n- ``exceedance``: Exceedance probability that can be used plotting flow\n  duration curves;\n- ``flow_duration_curve_slope``: Slope of flow duration curve;\n- ``flashiness_index``: Flashiness index;\n- ``mean_monthly``: Mean monthly summary of a time series that can be used\n  for plotting regime curves;\n- ``rolling_mean_monthly``: Rolling mean monthly summary of a time series\n  that can be used for plotting smoothed regime curves;\n- ``baseflow``: Extracting baseflow from a streamflow time series using the\n  Lyne and Hollick digital filter (Ladson et al., 2013);\n- ``baseflow_recession``: Baseflow recession analysis using the nonparametric\n  analytic (Posavec et al., 2006) and exponential fit methods;\n- ``baseflow_index``: Baseflow index;\n- ``aridity_index``: Aridity index;\n- ``seasonality_index_walsh``: Seasonality index (Walsh and Lawler, 1981);\n- ``seasonality_index_markham``: Seasonality index (Markham, 1970);\n- ``extract_extrema``: Determining the location of local maxima and minima in a\n  time series;\n\nMoreover, the package has a class called ``HydroSignatures`` that can be used to compute\nall these signatures by passing a streamflow and a precipitation time series, both\nin millimeters per day (or any other unit of time). This class supports subtraction\nand inequality operators, which can be used to compare two ``HydroSignatures`` objects.\nYou can serialize the class to a JSON object using the ``to_json`` method or convert it\nto a dictionary using the ``to_dict`` method.\n\nMoreover, ``numba`` is an optional dependency for the ``baseflow`` function.\nInstalling ``numba`` will speed up the computation of baseflow significantly.\nFor more efficient handling of NaN values, you can also install ``numbagg``.\n\nYou can also try using HydroSignatures without installing\nit on your system by clicking on the binder badge. A Jupyter Lab\ninstance with the HyRiver stack pre-installed will be launched in your web browser, and you\ncan start coding!\n\nMoreover, requests for additional functionalities can be submitted via\n`issue tracker \u003chttps://github.com/hyriver/hydrosignatures/issues\u003e`__.\n\nCitation\n--------\nIf you use any of HyRiver packages in your research, we appreciate citations:\n\n.. code-block:: bibtex\n\n    @article{Chegini_2021,\n        author = {Chegini, Taher and Li, Hong-Yi and Leung, L. Ruby},\n        doi = {10.21105/joss.03175},\n        journal = {Journal of Open Source Software},\n        month = {10},\n        number = {66},\n        pages = {1--3},\n        title = {{HyRiver: Hydroclimate Data Retriever}},\n        volume = {6},\n        year = {2021}\n    }\n\nInstallation\n------------\n\nYou can install HydroSignatures using ``pip``:\n\n.. code-block:: console\n\n    $ pip install hydrosignatures\n\nor from the ``conda-forge`` repository using `Conda \u003chttps://docs.conda.io/en/latest/\u003e`__\nor `Mamba \u003chttps://github.com/conda-forge/miniforge\u003e`__:\n\n.. code-block:: console\n\n    $ conda install -c conda-forge hydrosignatures\n\nQuick start\n-----------\n\nLet's explore the capabilities of ``HydroSignatures`` by getting streamflow\nusing PyGeoHydro, basin geometry using PyNHD and precipitation using PyDaymet.\nIn this example, we select West Branch Herring Run At Idlewylde, MD, as the\nwatershed of interest and compute the hydrological signatures for the period\nfrom 2010 to 2020.\n\n.. code-block:: python\n\n    import pydaymet as daymet\n    import hydrosignatures as hs\n    import pygeohydro as gh\n    from hydrosignatures import HydroSignatures\n    from pygeohydro import NWIS\n    from pynhd import WaterData\n\n    site = \"01585200\"\n    start = \"2010-01-01\"\n    end = \"2020-12-31\"\n\nFirst, we get the basin geometry of the watershed using ``gagesii_basins`` layer of\nthe USGS's WaterData web service.\n\n.. code-block:: python\n\n    wd = WaterData(\"gagesii_basins\")\n    geometry = wd.byid(\"gage_id\", site).geometry[0]\n\nThen, we obtain the station's info and streamflow data using NWIS. Note that\nwe should convert the streamflow from cms to mm/day.\n\n.. code-block:: python\n\n    nwis = NWIS()\n    info = nwis.get_info({\"site\": site})\n    area_sqm = info.drain_sqkm.values[0] * 1e6\n    q_cms = nwis.get_streamflow(site, (start, end))\n    q_mmpd = q_cms * (24.0 * 60.0 * 60.0) / area_sqm * 1e3\n    q_mmpd.index = pd.to_datetime(q_mmpd.index.date)\n\nNext, we retrieve the precipitation data using PyDaymet over the whole basin\nusing the basin geometry and take its mean as the basin's precipitation.\n\n.. code-block:: python\n\n    prcp = daymet.get_bygeom(geometry, (start, end), variables=\"prcp\")\n    p_mmpd = prcp.prcp.mean(dim=[\"x\", \"y\"]).to_pandas()\n    p_mmpd.index = pd.to_datetime(p_mmpd.index.date)\n    q_mmpd = q_mmpd.loc[p_mmpd.index]\n\nNow, we can pass these two to the ``HydroSignatures`` class:\n\n.. code-block:: python\n\n    sig = HydroSignatures(q_mmpd, p_mmpd)\n\nThe ``values`` property of this class contains the computed signatures. For example,\nlet's plot the regime curves:\n\n.. code-block:: python\n\n    sig.values.mean_monthly.plot()\n\n\n.. image:: https://raw.githubusercontent.com/hyriver/HyRiver-examples/main/notebooks/_static/signatures_rc.png\n    :target: https://docs.hyriver.io/examples/notebooks/signatures.ipynb\n    :align: center\n\nNote that, you can also use the functions directly. For example, let's get\nstreamflow observations for another station and separate the baseflow using\nvarious filter parameters and compare them:\n\n.. code-block:: python\n\n    import numpy as np\n    import pandas as pd\n\n    q = nwis.get_streamflow(\"12304500\", (\"2019-01-01\", \"2019-12-31\"))\n    alpha = np.arange(0.9, 1, 0.01)\n    qb = pd.DataFrame({a: hs.baseflow(q.squeeze(), alpha=a) for a in alpha})\n\n\n.. image:: https://raw.githubusercontent.com/hyriver/HyRiver-examples/main/notebooks/_static/signatures_bf.png\n    :target: https://docs.hyriver.io/examples/notebooks/signatures.ipynb\n    :align: center\n\nWe can also carry out a baseflow recession analysis using the ``baseflow_recession``\nfunction. For this we need to get streamflow data for a longer period.\n\n.. code-block:: python\n\n    q = nwis.get_streamflow(\"12304500\", (\"2000-01-01\", \"2019-12-31\"))\n    mrc_np, bfr_k_np = hs.baseflow_recession(q, fit_method=\"nonparametric_analytic\")\n    mrc_exp, bfr_k_exp = hs.baseflow_recession(q, fit_method=\"exponential\")\n\nAccording to Safeeq et al. (2013), $K$ value of $0.065$ is the threshold between groundwater\ndominated slow-draining systems and shallow subsurface flow dominated fast draining systems.\nIn this example, since $K= 0.056$, the watershed is groundwater dominated.\n\n.. image:: https://raw.githubusercontent.com/hyriver/HyRiver-examples/main/notebooks/_static/recession.png\n    :target: https://docs.hyriver.io/examples/notebooks/signatures.ipynb\n    :align: center\n\nLastly, let's compute Markham's seasonality index for all streamflow time series of\nthe stations in the CAMELS dataset. We retrieve the CAMELS dataset using PyGeoHydro:\n\n.. code-block:: python\n\n    import xarray as xr\n\n    _, camels_qobs = gh.get_camels()\n    discharge = camels_qobs.discharge.dropna(\"station_id\")\n    discharge = xr.where(discharge \u003c 0, 0, discharge)\n    si = hs.seasonality_index_markham(discharge.to_pandas())\n\nMore examples can be found `here \u003chttps://docs.hyriver.io/examples.html\u003e`__.\n\nContributing\n------------\n\nContributions are very welcomed. Please read\n`CONTRIBUTING.rst \u003chttps://github.com/hyriver/hydrosignatures/blob/main/CONTRIBUTING.rst\u003e`__\nfile for instructions.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhyriver%2Fhydrosignatures","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhyriver%2Fhydrosignatures","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhyriver%2Fhydrosignatures/lists"}