A river object as produced by aggregate_OCN.

Aggregation level at which AEMs are to be calculated. It must be equal to either "RN" or "AG".

Determines how and if weights should be used to compute the AEMs. Defaults to NULL, which applies equal weights to all links of the OCN. It can be one of "gravity", "exponential", "linear", "parabolic" or a user-specified function. See details.

Identifies how resisitance (i.e., the variable negatively related to the link weight) is calculated. Defaults to "length" (i.e., resistance equal to link length). Alternatively, resistance = "time" uses water travel time to weigh the links. In such a case, water velocities must be contained in the OCN (e.g. via rivergeometry_OCN).

Logical. Should Moran's I statistics be computed and random tests be performed via moran.randtest?

A river object.

Further arguments.

A river object as produced by aggregate_OCN.

Aggregation level at which the OCN is converted into an igraph object. It must be equal to either "FD", "RN" or "AG".

A river object as produced by landscape_OCN.

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.

If "Strahler", Strahler stream order is computed; if "Shreve", Shreve stream order is computed.

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.

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

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

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

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.

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.

Vector (of length RN$nNodes) containing drainage area values for all RN nodes (in square planar units).

Adjacency matrix (RN$nNodes by RN$nNodes) at the RN level. It is a spam object.

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.

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

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

Number of nodes at the RN level.

Vector (of length RN$nNodes) providing the number of nodes upstream of each node (the node itself is included).

Vector (of length OCN$FD$nOutlet) indices of nodes at RN level corresponding to outlets.

Vector (of length RN$nNodes) of pixel slopes at RN level.

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.

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

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.

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

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

Vectors (of length RN$nNodes) of X, Y coordinates of nodes at RN level.

Vector (of length RN$nNodes) of Z coordinates of nodes at RN level.

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

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

Adjacency matrix (AG$nNodes by AG$nNodes) at the AG level. It is a spam object.

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.

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.

Number of nodes resulting from the aggregation process.

Vector (of length AG$nNodes) providing the number of nodes (at the AG level) upstream of each node (the node itself is included).

Vector (of length OCN$FD$nOutlet) with indices of outlet nodes, i.e. nodes whose AG$downNode value is 0.

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.

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.

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

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.

List (of length AG$nNodes) whose object i is a vector of indices of FD nodes constituting the edge departing from node i.

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.

List (of length AG$nNodes) whose object i is a vector of indices of RN nodes constituting the edge departing from node i.

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

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

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.

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.

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.

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.

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

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.

List (of length SC$nNodes) whose object i is a vector of indices of FD pixels constituting the subcatchment i.

Vectors (of length SC$nNodes) of X, Y coordinates (in planar units) of subcatchment centroids.

Vector (of length SC$nNodes) of average subcatchment elevation (in elevational units).

A river object (as generated by create_OCN).

Number of iterations that the OCN search algorithm performs.

Parameter of the function used to describe the temperature of the simulated annealing algorithm. See create_OCN. If NULL, it is set equal to the last element of OCN$coolingRate.

Parameter of the function used to describe the temperature of the simulated annealing algorithm. See create_OCN.

Number of updates given during the OCN search process (only effective if any(displayUpdates,showIntermediatePlots)=TRUE.).

If TRUE, the OCN plot is updated nUpdates times during the OCN search process. Note that, for large lattices, showIntermediatePlots = TRUE might slow down the search process considerably (especially when easyDraw = FALSE).

Threshold drainage area value used to display the network (only effective when showIntermediatePlots = TRUE).

Logical. If TRUE, the whole network is displayed (when showIntermediatePlots = TRUE), and pixels with drainage area lower than thrADraw are displayed in light gray. If FALSE, only pixels with drainage area greater or equal to thrADraw are displayed. Default is FALSE if dimX*dimY <= 40000, and TRUE otherwise. Note that setting easyDraw = FALSE for large networks might slow down the process considerably.

State if updates are printed on the console while the OCN search algorithm runs.

0

No update is given.

1

An estimate of duration is given (only if dimX*dimY > 1000, otherwise no update is given).

2

Progress updates are given. The number of these is controlled by nUpdates

Longitudinal dimension of the lattice (in number of pixels).

Latitudinal dimension of the lattice (in number of pixels).

Number of outlets. If nOutlet = "All", all border pixels are set as outlets.

