Functions for Canadian hydrological analyses

Description

CSHShydRology is intended for the use of hydrologists, particularly those in Canada. It will contain functions which focus on the use of Canadian data sets, such as those from Environment Canada. The package will also contain functions which are suited to Canadian hydrology, such as the important cold-region hydrological processes. CSHShydRology will also contain functions which work with Canadian hydrological models, such as Raven, CRHM, Watflood, and MESH.

This package has been developed with the assistance of the Canadian Society for Hydrological Sciences (CSHS) https://cshs.cwra.org/en/ which is an affiliated society of the Canadian Water Resources Association (CWRA) https://cwra.org/.

The CSHShydRology will contain functions grouped into several themes, including:

Statistical hydrology

trend detection, data screening, frequency analysis, regionalization

Basic data manipulations

input/conversion/adapter functions, missing data infilling

Visualization

data visualization, standardized plotting functions

Spatial hydrology

basin delineation, landscape data analysis, working with GIS

Streamflow measurement analysis

rating curve analysis, velocity profiles, naturalization

Network design/analysis

homogeneity assessment

Ecohydrology

fisheries and ecological analysis

Wrappers/unwrappers

between other packages and CSHShydRology

Author(s)

Maintainer: Kevin Shook kevin.shook@usask.ca

Authors:

• Paul Whitfield paul.h.whitfield@gmail.com

• Robert Chlumsky rchlumsk@uwaterloo.ca

• Daniel Moore dan.moore@ubc.ca

• Martin Durocher

Other contributors:

• Matthew Lemieux [contributor]

• Jason Chiang [contributor]

• Joel Trubilowicz [contributor]

• SJ Kim [contributor]

References

To cite CSHShydRology in publications, use the command citation("CSHShydRology") to get the current version of this citation.

See Also

Useful links:

• https://github.com/CSHS-hydRology/CSHShydRology

Basic data manipulation functions

Description

These functions read in or convert values among formats

ch_read_ECDE_flows

Reads a file of WSC daily flows from ECDataExplorer

ch_get_ECDE_metadata

Reads station meta data from ECDataExplorer

ch_get_wscstation

Reads station information from a data file produced by ECDE

ch_read_AHCCD_daily

Reads file of daily AHCCD values

ch_read_AHCCD_monthly

Reads file of monthly AHCCD values

ch_tidyhydat_ECDE

Reads flows using tidyhydat and converts to ECDE format

ch_tidyhydat_ECDE_meta

Reads station meta data using tidyhydat and converts to ECDE-like format

Streamflow data

Description

Daily river discharge for the station 01AD002 on St. John River at Fort Kent, New Brunswick. Data ranges from 1926 to 2014, for basin area of 14700 sq km.

Usage

CAN01AD002

Format

An object of class data.frame with 32234 rows and 2 columns.

Author(s)

Martin Durocher

Source

https://wateroffice.ec.gc.ca/

CAN05AA008

Description

A dataframe of Water Survey of Canada (WSC) daily flows for station 05AA008, CROWSNEST RIVER AT FRANK Alberta. Drainage area 403 km2.

Usage

CAN05AA008

Format

A dateframe with 25252 rows and 5 columns spanning the period 1910-2013.

Details

Variables:

ID

StationID

PARAM

Parameter 1=Flow, 2=Level

Date

R date

Flow

Daily flow in m^3/s

SYM

Water Survey FLags A, B, D, E

Source

Water Survey of Canada

List of Water Survey of Canada hydrometic stations.

Description

A dataframe of station information, as extracted from HYDAT using ECDataExplorer.

Usage

HYDAT_list

Format

A dateframe with a row for each station and 20 columns.

Details

Variables:

Station

StationID

StationName

Station Name

HYDStatus

Active or Discontinued

Prov

Province

Latitude

Longitude

DrainageArea

km^2

Years

Number of years with data

From

Start Year

To

End Year

Reg.

Regulated

Flow

If TRUE/Yes

Level

If TRUE/Yes

Sed

If TRUE/Yes

OperSched

Continuous or Seasonal

RealTime

If TRUE/Yes

RHBN

If TRUE/Yes the station is in the reference hydrologic basin network

Region

ECCC Region

Datum

Reference datum

Operator

Operator

Source

Water Survey of Canada

Spatial Hydrology functions

Description

These functions perform spatial analyses important in hydrology. All of the functions with the prefix ch_wbt require the installation of the package Whitebox. The functions include:

ch_wbt_removesinks

Removes sinks from a DEM by deepening drainage network

ch_wbt_fillsinks

Removes sinks from a DEM by filling them

ch_wbt_catchment

Generates catchment boundaries for a conditioned DEM based on specified points of interest

ch_wbt_channels

Generates a drainage network from DEM

ch_wbt_flow_accumulation

Accumulates flows downstream in a cathcment

ch_wbt_flow_direction

Calculated flow directions for each cell in DEM

ch_wbt_pourpoints

Snaps pour points to channel

ch_wbt_catchment_onestep

Performs all catchment delineations in a single function

ch_contours

Creates contour lines from DEM

ch_checkcatchment

Provides a simple map to check the outputs from ch_saga_catchment

ch_checkchannels

Provides a simple map to check the outputs from ch_saga_channels

ch_volcano_raster

Returns a raster object of land surface elevations

The Whitebox functions support the following file types for raster data:

type

extension

GeoTIFF

*.tif, *.tiff

Big GeoTIFF

*.tif, *.tiff

Esri ASCII

*.txt, *.asc

Esri BIL

*.flt, *.hdr

GRASS ASCII

*.txt, *.asc

Idrisi

*.rdc, *.rst

SAGA Binary

*.sdat, *.sgrd

Surfer ASCII

*.grd

Surfer Binary

*.grd

Whitebox

*.tas, *.dep

Statistical analysis functions

Description

These functions perform statistical analyses

ch_binned_MannWhitney

Compares two time periods of data using Mann-Whitney test

ch_fdcurve

Finds flow exceedence probabilities

ch_get_peaks

Finds peak flows over a specified threshold

Visualization functions

Description

These functions are primarily intended for graphing, although some analyses may also be done.

ch_booth_plot

Plot of peaks over a threshold

ch_flow_raster

Raster plot of streamflows

ch_flow_raster_qa

Raster plot of streamflows with WSC quality flags

ch_flow_raster_trend

Raster plot and simple trends of observed streamflows

ch_hydrograph_plot

Plots hydrographs and/or precipitation

ch_polar_plot

Polar plot of daily streamflows

ch_regime_plot

Plots the regime of daily streamflows

Generates the x axis beginning on specified day of year

Description

Generates an axis for day of year or day of water year; used by ch_regime_plot. Obtaining the day of water year needs to be done separately.

Usage

ch_axis_doy(wyear = 1)

Arguments

Value

Plots a water year axis on a standard R plot

Author(s)

Paul Whitfield

See Also

ch_regime_plot

Examples

a <- seq(1, 365)
b <- runif(365)
plot(a, b,  type = "p", xlab = "", xaxt = "n")
ch_axis_doy(wyear = 10) # starts in October

Compares two time periods of data using Mann-Whitney test

Description

Compares two time periods of data using the Mann-Whitney test. Data are binned based upon a bin size, and data are extracted for two time periods and tests for change between two such periods result can be passed to ch_polar_plot or ch_decades_plot for visualization.

Usage

ch_binned_MannWhitney(
  DF,
  step,
  range1,
  range2,
  ptest = 0.05,
  variable = "discharge",
  metadata = NULL
)

Arguments

Value

Returns a list containing:

Author(s)

Paul Whitfield

References

Whitfield, P.H., Cannon, A.J., 2000. Recent variations in climate and hydrology in Canada. Canadian Water Resources Journal 25: 19-65.

See Also

ch_polar_plot ch_polar_plot_prep ch_decades_plot

Examples

data(HYDAT_list)
data(CAN05AA008)
# first example fails due to missing data in both periods
range1 <- c(1960,1969)
range2 <- c(1990,1999)
b_MW <- ch_binned_MannWhitney(CAN05AA008, step = 5, range1, range2, ptest = 0.05)

range1 <- c(1970,1979)
range2 <- c(1990,1999)
b_MW <- ch_binned_MannWhitney(CAN05AA008, step = 5, range1, range2, ptest = 0.05)

Create Booth plot of peaks over a threshold

Description

A Booth plot is a plot of peaks over threshold flood events with duration on the horizontal and either magnitude (default) or volume on the vertical axis.

