UpstreamGeoData {HYPEtools}

Calculate upstream sums and averages of selected GeoData contents

Description

Function to calculate upstream sums and averages for selected variables of imported GeoData.txt files.

Usage

UpstreamGeoData(
  subid = NULL,
  gd,
  bd = NULL,
  olake.slc = NULL,
  bd.weight = FALSE,
  signif.digits = 5,
  progbar = TRUE
)

Arguments

subid

Integer vector of SUBIDs for which to calculate upstream properties (must exist in gd). If NULL (default), upstream areas for all SUBIDs will be calculated.

gd

A data frame containing a column with SUBIDs and a column with areas, e.g. an imported 'GeoData.txt' file.

bd

A data frame with bifurcation connections, e.g. an imported 'BranchData.txt' file. Optional argument.

olake.slc

Integer,SLC class number which represents outlet lake fractions. Mandatory for weighted averaging of outlet lake depths.

bd.weight

Logical, if set to TRUE, flow weights will be applied for areas upstream of stream bifurcations. See AllUpstreamSubids for further details on flow fraction computation.

signif.digits

Integer, number of significant digits to round upstream variables to. See also signif. Set to NULL to prevent rounding.

progbar

Logical, display a progress bar while calculating SLC class fractions. Adds overhead to calculation time but useful when subid is NULL or contains many SUBIDs.

Details

UpstreamGeoData calculates upstream averages or sums of selected variables in a GeoData data frame, including branch connections in case of stream bifurcations but not including potential irrigation links or groundwater flows. Averages are weighted by sub-catchment area, with the exception of outlet lake depths and rural household emission concentrations provided in GeoData variables 'lake_depth', 'loc_tn', and 'loc_tp'. Outlet lake depths are weighted by outlet lake area and the GeoData column with SLC class fractions for outlet lakes must be provided in function argument col.olake.slc. Rural household emissions are weighted by emission volume as provided in column 'loc_vol'. Elevation and slope standard deviations are averaged if the corresponding mean values exist (sample means are required to calculate overall means of standard deviations).

Currently, the following variables are considered:

Area-weighted average

elev_mean, slope_mean, buffer, close_w, latitude, longitude, all SLC classes, lake depths, elev_std, slope_std

Volume-weighted average

loc_tn, loc_tp

Sum

area, rivlen, loc_vol

Value

UpstreamGeoData returns a data frame with the same number of columns as argument gd and number of rows corresponding to number of SUBIDs in argument subid, with updated upstream columns marked with a leading 'UP_' in the column names.

See Also

UpstreamSLCClasses SumUpstreamArea AllUpstreamSubids

Examples

te <- ReadGeoData(filename = system.file("demo_model", "GeoData.txt", package = "HYPEtools"))
# Upstream stats for domain outlet
UpstreamGeoData(subid = OutletSubids(te), gd = te, olake.slc = 1, progbar = FALSE)