OCNet (version 1.2.2)

paths_OCN: Calculate paths between nodes in an Optimal Channel Network

Description

Function that determines upstream and downstream paths and path lengths between any nodes of the network at the aggregated level.

Usage

paths_OCN(OCN, level = c("RN","AG"), whichNodes = NULL, includePaths = FALSE, 
includeDownstreamNode = FALSE, includeUnconnectedPaths = FALSE, displayUpdates = FALSE)

Value

A river object that contains all objects contained in OCN, in addition to the objects listed below.

RN$downstreamPath

List (of length OCN$RN$nNodes) whose object i is a list (of length OCN$RN$nNodes). If nodes i and j are connected by a downstream path, then RN$downstreamPath[[i]][[j]] is a vector containing the indices of the nodes constituting such path (i and j are included). If i and j are not connected by a downstream path, then RN$downstreamPath[[i]][[j]] = NULL. Only present if includePaths = TRUE.

RN$downstreamPathLength

Sparse matrix (OCN$RN$nNodes by OCN$RN$nNodes) containing length of paths between nodes that are connected by a downstream path; if i and j are not connected by a downstream path, then RN$downstreamPathLength[i,j] = 0. Note that RN$downstreamPathLength[i,i] = 0 if includeDownstreamNode = FALSE; alternatively, it is RN$downstreamPathLength[i,i] = OCN$RN$leng[i]. It is a spam object.

RN$downstreamLengthUnconnected

Matrix (OCN$RN$nNodes by OCN$RN$nNodes). RN$downstreamLengthUnconnected[i,j] is the length of the downstream portion of a path joining node i to j if i and j are not connected by a downstream path. Specifically, RN$downstreamLengthUnconnected[i,j] = RN$downstreamPathLength[i,k], where k is a node such that there exist a downstream path from i to k and from j to k, and these paths are the shortest possible. Note that the length of the upstream portion of the path joining i to j is given by RN$downstreamLengthUnconnected[j,i]. If instead i and j are joined by a downstream path, then RN$downstreamLengthUnconnected[i,j] = 0. Only present if includeUnconnectedPaths = TRUE.

AG$downstreamPath

List (of length OCN$AG$nNodes) whose object i is a list (of length OCN$AG$nNodes). If nodes i and j are connected by a downstream path, then AG$downstreamPath[[i]][[j]] is a vector containing the indices of the nodes constituting such path (i and j are included). If i and j are not connected by a downstream path, then AG$downstreamPath[[i]][[j]] = NULL. Only present if includePaths = TRUE.

AG$downstreamPathLength

Sparse matrix (OCN$AG$nNodes by OCN$AG$nNodes) containing length of paths between nodes that are connected by a downstream path; if i and j are not connected by a downstream path, then AG$downstreamPathLength[i,j] = 0. Note that AG$downstreamPathLength[i,i] = 0 if includeDownstreamNode = FALSE; alternatively, it is AG$downstreamPathLength[i,i] = OCN$AG$leng[i]. It is a spam object.

AG$downstreamLengthUnconnected

Matrix (OCN$AG$nNodes by OCN$AG$nNodes). AG$downstreamLengthUnconnected[i,j] is the length of the downstream portion of a path joining node i to j if i and j are not connected by a downstream path. Specifically, AG$downstreamLengthUnconnected[i,j] = AG$downstreamPathLength[i,k], where k is a node such that there exist a downstream path from i to k and from j to k, and these paths are the shortest possible. Note that the length of the upstream portion of the path joining i to j is given by AG$downstreamLengthUnconnected[j,i]. If instead i and j are joined by a downstream path, then AG$downstreamLengthUnconnected[i,j] = 0. Only present if includeUnconnectedPaths = TRUE.

Arguments

OCN

A river object as produced by aggregate_OCN.

level

Character vector. At which level should paths be calculated? Possible values are "RN", "AG", or both.

whichNodes

List. It allows specifying a subset of nodes for which paths are computed. In the case of large rivers, this could speed up the function execution substantially. It must contain objects named RN and/or AG. Each of these objects is a vector with the indices of the nodes for which paths are to be calculated. Default is NULL, which leads to calculation of paths between all nodes at the level(s) specified in level. If whichNodes contains a single object (RN or AG), this is taken as the level at which paths are calculated (i.e., level is overwritten). If not present, the outlet node is automatically added. See example.

includePaths

Logical. If TRUE, RN$downstreamPath and AG$downstreamPath are included to the output object. Note that this might slow down the function execution considerably, and create RAM issues for very large OCNs.

includeDownstreamNode

Logical. If TRUE, path lengths include the length of the edge departing from the last downstream node of the path.

includeUnconnectedPaths

Logical. If TRUE, calculate path lengths between unconnected nodes (RN$downstreamLengthUnconnected and AG$downstreamLengthUnconnected). Note that this might slow down the function execution considerably, and create RAM issues for very large OCNs.

displayUpdates

Logical. State if updates are printed on the console while paths_OCN runs.

Examples

# 1) Calculate paths between nodes of an OCN
OCN <- paths_OCN(aggregate_OCN(landscape_OCN(OCN_20), thrA = 4))
# \donttest{
# 2) Display distance to outlet (at the RN level) along the main stem
# of an OCN
OCN <- aggregate_OCN(landscape_OCN(OCN_250_T)) # this takes some seconds
OCN <- paths_OCN(OCN, includePaths = TRUE) # this takes some seconds

distanceToOutlet <- OCN$RN$downstreamPathLength[,OCN$RN$outlet]
farthestNode <- which(distanceToOutlet == max(distanceToOutlet))
mainStem <- OCN$RN$downstreamPath[[farthestNode]][[OCN$RN$outlet]]
theme <- rep(NaN, OCN$RN$nNodes)
theme[mainStem] <- distanceToOutlet[mainStem]

draw_thematic_OCN(theme, OCN)
title("Distance to outlet along the main stem [pixel units]")

# 3) use whichNodes to compute distance between two non flow-connected nodes 
OCN <- aggregate_OCN(landscape_OCN(OCN_250_T)) # this takes some seconds
RNnodes <- c(483, 516)
plot(OCN)
points(OCN$RN$X[RNnodes], OCN$RN$Y[RNnodes], pch = 19) # nodes 483 and 516 are not flow-connected
OCN <- paths_OCN(OCN, whichNodes = list(RN=RNnodes), includePaths = TRUE,
				 includeUnconnectedPaths = TRUE)
OCN$RN$downstreamPath[[RNnodes[1]]][[OCN$RN$outlet]] 
# the outlet node has been added to whichNodes$RN
OCN$RN$downstreamLengthUnconnected[RNnodes[1], RNnodes[2]] 
# distance from node 1 to the common downstream confluence
OCN$RN$downstreamLengthUnconnected[RNnodes[2], RNnodes[1]] 
# distance from node 2 to the common downstream confluence
# }