Usage

ch_booth_plot(events, threshold, title, type = "mag", colour1 = 1, colour2 = 1)

Arguments

Value

No value is returned; a standard R graphic is created.

Author(s)

Paul Whitfield

References

Booth, E.G., Mount, J.F., Viers, J.H. 2006. Hydrologic Variability of the Cosumnes River Floodplain. San Francisco Estuary & Watershed Science 4:21.

Whitfield, P.H., and J.W. Pomeroy. 2016. Changes to flood peaks of a mountain river: implications for analysis of the 2013 flood in the Upper Bow River, Canada. Hydrological Processes 30:4657-73. doi: 10.1002/hyp.10957.

See Also

ch_get_peaks

Examples

threshold <- 0.1 * max(CAN05AA008$Flow)  # arbitrary threshold
peaks <- ch_get_peaks(CAN05AA008, threshold)
events <- peaks$POTevents
ch_booth_plot(events, threshold, title = "05AA008", type='mag')
ch_booth_plot(events, threshold, title = "05AA008", type='vol')

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

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

Check Catchments

Description

Generates a simple map to allow a visual assessment of the catchment boundaries relative to the elevation contours.

Usage

ch_checkcatchment(
  dem,
  catchment,
  outlet,
  outlet_label = NULL,
  main_label = "",
  bbox_type = "catchment",
  channel_vec = NULL,
  cb_colour = "red",
  pp_colour = "red",
  channel_colour = "blue",
  contour_colour = "grey",
  plot_na = TRUE,
  plot_scale = TRUE,
  na_location = "tr",
  scale_location = "bl"
)

Arguments

Details

Also generates a table summarizing the catchments, including the coordinates of the outlet point and the catchment area.

Value

TRUE. A map of the catchments is also plotted and the catchment parameters are printed.

Author(s)

Dan Moore and Kevin Shook

See Also

ch_checkchannels

Examples

# Only proceed if Whitebox executable is installed
library(whitebox)
if (check_whitebox_binary()){
  library(raster)
  test_raster <- ch_volcano_raster()
  dem_raster_file <- tempfile(fileext = ".tif")
  no_sink_raster_file <- tempfile("no_sinks", fileext = ".tif")

  # write test raster to file
  writeRaster(test_raster, dem_raster_file, format = "GTiff")

  # remove sinks
  removed_sinks <- ch_wbt_removesinks(dem_raster_file, no_sink_raster_file, 
  method = "fill")

  # get flow accumulations
  flow_acc_file <- tempfile("flow_acc", fileext = ".tif")
  flow_acc <- ch_wbt_flow_accumulation(no_sink_raster_file, flow_acc_file)

  # get pour points
  pourpoint_file <- tempfile("volcano_pourpoints", fileext = ".shp")
  pourpoints <- ch_volcano_pourpoints(pourpoint_file)
  snapped_pourpoint_file <- tempfile("snapped_pourpoints", fileext = ".shp")
  snapped_pourpoints <- ch_wbt_pourpoints(pourpoints, flow_acc_file, pourpoint_file,
  snapped_pourpoint_file, snap_dist = 10)

# get flow directions
  flow_dir_file <- tempfile("flow_dir", fileext = ".tif")
  flow_dir <- ch_wbt_flow_direction(no_sink_raster_file, flow_dir_file)
  fn_catchment_ras <- tempfile("catchment", fileext = ".tif")
  fn_catchment_vec <- tempfile("catchment", fileext = ".shp")
  catchments <- ch_wbt_catchment(snapped_pourpoint_file, flow_dir_file, 
  fn_catchment_ras, fn_catchment_vec)

# check results
  ch_checkcatchment(test_raster, catchments, snapped_pourpoints)
} else {
  message("Examples not run as Whitebox executable not found")
}

Check Channels

Description

Generates a map of the generated channel network layer.

Usage

ch_checkchannels(
  dem,
  channels,
  outlet = NULL,
  main_label = "",
  channel_colour = "blue",
  pp_colour = "red",
  contour_colour = "grey"
)

Arguments

Details

Generates a simple map of the drainage network plotted over the contours to allow a visual assessment.

Value

Author(s)

Dan Moore

See Also

ch_checkcatchment

Examples

# Only proceed if Whitebox executable is installed
library(whitebox)
if (check_whitebox_binary()){
  library(raster)
  test_raster <- ch_volcano_raster()
  dem_raster_file <- tempfile(fileext = c(".tif"))
  no_sink_raster_file <- tempfile("no_sinks", fileext = c(".tif"))

  # write test raster to file
  writeRaster(test_raster, dem_raster_file, format = "GTiff")

  # remove sinks
  removed_sinks <- ch_wbt_removesinks(dem_raster_file, no_sink_raster_file, method = "fill")

  # get flow accumulations
  flow_acc_file <- tempfile("flow_acc", fileext = c(".tif"))
  flow_acc <- ch_wbt_flow_accumulation(no_sink_raster_file, flow_acc_file)

  # get flow directions
  flow_dir_file <- tempfile("flow_dir", fileext = c(".tif"))
  flow_dir <- ch_wbt_flow_direction(no_sink_raster_file, flow_dir_file)
  channel_raster_file <- tempfile("channels", fileext = c(".tif"))
  channel_vector_file <- tempfile("channels", fileext = c(".shp"))
  channels <- ch_wbt_channels(flow_acc_file, flow_dir_file, channel_raster_file,
  channel_vector_file, 1)

  # get pour points
  pourpoint_file <- tempfile("volcano_pourpoints", fileext = ".shp")
  pourpoints <- ch_volcano_pourpoints(pourpoint_file)
  snapped_pourpoint_file <- tempfile("snapped_pourpoints", fileext = ".shp")
  snapped_pourpoints <- ch_wbt_pourpoints(pourpoints, flow_acc_file, pourpoint_file,
  snapped_pourpoint_file, snap_dist = 10)
  ch_checkchannels(test_raster, channels, snapped_pourpoints)
} else {
  message("Examples not run as Whitebox executable not found")
}

Calculates the circular mean, median, and regularity

Description

Calculate the circular mean, median, and regularity using a year of 365 days. Days of year are converted to degrees internally, results are returned as positive days of year

Usage

ch_circ_mean_reg(dataframe)

Arguments

Value

Returns a list of the following statistics

References

Pewsey, A., M. Neuhauser, and G. D. Ruxton. 2014. Circular Statistics in R, 192 pp., Oxford University Press. Whitfield, P. H. 2018. Clustering of seasonal events: A simulation study using circular methods. Communications in Statistics - Simulation and Computation 47(10): 3008-3030. Burn, D. H., and P. H. Whitfield. 2021*. Changes in the timing of flood events resulting from climate change.

See Also

ch_sh_get_amax

Examples

data(CAN05AA008)
am <- ch_sh_get_amax(CAN05AA008)
m_r <- ch_circ_mean_reg(am)

Clear Working Directory

Description

Empties and removes a working directory.

Usage

ch_clear_wd(wd, do_check = TRUE)

Arguments

Details

The data for raster layers read in as Whitebox files are held on disk rather than in memory

Value

Author(s)

Dan Moore

See Also

ch_create_wd to create working directory

Examples

# not tested as deleting all files in the directory cannot be tested in CRAN

# create an empty working directory
my_wd <- tempdir()
ch_create_wd(my_wd) # confirm creation

# clear the working directory
ch_clear_wd(my_wd)

Creates a colour gradient

Description

Creates a colour gradient for plotting.

Usage

ch_col_gradient(
  x,
  colors = c("darkred", "red", "white", "blue", "darkblue"),
  colsteps = 100,
  climits = NULL
)

Arguments

Value

Author(s)

modified by Paul Whitfield

Examples

plot(rnorm(20),col='black')

# create a red blue colour gradient for plotting
mycol <- ch_col_gradient(rnorm(20), colsteps = 100)

# plot more random points in transparent blue colour
points(rnorm(20), col = mycol)

Add Transparency to plot colours

Description

Adds transparency to a colour based on an integer between 0 and 255, with 0 being fully transparent and 255 being opaque. Based on function rvn_col_transparent in package RavenR.

Usage

ch_col_transparent(colour, trans)

Arguments

Value

Author(s)

Rob Chlumsky; Paul Whitfield

See Also

See original code on post in Stack Overflow plot points transparent in R

Examples

 # plot randomly distributed data