Side of the lattice where the outlet(s) is/are placed. It is a vector of characters, whose allowed values are "N" (northern side), "E", "S", "W". Its length must be equal to nOutlet.

Vector of positions of outlets within the sides specified by outletSide. If outletSide[i] = "N" or "S", then outletPos[i] must be a natural number in the interval 1:dimX; if outletSide[i] = "W" or "E", then outletPos[i] must be a natural number in the interval 1:dimY. If nOutlet > 1 is specified by the user and outletSide, outletPos are not, a number of outlets equal to nOutlet is randomly drawn among the border pixels. Its length must be equal to nOutlet.

If TRUE, periodic boundaries are applied. In this case, the lattice is the planar equivalent of a torus.

Configuration of the initial state of the network. Possible values: "I" (representing a valley); "T" (T-shaped drainage pattern); "V" (V-shaped drainage pattern); "H" (hip roof). Default value is set to "I", unless when nOutlet = "All", where default is "H". See Details for explanation on initial network state in the multiple outlet case.

Matrix (dimY by dimX) with custom initial flow directions. Possible entries to flowDirStart are natural numbers between 1 and 8, indicating direction of flow from one cell to the neighbouring one. Key is as follows:

1

+1 column

2

-1 row, +1 column

3

-1 row

4

-1 row, -1 column

5

-1 column

6

+1 row, -1 column

7

+1 row

8

+1 row, +1 column

Exponent of the functional sum(A^expEnergy) that is minimized during the OCN search algorithm.

Size of a pixel in planar units.

Longitudinal coordinate of the lower-left pixel.

Latitudinal coordinate of the lower-left pixel.

Number of iterations for the OCN search algorithm.

Number of updates given during the OCN search process (only effective if any(displayUpdates,showIntermediatePlots)=TRUE.).

Parameters of the function used to describe the temperature of the simulated annealing algorithm. See details.

If TRUE, the OCN plot is updated nUpdates times during the OCN search process. Note that, for large lattices, showIntermediatePlots = TRUE might slow down the search process considerably (especially when easyDraw = FALSE).

Threshold drainage area value used to display the network (only effective when showIntermediatePlots = TRUE).

Logical. If TRUE, the whole network is displayed (when showIntermediatePlots = TRUE), and pixels with drainage area lower than thrADraw are displayed in light gray. If FALSE, only pixels with drainage area greater or equal to thrADraw are displayed. Default is FALSE if dimX*dimY <= 40000, and TRUE otherwise. Note that setting easyDraw = FALSE for large networks might slow down the process considerably.

If TRUE, energy is saved (see Value for its definition).

If TRUE, exitFlag is saved (see Value for its definition).

If TRUE, the adjacency matrix relative to 8-nearest-neighbours connectivity is saved.

If TRUE, the adjacency matrix relative to 4-nearest-neighbours connectivity is saved.

State if updates are printed on the console while the OCN search algorithm runs.

0

No update is given.

1

An estimate of duration is given (only if dimX*dimY > 1000, otherwise no update is given).

2

Progress updates are given. The number of these is controlled by nUpdates

Vector (of length dimX*dimY) containing drainage area values for all FD pixels (in square planar units).

Adjacency matrix (dimX*dimY by dimX*dimY) at the FD level. It is a spam object.

Vector (of length dimX*dimY) representing the adjacency matrix at FD level in a vector form: if FD$downNode[i] = j then FD$W[i,j] = 1. If o is the outlet pixel, then FD$downNode[o] = 0.

Vector (of length dimX*dimY) containing X (Y) coordinate values for all FD pixels.

Number of nodes at FD level (equal to dimX*dimY).

Vector (of length nOutlet) indices of pixels at FD level corresponding to outlets.

Vector (of length dimX*dimY) representing a permutation of the FD pixels: perm[(which(perm==i) - FD$A[i] + 1):which(perm==i)] gives the indices of the pixels that drain into pixel i.

Initial energy value.

Vector (of length nIter) of energy values for each stage of the OCN during the search algorithm (only present if saveEnergy = TRUE).

Vector (of length nIter) showing the outcome of the rewiring process (only present if saveExitFlag = TRUE). Its entries can assume one of the following values:

0

Rewiring is accepted.

1

Rewiring is not accepted (because it does not lower energy or according to the acceptance probability of the simulated annealing algorithm).

2

