Aggregate an Optimal Channel Network — aggregate

Function that, given an OCN, builds the network at the river network (RN), aggregated (AG), subcatchment (SC), and catchment (CM) levels.

Usage

aggregate_OCN(OCN, thrA = 0.002 * OCN$FD$nNodes *
  OCN$cellsize^2, streamOrderType = "Strahler", maxReachLength = Inf,
  equalizeLengths = FALSE, breakpoints = NULL, displayUpdates = FALSE)

Arguments

OCN: A river object as produced by landscape_OCN.
thrA: Threshold value on drainage area used to derive the aggregated network. If thrA = 0, no aggregation is performed: every FD node is also a node at the RN and AG levels. In this case, the function aggregate_OCN can still be used to compute statistics such as OCN$AG$streamOrder.
streamOrderType: If "Strahler", Strahler stream order is computed; if "Shreve", Shreve stream order is computed.
maxReachLength: Maximum reach length allowed (in planar units). If the path length between a channel head and the downstream confluence is higher than maxReachLength, the reach starting from the channel head will have a length up to maxReachLength, while the next downstream pixel is considered as a new channel head, from which a new reach departs. Values lower than OCN$cellsize*sqrt(2) are not allowed. If maxReachLength < 2*OCN$cellsize, every RN node is also an AG node.
equalizeLengths: Logical. Only effective when maxReachLength < Inf. If TRUE, reaches longer than maxReachLength are split in portions of similar length. If FALSE (default), a split is made whenever adding one more pixel to a reach would violate the maxReachLength constrain, which could result in the creation of very short reaches. Note that setting equalizeLengths = TRUE might increase the number of AG nodes with respect to the default case (see example 2).
breakpoints: Indices of additional nodes at the RN level that should be also nodes at the AG level (beyond source, confluence, outlet nodes and AG nodes determined via maxReachLength). To determine such indices, a preliminary run of aggregate_OCN with the same thrA would be required (see example 3).
displayUpdates: Logical. State if updates are printed on the console while aggregate_OCN runs.

Value

A river object that contains all objects contained in OCN, in addition to the objects listed below. New sublists RN, AG, SC, containing variables at the corresponding aggregation levels, are created. Refer to section 4.2 of the vignette for a more detailed explanation on values OCN$XX$toYY, where XX and YY are two random aggregation levels.