plot(rnorm(20), col='black')

# create a transparent blue colour for plotting
mycol <- ch_col_transparent('blue', 100)

# plot more random points in transparent blue colour
points(rnorm(20),col = mycol)

 # plot randomly distributed data
plot(rnorm(20), col = 'blue')

# create two transparent colour for plotting
mycol <- ch_col_transparent(c('green',"red"), c(100, 200))

# plot more random points in transparent colours
points(rnorm(20), col = mycol[2])

ch_color_gradient

Description

set colour gradient

Usage

ch_color_gradient(
  x,
  colors = c("darkred", "red", "white", "green", "darkgreen"),
  colsteps = 100,
  climits = NULL
)

Arguments

Value

vector of colors

Author(s)

Paul Whitfield

Examples

cxin <- c(0, 1, 1, 3, 4, 5, 10)
cxout <- ch_color_gradient(cxin)
#[1] "#8B0000" "#B50000" "#B50000" "#FF2B2B" "#FF9292"
#[6] "#FFF9F9" "#006400"

Create Contours

Description

Creates contour lines from a DEM.

Usage

ch_contours(dem, zmin = NULL, zmax = NULL, n_levels = 10, z_levels = NULL)

Arguments

Details

Generates contour lines from a DEM, which are returned as an sf object. The user can either provide a vector of elevation values by specifying the z_levels argument, or by supplying the minimum and maximum elevations (zmin and zmax) and the number of contour lines (n_levels).

Value

Author(s)

Dan Moore

Examples

# use volcano DEM
dem <- ch_volcano_raster()
# generate contours
contours <- ch_contours(dem)

# plot contours map
plot(contours)

Create working directory

Description

Creates a working directory.

Usage

ch_create_wd(wd)

Arguments

Value

Author(s)

Dan Moore

See Also

ch_clear_wd to clear the working directory

Examples

# not tested automatically as will return a warning
ch_create_wd(tempdir())

Extracts a specified time period from a longer record

Description

The function could also be used to get the same period of time from several station for comparison.

Usage

ch_cut_block(DF, st_date, end_date)

Arguments

Value

Returns a portion of the original dataframe.

Author(s)

Paul Whitfield

Examples

data(CAN05AA008)
subset <- ch_cut_block(CAN05AA008,"2000/01/01", "2010/12/31")

Subsets dates by string

Description

Subsets a data frame by an specified date range, provided as a string by the prd argument. This function is meant to emulate the subsetting capability of the xts package.

Usage

ch_date_subset(df, prd)

Arguments

Value

Author(s)

Robert Chlumsky

Examples

{
dd <- seq.Date(as.Date("2010-10-01"), as.Date("2013-09-30"), by = 1)
x <- rnorm(length(dd))
y <- abs(rnorm(length(dd)))*2
df <- data.frame("Date" = dd,x,y)
prd <- "2011-10-01/2012-09-30"
summary(ch_date_subset(df,prd))}

Plots output from ch_binned_MannWhitney for decades

Description

Creates a simple plot comparing two decades from the output of ch_binned_MannWhitney.

Usage

ch_decades_plot(mplot)

Arguments

Value

A standard R graphic is created.

Author(s)

Paul Whitfield

See Also

ch_decades_plot

Examples

range1 <- c(1970, 1979)
range2 <- c(1990, 1999)
b_MW <- ch_binned_MannWhitney(CAN05AA008, step = 5, range1, range2, ptest = 0.05)
ch_decades_plot(b_MW)

Days of year and water year

Description

Converts an array of dates into a dataframe with date, year, month, doy, wyear, dowy.

The day of water year is computed from the first of the specified water year month.

Usage

ch_doys(Date, water_yr = 10)

Arguments

Details

Converts a date array into a data frame with years, wateryears, and days of year and of water year.

Value

Returns a dataframe with date information:

Author(s)

Paul Whitfield, Kevin Shook

Examples

dd <- seq.Date(as.Date("2010-01-01"), as.Date("2018-01-01"),by = 1)
output <- ch_doys(dd, water_yr=10)
head(output)

Plot Flow Duration Curve

Description

A flow duration curve is a plot of flow magnitude against exceedance probability. The plot may contain the Gustard Curves (default) or they can be omitted. The default is for curves to be plotted against probability, but an option is to plot against the normalized exceedance probability. In that case, the x axis represents a normal distribution.

Usage

ch_fdcurve(DF, normal = FALSE, gust = TRUE, metadata = NULL)

Arguments

Details

Create a Flow Duration Curve based upon Observations.

Value

Plots the flow duration curve and returns a data frame containing:

Author(s)

Paul Whitfield

References

Gustard, A., A. Bullock, and J.M. Dixon. 1992. Low flow estimation in the United Kingdom. Institute of Hydrology, 292. Wallingford: Institute of Hydrology.

Vogel, R.M., and N.M. Fennessy. 1994. Flow-duration curves. I: New Interpretation and confidence intervals. Journal of Water Resources Planning and Management ASCE 120:485-504.

Vogel, R.M., and N.M. Fennessy. 1995. Flow duration curves II: A review of applications in water resources planning. Water Resources Bulletin 31:1030-9.

Examples

data(HYDAT_list)
data(CAN05AA008)
# plot with Gustard 1992 curves
test <- ch_fdcurve(CAN05AA008, normal = FALSE, gust = TRUE)
# plot with normalized exceedance probability
test <- ch_fdcurve(CAN05AA008, normal = TRUE, gust = FALSE)

Raster plot of daily streamflows

Description

Produces a raster plot: years by day of year, showing magnitude of flow. This produces a plot showing the flow data in colours, showing different context than in a hydrograph. High flows are in warm colours.

Usage

ch_flow_raster(
  DF,
  rastercolours = c("lightblue", "cyan", "blue", "slateblue", "orange", "red"),
  metadata = NULL
)

Arguments

Value

No value is returned; a standard R graphic is created.

Author(s)

Paul Whitfield

See Also

ch_read_ECDE_flows

ch_flow_raster_trend ch_flow_raster_qa

Examples

ch_flow_raster(CAN05AA008)

Raster plot of daily streamflows with WSC quality flags

Description

Raster plot with WSC quality flags. This produces a plot showing the flow data in grayscale overlain by the Water Survey of Canada quality flags. Colours are consistent with ECDataExplorer. Raster layout lets the use see the flags in a different context than in a hydrograph.

Usage

ch_flow_raster_qa(DF, metadata = NULL)

Arguments

Value

Produces a raster plot: years against day of year, showing the data flags:

Returns TRUE if executed properly; a standard R graphic is created.

Author(s)

Paul Whitfield

See Also

ch_read_ECDE_flows

ch_flow_raster_trend ch_flow_raster

Examples

data(HYDAT_list)
data(CAN05AA008)
qaplot <- ch_flow_raster_qa(CAN05AA008)

Raster plot and simple trends of observed streamflows by periods

Description

Creates a raster plot plus trend plots for day of year, which are binned by a number of days (step), and the max, min, and median annual discharge across years. The plot contains four panels based upon binned data.

Usage

ch_flow_raster_trend(
  DF,
  step = 5,
  missing = FALSE,
  metadata = NULL,
  colours = c("lightblue", "cyan", "blue", "slateblue", "darkblue", "red")
)

Arguments

Details

The four plots are: (1) The maximum,minimum,and median flow with a trend test for each period: red arrows indicate decreases, blue arrows indicate increases. (2) The scale bar for the colours used in the raster plot, (3) The raster plot with a colour for each period and each year where data exist, and (4) A time series plot of the minimum, median, and maximum annual bin values. If there is no trend (p > 0.05) the points are black. Decreasing trends are in red, increasing trends are in blue.

Value

Returns a list containing:

Author(s)

Paul Whitfield

References

Whitfield, P. H., Kraaijenbrink, P. D. A., Shook, K. R., and Pomeroy, J. W. 2021. The Spatial Extent of Hydrological and Landscape Changes across the Mountains and Prairies of Canada in the Mackenzie and Nelson River Basins Based on data from a Warm Season Time Window, Hydrology and Earth Systems Sciences 25: 2513-2541.

See Also

ch_flow_raster

Examples

 data(CAN05AA008)
 mplot <- ch_flow_raster_trend(CAN05AA008, step=5)

Reads Environment Canada Date Explorer (ECDE) meta data file

Description

Reads the file that is generated from ECDE 'save favourite stations' to capture the ECDE metadata. The dataframe returned contains 20 fields from ECDE.

