ch_catchment_hyps {CSHShydRology}

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 not tested automatically as it is very slow to execute due to the downloading
library(raster)
library(magrittr)
# 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))