Skip to content

Commit 07daaf2

Browse files
e-larosepre-commit-ci[bot]Zeitsperrehuard
authored
Hydrological signatures (#2227)
### What kind of change does this PR introduce? - More hydrological signatures have been added ### Does this PR introduce a breaking change? No. --------- Signed-off-by: Trevor James Smith <10819524+Zeitsperre@users.noreply.github.com> Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com> Co-authored-by: Trevor James Smith <10819524+Zeitsperre@users.noreply.github.com> Co-authored-by: David Huard <huard.david@ouranos.ca>
1 parent 5852fc9 commit 07daaf2

File tree

14 files changed

+977
-32
lines changed

14 files changed

+977
-32
lines changed

.gitignore

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -113,8 +113,8 @@ docs/_dynamic/indicators.json
113113
docs/variables.json
114114

115115
# autogenerated BibTeX files
116-
docs/tmp_saved_input_references.bib
117116
docs/paper/tmp_saved_input_paper.bib
117+
docs/tmp_saved_input_references.bib
118118

119119
# VS Code
120120
.vscode

.zenodo.json

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -88,6 +88,11 @@
8888
"affiliation": "Ouranos Consortium, Montréal, Québec, Canada",
8989
"orcid": "0000-0003-0738-3940"
9090
},
91+
{
92+
"name": "Larose, Ève",
93+
"affiliation": "Polytechnique, Montréal, Québec, Canada",
94+
"orcid": "0009-0005-0832-4047"
95+
},
9196
{
9297
"name": "Lierhammer, Ludwig",
9398
"affiliation": "Deutscher Wetterdienst, Hamburg, Germany",

AUTHORS.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -52,3 +52,4 @@ Contributors
5252
* Jack Kit-tai Wong <kit.tai.wong@gmail.com> `@jack-ktw <https://github.com/jack-ktw>`_
5353
* Jens de Bruijn <j.a.debruijn@outlook.com> `@jensdebruijn <https://github.com/jensdebruijn>`_
5454
* Armin Hofmann `@HofmannGeo <https://github.com/HofmannGeo>`_
55+
* Eve Larose <eve.larose.r@gmail.com> `@e-larose <https://github.com/e-larose>`_

CHANGELOG.rst

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ Changelog
44

55
v0.60.0 (unreleased)
66
--------------------
7-
Contributors to this version: Éric Dupuis (:user:`coxipi`), Trevor James Smith (:user:`Zeitsperre`), Juliette Lavoie (:user: `juliettelavoie`).
7+
Contributors to this version: Éric Dupuis (:user:`coxipi`), Trevor James Smith (:user:`Zeitsperre`), Juliette Lavoie (:user: `juliettelavoie`), Ève Larose (:user:`e-larose`), Faisal Mahmood (:user:`faimahsho`), David Huard (:user:`huard`).
88

99
Breaking changes
1010
^^^^^^^^^^^^^^^^
@@ -15,6 +15,7 @@ New indicators and features
1515
^^^^^^^^^^^^^^^^^^^^^^^^^^^
1616
* `xclim` now officially supports Python 3.14. (:issue:`2259`, :pull:`2305`).
1717
* New missing algorithm ``some_but_not_all``. (:pull:`2290`).
18+
* New hydrological indices added to ``xclim.indices._hydrology.py``. (:issue:`1624`, :pull:`2227`).
1819

1920
Bug fixes
2021
^^^^^^^^^

CITATION.cff

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -48,6 +48,9 @@ authors:
4848
- family-names: Labonté
4949
given-names: Marie-Pier
5050
orcid: "https://orcid.org/0000-0003-0738-3940"
51+
- family-names: "Larose"
52+
given-names: "Ève"
53+
orcid: "https://orcid.org/0009-0005-0832-4047"
5154
- family-names: Lierhammer
5255
given-names: Ludwig
5356
orcid: "https://orcid.org/0000-0002-7207-0003"

docs/references.bib

Lines changed: 225 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4762,3 +4762,228 @@ @incollection{ecwmf_physical_2016
47624762
https://www.ecmwf.int/sites/default/files/elibrary/2016/17117-part-iv-physical-processes.pdf
47634763
}
47644764
}
4765+
@article{alonso_gonzalez_2022,
4766+
title = {
4767+
Combined influence of maximum accumulation and melt rates on the duration
4768+
of the seasonal snowpack over temperate mountains
4769+
},
4770+
journal = {Journal of Hydrology},
4771+
volume = {608},
4772+
pages = {127574},
4773+
year = {2022},
4774+
issn = {0022-1694},
4775+
doi = {https://doi.org/10.1016/j.jhydrol.2022.127574},
4776+
url = {https://www.sciencedirect.com/science/article/pii/S0022169422001494},
4777+
author = {
4778+
Esteban Alonso-Gonz\'{a}lez and Jes\'{u}s Revuelto and Steven R. Fassnacht
4779+
and Juan {Ignacio L\'{o}pez-Moreno}
4780+
},
4781+
abstract = {
4782+
The duration of the seasonal snowpack determines numerous aspects of the
4783+
water cycle, ecology and the economy in cold and mountainous regions, and
4784+
is a balance between the magnitude of accumulated snow and the rate of
4785+
melt. The contribution of each component has not been well quantified under
4786+
contrasting topography and climatological conditions although this may
4787+
provide useful insights into how snow cover duration could respond to
4788+
climate change. Here, we examined the contribution of the annual peak snow
4789+
water equivalent (SWE) and the seasonal melt rate to define the duration of
4790+
the snowpack over temperate mountains, using snow data for mountain areas
4791+
with different climatological characteristics across the Iberian Peninsula.
4792+
We used a daily snowpack database for the period 1980--2014 over Iberia to
4793+
derive the seasonal peak SWE, melt rate and season snow cover duration. The
4794+
influence of peak SWE and melt rates on seasonal snow cover duration was
4795+
estimated using a stepwise linear model approach. The stepwise linear
4796+
models showed high R-adjusted values (average R-adjusted = 0.7), without
4797+
any clear dependence on the elevation or geographical location. In general,
4798+
the peak SWE influenced the snow cover duration over all of the mountain
4799+
areas analysed to a greater extent than the melt rates (89.1\%, 89.2\%,
4800+
81.6\%, 93.2\% and 95.5\% in the areas for the Cantabrian, Central,
4801+
Iberian, Pyrenees and Sierra Nevada mountain ranges, respectively). At
4802+
these colder sites, the melt season occurs mostly in the spring and tends
4803+
to occur very fast. In contrast, the areas where the melt rates dominated
4804+
snow cover duration were located systematically at lower elevations, due to
4805+
the high interannual variability in the occurrence of annual peak SWE (in
4806+
winter or early spring), yielding highly variable melt rates. However, in
4807+
colder sites the melt season occurs mostly in spring and it is very fast in
4808+
most of the years. The results highlight the control that the seasonal
4809+
precipitation patterns, in combination with temperature, exert on the
4810+
seasonal snow cover duration by influencing the peak SWE and suggest a
4811+
future increased importance of melt rates as temperatures increase. Despite
4812+
the high climatological variability of the Iberian mountain ranges, the
4813+
results showed a consistent behaviour along the different mountain ranges,
4814+
indicating that the methods and results may be transferrable to other
4815+
temperate mountain areas of the world.
4816+
}
4817+
}
4818+
@article{sauquet_2025,
4819+
author = {
4820+
Sauquet, E. and Evin, G. and Siauve, S. and Aissat, R. and Arnaud, P. and
4821+
B\'erel, M. and Bonneau, J. and Branger, F. and Caballero, Y. and
4822+
Coll\'eoni, F. and Ducharne, A. and Gailhard, J. and Habets, F. and
4823+
Hendrickx, F. and H\'eraut, L. and Hingray, B. and Huang, P. and Jaouen, T.
4824+
and Jeantet, A. and Lanini, S. and Le Lay, M. and Magand, C. and Mimeau, L.
4825+
and Monteil, C. and Munier, S. and Perrin, C. and Robelin, O. and Rousset,
4826+
F. and Soubeyroux, J.-M. and Strohmenger, L. and Thirel, G. and Tocquer, F.
4827+
and Tramblay, Y. and Vergnes, J.-P. and Vidal, J.-P.
4828+
},
4829+
title = {
4830+
A large transient multi-scenario multi-model ensemble of future streamflow
4831+
and groundwater projections in France
4832+
},
4833+
journal = {EGUsphere},
4834+
volume = {2025},
4835+
year = {2025},
4836+
pages = {1--41},
4837+
url = {https://egusphere.copernicus.org/preprints/2025/egusphere-2025-1788/},
4838+
doi = {10.5194/egusphere-2025-1788}
4839+
}
4840+
@article{burn_2010,
4841+
author = {Burn, Donald H. and Sharif, Mohammed and Zhang, Kan},
4842+
title = {Detection of trends in hydrological extremes for Canadian watersheds},
4843+
journal = {Hydrological Processes},
4844+
volume = {24},
4845+
number = {13},
4846+
pages = {1781--1790},
4847+
keywords = {flood analysis, low flow events, climate change, trend analysis, Canada},
4848+
doi = {https://doi.org/10.1002/hyp.7625},
4849+
url = {https://onlinelibrary.wiley.com/doi/abs/10.1002/hyp.7625},
4850+
eprint = {https://onlinelibrary.wiley.com/doi/pdf/10.1002/hyp.7625},
4851+
abstract = {
4852+
Abstract The potential impacts of climate change can alter the risk to
4853+
critical infrastructure resulting from changes to the frequency and
4854+
magnitude of extreme events. As well, the natural environment is affected
4855+
by the hydrologic regime, and changes in high flows or low flows can have
4856+
negative impacts on ecosystems. This article examines the detection of
4857+
trends in extreme hydrological events, both high and low flow events, for
4858+
streamflow gauging stations in Canada. The trend analysis involves the
4859+
application of the Mann–Kendall non-parametric test. A bootstrap resampling
4860+
process has been used to determine the field significance of the trend
4861+
results. A total of 68 gauging stations having a nominal record length of
4862+
at least 50 years are analysed for two analysis periods of 50 and 40 years.
4863+
The database of Canadian rivers investigated represents a diversity of
4864+
hydrological conditions encompassing different extreme flow generating
4865+
processes and reflects a national scale analysis of trends. The results
4866+
reveal more trends than would be expected to occur by chance for most of
4867+
the measures of extreme flow characteristics. Annual and spring maximum
4868+
flows show decreasing trends in flow magnitude and decreasing trends in
4869+
event timing (earlier events). Low flow magnitudes exhibit both decreasing
4870+
and increasing trends. Copyright \textcopyright{} 2010 John Wiley \& Sons,
4871+
Ltd.
4872+
},
4873+
year = {2010}
4874+
}
4875+
@article{zomer_2022,
4876+
title = {
4877+
Version 3 of the global aridity index and potential evapotranspiration
4878+
database
4879+
},
4880+
author = {Zomer, Robert J and Xu, Jianchu and Trabucco, Antonio},
4881+
journal = {Scientific Data},
4882+
volume = {9},
4883+
number = {1},
4884+
pages = {409},
4885+
year = {2022},
4886+
publisher = {Nature Publishing Group UK London}
4887+
}
4888+
@article{knoben_2024,
4889+
title = {
4890+
Setting expectations for hydrologic model performance with an ensemble of
4891+
simple benchmarks
4892+
},
4893+
author = {Knoben, Wouter JM},
4894+
journal = {Hydrological Processes},
4895+
volume = {38},
4896+
number = {10},
4897+
pages = {e15288},
4898+
year = {2024},
4899+
publisher = {Wiley Online Library}
4900+
}
4901+
@article{singh_2019,
4902+
title = {Towards baseflow index characterisation at national scale in New Zealand},
4903+
journal = {Journal of Hydrology},
4904+
volume = {568},
4905+
pages = {646--657},
4906+
year = {2019},
4907+
issn = {0022-1694},
4908+
doi = {https://doi.org/10.1016/j.jhydrol.2018.11.025},
4909+
url = {https://www.sciencedirect.com/science/article/pii/S0022169418308801},
4910+
author = {
4911+
Shailesh Kumar Singh and Markus Pahlow and Doug J. Booker and Ude Shankar
4912+
and Alejandro Chamorro
4913+
},
4914+
keywords = {Baseflow, Quickflow, Prediction, BFI, Random forests technique},
4915+
abstract = {
4916+
Streamflow is typically divided into two components for hydrograph
4917+
separation, quickflow and baseflow. Baseflow is the portion of streamflow
4918+
that contains groundwater flow and flow from other delayed sources and is
4919+
of key importance for river basin ecology and water resources planning and
4920+
management. The BaseFlow Index (BFI) is defined as the ratio of long-term
4921+
mean baseflow to total streamflow. Knowledge of the BFI is not directly
4922+
available for ungauged catchments and hence for most of the terrestrial
4923+
land surface. In this study, the BFI was determined for all river reaches
4924+
in New Zealand. First a recursive digital filtering technique was applied
4925+
to separate baseflow from total streamflow for 482 gauged sites across New
4926+
Zealand, whereby an individual filter parameter was determined for each
4927+
catchment. Based on the baseflow and total streamflow data the long-term
4928+
BFI for each gauged site was determined, as well as seasonal values of BFI.
4929+
BFI varies between 0.20 and 0.96 with an average of 0.53, which indicates
4930+
that 53\% of long-term streamflow in New Zealand is likely to originate
4931+
from groundwater discharge and other delayed sources. Long-term BFI values
4932+
for all river reaches that comprise the New Zealand river network were
4933+
predicted using the random forest technique. Furthermore, the winter to
4934+
summer BFI for all river reaches in New Zealand were also determined.
4935+
Distinct spatial patterns of the BFI were identified. While the spatial
4936+
distribution and the magnitude of the BFI was determined by a combination
4937+
of factors, certain patterns can be attributed to geological formations in
4938+
New Zealand, namely the volcanic plateau region and the Southern Alps.
4939+
While the dataset determined in this work can support work specifically
4940+
pertaining to water resources planning and management in New Zealand, in
4941+
particular water supply, stream ecology and pollution risk, the methodology
4942+
devised to calculate the BFI for gauged sites and to predict the BFI for
4943+
ungauged sites is applicable to any region around the world.
4944+
}
4945+
}
4946+
@article{jaffres_2021,
4947+
title = {
4948+
Hydrological characteristics of Australia: relationship between surface
4949+
flow, climate and intrinsic catchment properties
4950+
},
4951+
journal = {Journal of Hydrology},
4952+
volume = {603},
4953+
pages = {126911},
4954+
year = {2021},
4955+
issn = {0022-1694},
4956+
doi = {https://doi.org/10.1016/j.jhydrol.2021.126911},
4957+
url = {https://www.sciencedirect.com/science/article/pii/S0022169421009616},
4958+
author = {
4959+
Jasmine B.D. Jaffr\'{e}s and Ben Cuff and Chris Cuff and Iain Faichney and
4960+
Matthew Knott and Cecily Rasmussen
4961+
},
4962+
keywords = {
4963+
Climate variability, Non-perennial streams, Surface hydrology, Topography,
4964+
Soil field capacity, Water infiltration
4965+
},
4966+
abstract = {
4967+
Streamflow and baseflow dynamics are driven by complex, interconnected
4968+
catchment properties. A national study was conducted to assess the
4969+
relationship between surface flow, climate and intrinsic catchment
4970+
attributes in Australia. Subcatchments were delineated based on Horton's
4971+
5th stream order and were characterised by identifying parameters that
4972+
influence streamflow and flood behaviour. Because observational datasets
4973+
like rainfall and streamflow commonly have a non-normal distribution, the
4974+
method of L-moments was applied to several time series. Surface hydrology
4975+
and baseflow patterns were represented by twenty indices, which were
4976+
statistically summarised via principal component (PC) analysis, yielding
4977+
six PCs. Forty catchment descriptors from the themes of climate,
4978+
topography, surface condition and hydrogeology were used to investigate
4979+
their link with runoff patterns. Among these is the land surface value, a
4980+
newly defined index incorporating soil properties and land use to estimate
4981+
the capacity for water infiltration. All metrics were explored via
4982+
correlation and regression analysis against the surface hydrology PCs and
4983+
their influence on runoff discussed. The predictive skill of the regression
4984+
models is improved when non-perennial waterways are excluded. Although
4985+
rainfall characteristics dominate streamflow behaviour, topographical and
4986+
surface conditions also greatly impact on runoff, especially during
4987+
low-flow periods.
4988+
}
4989+
}

pyproject.toml

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -109,7 +109,7 @@ docs = [
109109
"sphinxcontrib-bibtex",
110110
"sphinxcontrib-svg2pdfconverter[Cairosvg]"
111111
]
112-
extras = ["flox >=0.9", "lmoments3 >=1.0.7", "numbagg >=0.8", "xsdba >=0.4.0"]
112+
extras = ["flox >=0.9", "lmoments3 >=1.0.7", "numbagg >=0.8", "xsdba >=0.4.0", "pymannkendall >=1.4.0"]
113113
all = ["xclim[dev]", "xclim[docs]", "xclim[extras]"]
114114

115115
[project.scripts]
@@ -171,6 +171,7 @@ pep621_dev_dependency_groups = ["all", "dev", "docs"]
171171
"pyyaml" = "yaml"
172172

173173
[tool.deptry.per_rule_ignores]
174+
DEP001 = ["pymannkendall"]
174175
DEP002 = ["bottleneck", "h5netcdf", "lmoments3", "numbagg", "pyarrow"]
175176
DEP004 = ["matplotlib", "pooch", "pytest", "pytest_socket"]
176177

src/xclim/core/dataflags.py

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -71,6 +71,7 @@ def __str__(self):
7171
"outside_n_standard_deviations_of_climatology",
7272
"percentage_values_outside_of_bounds",
7373
"register_methods",
74+
"specific_discharge_extremely_high",
7475
"tas_below_tasmin",
7576
"tas_exceeds_tasmax",
7677
"tasmax_below_tasmin",
@@ -816,3 +817,35 @@ def ecad_compliant(
816817
if append:
817818
return xarray.merge([ds, ecad_flag])
818819
return ecad_flag
820+
821+
822+
@declare_units(da="[speed]", thresh="[speed]")
823+
def specific_discharge_extremely_high(da: xarray.DataArray, *, thresh: Quantified = "100 mm d-1") -> xarray.DataArray:
824+
"""
825+
Check if specific discharge values exceed 100 mm per day for any given day.
826+
827+
Parameters
828+
----------
829+
da : xarray.DataArray
830+
Specific discharge.
831+
thresh : str
832+
Threshold above which specific discharges are considered problematic and a flag is raised.
833+
834+
Returns
835+
-------
836+
xarray.DataArray, [bool]
837+
Boolean array of True where specific discharges are above the threshold.
838+
839+
Examples
840+
--------
841+
To gain access to the flag_array:
842+
843+
>>> from xclim.core.dataflags import specific_discharge_extremely_high
844+
>>> qspec = specific_discharge_dataset.qspec
845+
>>> flagged = specific_discharge_extremely_high(qspec)
846+
"""
847+
thresh_converted = convert_units_to(thresh, da, context="hydro")
848+
extreme_high_discharge = _sanitize_attrs(da > thresh_converted)
849+
extreme_high_discharge.attrs["description"] = f"One or multiple specific {da.name} found in excess of {thresh}."
850+
extreme_high_discharge.attrs["units"] = ""
851+
return extreme_high_discharge

src/xclim/data/variables.yml

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,12 @@ variables:
55
description: Air density.
66
dimensions: "[density]"
77
standard_name: air_density
8+
areacella:
9+
canonical_units: m2
10+
cell_methods: "area: sum"
11+
description: Atmospheric grid cell area.
12+
dimensions: "[area]"
13+
standard_name: cell_area
814
areacello:
915
canonical_units: m2
1016
cell_methods: "area: sum"
@@ -20,6 +26,7 @@ variables:
2026
canonical_units: m3 s-1
2127
cell_methods: "time: mean"
2228
description: The amount of water, in all phases, flowing in the river channel and flood plain.
29+
dimensions: "[length]**3/[time]"
2330
standard_name: water_volume_transport_in_river_channel
2431
dtr:
2532
canonical_units: K
@@ -252,10 +259,19 @@ variables:
252259
standard_name: lwe_thickness_of_snow_amount
253260
data_flags:
254261
- negative_accumulation_values:
262+
qspec:
263+
canonical_units: m s-1
264+
cell_methods: "time: mean"
265+
description: The amount of water, in all phases, flowing in the river channel and flood plain per unit of drainage area.
266+
dimensions: "[length]/[time]"
267+
data_flags:
268+
- specific_discharge_extremely_high:
269+
thresh: 100 mm d-1
255270
q:
256271
canonical_units: m3 s-1
257272
cell_methods: "time: mean"
258273
description: The amount of water, in all phases, flowing in the river channel and flood plain.
274+
dimensions: "[length]**3/[time]"
259275
standard_name: water_volume_transport_in_river_channel
260276
tas:
261277
canonical_units: K

0 commit comments

Comments
 (0)