CalculateRiverDistance: Calculate River Distance Between Two SUBIDs

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

Calculate River Distance Between Two SUBIDs

Description

Calculates the river distance between two SUBIDs along the routing network. The distance is calculated by summing the RIVLEN values of the subbasins between the two requested SUBIDs. The sign of the returned distance indicates the direction of the routing: positive if SUBID1 is upstream of SUBID2, and negative if SUBID1 is downstream of SUBID2.

Usage

CalculateRiverDistance(SUBID1, SUBID2, gd, bd = NULL)

Arguments

SUBID1	Numeric or character. The first SUBID.
SUBID2	Numeric or character. The second SUBID.
gd	A data frame containing HYPE geographical data (i.e. an imported 'GeoData.txt' file). Must contain the columns SUBID, MAINDOWN, and RIVLEN.
bd	Optional data frame containing HYPE branch data. Used by AllDownstreamSubids() to determine the routing network. Default is NULL.

Details

The function first checks that both requested SUBIDs exist in gd and that the RIVLEN column is available. It then uses AllDownstreamSubids() to identify the downstream routing from the first SUBID.

If SUBID2 is downstream of SUBID1, the distance is returned as a positive value. If SUBID1 is downstream of SUBID2, the routing direction is reversed and the distance is returned as a negative value.

The distance is calculated by summing the RIVLEN values for the SUBIDs between the two requested SUBIDs. The RIVLEN of the upstream SUBID itself is not included in the calculation.

If no routing connection exists between the two SUBIDs, the function issues a warning and returns NA.

Value

A numeric value giving the river distance between SUBID1 and SUBID2. The value is positive when SUBID1 is upstream of SUBID2 and negative when SUBID1 is downstream of SUBID2. Returns NA if no routing connection exists between the two SUBIDs.

See Also

AllDownstreamSubids() AllUpstreamSubids()

Examples

# Read GeoData and BranchData files
gd <- ReadGeoData(
  filename = system.file("demo_model", "GeoData.txt", package = "HYPEtools")
)
bd <- ReadGeoData(
  filename = system.file("demo_model", "GeoData.txt", package = "HYPEtools")
)

# Calculate the river distance between two SUBIDs
CalculateRiverDistance(
  SUBID1 = 3344,
  SUBID2 = 3587,
  gd = gd
)

HYPEtools documentation built on Sept. 3, 2026, 1:06 a.m.