R: Aggregate an Optimal Channel Network

aggregate_OCN {OCNet}

R Documentation

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$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$cellsizesqrt(2)` are not allowed. If `maxReachLength < 2OCN$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.

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

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.

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)


# 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)



# 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

[Package OCNet version 1.2.2 Index]