ch_catchment_hyps: Catchment hypsometry

In CSHS-hydRology/CSHShydRology: Canadian Hydrological Analyses

Catchment hypsometry

Description

Finds the hypsometric curve, which is the total fraction of the area below vs. elevation, for a given basin.

Usage

ch_catchment_hyps(
  catchment,
  dem,
  z_levels = NULL,
  n_levels = 10,
  zmin = NULL,
  zmax = NULL,
  quantiles = NULL,
  hypso_plot = FALSE,
  z_units = "m",
  col = "red",
  type = "o",
  xlab = "Fraction of catchment below given elevation",
  ylab = paste0("Elevation (", z_units, ")"),
  add_grid = FALSE,
  ...
)

Arguments

catchment	A sf object containing the catchment divide.
dem	A raster object of the Digital Elevation Model.
z_levels	Vector of elevation levels for the hypsometry. If specified, then no other elevation parameters are required. Default is NULL.
n_levels	If specified, sets number of elevation intervals. Can be used with zmin and zmax. Default is NULL.
zmin	Minimum elevation for hypsometry. If not specified, minimum catchment elevation is used. Default is NULL.
zmax	Maximum elevation for hypsometry. If not specified, maximum catchment elevation is used. Default is NULL.
quantiles	Vector of elevation quantiles. Default is NULL.
hypso_plot	if TRUE the hypsometric curve is plotted. Default is NULL.
z_units	Elevation units for plot. Default is m.
col	Colour for plot. Default is red.
type	Type of plot. Defailt is o (lines with overplotted points).
xlab	Plot x-axis label.
ylab	Plot y-axis label.
add_grid	If TRUE, a grid is added to the plot. Default is FALSE
...	Other parameters for the graph

Details

The elevations may be passed as a vector of elevations, or of elevation quantiles, or as minimum and maximum elevations and the number of elevation intervals. A plot of the curve may also be created.

Value

Returns a data frame of elevations and catchment fractions below.

Author(s)

Dan Moore

Examples

## note: example tagged as 'donttest' as it is very slow to execute due to the downloading
library(raster)
# change the following line to specify a directory to hold the data
dir_name <- tempdir(check = FALSE)
# create directory to store data sets
if (!dir.exists(dir_name)) {
  dir.create(dir_name, recursive = TRUE)
}
# get 25-m dem
dem_fn <- file.path(dir_name, "gs_dem25.tif")
dem_url <- "https://zenodo.org/record/4781469/files/gs_dem25.tif"
dem_upc <- ch_get_url_data(dem_url, dem_fn)
dem_upc

# get catchment boundaries
cb_fn <- file.path(dir_name, "gs_catchments.GeoJSON")
cb_url <- "https://zenodo.org/record/4781469/files/gs_catchments.GeoJSON"
cb <- ch_get_url_data(cb_url, cb_fn)

# quick check plot - all catchments
raster::plot(dem_upc)
plot(cb, add = TRUE, col = NA)

# subset 240 catchment
cb_240 <- cb %>% dplyr::filter(wsc_name == "240")
plot(cb_240, col = NA)

## test function 

# test different combinations of arguments
ch_catchment_hyps(cb_240, dem_upc, quantiles = seq(0, 1, 0.1))
ch_catchment_hyps(cb_240, dem_upc, z_levels = seq(1600, 2050, 50))
ch_catchment_hyps(cb_240, dem_upc, n_levels = 6)
ch_catchment_hyps(cb_240, dem_upc)
ch_catchment_hyps(cb_240, dem_upc, zmin = 1600, zmax = 2050)
ch_catchment_hyps(cb_240, dem_upc, zmin = 1600, zmax = 2050, n_levels = 6)

# generate a graph
ch_catchment_hyps(cb_240, dem_upc, hypso_plot = TRUE)
ch_catchment_hyps(cb_240, dem_upc, hypso_plot = TRUE, 
              col = "blue", type = "l", ylim = c(1500, 2200))
ch_catchment_hyps(cb_240, dem_upc, hypso_plot = TRUE, 
              add_grid = TRUE, quantiles = seq(0, 1, 0.1))
ch_catchment_hyps(cb_240, dem_upc, hypso_plot = TRUE,
              ylab = expression("z ("*10^{-3} ~ "km)"))

# extract specific quantiles (e.g., median and 90%)
ch_catchment_hyps(cb_240, dem_upc, quantiles = c(0.5,0.9))

CSHS-hydRology/CSHShydRology documentation built on Aug. 18, 2022, 4:44 p.m.