2.1 Theoretical background

Let us consider a regular lattice made up of N cells, where each cell represents the generic node i of the network. Each node i is connected via a link to one of its nearest neighbors. The energy dissipation across the ith network link is proportional to , where Q_i is the landscape-forming discharge in the link (Rinaldo et al., 2014), and the corresponding elevation drop, with s_i identifying slope and L_i link length. By assuming (Rodriguez-Iturbe & Rinaldo, 2001), where A_i is the area drained by link i, and the slope–area relationship (Tarboton et al., 1989), the functional representing total energy expenditure across a landscape formed by N cells reads.

(1)

Note that link lengths do not appear in the above formula, as they can be considered constant with no loss of generality. The OCN configuration is defined by an adjacency matrix W whose corresponding set of drainage areas yields a local, dynamically accessible minimum of Equation (1). Note that the correspondence between A and the adjacency matrix W of a tree is subsumed by the relationship , where I _N is the identity matrix of order N, and 1 a N-dimensional vector of ones (Bertuzzo et al., 2015).

Minimization of Equation (1) is operated by means of a simulated annealing technique: starting from a feasible initial flow configuration (i.e., a spanning tree, see Figure 2a,e), a link at a time is rewired to one of its nearest neighbors; if the obtained configuration is a spanning tree, H is computed; the new configuration is accepted if it lowers total energy expenditure; if this is not the case, the new configuration can still be accepted with a probability controlled by the cooling schedule of the simulated annealing algorithm. Such myopic search, which only explores close configurations, actually mimics the type of optimization that nature performs, at least in fluvial landscapes (Rinaldo et al., 2014). Notably, restricting the search of a network yielding a minimum of Equation (1) to spanning, loopless configurations entails no approximation, because every spanning tree is a local minimum of total energy dissipation (Banavar, Colaiori, Flammini, Maritan, & Rinaldo, 2000). The shape of the so-obtained OCN retains the heritage of the initial flow configuration, although the extent to which this occurs is partly controlled by the cooling schedule adopted (Figure 2). This underpins the concept of feasible optimality, that is, the search for dynamically accessible configurations.

2.2 Overall setup of the package

The OCNet package consists of a series of functions that allow constructing river-analogue networks as well as calculating a number of metrics and descriptors commonly used in spatial ecology. The networks constructed by the package are built at several levels of aggregation. At each level, they are generally defined by a number of nodes, an adjacency matrix, a vector of contributing areas and two vectors with longitudinal and latitudinal coordinates of the nodes. The functions constituting the OCNet package are intended to be applied in sequential order, and the respective output can be directly used to visualize the created networks and linked to other commonly used R-packages.

The first function, create_OCN, only requires the longitudinal and latitudinal dimensions of the lattice as necessary inputs, while several other parameters can be optionally tuned to obtain customized results. Some examples are provided in the following section; extensive further information is given in the package documentation. The output of create_OCN is a list containing a sublist termed FD that, in turn, encloses key information on the topology of the network, among which the adjacency matrix (written in sparse form via the spam format (Furrer & Sain, 2010)) and a vector of contributing areas. The subsequent functions landscape_OCN (generation of the three-dimensional landscape derived from the network configuration), aggregate_OCN (aggregation of the OCN at various levels—see Aggregation levels), paths_OCN (evaluation of paths among network nodes, and lengths thereof), rivergeometry_OCN (hydraulic geometry of the river network, following Leopold and Maddock (1953)) require as necessary input the output list produced by the previous function, in the aforementioned order (except rivergeometry_OCN, which can be executed after aggregate_OCN). The output of these functions is a list where all objects of the input list are copied, and to which new objects are added. Note that output lists contain all input values, to avoid inconsistencies in the sequential application of functions. A group of functions (identified by the prefix “draw_”, see examples in Figure 3) are devoted to graphical representations of the OCN.

2.3 Aggregation levels

Before moving to the illustration of some possible applications of the package, we here clarify some concepts and terminology with respect to the aggregation of OCNs. Additional details are provided in the package documentation. Networks produced by the OCN algorithm can be used in a variety of fashions (see Table 1 for a review) by exploiting different connectivity metrics that are embedded in the OCN construct. At a first, nonaggregated level, each cell of the lattice (also termed as pixel) constitutes a node of the network (see Figure 4), and the connectivity among nodes is ruled by the flow direction pattern (represented by the adjacency matrix) obeying the OCN principle. This is here referred to as the flow direction level (FD).