Usage

ch_get_ECDE_metadata(filename, writefile = NULL)

Arguments

Value

Returns a dataframe consisting of:

Author(s)

Paul Whitfield <paul.h.whitfield@gmail.com>

Examples

## Not run: 
# Don't run this example as it requires an ECDE file
filename <- "FavHydatStations.tb0"        # dummy file name (not supplied)
meta0 <- ch_get_ECDE_metadata(filename)
meta1 <- ch_get_ECDE_metadata(filename, writefile="study52_metadata.csv")

## End(Not run)

Extracts peak flows over a threshold

Description

This function is development code being shared as is. It is expected that the user will be interested in the data frame returned for POT analysis and for plotting (i.e. ch_booth_plot).

This function retrieves peaks greater than or equal to the prescribed threshold. It returns a data frame of peak characteristics suitable for subsequent analysis.

The portion under development is returns a list of the flows during an event with the values of the four preceding days and three subsequent days. If the peak is a single point the fragment is nine points long; if the events is longer the fragment contains all days above the threshold and eight additional days.

Usage

ch_get_peaks(dataframe, threshold)

Arguments

Value

Returns a list containing:

The POTevents data frame contains five columns:

The case list contains the flows during an event and also for four preceding and subsequent days. Each event will have a length between nine to n days in length. Note: in rare cases where the event is in progress when data becomes available the event might be shorter than nine days long.

Author(s)

Paul Whitfield

References

Burn, D.H., Whitfield, P.H., Sharif, M., 2016. Identification of changes in floods and flood regimes in Canada using a peaks over threshold approach. Hydrological Processes, 39: 3303-3314. DOI:10.1002/hyp.10861

Whitfield, P.H., and J.W. Pomeroy. 2016. Changes to flood peaks of a mountain river: implications for analysis of the 2013 flood in the Upper Bow River, Canada. Hydrological Processes 30:4657-73. doi: 10.1002/hyp.10957.

See Also

ch_booth_plot

Examples

CAN05AA008 <- CAN05AA008
threshold <- 0.5*max(CAN05AA008$Flow)  # arbitrary threshold
my_peaks <- ch_get_peaks(CAN05AA008, threshold)
str(my_peaks)

Gets remote data sets

Description

Accesses data sets, via a url the first time, saves them locally, then accesses them locally after the first time the script is executed.

Usage

ch_get_url_data(gd_url, gd_filename, quiet = FALSE)

Arguments

Value

Returns a data frame (from a .csv file), a raster object (from a .tif file), or an sf object (from a GeoJSON file).

Author(s)

Dan Moore

Examples

# Example not tested automatically as multiple large data files are downloaded which is slow

# Tested using files in the Upper Penticton Creek
# zenodo repository https://zenodo.org/record/4781469
library(ggplot2)
library(raster)

# create directory to store data sets
dir_name <- tempdir(check = FALSE)
if (!dir.exists(dir_name)) {
  dir.create(dir_name)
}
 
# test with soil moisture data in csv format
sm_fn <- file.path(dir_name, "sm_data.csv")
sm_url <- "https://zenodo.org/record/4781469/files/sm_data.csv"
sm_data <- ch_get_url_data(sm_url, sm_fn)
head(sm_data)

# test with tif/tiff file containing a dem
ra_fn <- file.path(dir_name, "gs_dem25.tif")
ra_url <- "https://zenodo.org/record/4781469/files/gs_dem25.tif"
ra_data <- ch_get_url_data(ra_url, ra_fn)
plot(ra_data)

# test with GeoJSON
gs_fn <- file.path(dir_name, "gs_soilmaps.GeoJSON")
gs_url <- "https://zenodo.org/record/4781469/files/gs_soilmaps.GeoJSON"
gs_data <- ch_get_url_data(gs_url, gs_fn)

ggplot(gs_data) +
  geom_sf(aes(fill = new_key)) +
  labs(fill = "Soil class",
       x = "UTM Easting (m)",
       y = "UTM Northing (m)") +
  coord_sf(datum = 32611) +
  theme_bw()

Reads station information from a data file produced by ECDE

Description

Retrieves station information for an individual Water Survey of Canada site, based on stationID; adds a text string at position 21 that combines key elements for a title.

Usage

ch_get_wscstation(stnID, metadata = NULL)

Arguments

Value

Returns a line from a data frame with 21 variables

Author(s)

Paul Whitfield

Examples

data("HYDAT_list")
s_info <- ch_get_wscstation("05BB001", metadata = HYDAT_list)
title <- s_info[21]
print(title)

Hydrograph plot

Description

Creates a hydrograph plot for simulated, observed, and inflow hydrograph series, including precipitation if provided. The secondary y axis will be used to plot the precip time series.

Usage

ch_hydrograph_plot(
  flows = NULL,
  precip = NULL,
  prd = NULL,
  winter_shading = FALSE,
  winter_colour = "cyan",
  range_mult_flow = NULL,
  range_mult_precip = 1.5,
  flow_labels = NULL,
  ylabel = NULL,
  precip_label = "Precipitation [mm]",
  leg_pos = NULL,
  leg_box = NULL,
  zero_axis = TRUE
)

Arguments

Details

Assumes that the supplied time series have the same length and duration in time. If this is not true, then the defined period or period calculated from the first available flow series will be used to determine the plotting limits in time. The supplied time series should be in xts format. Note that a plot title is purposely omitted in order to allow the automatic generation of plot titles.

Value

Returns TRUE if the function is executed properly.

Author(s)

Robert Chlumsky

Examples

# example with synthetic random data
dd <- seq.Date(as.Date("2010-10-01"), as.Date("2013-09-30"),by = 1)
x <- abs(rnorm(length(dd)))
y <- abs(rnorm(length(dd))) * x
df <- data.frame("Date" = dd, x, y)
myprd <- "2011-10-01/2012-09-30"

precip <- data.frame("Date" = dd," precip" = abs(rnorm(length(dd))) * 10)

# basic hydrograph plot
ch_hydrograph_plot(flows = df, winter_shading = FALSE)

# with different labels and winter shading
ch_hydrograph_plot(flows = df, winter_shading = TRUE,
 flow_labels = c("simulated", "observed"))

# add precipitation, increase the plot ranges to separate flows and precip, and add a legend box
ch_hydrograph_plot(flows = df, precip = precip, range_mult_flow = 1.7, 
range_mult_precip = 2, leg_box = TRUE)

Polar plot of daily streamflows

Description

Produces a polar plot similar to that used in Whitfield and Cannon, 2000. It uses output from the function ch_binned_MannWhitney or a data structure created using the function ch_polar_plot_prep.

Usage

ch_polar_plot(
  bmw,
  lcol1 = c("black", "gray50"),
  lcol2 = c("black", "gray50"),
  lfill = c("yellow", "green"),
  lsig = c("red", "blue")
)

Arguments

Value

No value is returned; a standard R graphic is created.

Author(s)

Paul Whitfield

References

Whitfield, P.H. and A.J. Cannon. 2000. Polar plotting of seasonal hydrologic and climatic data. Northwest Science 74: 76-80.

Whitfield, P.H., Cannon, A.J., 2000. Recent variations in climate and hydrology in Canada. Canadian Water Resources Journal 25: 19-65.

See Also

ch_binned_MannWhitney ch_polar_plot_prep

Examples

range1 <- c(1970,1979)
range2 <- c(1990,1999)
b_MW <- ch_binned_MannWhitney(CAN05AA008, step = 5, range1, range2, 
ptest <- 0.05)
ch_polar_plot(b_MW)

Polar / circular plots of peak flows

Description

Polar / circular plots of peak flows. Creates a polar plot of flow peaks in one of several different forms. Basic plot has shading for nival and pluvial centroids.

Usage

ch_polar_plot_peaks(
  title = NA,
  direction = NULL,
  regularity = NULL,
  days = NULL,
  shading = FALSE,
  shade = 35,
  pt_col = "darkblue",
  in_pch = NULL,
  in_cex = NULL,
  in_col = NULL,
  in_detail = NULL,
  labels = NULL,
  label_pos = NULL,
  out_pch = 16,
  out_cex = 0.8,
  ...
)

Arguments

Value

Creates a circular plot of peak flows.

Note

points inside the plot

in_pch, in_col, and in_cex will normally be of the same length and that would be the maximum index of in_detail

points on the outside