Rewiring is invalid because a loop in the graph was generated, therefore the network is no longer a direct acyclic graph.

3

Rewiring is invalid because of cross-flow. This means that, for example, in a 2x2 cluster of pixel, the southwestern (SW) corner drains into the NE one, and SE drains into NW. Although this circumstance does not imply the presence of a loop in the graph, it has no physical meaning and is thereby forbidden.

Adjacency matrix (dimX*dimY by dimX*dimY) that describes 4-nearest-neighbours connectivity between pixels: N4$W[i,j] = 1 if pixel j shares an edge with i, and is null otherwise. It is saved only if saveN4 = TRUE.

Adjacency matrix (dimX*dimY by dimX*dimY) that describes 8-nearest-neighbours connectivity between pixels: N8$W[i,j] = 1 if pixel j shares an edge or a vertex with i, and is null otherwise. It is saved only if saveN8 = TRUE.

Matrix with custom initial flow directions. Cells outside the catchment must have value equal to NaN. Cells within the catchment have natural numbers between 0 and 8. Key is as follows:

0

Outlet

1

+1 column

2

-1 row, +1 column

3

-1 row

4

-1 row, -1 column

5

-1 column

6

+1 row, -1 column

7

+1 row

8

+1 row, +1 column

Note that flowDirStart must have at least one outlet, that is one cell with value 0. The position of outlet(s) will not be altered by the OCN search algorithm.

Exponent of the functional sum(A^expEnergy) that is minimized during the OCN search algorithm.

Size of a pixel in planar units.

Longitudinal (column-wise) coordinate of the lower-left pixel of flowDirStart.

Latitudinal (row-wise) coordinate of the lower-left pixel of flowDirStart.

Number of iterations for the OCN search algorithm. Default is 40 times the number of non-NaN pixels of flowDirStart.

Number of updates given during the OCN search process (only effective if any(displayUpdates,showIntermediatePlots)=TRUE.).

Parameters of the function used to describe the temperature of the simulated annealing algorithm. See details.

If TRUE, the OCN plot is updated nUpdates times during the OCN search process. Note that, for large lattices, showIntermediatePlots = TRUE might slow down the search process considerably (especially when easyDraw = FALSE).

Threshold drainage area value used to display the network (only effective when showIntermediatePlots = TRUE). Default value is 0.002*cellsize^2*nNodes, where nNodes is the number of non-NaN pixels of flowDirStart.

Logical. If TRUE, the whole network is displayed (when showIntermediatePlots = TRUE), and pixels with drainage area lower than thrADraw are displayed in light gray. If FALSE, only pixels with drainage area greater or equal to thrADraw are displayed. Default is FALSE if dimX*dimY <= 40000, and TRUE otherwise. Note that setting easyDraw = FALSE for large networks might slow down the process considerably.

If TRUE, energy is saved (see Value for its definition).

If TRUE, exitFlag is saved (see Value for its definition).

State if updates are printed on the console while the OCN search algorithm runs.

0

No update is given.

1

An estimate of duration is given (only if dimX*dimY > 1000, otherwise no update is given).

2

Progress updates are given. The number of these is controlled by nUpdates

Number of iteration of the Peano scheme. The resulting network will span a domain of size 2^(nIterPeano + 1) by 2^(nIterPeano + 1).

Corner where the outlet is located, expressed as intercardinal direction. Possible values are "NE", "SE", "SW", "NW".

X coordinate of the lower-left pixel (expressed in planar units).

Y coordinate of the lower-left pixel (expressed in planar units).

Size of a pixel (expressed in planar units).

A river object as produced by landscape_OCN.

Threshold drainage area value used to display the network.

If TRUE, the real shape of OCNs is plotted. If flow crosses a boundary, the pixel that is not contiguous to its outlet is flipped. It is only effective if OCN$PeriodicBoundaries = TRUE

If TRUE, plot catchment(s) contours.

Color palette used to plot the river network(s). Default is a rearranged version of theme "Dark 3" (see hcl.pals). colPalRiver accepts both functions creating color palettes and vectors of colors (of which the first OCN$nOutlet elements are used). If a single color value is provided and OCN$nOutlet > 1, all river networks are drawn with the same color.

Color palette used to plot the catchment contour(s). Details as in colPalRiver. Additionally, if colPalCont = 0, the palette specified in colPalRiver is copied.

