DirectUpstreamSubids: Find Direct Upstream SUBIDs, with Flow Fractions

In HYPEtools: Tools for Processing and Analyzing Files from the Hydrological Catchment Model HYPE

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), defaults to NULL. If non-NULL, DirectUpstreamSubids returns the direct upstream SUBIDs for this sub-catchment, otherwise for all sub-catchments in gd.
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)

HYPEtools documentation built on Sept. 11, 2024, 8:34 p.m.