Title: Generate Stochastic Branching Networks
Version: 1.0.0
Description: Generate Stochastic Branching Networks ('SBNs'). Used to model the branching structure of rivers.
License: MIT + file LICENSE
Encoding: UTF-8
RoxygenNote: 7.1.2
Imports: igraph, stats
URL: https://flee598.github.io/SBN/
NeedsCompilation: no
Packaged: 2022-01-17 05:02:54 UTC; flee598
Author: Finnbar Lee [aut, cre]
Maintainer: Finnbar Lee <lee.finnbar@gmail.com>
Repository: CRAN
Date/Publication: 2022-01-17 19:42:42 UTC

Change the upstream/downstream direction of an SBN

Description

Change the upstream/downstream direction of an SBN to either, reversed or undirected.

Usage

sbn_change_dir(g, method = c("rev", "undir"))

Arguments

g

a river network as an igraph object. Must be a downstream directed graph.

method

one of "rev" or "undir", determining what to convert the network to.

Value

A river network as an igraph object.

Examples

g <- sbn_create(10, 0.7)
sbn_change_dir(g, method = "rev")

Create SBNs

Description

An SBN river network as a downstream directed igraph object.

Usage

sbn_create(n, p)

Arguments

n

desired number of nodes.

p

branching probability, from 0 - 1. Passed to stats::rbinom(), the probability of success in two attempts at adding upstream branches.

Details

SBNs are generated using a stochastic branching process. The network generation process starts from an initial downstream node (the river mouth). At each iteration a random node in the network, with no upstream connections is selected, and zero, one or two nodes are added upstream of it, depending on a branching probability (p). This process is repeated until a pre-determined number of nodes across the entire network is attained (n).

Value

A river network as an igraph object.

Examples

sbn_create(10, 0.7)

Convert to a downstream directed network

Description

Convert an upstream directed or non-directed network to a downstream directed network.

Usage

sbn_down_dir(g, mouth)

Arguments

g

a river network as an igraph object.

mouth

river mouth vertex id.

Value

A downstream directed network.

Examples

g <- sbn_create(10, 0.7)

# to undirected
g <- sbn_change_dir(g, method = "undir")

# undirected to downstream directed
sbn_down_dir(g, mouth = 1)

Find all downstream nodes

Description

Find all nodes downstream of a given node.

Usage

sbn_get_downstream(g, node)

Arguments

g

a river network as an igraph object. Must be a downstream directed graph.

node

target node to get all downstream nodes of.

Value

a vector of downstream node id's.

Examples

g <- sbn_create(10, 0.7)
sbn_get_downstream(g, 10)

Find all headwater nodes

Description

Find all headwater nodes in a network.

Usage

sbn_get_hw(g)

Arguments

g

a river network as an igraph object. Must be a downstream directed graph.

Value

A vector of headwater node id's.

Examples

g <- sbn_create(10, 0.7)
sbn_get_hw(g)

Find river mouth node

Description

Find river mouth node from a directed graph.

Usage

sbn_get_outlet(g)

Arguments

g

a river network as an igraph object. Must be a downstream directed graph.

Value

An integer identifying the id of river mouth node.

Examples

g <- sbn_create(10, 0.7)
sbn_get_outlet(g)

Find all nodes upstream of a given node

Description

Find all nodes upstream of a given node.

Usage

sbn_get_upstream(g, node)

Arguments

g

a river network as an igraph object. Must be a downstream directed graph.

node

target node to get all upstream nodes of.

Value

A vector of upstream node id's.

Examples

g <- sbn_create(10, 0.7)
sbn_get_upstream(g, 2)

Get node strahler order

Description

Calculate the reach (node) Strahler for all nodes in a river network. The function will not work if any of the nodes in the network have more than two adjacent upstream reaches (e.g. some networks generated by the OCNet package).

Usage

sbn_strahler(g)

Arguments

g

a river network as an igraph object. Must be a downstream directed graph.

Value

a vector of stream Strahler orders.

Examples

g <- sbn_create(10, 0.7)
sbn_strahler(g)

Convert network to various adjacency/distance matrix formats

Description

Convert a downstream directed SBN to various adjacency or distance matrix formats.

Usage

sbn_to_mtx(
  g,
  method = c("dwn_mtx", "undir_mtx", "up_mtx", "n2n_dist_up", "n2n_dist_dwn",
    "n2n_dist_undir"),
  unconnected = Inf,
  weights = NULL
)

Arguments

g

a river network as an igraph object. Must be a downstream directed graph.

method

one of "dwn_mtx", an adjacency matrix for a downstream directed SBN, "up_mtx", an adjacency matrix for a upstream directed SBN, "undir_mtx", an adjacency matrix for a undirected SBN, "n2n_dist_up", "n2n_dist_dwn" or "n2n_dist_undir", an adjacency matrix of upstream, downstream or undirected node to node distances.

unconnected

when generating node-to-node distance matrices, what value should be used for unconnected elements. For example, in a downstream directed network, all upstream links are considered unconnected. Default value is Inf but other options are possible, such as NA or 0.

weights

passed to igraph::shortest.paths(). Possibly a numeric vector giving edge weights. If this is NULL and the graph has a weight edge attribute, then the attribute is used. If this is NA then no weights are used (even if the graph has a weight attribute).

Value

An adjacency or distance matrix.

Examples

g <- sbn_create(10, 0.7)
sbn_to_mtx(g, method = "dwn_mtx")