If equal to 1, black squares are drawn at the outlets' locations behind the river; if 2 they are plotted on top of the river.

Shape of the outlet points (if drawOutlets = TRUE). See points for legend.

Color palette used to plot the outlet points (if drawOutlets = TRUE). Details as in colPalRiver. Additionally, if colPalOut = 0, the palette specified in colPalRiver is copied.

Minimum and maximum values of line width used to display the OCN (actual line width is proportional to the square root of drainage area).

Line width value for catchment contour plotting.

Logical. If TRUE, add to an already existing plot. Taken as FALSE (with a warning if a different value is supplied) if no graphics device is open.

A river object as produced by landscape_OCN.

Color palette used for the plot.

Logical. If TRUE, image.plot is used to display the legend; as a result, elements (e.g. node coordinates) subsequently plotted of on top of the 2D elevation map might be wrongly positioned.

Logical. If TRUE, draw the OCN on top of the elevation map.

Threshold drainage area value used to display the network.

Color used to display the OCN (only effective if drawRiver = TRUE).

Minimum and maximum values of line width used to display the OCN (actual line width is proportional to the square root of drainage area).

List of arguments passed to imagePlot (or to image if addLegend = FALSE). For example, argument smallplot can be used to specify the plot coordinates for the legend.

A river object as produced by landscape_OCN.

2x1 vector (only effective if chooseCM = FALSE). For aesthetic purposes, the elevation map can be coarse-grained into a OCN$dimX/coarseGrain[1]-by-OCN$dimX/coarseGrain[2] domain, where each cell's elevation is the average of elevations of the corresponding coarseGrain[1]-by-coarseGrain[2] cells of the original elevation field. coarseGrain[1] and coarseGrain[2] must be divisors of OCN$dimX and OCN$dimY, respectively. coarseGrain = c(2,2) is often sufficient to achieve a good graphical results for large (i.e. at least 100x100 nodes) OCNs.

Color palette used for the plot.

If TRUE, add colorbar to the plot.

If TRUE, draw the OCN on top of the elevation field.

Threshold drainage area value used to display the network.

Color used to plot the river.

Additional parameters passed to the perspective plotting function persp. theta expresses azimuthal direction; phi gives colatitude; expand is the expansion factor for the Z coordinates; shade controls the shade at a surface facet.

Minimum and maximum values of line width used to display the OCN (actual line width is proportional to the square root of drainage area).

Only effective if addColorbar = TRUE. List of arguments passed to imagePlot for drawing a continuous legend. For example, argument smallplot can be used to specify the plot coordinates for the legend.

A river object as produced by landscape_OCN.

2x1 vector (only effective if chooseCM = FALSE). For aesthetic purposes, the elevation map can be coarse-grained into a OCN$dimX/coarseGrain[1]-by-OCN$dimX/coarseGrain[2] domain, where each cell's elevation is the average of elevations of the corresponding coarseGrain[1]-by-coarseGrain[2] cells of the original elevation field. coarseGrain[1] and coarseGrain[2] must be divisors of OCN$dimX and OCN$dimY, respectively. coarseGrain = c(2,2) is often sufficient to achieve a good graphical results for large (i.e. at least 100x100 nodes) OCNs.

Index of catchment to display (only effective if OCN$nOutlet > 1). It can be a logical, or a scalar within 1:length(OCN$nOutlet). If TRUE, the catchment with largest area is displayed. Note that, if the size of the chosen catchment is too small (e.g. OCN$CM$A[chooseCM] < 5*OCN$cellsize^2), an error might occur due to failure in triangulation.

If TRUE, add colorbar to the plot.

If TRUE, draw the OCN on top of the elevation field.

Threshold drainage area value used to display the network.

Color used to plot the river.

Minimum and maximum values of line width used to display the OCN (actual line width is proportional to the square root of drainage area).