Author(s)

Paul Whitfield

References

Pewsey, A., M. Neuhauser, and G. D. Ruxton. 2014. Circular Statistics in R, 192 pp., Oxford University Press.

Whitfield, P. H. 2018. Clustering of seasonal events: A simulation study using circular methods. Communications in Statistics - Simulation and Computation 47(10): 3008-3030.

Burn, D. H., and P. H. Whitfield. 2023. Changes in the timing of flood events resulting from climate change. Journal of Hydrology.

Examples

# base plot
ch_polar_plot_peaks() 

#base plot with area shading
ch_polar_plot_peaks(shading = TRUE)

# plot of annual maximum series
data(CAN05AA008)
am <- ch_sh_get_amax(CAN05AA008)
ch_polar_plot_peaks(days = am$doy, title = "05AA008")

#remove partial years
am <-am[am$days >= 365,]
ch_polar_plot_peaks(days = am$doy, title = "05AA008")

#plot the centroid
m_r <- ch_circ_mean_reg(am)
ch_polar_plot_peaks(direction = m_r$mean, regularity = m_r$regularity, title = "05AA008")

# plot peaks and centroid
ch_polar_plot_peaks(days = am$doy, direction = m_r$mean, regularity = m_r$regularity, 
title = "05AA008")

Creates a data structure to be passed to ch_polar_plot

Description

Could be used to move data from a different type of analysis different to the ch_binned_MannWhitney function which uses flows. The two series need to be of the same length and their length is related to the step size. For examples, for five day periods there will be 73 periods.

Usage

ch_polar_plot_prep(
  station,
  plot_title,
  step,
  x0,
  x1,
  stat,
  prob,
  test_s,
  variable = "discharge",
  bin_method = "unstated",
  test_method = "unstated",
  lline1 = "Period 1",
  lline2 = "Period 2",
  pvalue = 0.05
)

Arguments

Value

Returns a list containing:

The series data frame contains

Author(s)

Paul Whitfield

References

Whitfield, P.H. and A.J. Cannon. 2000. Polar plotting of seasonal hydrologic and climatic data. Northwest Science 74: 76-80.

Whitfield, P.H., Cannon, A.J., 2000. Recent variations in climate and hydrology in Canada. Canadian Water Resources Journal 25: 19-65.

See Also

ch_binned_MannWhitney ch_polar_plot

Plots a hydrograph with the data quality symbols and returns a report on qa symbols and missing data.

Description

Plots a hydrograph of a WSC daily data file read from from ECDataExplorer (ECDE). The hydrograph shows individual days with data quality symbols [SYM] in colour and counts cases of each and reports them in the legend. The colours and symbols are those produced by ECDataExplorer.

There is an option is to provide start and end dates to show only part of the time period for which data exists and the plot is annotated to indicate this. Counts of missing observations is also provided in the legend.

Usage

ch_qa_hydrograph(
  DF,
  st_date = NULL,
  end_date = NULL,
  cts = TRUE,
  rescale = FALSE,
  sym_col = c("black", "green", "cyan", "yellow", "red", "white"),
  metadata = NULL
)

Arguments

Value

Produces a plot and returns a list that contains:

Author(s)

Paul Whitfield

Examples

m_test <- ch_qa_hydrograph(CAN05AA008)
m_test <- ch_qa_hydrograph(CAN05AA008, st_date="1980-01-01", end_date="1999-12-31")

Reads AHCCD daily file

Description

This program reads an Adjusted and Homogenized Canadian Climate Data (AHCCD) of daily precipitation or temperatures. The values are arranged as month x day, which makes them difficult to read using standard R functions.

Usage

ch_read_AHCCD_daily(daily_file)

Arguments

Value

If successful, returns the values in a data frame, consisting of the date, the value and the data code.

Author(s)

Kevin Shook

References

Daily AHCCD data are available from http://crd-data-donnees-rdc.ec.gc.ca/CDAS/products/EC_data/AHCCD_daily/. Any use of the data must cite Mekis, E and L.A. Vincent, 2011: An overview of the second generation adjusted daily precipitation dataset for trend analysis in Canada. Atmosphere-Ocean, 49 (2), 163-177.

See Also

ch_read_AHCCD_monthly

Examples

## Not run: 
# Don't run this example as it requires a file, and use of the dummy
# file will cause an error message

stoon_daily_tmax <- ch_read_AHCCD_daily("dx40657120.txt")
## End(Not run)

Reads AHCCD monthly file

Description

This program reads an Adjusted and Homogenized Canadian Climate Data (AHCCD) data of precipitation or temperatures. The values are arranged as year x month, which makes them difficult to read using standard R functions.

Usage

ch_read_AHCCD_monthly(monthly_file = NULL)

Arguments

Value

If successful, returns the values in a dataframe, consisting of the year, the month, the value and the data code.

Author(s)

Kevin Shook

References

Any use of the data must cite Mekis, E and L.A. Vincent, 2011: An overview of the second generation adjusted daily temperature and precipitation dataset for trend analysis in Canada. Atmosphere-Ocean, 49 (2), 163-177.

See Also

ch_read_AHCCD_daily

Examples

## Not run: 
# Don't run these examples as use of the dummy
# files will cause error messages

Stoon_monthly_precip <- ch_read_AHCCD_monthly("mt4057120.txt")
NB_monthly_tmean <- ch_read_AHCCD_monthly("mm4045695.txt") 
## End(Not run)

Reads a file of WSC daily flows from ECDataExplorer (ECDE)

Description

Reads in a file WSC daily flows as returned from the Windows program ECDataExplorer, converts the Date, and omits the last 3 lines as these contain the data disclaimer and not data. The function can read values from a url.

Usage

ch_read_ECDE_flows(filename)

Arguments

Value

Returns a dataframe with the last three rows removed:

Author(s)

Paul Whitfield

Examples

## Not run: 
# Not run as requires a file returned by the Windows program ECDataExplorer
# Using a dummy file name as an example
mfile <- "04JD005_Daily_Flow_ts.csv"
mdata <- ch_read_ECDE_flows(mfile)
## End(Not run)


# Not tested automatically as it is slow to read from a url
url1 <- "https://zenodo.org/record/7007830/files/08NL007_Daily_Flow_ts.csv"
values <- ch_read_ECDE_flows(url1)

Plots the regime of daily streamflows using quantiles

Description

Produces a regime hydrograph similar to that in the reference. It shows the flow quantiles for each day of the year and the maximum and minimum. Parameters can be set to change colours and set the y-scale to allow plots of same scale to be produced.

Usage

ch_regime_plot(
  DF,
  wyear = 1,
  colour = TRUE,
  mx = 1,
  metadata = NULL,
  quant = c(0.95, 0.9, 0.75, 0.5, 0.25, 0.1, 0.05)
)

Arguments

Value

No value is returned; a standard R graphic is created.

Author(s)

Paul Whitfield

References

MacCulloch, G. and P. H. Whitfield (2012). Towards a Stream Classification System for the Canadian Prairie Provinces. Canadian Water Resources Journal 37: 311-332.

Examples

data(CAN05AA008)
ch_regime_plot(CAN05AA008, colour = TRUE, wyear = 1)

Distance in seasonal space

Description

Calculates a matrix of distances between points in the seasonal space that characterizes timing and regularity. It is equivalent to Euclidean distance applied to regularity (radius) and timing (angle) separately.

Usage

ch_rfa_distseason(x, ...)

## S3 method for class 'numeric'
ch_rfa_distseason(x, a, w = 1/pi, ...)

## S3 method for class 'data.frame'
ch_rfa_distseason(x, w = 1/pi, ...)

## S3 method for class 'formula'
ch_rfa_distseason(form, x, w = 1/pi, ...)

Arguments

Value

Returns a matrix of distances between points in the seasonal space that characterizes timing and regularity.

Author(s)

Martin Durocher

References

Durocher, M., Burn, D. H., & Ashkar, F. (2019). Comparison of estimation methods for a nonstationary index-flood model in flood frequency analysis using peaks over threshold. https://doi.org/10.31223/osf.io/rnepc

See Also

ch_rfa_seasonstat

Examples

scoord <- data.frame(radius = runif(5), 
                     angle = runif(5,0,2*pi))

ch_rfa_distseason(radius ~ angle , scoord)

Extracts the annual maxima of a daily time series

Description

Extracts the annual maxima of a daily time series

Usage

ch_rfa_extractamax(x, ...)