FD$toRN: Vector (of length OCN$FD$nNodes) whose values are equal to 0 if the FD node is not a node at the RN level. If FD$toRN[i] != 0, then FD$toRN[i] is the index at the RN level of the node whose index at the FD level is i. Thereby, FD$toRN[i] = j implies RN$toFD[j] = i.
FD$toSC: Vector (of length OCN$FD$nNodes) of SC indices for all nodes at the FD level. If OCN$FD$toSC[i] = j, then i %in% OCN$SC$toFD[[j]] = TRUE.
RN$A: Vector (of length RN$nNodes) containing drainage area values for all RN nodes (in square planar units).
RN$W: Adjacency matrix (RN$nNodes by RN$nNodes) at the RN level. It is a spam object.
RN$downNode: Vector (of length RN$nNodes) representing the adjacency matrix at RN level in a vector form: if RN$downNode[i] = j then RN$W[i,j] = 1. If o is the outlet node, then RN$downNode[o] = 0.
RN$drainageDensity: Drainage density of the river network, calculated as total length of the river network divided by area of the lattice. It is expressed in planar units^(-1).
RN$leng: Vector (of length RN$nNodes) of lengths of edges departing from nodes at the RN level. Its values are equal to either 0 (if the corresponding node is an outlet), OCN$cellsize (if the corresponding flow direction is horizontal/vertical), or sqrt(2)*OCN$cellsize (diagonal flow).
RN$nNodes: Number of nodes at the RN level.
RN$nUpstream: Vector (of length RN$nNodes) providing the number of nodes upstream of each node (the node itself is included).
RN$outlet: Vector (of length OCN$FD$nOutlet) indices of nodes at RN level corresponding to outlets.
RN$Slope: Vector (of length RN$nNodes) of pixel slopes at RN level.
RN$toAG: Vector (of length RN$nNodes) whose values are equal to 0 if the RN node is not a node at the AG level. If RN$toAG[i] != 0, then RN$toAG[i] is the index at the AG level of the node whose index at the RN level is i. Thereby, RN$toAG[i] = j implies AG$toRN[j] = i.
RN$toAGReach: Vector (of length RN$nNodes) identifying to which edge (reach) the RN nodes belong. If RN$toAGReach[i] = j, the RN node i belongs to the edge departing from from the AG node j (which implies that it may correspond to the AG node j itself.)
RN$toFD: Vector (of length RN$nNodes) with indices at FD level of nodes belonging to RN level. RN$toFD[i] = j implies OCN$FD$toRN[j] = i.
RN$toCM: Vector (of length RN$nNodes) with catchment index values for each RN node. Example: RN$toCM[i] = j if node i drains into the outlet whose location is defined by outletSide[j], outletPos[j].
RN$upstream: List (of length RN$nNodes) whose object i is a vector (of length RN$nUpstream[i]) containing the indices of nodes upstream of a node i (including i).
RN$X, RN$Y: Vectors (of length RN$nNodes) of X, Y coordinates of nodes at RN level.
RN$Z: Vector (of length RN$nNodes) of Z coordinates of nodes at RN level.
AG$A: Vector (of length AG$nNodes) containing drainage area values for all nodes at AG level. If i is a channel head, then AG$A[RN$toAG[i]] = RN$A[i].
AG$AReach: Vector (of length AG$nNodes) containing drainage area values computed by accounting for the areas drained by edges departing from AG nodes. In other words, AG$AReach[i] is equal to the drainage area of the last downstream node belonging to the reach that departs from i (namely AG$AReach[i] = max(RN$A[RN$toAG == i])).
AG$W: Adjacency matrix (AG$nNodes by AG$nNodes) at the AG level. It is a spam object.
AG$downNode: Vector (of length AG$nNodes) representing the adjacency matrix at AG level in a vector form: if AG$downNode[i] = j then AG$W[i,j] = 1. If o is the outlet node, then AG$downNode[o] = 0.
AG$leng: Vector (of length AG$nNodes) of lengths of edges departing from nodes at AG level. Note that AG$leng[i] = sum(RN$leng[RN$toAG == i]). If o is an outlet node (i.e. (o %in% AG$outlet) = TRUE), then AG$leng[i] = 0.
AG$nNodes: Number of nodes resulting from the aggregation process.
AG$nUpstream: Vector (of length AG$nNodes) providing the number of nodes (at the AG level) upstream of each node (the node itself is included).
AG$outlet: Vector (of length OCN$FD$nOutlet) with indices of outlet nodes, i.e. nodes whose AG$downNode value is 0.
AG$slope: Vector (of length AG$nNodes) of slopes at AG level. It represents the (weighted) average slope of edges departing from nodes. If i is an outlet node (i.e. (i %in% AG$outlet) = TRUE), then AG$slope[i] = NaN.
AG$streamOrder: Vector (of length AG$nNodes) of stream order values for each node. If streamOrderType = "Strahler", Strahler stream order is computed. If streamOrderType = "Shreve", Shreve stream order is computed.
AG$upstream: List (of length AG$nNodes) whose object i is a vector (of length AG$nUpstream[i]) containing the indices of nodes (at the AG level) upstream of a node i (including i).
AG$toFD: Vector of length AG$nNodes) with with indices at FD level of nodes belonging to AG level. AG$toFD[i] = j implies OCN$FD$toAG[j] = i.
AG$ReachToFD: List (of length AG$nNodes) whose object i is a vector of indices of FD nodes constituting the edge departing from node i.
AG$toRN: Vector of length AG$nNodes) with with indices at RN level of nodes belonging to AG level. AG$toRN[i] = j implies OCN$FD$toRN[j] = i.
AG$ReachToRN: List (of length AG$nNodes) whose object i is a vector of indices of RN nodes constituting the edge departing from node i.
AG$toCM: Vector (of length AG$nNodes) with catchment index values for each AG node. Example: AG$toCM[i] = j if node i drains into the outlet whose location is defined by outletSide[j], outletPos[j].
AG$X, AG$Y: Vectors (of length AG$nNodes) of X, Y coordinates (in planar units) of nodes at the AG level. These correspond to the X, Y coordinates of the nodes constituting the upstream tips of the reaches. If i and j are such that AG$X[i] == RN$X[j] and AG$Y[i] == RN$Y[j], then AG$A[i] = RN$A[j].
AG$XReach, AG$YReach: Vector (of length AG$nNodes) of X, Y coordinates (in planar units) of the downstream tips of the reaches. If i and j are such that AG$XReach[i] == RN$X[j] and AG$YReach[i] == RN$Y[j], then AG$AReach[i] = RN$A[j]. If o is an outlet node, then AG$XReach = NaN, AG$YReach = NaN.
AG$Z: Vector (of length AG$nNodes) of elevation values (in elevational units) of nodes at the AG level. These correspond to the elevations of the nodes constituting the upstream tips of the reaches.
AG$ZReach: Vector (of length AG$nNodes) of Z coordinates (in elevational units) of the downstream tips of the reaches. If o is an outlet node, then AG$ZReach = NaN.
SC$ALocal: Vector (of length SC$nNodes) with values of subcatchment area, that is the number of FD pixels (multiplied by OCN$FD$cellsize^2) that constitutes a subcatchment. If o is an outlet node, then ALocal[o] = 0.
SC$W: Adjacency matrix (SC$nNodes by SC$nNodes) at the subcatchment level. Two subcatchments are connected if they share a border. Note that this is not a flow connection. Unlike the adjacency matrices at levels FD, RN, AG, this matrix is symmetric. It is a spam object. If o is an outlet node, then SC$W[o,] and SC$W[,o] only contain zeros (i.e., o is unconnected to the other nodes).
SC$nNodes: Number of subcatchments into which the lattice is partitioned. If nOutlet = 1, then SC$nNodes = AG$nNodes. If multiple outlets are present, SC$nNodes might be greater than AG$nNodes in the case when some catchments have drainage area lower than thrA. In this case, the indices from AG$nNodes + 1 to SC$nNodes identify subcatchment that do not have a corresponding AG node.
SC$toFD: List (of length SC$nNodes) whose object i is a vector of indices of FD pixels constituting the subcatchment i.
SC$X, SC$Y: Vectors (of length SC$nNodes) of X, Y coordinates (in planar units) of subcatchment centroids.
SC$Z: Vector (of length SC$nNodes) of average subcatchment elevation (in elevational units).

