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

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.

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

Examples

Run this code

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)