## S3 method for class 'formula'
ch_rfa_extractamax(form, x, tol = 0, ...)

## Default S3 method:
ch_rfa_extractamax(x, tol = 0, nlab = "n", ylab = "yy", ...)

Arguments

Value

Returns a data frame containing the annual (Monthly) maxima, the date and the number of observations during the year.

Author(s)

Martin Durocher

Examples

out <- ch_rfa_extractamax(flow ~ date, CAN01AD002, tol = 350)
head(out)

Circular plotting by day of year

Description

Create axis for plotting circular statistics in a unitary circle.

Usage

ch_rfa_julianplot(
  rose.col = "gray40",
  rose.lwd = 1.5,
  rose.cex = 1.5,
  rose.radius = seq(0.25, 1, 0.25),
  ...
)

Arguments

Value

Returns a empty rose plot by day of year

Author(s)

Martin Durocher

See Also

ch_rfa_seasonstat.

Examples

data(flowAtlantic)

ss <- ch_rfa_seasonstat(date ~ id, flowAtlantic$ams)

ch_rfa_julianplot()
points(y ~ x, ss, pch = 16, col = cut(ss[,'radius'], c(0,.5,.75,1)))

Seasonal statistics for flood peaks

Description

Return the circular or seasonal statistics of flood peaks. The angle represents the mean timing of the floods and the radius its regularity. For example, a radius of one represents perfect regularity. Can perform the analyses on multiple sites.

Usage

ch_rfa_seasonstat(x, ...)

## S3 method for class 'data.frame'
ch_rfa_seasonstat(x, ...)

## S3 method for class 'formula'
ch_rfa_seasonstat(form, x, ...)

Arguments

Value

Returns the circular or seasonal statistics of flood peaks.

Author(s)

Martin Durocher

References

Burn, D.H. (1997). Catchment similarity for regional flood frequency analysis using seasonality measures. Journal of Hydrology 202, 212-230. https://doi.org/10.1016/S0022-1694(97)00068-1

See Also

ch_rfa_distseason

Examples

dt <- ch_rfa_extractamax(flow~date, CAN01AD002)$date

ch_rfa_seasonstat(dt)

## Illustration of the analysis of multiple sites

F0 <- function(ii) data.frame(site = ii, dt = sample(dt, replace = TRUE))
x <- lapply(1:10, F0)
x <- do.call(rbind, x)
           
st <- ch_rfa_seasonstat(dt ~ site, x)

ch_rfa_julianplot()
points(y ~ x, st, col = 2, pch = 16)

Extracts annual maximum values from ECDE dataframe.

Description

Extracts annual maximum values, the date of occurrence, the day of year, and the completeness from ECDE dataframe. Uses functions from timeDate ( as.timeDate, dayOfYear).

Usage

ch_sh_get_amax(df)

Arguments

Value

Returns a dataframe with the following variables

Author(s)

Paul Whitfield

See Also

ch_read_ECDE_flows ch_circ_mean_reg

Examples

data(CAN05AA008)
amax <- ch_sh_get_amax(CAN05AA008)
str(amax)

Converts doy or dwy into a factor that is used to bin data

Description

Converts a series of a variable such as day of year into numbered bins. Whenever the number of bins does not divide in 365 evenly a message showing the number of bins created and the number of days added to the last bin is provided.

Simply put, ch_slice is used to convert doy into a factor which is a number of bins per year. A year can be converted into any number of bins; slice does it based upon a number of days. So when you send it an array of doy it slices that into bins of the desired width. For example, if the step is 5. They 365/5 gives 73 bins and because of leap years there might be one extra day added every four years to the final bin.

To illustrate for a bin of 5 days: doy: 1 2 3 4 5 6 7 8 9 10 11 12 Bin: 1 1 1 1 1 2 2 2 2 2 3 3

Usage

ch_slice(doy, step)

Arguments

Value

Returns a vector of bin numbers that is used as a factor for each day in the dataset and provides a message indicating the handling of partial bins

Author(s)

Paul Whitfield, Kevin Shook

See Also

ch_binned_MannWhitney ch_flow_raster_trend

Examples

doy <- c(1:365)
# first 30 days are 1, 31-60 are 2 etc
dice <- ch_slice(doy, 30)
plot(doy, dice)

Stacks EC values

Description

Converts data frames of Environment Canada year x month or month x day data to vectors.

Usage

ch_stack_EC(data_values = NULL, data_codes = NULL)

Arguments

Value

Returns a data frame with two columns: the data values, and the data codes.

Author(s)

Kevin Shook

Examples

## Not run: 
# Do not run as the function requires a data frame of EC data and
# the dummy variable will cause an error message
df <- ch_stack_EC(data_values, data_codes)

## End(Not run)

Helper function for selecting points for an axis

Description

Sub-samples a vector every n places. Many times there are so many years the labels on the plot overlap. ch_sub_set_years returns the position and label for the subset. The function can be used on any type of simple array.

Usage

ch_sub_set_Years(years, n)

Arguments

Value

a list containing:

Author(s)

Paul Whitfield

Examples

myears <- c(1900:2045)
myears <- ch_sub_set_Years(myears, 20)
myears

a <- LETTERS
my_alpha <- ch_sub_set_Years(a, 5)
my_alpha

Tests url to see if it will work

Description

Tests url to see if it will work

Usage

ch_test_url_file(url, quiet = FALSE)

Arguments

Value

Returns error if there was an error, warning if there was a warning. Otherwise, returns OK. Strings are returned instead of logical values to simplify checking result in calling function.

Author(s)

Kevin Shook

See Also

See original code on post in Stack Overflow How to write trycatch in R

Examples

# Not tested automatically as can be very slow
test_url <- "https://zenodo.org/record/4781469/files/sm_data.csv"
ch_test_url_file(test_url, quiet = TRUE)

Converts a tidyhydat daily flow data tibble to ECDE format

Description

Accessing daily flow data using tidyhydat is quick and efficient. However, it sometimes conflicts with other functions as tidyhydat changes variable names and some default entries. This function converts a tibble obtained from a tidyhydat tibble to a dataframe with standard Environment and Climate Change Canada Data Explorer (ECDE) names.

Usage

ch_tidyhydat_ECDE(data)

Arguments

Value

A dataframe or a list of flows with formats consistent with datafiles read using ch_read_ECDE_flows:

Author(s)

Paul Whitfield

See Also

ch_tidyhydat_ECDE_meta

Examples

# This example uses the built-in test database, by setting the hydat_path parameter
# You will want to use it with your actual HYDAT database
library(tidyhydat)
# check for existence of test database
test_db <- hy_test_db()
if (file.exists(test_db)) {
  hydat_path = hy_set_default_db(test_db)
  mdata <- hy_daily_flows(station_number=c("05AA008"))
  m_data <- ch_tidyhydat_ECDE(mdata)

  mdata <- hy_daily_flows(station_number=c("05AA008", "08MF005", "05HD008")) 
  mnew <- ch_tidyhydat_ECDE(mdata)
  str(mnew[[1]])
  str(mnew[[2]])
  str(mnew[[3]]) 
# note the order is in increasing alphabetical order
hy_set_default_db(NULL)    # Reset HYDAT database
}

Creates an ECDE-like dataframe of metadata from tidyhydat

Description

Extracts tombstone (meta) data for stations from tidyhydat in a format similar to that used by the Environment Canada Data Explorer (ECDE). The default does not capture all the fields in ECDE, which includes the most recent status of many fields such as operating schedule. Returning these values slows the function, particularly when all WSC stations are selected.

Usage

ch_tidyhydat_ECDE_meta(stations, all_ECDE = FALSE)

Arguments

Value

Returns a list with three items:

• meta - a dataframe of metadata from tidyhydat in ECDE form (not all ECDE fields are reproduced in this summary)

• H_version - version information, and

• th_meta - a dataframe with all tidyhdat fields including:

  • Station - StationID

  • StationName - Station Name

  • HYDStatus - Active or Discontinued

  • Prov - Province

  • Latitude

  • Longitude

  • DrainageArea - km^2

  • Years - number of years with data

  • From - Start Year

  • To - End Year

  • Reg. - Regulated?

  • Flow - not captured (differs from ECDE), unless all_ECDE = TRUE

  • Level - not captured (differs from ECDE), unless all_ECDE = TRUE

  • Sed - not captured (differs from ECDE), unless all_ECDE = TRUE

  • OperSched - not captured (differs from ECDE), unless all_ECDE = TRUE

  • RealTime - if TRUE/Yes

  • RHBN - if TRUE/Yes is in the reference hydrologic basin network

  • Region - number of region instead of name (differs from ECDE), unless all_ECDE = TRUE

  • Datum - reference number (differs from ECDE), unless all_ECDE = TRUE

  • Operator - reference number (differs from ECDE), unless all_ECDE = TRUE