Further parameters passed to function persp3d. The default value for aspect is c(OCN$dimX/sqrt(OCN$dimX*OCN$dimY, OCN$dimY/sqrt(OCN$dimX*OCN$dimY, 1)).

A river object as produced by create_OCN.

Threshold drainage area value used to display the network.

Color used to plot the river.

Logical. If TRUE, the whole network is displayed, and pixels with drainage area lower than thrADraw are displayed in light gray. If FALSE, only pixels with drainage area greater or equal to thrADraw are displayed. Default is FALSE if OCN$nNodes <= 40000, and TRUE otherwise. Note that setting easyDraw = FALSE for large networks might slow down the process considerably.

Minimum and maximum values of line width used to display the OCN (actual line width is proportional to the square root of drainage area).

Logical. If TRUE, add to an already existing plot. Taken as FALSE (with a warning if a different value is supplied) if no graphics device is open.

A river object as produced by aggregate_OCN.

Vector (of length OCN$SC$Nnodes expressing the spatial field of interest.

Logical. If TRUE, draw the OCN on top of the subcatchment map.

Color palette used. colPalette accepts both functions creating color palettes and vectors of colors. In the latter case, length(colPalette) must be greater than the number of color levels. If theme = NULL, default is c("#009900", "#FFFF00", "#FF9900", "#FF0000", "#FF00FF", "#9900CC", "#555555", "#BBBBBB"). Only the first n colors are used, where n is the number of different colors needed (calculated via a greedy coloring algorithm). colPalette accepts both functions creating color palettes and vectors of colors (see examples); in the latter case, the length of the vector cannot be lower than n (n cannot be predicted a priori, but generally 6 colors should suffice). If theme != NULL, default is colorRampPalette(c("yellow","red","black")).

Number of colors in the palette (only effective if theme is not null). colLevels must be a vector of the form c(minval, maxval) or c(minval, maxval, N_levels). The vector of breakpoints used to attribute theme values to a given color is then defined as seq(minval, maxval, N_levels). Default is minval = min(theme[!(is.nan(theme))]), maxval = max(theme[!(is.nan(theme))]), N_levels = 1000.

Color used to display the OCN (only effective if drawRiver = TRUE).

Logical. State if a legend should be displayed (only active if theme is not null.

Minimum and maximum values of line width used to display the OCN (actual line width is proportional to the square root of drainage area).

Logical. If TRUE, add to an already existing plot. Taken as FALSE (with a warning if a different value is supplied) if no graphics device is open.

Only effective if addLegend = TRUE. List of arguments passed to imagePlot for drawing a continuous legend. For example, argument smallplot can be used to specify the plot coordinates for the legend.

Further arguments to be passed to image. Default plot options are as in draw_thematic_OCN.

A river object as produced by aggregate_OCN. The order of arguments between OCN and theme can be swapped freely.

Vector (of length OCN$AG$Nnodes or OCN$RN$Nnodes) expressing the spatial field of interest. The vector can contain NA and NaN values to identify RN or AG nodes where the theme is not defined. The order of arguments between OCN and theme can be swapped freely.

Only effective if OCN$RN$nNodes == OCN$AG$nNodes. In such case, it must be equal to either "RN" or "AG"; as a result, theme will be interpreted as a spatial field in the corresponding aggregation level. Default is "AG".

Logical. If FALSE, a continuous color scheme is used. If TRUE, discrete color levels are applied. See also colLevels and examples.

Number of colors in the palette. If discreteLevels == FALSE, colLevels must be a vector of the form c(minval, maxval) or c(minval, maxval, N_levels). The vector of breakpoints used to attribute theme values to a given color is then defined as seq(minval, maxval, N_levels). Default is minval = min(theme[!(is.nan(theme))]), maxval = max(theme[!(is.nan(theme))]), N_levels = 1000. If discreteLevels == TRUE and is.null(colLevels) == TRUE, each unique value of theme is attributed a different color. If discreteLevels == TRUE and colLevels is a vector, colLevels is used as vector of breakpoints. In this case, the number of discrete colors is equal to length(colLevels) - 1.

Logical. If FALSE, nodes whose theme value is beyond the range established by the vector of breakpoints are attributed the color corresponding to the lowest (or highest) value in the color scheme. If TRUE, such nodes are attributed the color NaNcolor.

Color palette used to display theme values. colPalette accepts both functions creating color palettes and vectors of colors. In the latter case, length(colPalette) must be greater than the number of color levels. See examples below and hcl.colors.

Index of catchment to display (only effective if OCN$nOutlet > 1). It can be a logical or a numeric vector. If FALSE, all catchments are displayed. If TRUE, the catchment with largest area is displayed. If chooseCM is a subset of vector 1:length(OCN$nOutlet), only the catchment(s) identified by the indices in chooseCM are displayed.

Logical. If TRUE, the real shape of OCNs is plotted. If flow crosses a boundary, the pixel that is not contiguous to its outlet is flipped.

Logical. If FALSE, the theme is directly displayed on the river network. In this case, the edge departing from a given node is displayed with the color attributed to the node. If TRUE, the theme is displayed via markers at the locations of the nodes at the RN or AG level (depending on the length of theme). In this case, nanColor can be used to define the color of the river network.

Only effective if drawNodes == TRUE and length(theme) == OCN$RN$nNodes. Can assume values "upstream" or "downstream". If "upstream", nodes are drawn at the upstream ends of the corresponding edges (i.e. at the coordinates defined by OCN$AG$X, OCN$AG$Y). If "downstream", nodes are drawn at the downstream ends of the corresponding edges (i.e. at the coordinates defined by OCN$AG$XReach, OCN$AG$YReach).

Color attributed to RN or AG nodes whose theme value is NA or NaN.

Only effective if drawNodes == TRUE. Color used to display the OCN below the nodes.

Color used in the background of the figure. It can be either a single value, or a vector with number of components equal to length(chooseCM). If length(backgroundColor) == length(chooseCM), each color is used to identify a different catchment selected in chooseCM (corresponding to the respective outlet). If instead length(chooseCM) > 1 and length(backgroundColor) == 1, all catchments are colored with the same backgroundColor.

Logical. If TRUE, add legend to the plot. If also discreteLevels = FALSE, image.plot is used to display the legend, which appears as a colorbar; as a result, elements (e.g. node coordinates) subsequently plotted of on top of the 2D elevation map might be wrongly positioned.

Minimum and maximum values of line width used to display the OCN (actual line width is proportional to the square root of drainage area).

Logical. If TRUE, add to an already existing plot. Taken as FALSE (with a warning if a different value is supplied) if no graphics device is open.

Only effective if addLegend = TRUE and discreteLevels = FALSE. List of arguments passed to imagePlot for drawing a continuous legend. For example, argument smallplot can be used to specify the plot coordinates for the legend.

Only effective if addLegend = TRUE and discreteLevels = TRUE. List of arguments passed to legend for drawing a discrete legend.

Further arguments to be passed to plot.

A river object as produced by landscape_OCN

Vector of values of threshold drainage area (in squared planar units) for which the respective number of nodes at the RN and AG levels are computed. Note that it must be max(thrValues) <= min(OCN$CM$A), otherwise the catchment(s) with area lower than max(thrValues) degenerate to a network with zero nodes at the RN/AG level.

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.

If "Strahler", Strahler stream order is computed; if "Shreve", Shreve stream order is computed.

If 1, progress updates are printed in the console while the function is running. If 0, no updates are printed.

Copy of the input vector with the same name.

Vector (of the same length as thrValues) of number of nodes at the RN level resulting from the aggregation process with a threshold area values specified by thrValues.

Vector (of the same length as thrValues) of number of nodes at the AG level resulting from the aggregation process with a threshold area values specified by thrValues.

Vector (of the same length as thrValues) of values of drainage density of the river network resulting from the aggregation process with a threshold area values specified by thrValues. Drainage density is calculated as total length of the river network divided by area of the lattice. It is expressed in planar units^(-1).

Vector (of the same length as thrValues) of values of maximum stream order attained by the river network, resulting from the aggregation process with a threshold area values specified by thrValues.

A river object as produced by create_OCN.

slope of the outlet pixel (in elevation units/planar units).

Elevation of the lowest pixel (in elevation units).

If TRUE, when there are multiple catchments, minimize differences in elevation at the catchment borders by lifting catchments, while respecting zMin. If FALSE, all outlet pixels have elevation equal to zMin. This option is not effective for OCNs generated via create_general_contour_OCN.

Optimization method used by function optim (only used if optimizeDZ = TRUE).

List of control parameters used by function optim (only used if optimizeDZ = TRUE).

State if updates are printed on the console while landscape_OCN runs.

0

No update is given.

1

Concise updates are given.

2

More extensive updates are given (this might slow down the total function runtime).

Note that the display of updates during optimization of elevations (when optimizeDZ = TRUE) is controlled by parameter optimControl$trace.

Vector (of length OCN$FD$nNodes) of slope values (in elevation units/planar units) for each FD pixel, as derived by the slope/area relationship.

Vector (of length OCN$FD$nNodes) of pixel lengths. OCN$FD$leng[i] = OCN$FD$cellsize if flow direction in i is horizontal or vertical; OCN$FD$leng[i] = OCN$FD$cellsize*sqrt(2) if flow direction in i is diagonal.

Vector (of length OCN$FD$nNodes) with catchment index values for each FD pixel. Example: OCN$FD$toCM[i] = j if pixel i drains into the outlet whose location is defined by outletSide[j], outletPos[j].

When periodicBoundaries = TRUE, it is a vector (of length OCN$FD$nNodes) with real X coordinate of FD pixels. If periodicBoundaries = FALSE, it is equal to OCN$FD$X.

When periodicBoundaries = TRUE, it is a vector (of length OCN$FD$nNodes) with real Y coordinate of FD pixels. If periodicBoundaries = FALSE, it is equal to OCN$FD$Y.

Vector (of length OCN$FD$nNodes) of elevation values for each FD pixel. Values are calculated by consecutive implementation of the slope/area relationship along upstream paths.

Vector (of length OCN$nOutlet) with values of drainage area (in square planar units) for each of the catchments identified by the corresponding OCN$FD$outlet.

Adjacency matrix (OCN$nOutlet by OCN$nOutlet) at the catchment level. Two catchments 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.

List with number of objects equal to OCN$FD$nOutlet. Each object i is a list with X (Y) coordinates of the contour of catchment i for use in plots with exactDraw = FALSE (see functions draw_contour_OCN, draw_thematic_OCN). If catchment i is constituted by regions that are only connected through a diagonal flow direction, CM$XContour[[i]] (CM$Y_contour[[i]]) contains as many objects as the number of regions into which catchment i is split.

List with number of objects equal to OCN$FD$nOutlet. Each object i is a list with X (Y) coordinates of the contour of catchment i for use in plots with exactDraw = TRUE (see functions draw_contour_OCN, draw_thematic_OCN). If catchment i is constituted by regions that are only connected through a diagonal flow direction, CM$XContourDraw[[i]] (CM$YContourDraw[[i]]) contains as many objects as the number of regions into which catchment i is split.

List of output parameters produced by the optimization function optim (only present if optimizeDZ = TRUE).

A river object as produced by aggregate_OCN.

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

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.

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.

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

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.

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

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.

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.

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.

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.

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.

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.

A river object (or a numeric vector if y is a river).

A numeric vector to be displayed (or a river if x is a numeric vector). It is equivalent to theme in draw_subcatchments_OCN and draw_thematic_OCN. If y is specified, the river must have been aggregated. See details.

Optional argument. If type = "SC" or type = "subcatchments", draw_subcatchments_OCN is used (provided that the river object is aggregated); if type = "elev2D", draw_elev2D_OCN is used; if type = "contour", draw_contour_OCN is used (provided that the river object contains the CM field as produced by landscape_OCN or extract_river); alternatively, draw_thematic_OCN is used.

Arguments passed to the plotting functions draw_simple_OCN, draw_contour_OCN, draw_thematic_OCN. See details.

A river object as produced by aggregate_OCN.

Maximum river width allowed. If nOutlet = 1, it corresponds to the width at the outlet node.

Maximum river depth allowed. If nOutlet = 1, it corresponds to the depth at the outlet node.

Maximum water velocity allowed. If nOutlet = 1, it corresponds to the water velocity at the outlet node.

Exponents for the power law relationship between river width, depth, water velocity and contributing area. If none of expWidth, expDepth, expVelocity is specified by the user, the values expWidth = 0.5, expDepth = 0.4, expDepth = 0.1 proposed by Leopold and Maddock [1953] are used. It is possible to specify two out of these three exponents, provided that each of them lies in the range (0; 1) and their sum is lower than one. In this case, the missing exponent is calculated as the complement to one of the sum of the two values provided. If all three exponents are specified by the user, their sum must be equal to one.

Vector (of length OCN$RN$nNodes) of river width values for every RN node.

Vector (of length OCN$RN$nNodes) of river depth values for every RN node.

Vector (of length OCN$RN$nNodes) of water velocity values for every RN node.

Vector (of length OCN$AG$nNodes) of river width values for every AG node.

Vector (of length OCN$AG$nNodes) of river depth values for every AG node.

Vector (of length OCN$AG$nNodes) of water velocity values for every AG node.