| DirectUpstreamSubids {HYPEtools} | R Documentation |
Find Direct Upstream SUBIDs, with Flow Fractions
Description
Function to find direct upstream SUBIDs including flow fractions for MAINDOWN/BRANCHDOWN splits for a single sub-catchment or all sub-catchments in a GeoData-like data frame.
Usage
DirectUpstreamSubids(subid = NULL, gd, bd = NULL)
Arguments
subid |
Integer, SUBID of a target sub-catchment (must exist in |
gd |
Data frame, typically an imported 'GeoData.txt' file. Mandatory argument. See 'Details'. |
bd |
Data frame, typically an imported 'BranchData.txt' file. Optional argument, defaults to an empty placeholder. See 'Details'. |
Details
DirectUpstreamSubids identifies direct upstream SUBIDs for a user-provided target SUBID or
for all SUBIDs given in a data frame gd, typically an imported GeoData file.
A sub-catchment in HYPE can have several upstream sub-catchments. If there are more than one upstream sub-catchments, the downstream sub-catchment is a confluence. HYPE stores these connections in the GeoData file, in downstream direction, given as downstream SUBID in column 'MAINDOWN'. Bifurcations, i.e. splits in downstream direction, are also possible to model in HYPE. These additional downstream connections are provided in the BranchData file, together with flow fractions to each downstream SUBID.
Formally, gd can be any data frame which contains columns 'SUBID' and 'MAINDOWN' (not case-sensitive), and bd any
data frame which contains three columns: 'BRANCHID', 'SOURCEID', and 'MAINPART', and optionally columns 'MAXQMAIN', 'MINQMAIN', 'MAXQBRANCH'.
Typically, these are HYPE data files
imported through ReadGeoData and ReadBranchData. See HYPE documentation for further details on connections
Between SUBIDs in the model.
Value
DirectUpstreamSubids always returns a list. If argument subid is non-NULL, a list with two elements is returned:
subid contains an integer giving the target SUBID and upstr.df contains a data frame with columns
upstream (upstream SUBID), is.main (logical, TRUE if it is a MAINDOWN connection),
fraction (fraction of flow going into the target SUBID), and llim and ulim giving upper and lower flow boundaries which
optionally limit flow into the target SUBID.
If no specific SUBID was provided, DirectUpstreamSubids returns a list with upstream information for all SUBIDs in argument
gd, each list element containing the list described above, i.e. with an integer element (SUBID) and a data frame element
(upstream connections).
See Also
AllUpstreamSubids, which returns all upstream SUBIDs, i.e. the full upstream network up to the headwaters, for a given SUBID.
Examples
te <- ReadGeoData(filename = system.file("demo_model", "GeoData.txt", package = "HYPEtools"))
DirectUpstreamSubids(subid = 3594, gd = te)