Author(s)

Paul Whitfield, Kevin Shook

See Also

ch_get_ECDE_metadata ch_tidyhydat_ECDE

Examples

# This example uses the built-in test database, by setting the hydat_path parameter
# You will want to use it with your actual HYDAT database
library(tidyhydat)
# check for existence of test database
test_db <- hy_test_db()
if (file.exists(test_db)) {
  stations <- c("05AA008", "08MF005", "05HD008")
  hy_set_default_db(test_db)
  result <- ch_tidyhydat_ECDE_meta(stations)
  metadata <- result[[1]]
  version <- result[[2]]
  hy_set_default_db(NULL)    # Reset HYDAT database
}
## Not run: 
# This example is not run, as it will take several hours to execute and will
# return many warnings for stations having no data. Note that it is using the actual
# HYDAT database, which must have been installed previously
# This use of the function is intended for the package maintainers to 
# update the HYDAT_list data frame
result <- ch_tidyhydat_ECDE_meta("all", TRUE)
HYDAT_list <- result$meta

## End(Not run)

ch_tr_sign

Description

Converts MK (or other) slopes to integers 1-2-3 (negative, none, positive). These indices can be used to indicate trend direction.

Usage

ch_tr_sign(x, offset = 2)

Arguments

Value

Returns an array of indices (1, 2, 3)

Author(s)

Paul Whitfield

Examples

 mkin <- c( -0.23, 0.34, 0.0, .033, -0.55)
 mkout <- ch_tr_sign(mkin)
 # 1 3 2 3 1

ch_tr_signif()

Description

Convert pvalues to integers 1 for NS and 2 for significant using a pvalue that can be set (default is 0.05)

Usage

ch_tr_signif(x, pvalue = 0.05)

Arguments

Value

Returns an array of indices 1 and 2, where 1 is NS and 2 is significant

Author(s)

Paul Whitfield

Examples

 sin <- c( -0.052, 0.34, 0.012, -.033, -0.55)
 sout <- ch_tr_signif(sin)
 # 1 1 2 2 1

Creates a sample file of pour points

Description

Creates a file of pour points for the volcano DEM. The pour points define the outlets of sub-basins. These pour points are used by examples within other functions.

Usage

ch_volcano_pourpoints(pp_shp)

Arguments

Value

Returns an sf object containing 2 pour points for the volcano DEM. The pour points are also written to the specified file.

Author(s)

Dan Moore and Kevin Shook

See Also

ch_volcano_raster ch_wbt_pourpoints

Examples

pourpoint_file <- tempfile("volcano_pourpoints", fileext = c(".shp"))
pourpoints <- ch_volcano_pourpoints(pourpoint_file)
plot(pourpoints)

Create Test Raster

Description

Creates a raster object of land surface elevations, as used to test/demonstrate many functions requiring a digital elevation model (DEM).

Usage

ch_volcano_raster()

Details

No arguments are required as the DEM is created from the base volcano matrix of elevations.

Value

Returns a raster object of land surface elevations.

Author(s)

Dan Moore and Kevin Shook

Examples

test_raster <- ch_volcano_raster()

Delineate catchment boundaries

Description

Delineate catchment boundaries

Usage

ch_wbt_catchment(
  fn_pp_snap,
  fn_flowdir,
  fn_catchment_ras,
  fn_catchment_vec,
  return_vector = TRUE
)

Arguments

Value

If return_vector == TRUE a vector of the catchment is returned. Otherwise nothing is returned.

Author(s)

Dan Moore and Kevin Shook

See Also

ch_wbt_catchment_onestep

Examples

# Only proceed if Whitebox executable is installed
library(whitebox)
if (check_whitebox_binary()){
  library(raster)
  test_raster <- ch_volcano_raster()
  dem_raster_file <- tempfile(fileext = ".tif")
  no_sink_raster_file <- tempfile("no_sinks", fileext = ".tif")

  # write test raster to file
  writeRaster(test_raster, dem_raster_file, format = "GTiff")

  # remove sinks
  removed_sinks <- ch_wbt_removesinks(dem_raster_file, no_sink_raster_file, method = "fill")

  # get flow accumulations
  flow_acc_file <- tempfile("flow_acc", fileext = ".tif")
  flow_acc <- ch_wbt_flow_accumulation(no_sink_raster_file, flow_acc_file)

  # get pour points
  pourpoint_file <- tempfile("volcano_pourpoints", fileext = ".shp")
  pourpoints <- ch_volcano_pourpoints(pourpoint_file)
  snapped_pourpoint_file <- tempfile("snapped_pourpoints", fileext = ".shp")
  snapped_pourpoints <- ch_wbt_pourpoints(pourpoints, flow_acc_file, pourpoint_file,
  snapped_pourpoint_file, snap_dist = 10)

  # get flow directions
  flow_dir_file <- tempfile("flow_dir", fileext = ".tif")
  flow_dir <- ch_wbt_flow_direction(no_sink_raster_file, flow_dir_file)
  fn_catchment_ras <- tempfile("catchment", fileext = ".tif")
  fn_catchment_vec <- tempfile("catchment", fileext = ".shp")
  catchments <- ch_wbt_catchment(snapped_pourpoint_file, flow_dir_file, 
  fn_catchment_ras, fn_catchment_vec)
} else {
  message("Examples not run as Whitebox executable not found")
}

Delineates a catchment in a single step

Description

Calls all of the ch_wbt and other functions required to do the sub-tasks required to delineate a catchment. The names of files to be created are taken from the list created by the function ch_wbt_filenames.

Usage

ch_wbt_catchment_onestep(
  wd,
  in_dem,
  pp_sf,
  sink_method = "breach_leastcost",
  dist = NULL,
  check_catchment = TRUE,
  threshold = NULL,
  snap_dist = NULL,
  cb_colour = "red",
  pp_colour = "red",
  channel_colour = "blue",
  contour_colour = "grey",
  plot_na = TRUE,
  plot_scale = TRUE,
  na_location = "tr",
  scale_location = "bl",
  ...
)

Arguments

Value

Returns an sp object of the delineated catchment.

Author(s)

Dan Moore and Kevin Shook

See Also

ch_wbt_filenames

Examples

# Only proceed if Whitebox executable is installed
library(whitebox)
if (check_whitebox_binary()){
  library(raster)
  test_raster <- ch_volcano_raster()
  dem_raster_file <- tempfile(fileext = c(".tif"))
  # write test raster to file
  writeRaster(test_raster, dem_raster_file, format = "GTiff")
  wd <- tempdir()
  pourpoint_file <- tempfile("volcano_pourpoints", fileext = ".shp")
  pourpoints <- ch_volcano_pourpoints(pourpoint_file)
  catchment <- ch_wbt_catchment_onestep(wd = wd, in_dem = dem_raster_file, 
  pp_sf = pourpoints, sink_method = "fill", threshold = 1, snap_dist = 10)
} else {
  message("Examples not run as Whitebox executable not found")
}

Generate stream network

Description

Generate stream network

Usage

ch_wbt_channels(
  fn_flowacc,
  fn_flowdir,
  fn_channel_ras,
  fn_channel_vec,
  threshold = NULL,
  ...
)

Arguments

Value

Returns a sf vector object of the stream channels.

Author(s)

Dan Moore

Examples

# Only proceed if Whitebox executable is installed
library(whitebox)
if (check_whitebox_binary()){
  library(raster)
  test_raster <- ch_volcano_raster()
  dem_raster_file <- tempfile(fileext = c(".tif"))
  no_sink_raster_file <- tempfile("no_sinks", fileext = c(".tif"))

  # write test raster to file
  writeRaster(test_raster, dem_raster_file, format = "GTiff")

  # remove sinks
  removed_sinks <- ch_wbt_removesinks(dem_raster_file, no_sink_raster_file, method = "fill")

  # get flow accumulations
  flow_acc_file <- tempfile("flow_acc", fileext = c(".tif"))
  flow_acc <- ch_wbt_flow_accumulation(no_sink_raster_file, flow_acc_file)

  # get flow directions
  flow_dir_file <- tempfile("flow_dir", fileext = c(".tif"))
  flow_dir <- ch_wbt_flow_direction(no_sink_raster_file, flow_dir_file)
  channel_raster_file <- tempfile("channels", fileext = c(".tif"))
  channel_vector_file <- tempfile("channels", fileext = c(".shp"))
  channels <- ch_wbt_channels(flow_acc_file, flow_dir_file, channel_raster_file,
  channel_vector_file, 1)
  plot(channels)
} else {
  message("Examples not run as Whitebox executable not found")
}