As customary in hydrology when extracting a river network based on digital elevation models of the terrain (O'Callaghan & Mark, 1984), a threshold A_T on drainage area can be imposed to identify those pixels of the lattice that constitute nodes of the river network (RN, second level—see Terui et al. (2018) for an example of an ecological application of non-OCN synthetic networks akin to OCNs at the RN level). In a third, aggregated level (AG), nodes correspond to sources, confluences and outlet(s) of the river network identified at the RN level. The whole lattice is then partitioned into areas that directly drain into the nodes at the AG level, or the edges departing from them, thereby constituting the fourth, subcatchment level (SC).

A fifth level (catchment, CM) partitions the lattice into regions that are drained by different outlets, when the multiple-outlet option in create_OCN is enabled (see following section). Finally, in an optional, zero-level spatial structure, all lattice pixels are treated as nodes, but connectivity follows the Von Neumann (4 nearest neighbors, level N4) or Moore (8 nearest neighbors, level N8) neighborhoods, as in the green network described by Altermatt (2013). In this case, the OCN was used to generate a realistic elevation gradient governed by fluvial erosion, on which, for instance, the structure of terrestrial metapopulations can be studied (Bertuzzo et al., 2016; Giezendanner et al., 2019).

The final output of the OCNet functions is a list of lists, each of which named after the corresponding aggregation level (N4/N8, FD, RN, AG, SC, CM) and containing relevant topological and morphological information for that level. Variables may vary in number, type, and definition among the sublists, although the adjacency matrix is defined for all levels, while the drainage area vector is defined for all levels but N4/N8.

3.1 Number of outlets, boundary types, and elevational gradients

Although the OCN principle is primarily intended to be applied to networks spanning the whole drainage domain (where the area drained by the outlet is equal to the lattice area, see an example in Figure 3a–c), the generalization to the case of multiple networks—each of which subsumed by a different outlet—within the same lattice is straightforward. Indeed, the very same mathematical formulation presented in Theoretical background holds when multiple-outlet pixels are imposed. Technically, this is done by preventing these pixels to drain into their neighboring pixels. In this case, the sum of the areas drained by all outlet pixels is equal to the lattice area. In the package, the multiple-outlet option can be activated by means of the optional input nOutlet of function create_OCN. In the limiting case, all pixels at the lattice boundary can be treated as outlets (Bertuzzo et al., 2017; Sun, Meakin, & Jøssang, 1994). This is done by setting nOutlet = “All” in create_OCN. A graphical representation of an OCN obtained for the latter case is shown in Figure 3d.

When a pixel's flow direction is rewired during the search for an optimal network configuration, possible directions are generally those toward the eight neighboring pixels. This is not the case for the outlet pixels (which cannot be rewired) and the pixels at the lattice boundaries, which can be rewired to either three (corner pixels) or five (side pixels) neighboring cells. This latter assumption can be relaxed by allowing pixels at the boundary to drain into eight neighbors, by also considering pixels at the opposite sides as feasible directions. In OCNet, periodic boundaries can be enabled via the optional input periodicBoundaries of create_OCN. An example is shown in Figure 3g–i. Such option can be useful when the OCN lattice is to be considered as the periodic unit of an infinite landscape (Bertuzzo et al., 2016; Giezendanner et al., 2019), or when one aims at building OCNs spanning domains that are not lattice-shaped (see Figure 3f,i).

Once an OCN has been created by the simulated annealing algorithm, the iterative application of the slope–area relationship starting from the outlet node and moving in the upstream directions enables the derivation of the elevation field subsumed by the OCN (up to two constants, e.g., the elevation and slope of the outlet pixel). Some examples of elevational landscapes built on OCNs are provided in Figure 3b,e,h. Importantly, the slope–area relationship only holds for the channeled portion of the domain, which implies, strictly speaking, that the OCN must not be aggregated if one aims at making use of a three-dimensional landscape generated by an OCN. Moreover, the slope–area relationship is actually multiscaling (Tarboton et al., 1989), therefore the simple recursive application of (as performed by the function landscape_OCN) to yield an elevational landscape is to be considered as a first approximation, suitable for ecological applications. Methods to account for the scaling of the variance of the slope–area relationship exist (Grimaldi, Teles, & Bras, 2005), but are beyond the scope of this work.

3.2 Relationship between threshold drainage area and number of nodes

Owing to the somewhat heuristic procedure for the definition of an aggregated network based on a threshold drainage area value A_T, it is not possible to establish a priori how many nodes at the AG level correspond to a given A_T. This in fact depends on the configuration of the OCN at the FD level, which is the result of a stochastic process. This issue is particularly relevant when OCNs are used in experiments where practical reasons enforce a limitation on the number of nodes that can be handled, or when several OCN replicas with the same number of aggregated nodes are required.

To help overcome this issue, OCNet includes the function find_area_threshold_OCN, which requires as input a nonaggregated OCN (produced by landscape_OCN) and evaluates the number of nodes resulting from the aggregation procedure for different values of A_T. Such a function can therefore be used prior to aggregate_OCN to assess which threshold has to be used to obtain a network with the desired aggregation structure. Additionally, find_area_threshold_OCN also evaluates other variables that help characterize the network structure from a hydrological perspective, such as maximum stream order and drainage density. Maximum stream order can be of interest in some studies, when patch sizes need to be related to the structure of the underlying network but only few discrete dimensions are available, so that it is convenient to employ different patch sizes for different stream order values of the corresponding nodes (e.g., Harvey et al., 2018). Drainage density is relevant because it allows the assessment of hydrological characteristics of the aggregated OCN for a given metric resolution (i.e., the length in meters attributed to a pixel length—corresponding to the optional input cellsize of create_OCN), such as aridity and timing of the hydrologic response (Pallard, Castellarin, & Montanari, 2009).

Figure 5 shows results from the application of find_area_threshold_OCN to several OCNs built on large lattices. When A_T is lower than 2% of the lattice size, the number of nodes scales fairly well as a power law of the normalized threshold area (Figure 5a). This relationship allows qualitatively assessing the relevant range of A_T corresponding to a sought number of nodes at the AG level, which can be used as input in find_area_threshold_OCN to speed up its execution, especially for large networks. Scaling relationships with A_T are also found for maximum Strahler stream order (Figure 5b) and drainage density (Figure 5c). To provide an example, if a threshold A_T = 20 pixels is applied to a 200 × 200 OCN, the expected number of nodes at the AG level is 1,052.4, the expected maximum stream order is 5.56, and the expected drainage density is D_d = 0.1454 inverse planar units, which corresponds to a relatively wet catchment (D_d = 2.91/km) of area 100 km² (when 1 planar unit represents 50 m), or to a rather arid catchment (D_d = 1.46/km) of area 400 km² (if 1 planar unit is equal to 100 m). Notably, the relationship between drainage density and threshold area A_T mirrors the scaling behavior of drainage areas (Figure 5d), which is characterized by an exponent __ in the range [0.42;0.45] (see Introduction and Rinaldo et al. (2014)). Indeed, drainage density for a given A_T is roughly (i.e., if differences in lengths between vertical/horizontal and diagonal flow directions are neglected) equal to the number of pixels whose area is greater than or equal to A_T. Figure 5d also represents how the number of nodes at the RN level (N_RN) scales with varying A_T: to this end, it suffices to replace a with A_T and with .

The scaling behavior of OCNs displayed in Figure 5 can also provide useful information with respect to the choice of values of relevant parameters N and A_T that allow generating an OCN of adequate size for practical applications. To this extent, it is worthwhile to note that the OCN construct is invariant under coarse graining (Rinaldo et al., 2014; Rodriguez-Iturbe & Rinaldo, 2001), which means that the choice of the lattice dimension N does not affect the scaling of drainage areas. As in the example above, such choice should rather be based on geomorphological arguments, that is, the answers to the questions: What is the area that the OCN is supposed to drain? What are the expected values of maximum stream order and drainage density on this area? However, as a rule-of-thumb indication, we suggest to perform aggregation with a threshold not greater than , such that the obtained configuration is not affected by the finite-size scaling effect; this corresponds to an expected N_AG  ≥  30 (see Figure 5a).

3.3 Compatibility with existing R-packages

Specific functions of OCNet enable transformation of OCNs into objects that can be used by other commonly used R-packages in spatial ecology. In particular, compatibility with igraph (Csardi & Nepusz, 2006), a package for network analysis and visualization, is provided by function OCN_to_igraph. Moreover, function OCN_to_SSN transforms an OCN at a desired aggregation level into an object that can be read by SSN, a package on spatial statistical modeling and prediction for data on stream networks (Ver Hoef et al., 2014). Examples for these functions are shown in Figure 6. Finally, output from OCNet can be used in combination with R-packages for geostatistical modeling such as gstat (Pebesma, 2004), based on the coordinates of nodes of an OCN given at any aggregation level. Remarkably, adjacency matrices and other information can easily be extracted as base R objects, which guarantees compatibility with virtually every R-package and even other programming languages.

4.1 Generation of an OCN

Let us build an OCN with the following assumptions: it spans a 20 × 20 lattice, with a single outlet located close to the southwestern corner of the lattice, and each pixel represents a square of side 500 m (total size of the catchment is therefore 100 km²); the elevation, slope and channel width of the outlet node are 0 m a.s.l., 0.01, and 5 m, respectively; the threshold area used to aggregate the network is equal to 1.25 km². The code lines to build such network are the following:

set.seed(1) # use fixed random number generator.

OCN <- create_OCN(20, 20, outletPos = 3, cellsize = 500).

OCN <- landscape_OCN(OCN, slope0 = 0.01).

OCN <- aggregate_OCN(OCN, thrA = 1.25e6).

OCN <- paths_OCN(OCN, pathsRN = TRUE).

OCN <- rivergeometry_OCN(OCN, widthMax = 5).

The resulting OCN is shown in Figure 4.

4.2 Metapopulation model

Let us build a discrete-time, deterministic metapopulation model on the previously built OCN, according to the following assumptions: (a) the model is run on the OCN aggregated at the RN level (consisting of N_n nodes); (b) population growth at each node follows the Beverton-Holt model (Beverton & Holt, 1957), with baseline fecundity rate r = 1.05 constant for all nodes, and carrying capacity , where W_i is the river width of the network node i; (c) at each time step t, the number of individuals moving from node i is equal to , where g = 0.1 is a mobility rate constant for all nodes, and is the (expected) population size at node i and time t; (d) at each time step, individuals at node i can only move to a node that is directly connected to i, either downstream or upstream; (e) p_d and identify the probability to move downstream or upstream, respectively; (f) if the indegree of node i is larger than 1 (namely the node has multiple upstream connections), individuals moving upstream are split among the possible destination nodes into fractions Y_i proportional to their drainage areas; (g) as initial condition, all network nodes are uninhabited barring the node f that is farthest from the outlet (where ). The model equation hence reads.

where w_ij is a generic entry of the adjacency matrix W expressing OCN connectivity at the RN level; D_i (U_i) is equal to one if there is a downstream (upstream) connection available from node i and is null otherwise. Weights Y_i are defined as

where i′ is such that w_ii′ = 1, and A_i is the drainage area at node i.

We performed two model simulations to investigate the effect of parameters p_d, p_u on the time elapsed until the system reaches a steady state; in a first (default) run, no preferential direction of movement was assumed (p_d = p_u = 0.5); in the second run, a preference for downstream movement (p_d = 0.7, p_u = 0.3) was hypothesized. Results are shown in Figure 7. When p_d = 0.5, the invading species rapidly reaches the equilibrium in the initially occupied node, while colonization of the downstream patches is delayed. When a preference for downstream movement is attributed (p_d = 0.7), local population growth in the onset (green) node is slower, whereas invasion of the outlet node occurs faster, both in terms of initial growth and establishment of the equilibrium (see colored vertical lines in Figure 7a). Colonization of the headwater that is farthest from the onset node is also delayed with respect to the default case. As a result, when p_d = 0.7, the metapopulation size initially grows faster than when p_d = 0.5, due to fast invasion of the downstream nodes and growth of the local populations therein (see Figure 7b); in a second phase, the growth rate of the metapopulation is reduced, because invasion of the upstream nodes is hampered by the low p_u value, and the establishment of the equilibrium is delayed. As for the spatial spread of the metapopulation, when a preference for downstream movement is adopted, local population sizes at equilibrium tend to increase in the downstream nodes and decrease in the upstream nodes with respect to the default case (Figure 7a), resulting in a slightly lower overall metapopulation size at equilibrium (Figure 7b).