aggregate_OCN: Aggregate an Optimal Channel Network

Description

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$dimX * OCN$dimY *
  OCN$cellsize^2, streamOrderType = "Strahler", maxReachLength = Inf)

Arguments

OCN

List 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.

Value

A list 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 list.

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

Run this code

# NOT RUN {
# 1) aggregate a 20x20 OCN by imposing thrA = 4
OCN <- aggregate_OCN(landscape_OCN(OCN_20), thrA = 4)

# }
# NOT RUN {
# 2) explore the effects of thrA and maxReachLength 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

old.par <- par(no.readonly = TRUE)
par(mfrow = c(1,3))
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=""))
par(old.par)
# }

Run the code above in your browser using DataLab