| Title: | Hysteretic and Gatekeeping Depressions Model |
|---|---|
| Description: | Implementation of the Hysteretic and Gatekeeping Depressions Model (HGDM) which calculates variable connected/contributing areas and resulting discharge volumes in prairie basins dominated by depressions ("slough" or "potholes"). The small depressions are combined into a single "meta" depression which explicitly models the hysteresis between the storage of water and the connected/contributing areas of the depressions. The largest (greater than 5% of the total depressional area) depression (if it exists) is represented separately to model its gatekeeping, i.e. the blocking of upstream flows until it is filled. The methodolgy is described in detail in Shook and Pomeroy (2025, <doi:10.1016/j.jhydrol.2025.132821>). |
| Authors: | Kevin Shook [cre, aut] |
| Maintainer: | Kevin Shook <[email protected]> |
| License: | GPL-3 |
| Version: | 1.0.0 |
| Built: | 2025-02-22 06:56:03 UTC |
| Source: | https://github.com/centreforhydrology/hgdmr |
HGDMr is an implementation of the Hysteretic and Gatekeeping Depressions Model (HGDM) which is a one-dimensional model of the effects of varying connected/contributing fractions of Canadian Prairie basins.
Using specified fluxes (rainfall, snowmelt, upland runoff and evaporation), HGDM computes a) the time-varying connected/contributing fraction of a basin having depressional storage and b) the depth of discharge in each time interval.
Note that this model does not route the flows through the basin. This would require the use of another R package, such as RHMS, which has the function 'reachRouting'.
Maintainer: Kevin Shook [email protected]
Shook, Kevin R., and John W. Pomeroy. “The Hysteretic and Gatekeeping Depressions Model - A New Model for Variable Connected Fractions of Prairie Basins.” Journal of Hydrology 654 (June 1, 2025): 132821. https://doi.org/10.1016/j.jhydrol.2025.132821.
Shook, Kevin R., Zhihua He, John W. Pomeroy, Chris Spence, and Colin J. Whitfield. “A Practitioner-Oriented Regional Hydrology Data Product for Use in Site-Specific Hydraulic Applications.” Scientific Data 11, no. 1 (October 14, 2024): 1125. https://doi.org/10.1038/s41597-024-03962-1.
Clark, Martyn P., and Kevin R. Shook. “The Numerical Formulation of Simple Hysteretic Models to Simulate the Large-Scale Hydrological Impacts of Prairie Depressions.” Water Resources Research 58, no. 12 (2022): e2022WR032694. https://doi.org/10.1029/2022WR032694.
Shook, Kevin, Simon Papalexiou, and John W. Pomeroy. “Quantifying the Effects of Prairie Depressional Storage Complexes on Drainage Basin Connectivity.” Journal of Hydrology 593 (February 1, 2021): 125846. https://doi.org/10.1016/j.jhydrol.2020.125846.
Shook, Kevin, John W Pomeroy, Christopher Spence, and Lyle Boychuk. “Storage Dynamics Simulations in Prairie Wetland Hydrology Models: Evaluation and Parameterization.” Hydrological Processes 27, no. 13 (June 2013): 1875–89. https://doi.org/10.1002/hyp.9867.
Useful links:
A dataframe of daily CRHM fluxes modelled for basin 7120951600. The fluxes were taken from the PHyDAP project https://www.frdr-dfdr.ca/repo/dataset/7ce4bd7a-4bcc-4f8c-8129-32a691f46c8e hourly outputs of CRHM models forced with ERA5 data over the period 1950-2020. The fluxes were then aggregated to daily values.
daily_7120951600daily_7120951600
A dateframe with 25932 rows and 5 columns spanning the period 1950-2020.
Variables:
R date
Daily rainfall on water (mm)
Daily snow melt on water (mm)
Daily upland runoff (mm)
Daily water evaporation (mm)
PHyDAP
Shook, Kevin R., Zhihua He, John W. Pomeroy, Chris Spence, and Colin J. Whitfield. “A Practitioner-Oriented Regional Hydrology Data Product for Use in Site-Specific Hydraulic Applications.” Scientific Data 11, no. 1 (October 14, 2024): 1125. https://doi.org/10.1038/s41597-024-03962-1.
Applies the Hysteretic and Gatekeeping Depressions Model to basin-scale fluxes determined by hydrological modelling to calculate the outflows during a given time interval. Note than no routing is performed.
HGDM( upland_area = NULL, small_depression_area = NULL, large_depression_area = NULL, area_units = "km2", max_small_depression_storage = 0, max_large_depression_storage = 0, initial_small_depression_storage = 0, initial_large_depression_storage = 0, storage_units = "mm", small_depressions_initial_connected_fraction = 0, upland_fraction_to_small = 0, upland_fraction_to_large = 0, upland_fraction_to_outlet = 0, small_fraction_to_large = 0, forcings = NULL, small_p = NULL, large_rating = 0, sub_intervals = 1 )HGDM( upland_area = NULL, small_depression_area = NULL, large_depression_area = NULL, area_units = "km2", max_small_depression_storage = 0, max_large_depression_storage = 0, initial_small_depression_storage = 0, initial_large_depression_storage = 0, storage_units = "mm", small_depressions_initial_connected_fraction = 0, upland_fraction_to_small = 0, upland_fraction_to_large = 0, upland_fraction_to_outlet = 0, small_fraction_to_large = 0, forcings = NULL, small_p = NULL, large_rating = 0, sub_intervals = 1 )
upland_area |
Required. Area of uplands, which drain to the outlet, small depressions or the large depression. |
small_depression_area |
Required. Area of small depressions. |
large_depression_area |
Optional. If |
area_units |
Units of all areas. Must be one of km2 (default), ha or m2. |
max_small_depression_storage |
Maximum depth of storage in small depressions. |
max_large_depression_storage |
Maximum depth of storage in large depressions. |
initial_small_depression_storage |
Initial depth of storage in small depressions. |
initial_large_depression_storage |
Initial depth of storage in large depressions. |
storage_units |
Units of all storage depths. Must be one of mm (default) m, or m3. If a depth is specified then it will be converted to a volume by multiplying by the appropriate area. |
small_depressions_initial_connected_fraction |
Initial connected fraction (0-1). |
upland_fraction_to_small |
Fraction of uplands draining to small depressions. If |
upland_fraction_to_large |
Fraction of uplands draining to large depression. This is the basin of the large depression. |
upland_fraction_to_outlet |
Fraction of uplands draining directly to outlet. Analogous to the effective fraction. |
small_fraction_to_large |
Fraction of small depression area draining into large depression. Governed by location of large depression in the basin. |
forcings |
Required. A data frame of time series of |
small_p |
Parameter for small depression water volume-area relationship. |
large_rating |
Rating curve parameters for large depression. |
sub_intervals |
Number of sub-intervals for solution of each time step. |
Returns a data frame. Depending on whether or not a large depression was
specified, the data frame will have differing variables. Note that regardless of the
units specified for areas and volumes, all of the variables returned are in SI
dimensions, i.e. 'm' and 'm/s'
values
If no large depression is specified, the returned variables are:
R date or POSIXct datetime.
The connected/contributing fraction of the basin. Includes both the meta depression and the upland fraction connected to the outlet.
The volume of outflow (m ) in the interval.
The connected/contributing fraction of the meta depression.
The volume of water (m ) retained in the meta depression.
The depth of water (m) retained in the meta depression.
The area of water (m ) retained in the meta depression.
If there is a large depression, then 'total_contrib_frac' includes the effect of the large depression and the additional variables are also returned:
R date or POSIXct datetime.
The connected/contributing fraction of the large depression.
The volume of water (m ) retained in the large depression.
The area of water (m ) retained in the large depression.
{ daily_fluxes <- daily_7120951600 basin_area <- 100 small_depression_frac <- 0.24 small_depression_area <- small_depression_frac * basin_area large_depression_area <- 0 upland_area <- basin_area - (small_depression_area + large_depression_area) area_units <- "km2" max_small_depression_storage <- 300 max_large_depression_storage <- 0 initial_small_depression_storage <- max_small_depression_storage / 2 initial_large_depression_storage <- max_large_depression_storage / 2 storage_units <- "mm" small_depressions_initial_connected_fraction <- 0 upland_fraction_to_small <- 0.98 upland_fraction_to_large <- 0 upland_fraction_to_outlet <- 0.02 small_fraction_to_large <- 0 small_p <- 1.2 large_rating <- 1.4 sub_intervals <- 1 results <- HGDM(upland_area, small_depression_area, large_depression_area = 0, area_units = "km2", max_small_depression_storage, max_large_depression_storage, initial_small_depression_storage, initial_large_depression_storage, storage_units, small_depressions_initial_connected_fraction, upland_fraction_to_small, upland_fraction_to_large, upland_fraction_to_outlet, small_fraction_to_large, forcings = daily_fluxes[1:100,], small_p = small_p, large_rating = large_rating, sub_intervals = sub_intervals) }{ daily_fluxes <- daily_7120951600 basin_area <- 100 small_depression_frac <- 0.24 small_depression_area <- small_depression_frac * basin_area large_depression_area <- 0 upland_area <- basin_area - (small_depression_area + large_depression_area) area_units <- "km2" max_small_depression_storage <- 300 max_large_depression_storage <- 0 initial_small_depression_storage <- max_small_depression_storage / 2 initial_large_depression_storage <- max_large_depression_storage / 2 storage_units <- "mm" small_depressions_initial_connected_fraction <- 0 upland_fraction_to_small <- 0.98 upland_fraction_to_large <- 0 upland_fraction_to_outlet <- 0.02 small_fraction_to_large <- 0 small_p <- 1.2 large_rating <- 1.4 sub_intervals <- 1 results <- HGDM(upland_area, small_depression_area, large_depression_area = 0, area_units = "km2", max_small_depression_storage, max_large_depression_storage, initial_small_depression_storage, initial_large_depression_storage, storage_units, small_depressions_initial_connected_fraction, upland_fraction_to_small, upland_fraction_to_large, upland_fraction_to_outlet, small_fraction_to_large, forcings = daily_fluxes[1:100,], small_p = small_p, large_rating = large_rating, sub_intervals = sub_intervals) }