In flee598/SBN: Generate Stochastic Branching Networks

knitr::opts_chunk$set(
  dpi = 500,
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  warning = FALSE,
  message = FALSE 
)

SBN

The purpose of this package is to generate Stochastic Branching Networks (SBNs), which are frequently used to represent the branching structure of rivers in ecological models. The functions in this package rely heavily on the igraph package.

See the help page for additional details.

The fundamental unit of the SBN package is a downstream directed igraph object. The package contains functions for generating and manipulating these networks. The functions should also work on river networks generated in other packages, which have subsequently been converted to igraph objects (e.g. OCNs).

Aside from downstream directed networks upstream directed and undirected networks can be generated.

# Illustration of plotting an SBN using ggraph

library(SBN)
library(igraph)    # for layout_as_tree
library(ggraph)    # for ggplot2 style plotting
library(patchwork) # for combining plots

# generate an SBN
g <- sbn_create(10, 0.7)

# Downstream directed graph --------------------------------------------------

# reverse to upstream directed graph - works
g_rev <- sbn_change_dir(g, method = "rev")

# define layout
l <- igraph::layout_as_tree(g_rev, flip.y = FALSE)

p1 <- ggraph(g_rev, l) +
  geom_node_point(size = 5) +
  geom_edge_link(arrow = arrow(length = unit(4, 'mm'), ends = "first"),
                 end_cap = circle(4, 'mm'),
                 start_cap = circle(4, 'mm')) +
  theme_void()  +
  labs(title = "Downstream")

# Upstream directed graph --------------------------------------------------

p2 <- ggraph(g_rev, l) +
  geom_node_point(size = 5) +
  geom_edge_link(arrow = arrow(length = unit(4, 'mm'), ends = "last"),
                 end_cap = circle(4, 'mm'),
                 start_cap = circle(4, 'mm')) +
  theme_void() +
  labs(title = "Upstream")


# undirected graph --------------------------------------------------
p3 <- ggraph(g_rev, layout = l) +
  geom_node_point(size = 5) +
  geom_edge_link() +
  theme_void() +
  labs(title = "Undirected")

p1 + p2 + p3

Installation

SBN is available on CRAN

install.packages("SBN")

Or to install the latest development version

devtools::install_github("flee598/SBN")

Generatting SBNs

library(SBN)
# generate an SBN with 10 nodes and a branching probability of 0.7
g <- sbn_create(10, 0.7)
g

# plotting the above network
library(igraph)    # for layout_as_tree
library(ggraph)    # for ggplot2 style plotting

# reverse to upstream diected graph - works
g_rev <- sbn_change_dir(g, method = "rev")

V(g)$name <- 1:gorder(g)

# define layout
l <- igraph::layout_as_tree(g_rev, flip.y = FALSE)

ggraph(g_rev, l) +
  geom_node_point(size = 5) +
  geom_edge_link(arrow = arrow(length = unit(4, 'mm'), ends = "first"),
                 end_cap = circle(4, 'mm'),
                 start_cap = circle(4, 'mm')) +
  geom_node_label(aes(label = name)) +
  theme_void()

Basic manipulation

The SBN package has a handful of functions for basic manipulation of networks.

# identify all headwater nodes
sbn_get_hw(g)

# get all nodes downstream of node 10
sbn_get_downstream(g, 10)

# get all nodes upstream of node 2
sbn_get_upstream(g, 2)

# get the id of the outlet node
sbn_get_outlet(g)

# get the node-to-node distance of an undirected network
sbn_to_mtx(g, method = "n2n_dist_undir")

# downstream directed network to upstream directed network
sbn_change_dir(g, method = "rev")

Calculating Strahler order

Calculate the Strahler order of nodes in a network.

# Strahler order
sbn_strahler(g)

A note on plotting SBNs

For quick plotting I have generally used ggraph with the tree layout. As far as I can tell, the tree algorithm doesn't play nice with a downstream directed network, and therefore for plotting purposes you need to reverse the network to an upstream directed one and it works fine. It is a bit fiddly, but I haven't found any simple "out-of-the-box" alternative as of yet. Another option is to generate your own node coordinates (as OCNet does), but I haven't gotten around to implementing that.

# Illustration of plotting an SBN using ggraph

library(SBN)
library(igraph)  # for layout_as_tree
library(ggraph)  # for ggplot2 style plotting

# generate an SBN
g <- sbn_create(10, 0.7)

# Attempt 1 ------------------------------------------------
# no layout defined - doesn't work
ggraph(g) +
  geom_node_point(size = 5) +
  geom_edge_link() +
  theme_graph()

# Attempt 2 ------------------------------------------------
# try using layout_as_tree layout - doesn't work
l <- igraph::layout_as_tree(g, flip.y = FALSE)

ggraph(g, layout = l) +
  geom_node_point(size = 5) +
  geom_edge_link() +
  theme_graph()

# Attempt 3 ------------------------------------------------
# reverse to upstream directed graph - works
g_rev <- sbn_change_dir(g, method = "rev")

# define layout
l <- igraph::layout_as_tree(g_rev, flip.y = FALSE)

# plot
ggraph(g_rev, layout = l) +
  geom_node_point(size = 5) +
  geom_edge_link() +
  theme_graph()

# Attempt 4 ------------------------------------------------
# add downstream arrows - doesn't really serve any purpose..
ggraph(g_rev, l) +
  geom_node_point(size = 5) +
  geom_edge_link(arrow = arrow(length = unit(4, 'mm'), ends = "first"),
                 end_cap = circle(4, 'mm'),
                 start_cap = circle(4, 'mm')) +
  theme_graph()