The Hysteretic and Gatekeeping Depressions Model (HGDM)

Description

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'.

Author(s)

Maintainer: Kevin Shook kevin.shook@usask.ca

References

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.

See Also

Useful links:

• https://github.com/CentreForHydrology/HGDMr

Applies HGDM to forcings

Description

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.

Usage

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
)

Arguments

Value

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^3/s' values

If no large depression is specified, the returned variables are:

date or datetime

R date or POSIXct datetime.

total_contrib_frac

The connected/contributing fraction of the basin. Includes both the meta depression and the upland fraction connected to the outlet.

total_outflow_volume

The volume of outflow (m ^3) in the interval.

small_depression_contrib_frac

The connected/contributing fraction of the meta depression.

small_depression_water_volume

The volume of water (m ^3) retained in the meta depression.

small_depression_water_depth

The depth of water (m) retained in the meta depression.

small_depression_water_area

The area of water (m ^2) 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:

date or datetime

R date or POSIXct datetime.

large_depression_contrib_frac

The connected/contributing fraction of the large depression.

large_depression_water_volume

The volume of water (m ^3) retained in the large depression.

large_depression_water_area

The area of water (m ^2) retained in the large depression.

Examples

{ 
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)
}

Determines if area-volume estimation is by equation or rating

Description

Determines if area-volume estimation is by equation or rating

Usage

area_frac(volume, max_volume, max_area = NULL, rating_parameters)

Arguments

Value

Returns water area fraction

Author(s)

Kevin Shook

Examples

water_area_frac <- area_frac(1000, 2000, NULL, 1.2)

daily basin 7120951600 PHyDAP fluxes

Description

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.

Usage

daily_7120951600

Format

A dateframe with 25932 rows and 5 columns spanning the period 1950-2020.

Details

Variables:

date

R date

rainfall

Daily rainfall on water (mm)

snowmelt

Daily snow melt on water (mm)

runoff

Daily upland runoff (mm)

evap

Daily water evaporation (mm)

Source

PHyDAP

References

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.

Calculates connected/contributing fraction

Description

Calculates connected/contributing fraction

Usage

linear_hysteresis_CF(
  current_storage = 0,
  delta_storage = 0,
  max_storage = 0,
  current_contrib_frac = 0,
  threshold = -0.01
)

Arguments

Value

Returns the updated connected/contributing fraction

Author(s)

Kevin Shook

Examples

cf <- linear_hysteresis_CF(current_storage = 50,
delta_storage = 10, max_storage = 100, current_contrib_frac = 0)

Convert depressional storage volume to area

Description

Convert depressional storage volume to area

Usage

vol2area_rating(rating_curve, volumes, method = "linear")

Arguments

Value

Returns a scalar or vector of lake stages

Author(s)

Kevin Shook

Examples

{
rating_curve <- data.frame(area=1:10, volume=seq(10, 100, 10))
a <- vol2area_rating(rating_curve, 55)
}

Estimates total depressional water area fraction

Description

Estimates total depressional water area fraction

Usage

volfrac2areafrac_Clark(volume_frac, p)

Arguments

Value

Returns the fractional water area

Author(s)

Kevin Shook

Examples

areafrac <- volfrac2areafrac_Clark(0.5, 1.2)