Checks for WhiteboxTools executable

Description

Checks for WhiteboxTools executable

Usage

ch_wbt_check_whitebox()

Value

If WhiteboxTools cannot be found, a message explaining what to do is displayed.

Author(s)

Kevin Shook

Examples

# Only proceed if Whitebox executable is installed
library(whitebox)
if (check_whitebox_binary()){
  ch_wbt_check_whitebox()
} else {
  message("Example not run as Whitebox executable not found")
}

Creates names for Whitebox function input and output files

Description

Creates a list of the files used for inputs and outputs by the Whitebox functions. This function needs to be called before calling any of the other Whitebox (i.e. those prefixed by cd_wbt) functions. If the file names are not specified, default names will be used. All raster files are TIFF (.tif), all vector files are shapefiles (.shp).

Usage

ch_wbt_filenames(
  wd = NULL,
  fn_dem = "dem.tif",
  fn_dem_fsc = "dem_fsc.tif",
  fn_dem_ns = "dem_ns.tif",
  fn_flowacc = "flow_acc.tif",
  fn_flowdir = "flow_dir.tif",
  fn_channel_ras = "channel.tif",
  fn_channel_vec = "channel.shp",
  fn_catchment_ras = "catchment.tif",
  fn_catchment_vec = "catchment.shp",
  fn_pp = "pp.shp",
  fn_pp_snap = "pp_snap.shp"
)

Arguments

Value

Returns a list of the input and output file names

Author(s)

Dan Moore

Examples

wbt_file_names <- ch_wbt_filenames(getwd())

Creates flow accumulation grid file

Description

Creates flow accumulation grid file

Usage

ch_wbt_flow_accumulation(fn_dem_ns, fn_flowacc, return_raster = TRUE)

Arguments

Value

If return_raster = TRUE, the flow accumulation grid will be returned as a raster object, otherwise NULL is returned.

Author(s)

Dan Moore

Examples

# Only proceed if Whitebox executable is installed
library(whitebox)
if (check_whitebox_binary()){
  library(raster)
  test_raster <- ch_volcano_raster()
  dem_raster_file <- tempfile(fileext = c(".tif"))
  no_sink_raster_file <- tempfile("no_sinks", fileext = c(".tif"))

  # write test raster to file
  writeRaster(test_raster, dem_raster_file, format = "GTiff")

  # remove sinks
  removed_sinks <- ch_wbt_removesinks(dem_raster_file, no_sink_raster_file, method = "fill")

  # get flow accumulations
  flow_acc_file <- tempfile("flow_acc", fileext = c(".tif"))
  flow_acc <- ch_wbt_flow_accumulation(no_sink_raster_file, flow_acc_file)
  plot(flow_acc)
} else {
  message("Examples not run as Whitebox executable not found")
}

Creates flow direction grid file

Description

Creates flow direction grid file

Usage

ch_wbt_flow_direction(fn_dem_ns, fn_flowdir, return_raster = TRUE)

Arguments

Value

If return_raster = TRUE (the default), the flow direction grid will be returned as a raster object, in addition to being written to fn_flowdir. If return_raster = FALSE, the output file will still be created but a NULL value is returned.

Author(s)

Dan Moore

Examples

# Only proceed if Whitebox executable is installed
library(whitebox)
if (check_whitebox_binary()){
  library(raster)
  test_raster <- ch_volcano_raster()
  dem_raster_file <- tempfile(fileext = c(".tif"))
  no_sink_raster_file <- tempfile("no_sinks", fileext = c(".tif"))

  # write test raster to file
  writeRaster(test_raster, dem_raster_file, format = "GTiff")

  # remove sinks
  removed_sinks <- ch_wbt_removesinks(dem_raster_file, no_sink_raster_file, method = "fill")

  # get flow directions
  flow_dir_file <- tempfile("flow_dir", fileext = c(".tif"))
  flow_dir <- ch_wbt_flow_direction(no_sink_raster_file, flow_dir_file)
  plot(flow_dir)
} else {
  message("Examples not run as Whitebox executable not found")
}

Snap pour points to channels

Description

Pour points describe the outlets of sub-basins within a DEM. To use the pour points to delineate catchments, they must align with the drainage network. This function snaps (forces the locations) of pour points to the channels.

Usage

ch_wbt_pourpoints(
  pp_sf = NULL,
  fn_flowacc,
  fn_pp,
  fn_pp_snap,
  check_crs = TRUE,
  snap_dist = NULL,
  ...
)

Arguments

Value

Returns a sf object of the specified pour points snapped to the channel network.

Author(s)

Dan Moore

See Also

ch_volcano_pourpoints

Examples

# Only proceed if Whitebox executable is installed
library(whitebox)
if (check_whitebox_binary()){
  library(raster)
  test_raster <- ch_volcano_raster()
  dem_raster_file <- tempfile(fileext = c(".tif"))
  no_sink_raster_file <- tempfile("no_sinks", fileext = c(".tif"))

  # write test raster to file
  writeRaster(test_raster, dem_raster_file, format = "GTiff")

  # remove sinks
  removed_sinks <- ch_wbt_removesinks(dem_raster_file, no_sink_raster_file, method = "fill")

  # get flow accumulations
  flow_acc_file <- tempfile("flow_acc", fileext = c(".tif"))
  flow_acc <- ch_wbt_flow_accumulation(no_sink_raster_file, flow_acc_file)

  # get pour points
  pourpoint_file <- tempfile("volcano_pourpoints", fileext = c(".shp"))
  pourpoints <- ch_volcano_pourpoints(pourpoint_file)
  snapped_pourpoint_file <- tempfile("snapped_pourpoints", fileext = c(".shp"))
  snapped_pourpoints <- ch_wbt_pourpoints(pourpoints, flow_acc_file, pourpoint_file,
  snapped_pourpoint_file, snap_dist = 10)
} else {
  message("Examples not run as Whitebox executable not found")
}

Removes sinks from a DEM

Description

Sinks are removed from a DEM using one of several methods. The raster file types supported are listed in Spatial_hydrology_functions.

Usage

ch_wbt_removesinks(
  in_dem,
  out_dem,
  method = "breach_leastcost",
  dist = NULL,
  fn_dem_fsc = NULL,
  ...
)

Arguments

Value

Returns a raster object containing the processed dem.

Author(s)

Dan Moore

Examples

# Only proceed if Whitebox executable is installed
library(whitebox)
if (check_whitebox_binary()){
  library(raster)
  test_raster <- ch_volcano_raster()
  dem_raster_file <- tempfile(fileext = c(".tif"))
  no_sink_raster_file <- tempfile("no_sinks", fileext = c(".tif"))

  # write test raster to file
  writeRaster(test_raster, dem_raster_file, format = "GTiff")

  # remove sinks
  removed_sinks <- ch_wbt_removesinks(dem_raster_file, no_sink_raster_file, method = "fill")
} else {
  message("Examples not run as Whitebox executable not found")
}

Designation of the water year

Description

Display water year

Usage

ch_wtr_yr(dates, start_month = 10)

Arguments

Value

Year starting in start_month

Source

http://stackoverflow.com/questions/27626533/r-create-function-to-add-water-year-column

Examples

date <- seq(as.Date("1910/1/1"), as.Date("1912/1/1"), "days")
wtr_yr_date <- ch_wtr_yr(dates=date, start_month=10)
df <- data.frame(wtr_yr_date, date)

Annual maxima from sites in the Atlantic region of Canada

Description

Contains the annual maxima of 45 hydrometric stations found in the region '01' of Water Survey of Canada. In additional to the annual maxima, the output list includes catchment descriptors (longitude, latitude, basin area, mean annual precipitation) and the geographical distance between each station.

Usage

flowAtlantic

Format

An object of class list of length 2.

Author(s)

Martin Durocher

Source

https://wateroffice.ec.gc.ca/