Finally, thrA is added to the river object.

Details

Note that each node (and the corresponding edge exiting from it, in the case of non-outlet nodes) at the AG level corresponds to a subcatchment at the SC level that shares the same index: for instance, SC$toFD[i] contains all elements of AG$toFD[i] (that is, the indices of pixels at FD level that constitute the edge departing from node i are also part of subcatchment i).

Examples

# 1a) aggregate a 20x20 OCN by imposing thrA = 4. 
OCN <- aggregate_OCN(landscape_OCN(OCN_20), thrA = 4)
draw_thematic_OCN(OCN, drawNodes = TRUE)


# \donttest{
# 1b) same as above, but identify all RN nodes as AG nodes
mrl <- 1.5*OCN_20$cellsize
OCN2 <- aggregate_OCN(landscape_OCN(OCN_20), thrA = 4, maxReachLength = mrl)
draw_thematic_OCN(OCN2, drawNodes = TRUE)

# }

# \donttest{
# 2) explore the effects of thrA, maxReachLength and equalizeLengths on a large OCN
OCN <- landscape_OCN(OCN_250_T) # it takes some seconds
OCN_a <- aggregate_OCN(OCN, thrA = 200) # it takes some seconds
OCN_b <- aggregate_OCN(OCN, thrA = 1000) # it takes some seconds
OCN_c <- aggregate_OCN(OCN, thrA = 1000, maxReachLength = 20) # it takes some seconds
OCN_d <- aggregate_OCN(OCN, thrA = 1000, maxReachLength = 20, 
equalizeLengths = TRUE) # it takes some seconds

old.par <- par(no.readonly = TRUE)
par(mfrow = c(2,2))
draw_subcatchments_OCN(OCN_a)
points(OCN_a$AG$X, OCN_a$AG$Y, pch = 19, col = "#0044bb") 
title(paste("No. AG nodes = ", as.character(OCN_a$AG$nNodes),
    sep=""))
draw_subcatchments_OCN(OCN_b)
points(OCN_b$AG$X, OCN_b$AG$Y, pch = 19, col = "#0044bb") 
title(paste("No. AG nodes = ", as.character(OCN_b$AG$nNodes),
    sep=""))
draw_subcatchments_OCN(OCN_c)
points(OCN_c$AG$X, OCN_c$AG$Y, pch = 19, col = "#0044bb") 
title(paste("No. AG nodes = ", as.character(OCN_c$AG$nNodes),
    sep=""))
    draw_subcatchments_OCN(OCN_d)
points(OCN_d$AG$X, OCN_d$AG$Y, pch = 19, col = "#0044bb") 
title(paste("No. AG nodes = ", as.character(OCN_d$AG$nNodes),
    sep=""))

par(old.par)
# note the difference between OCN_c and OCN_d at the bottom right corner of the lattice
# }

# 3) use of breakpoints
OCN <- aggregate_OCN(landscape_OCN(OCN_20), thrA = 5)
draw_thematic_OCN(OCN, drawNodes=TRUE)

# add an AG node downstream of node 1 at AG level
new_node_RN <- OCN$RN$downNode[OCN$AG$toRN[1]]
OCN2 <- aggregate_OCN(landscape_OCN(OCN_20), thrA = 5, breakpoints = new_node_RN)
draw_thematic_OCN(OCN2, drawNodes = TRUE)
points(OCN$RN$X[new_node_RN], OCN$RN$Y[new_node_RN], 
  pch = 19, col = "red") # this node has been added