Title: Using Block Model to Estimate the Robustness of Ecological Network
Version: 0.2.4
Description: Implementation of a variety of methods to compute the robustness of ecological interaction networks with binary interactions as described in <doi:10.1002/env.2709>. In particular, using the Stochastic Block Model and its bipartite counterpart, the Latent Block Model to put a parametric model on the network, allows the comparison of the robustness of networks differing in species richness and number of interactions. It also deals with networks that are partially sampled and/or with missing values.
License: GPL-3
URL: https://github.com/Chabert-Liddell/robber
BugReports: https://github.com/Chabert-Liddell/robber/issues
Depends: R (≥ 3.5)
Imports: blockmodels (≥ 1.1.2), ggplot2, GREMLINS, igraph, magrittr, pammtools, partitions, purrr, stats
Suggests: dplyr, forcats, knitr, patchwork, pbmcapply, RColorBrewer, rmarkdown, spelling, testthat, tibble, tidyr
VignetteBuilder: knitr
Encoding: UTF-8
Language: en-US
LazyData: true
RoxygenNote: 7.2.3
NeedsCompilation: no
Packaged: 2024-02-07 13:32:31 UTC; saint-clair
Author: Saint-Clair Chabert-Liddell ORCID iD [aut, cre]
Maintainer: Saint-Clair Chabert-Liddell <academic@chabert-liddell.com>
Repository: CRAN
Date/Publication: 2024-02-07 13:50:02 UTC

Pipe operator

Description

See magrittr::%>% for details.

Usage

lhs %>% rhs

Fast computation of the LBM robustness statistic for uniform extinctions

Description

This function provides much faster computation than robustness_lbm for the case where ext_seq = "uniform", when just the AUC statistic is needed and the robustness function is not needed. This is particularly useful if nr gets large.

Usage

auc_robustness_lbm(con, pi, rho, nr, nc)

Arguments

con

A matrix, the connectivity parameter

pi

A vector of length nrow(con), the proportion of row blocks

rho

A vector of length ncol(con), the proportion of column blocks

nr

An integer, the number of row (primary) species

nc

An integer, the number of column (secondary) species

Value

The AUC of the LBM Robustness function for uniform primary extinctions sequences.

Examples

con <- matrix(c(.5,.3,.3,.1), 2, 2)
pi  <- c(.25,.75)
rho <- c(1/3, 2/3)
nr <- 50
nc <- 30
auc_robustness_lbm(con, pi, rho, nr, nc)

Compare the robustness for different LBM parameters

Description

This function is designed to be used with a list of parameters as the one given by the function get_lbm_param(). The default parameters are designed such that the return value for a uniform extinction sequence is bounded above by 0.5.

Usage

compare_robustness(
  list_param,
  dens = 0.0156,
  new_nr = 100,
  new_nc = 100,
  ext_seq = "uniform"
)

Arguments

list_param

A list of list of LBM parameters, each list must contain at list con, pi and rho entries, such as the one returned by the function get_lbm_param(). The size of the network is optional.

dens

The density (connectance) used to compare the network. The com parameters of list_param will be normalized so that the average probability of interaction in the network is equal to dens. Default to 0.0156.

new_nr

The number of rows of the normalized networks. Default to 100.

new_nc

The number of columns of the normalized networks. Default to 100.

ext_seq

The distribution of the primary extinction sequence used to compare the networks. One of c("uniform", "decreasing", "increasing"). Default to "uniform".

Value

A list of the sames length as list_param, the robustness (AUC) after normalization for all set of parameters.

Examples

par1 <- list(con = matrix(c(.5,.3,.3,.1), 2, 2),
             pi  = c(.25,.75),
             rho = c(1/3, 2/3))
par2 <- list(con = matrix(c(.4,.1,.1,.4), 2, 2),
             pi  = c(.25,.75),
             rho = c(1/2, 1/2))
compare_robustness(list_param = list(par1, par2), ext_seq = "decreasing")
compare_robustness(list_param = list(par1, par2), ext_seq = "increasing")

Estimate the parameters of a LBM

Description

Estimate the parameters of a LBM

Usage

get_lbm_param(A, model_size = NULL, ...)

Arguments

A

A matrix, the incident matrix of the network

model_size

A vector of size 2, the size of the model parameters. If NULL, the default, model will be chosen as the one with the highest ICL criterion among all fitted models during the inference.

...

Additional arguments pass to the inference function of package GREMLIN if there are missing value and blockmodels if none.

Value

A list of the LBM parameters. The list is set

Examples

# When the size of the model is unknown:
data("seeddispersal")
param <- get_lbm_param(seeddispersal, ncores = 1L)
do.call(auc_robustness_lbm, param)

# For a fixed number of blocks (useful for comparison)
param <- get_lbm_param(seeddispersal, model_size = c(1, 3), ncores = 1L)
do.call(auc_robustness_lbm, param)

# For data with missing observations

A <- seeddispersal
A[sample(seq_len(nrow(A)), 5),
  sample(seq_len(ncol(A)), 10)] <- NA
param <- get_lbm_param(A, nbCores = 1L)
do.call(auc_robustness_lbm, param)

A binarized host-parasite network

Description

Locality: Tomsk-Tumen Reference:Hadfield JD, Krasnov BR, Poulin R, Shinichi N (2013) A tale of two phylogenies: comparative analyses of ecological interactions. The American Naturalist 183(2): 174-187

Usage

hostparasite

Format

A matrix of binary entries with 27 rows and 26 columns

Source

https://www.web-of-life.es/

https://datadryad.org/stash/dataset/doi:10.5061/dryad.jf3tj

Plot function pour robber class

Description

Plot function pour robber class

Usage

## S3 method for class 'robber'
plot(x, type = "function", add = FALSE, ...)

Arguments

x

An object of class robber

type

Type of the plot, just function

add

Whether it should be added to a previous ggplot

...

lty, col, ... to be passed to geom_step() in ggplot2

Value

A ggplot2 object

Examples

data("hostparasite", package = "robber")
rob <- robustness_emp(hostparasite)
plot(rob)

A plant-pollinator network

Description

Locality: Tenerife, Canary Islands Stald L (2003). Struktur og dynamik i rum og tid af et bestøvningsnetværk på Tenerife, De Kanariske Øer. Msc thesis (Univ of Aarhus, Aarhus, Denmark)

Usage

pollination

Format

A matrix of binary entries with 17 rows and 51 columns

Source

https://www.web-of-life.es/

Empirical Robustness of a Network

Description

Compute the robustness of an ecological network by averaging over a great number of randomly generated primary extinctions sequences

Usage

robustness_emp(
  A,
  ext_seq = "uniform",
  nb_iter = 300,
  net_type = "bipartite",
  method = "ordered",
  power = 1,
  block = NULL
)

Arguments

A

A binary incident matrix

ext_seq

A string, the rule for the primary extinctions sequences, one of "uniform", the default for uniform extinctions sequences, "decreasing" and "increasing" for primary extinctions sequences by increasing and decreasing degree order sequence on the row species

nb_iter

An integer, the number of generated sequences. Default to 300.

net_type

A string, the type of network. For now, only "bipartite" is available.

method

A string used when ext_seq = "decreasing" or ext_seq = "increasing":

  • "linear" (default) set an extinction probability for each row species that is linear in its degree. It is a shortcut for method = "power" and power = 1.

  • "ordered" strictly follow the degree order, i.e. the most connected species will always goes last for ext_seq = "increasing" or first for ext_seq = "decreasing".

power

An integer (default to 1). Only used when method = "power", the power to which the degree are elevated to compute the primary extinctions sequences for "increasing" and "decreasing" ext_seq. For 1, it is equivalent to method = "linear", for 0, it is the same as ext_seq = "uniform". The largest the number the closest it will be to method = "ordered".

block

A vector of row species memberships for method = "block"

Value

A list (robber object) with the following fields:

Examples

A <- matrix(c(1, 0, 0,
             0, 1, 0,
             0, 0, 1,
             1, 1, 1), nrow = 4, ncol = 3, byrow = TRUE)
my_rob <- robustness_emp(A, ext_seq = "increasing")
my_rob$fun
my_rob$auc

Robustness for LBM

Description

Compute the robustness for a given set of Latent Block Model parameters.

Usage

robustness_lbm(
  con = NULL,
  pi = NULL,
  rho = NULL,
  nr = NULL,
  nc = NULL,
  ext_seq = "uniform",
  method = "exact",
  approx_threshold = 10000,
  net = NULL,
  ...
)

Arguments

con

A matrix, the connectivity parameter

pi

A vector of length nrow(con), the proportion of row blocks

rho

A vector of length ncol(con), the proportion of column blocks

nr

An integer, the number of row (primary) species

nc

An integer, the number of column (secondary) species

ext_seq

A string, the rule for the primary extinctions sequences, one of:

  • "uniform", the default for uniform extinctions sequences,

  • "decreasing" and "increasing" for primary extinctions sequences by increasing and decreasing row blocks connection probability,

  • "natural" primary extinctions sequences with the block ordering given in the function parameter.

  • "blocks" primary extinctions sequences for all blocks permutation.

method

A string, the method used to compute the robustness by block. One of:

  • "exact" (the default), average on all possible networks

  • "no_empty_block" restricts the networks space to the ones with no empty block of primary species

  • "expected" restricts the networks space to the ones that have approximately the same number of species per block than the expected one. Do not do anything for ext_seq = "uniform".

approx_threshold

A numeric, the maximum size of the possible block partition allowed for exact robustness by block calculation. Higher threshold gives more precise results at the cost of computation times and possibly memory problem. Do not do anything for ext_seq = "uniform". When the threshold is exceeded the robustness is computed by a Monte Carlo approximation with approx_threshold number of samples.

net

A network, if given, the function will fit a LBM to obtain the parameters of the network and then compute the robustness.

...

Option to be passed to get_lbm_param function.

Value

A list and a robber type object:

Examples

con <- matrix(c(.5,.3,.3,.1), 2, 2)
pi  <- c(.25,.75)
rho <- c(1/3, 2/3)
nr <- 50
nc <- 30
my_rob <- robustness_lbm(con, pi, rho, nr, nc, ext_seq = "natural")
my_rob$fun
my_rob$auc
# A easier alternative way, if you don't know the parameters of the network:
data(hostparasite)
(robustness_lbm(net = hostparasite, ncores = 1L))

A seed-dispersal network

Description

Locality: North Negros Forest Reserve, Central Philippi Hammann, A. & Curio, B. (1999) Interactions among frugivores and fleshy fruit trees in a Philippine submontane rainforest.

Usage

seeddispersal

Format

A matrix of binary entries with 36 rows and 19 columns

Source

https://www.web-of-life.es/

https://conbio.org/publications/conservation-biology

Simulate a bipartite interaction network using block model

Description

Simulate a bipartite interaction network using block model

Usage

simulate_lbm(con, pi, rho, nr, nc, method = "gnp")

Arguments

con

A matrix, the connectivity between blocks. If method = "gnp" then each entry is the probability of interactions given 2 blocks. If method = "gnm" then each entry is the number of interactions between 2 blocks.

pi

A vector of the same length as nrow(con), the block mixture for the row species. If method = "gnp", then pi is a probability vector, if method = "gnm", then pi is the number of species per block, must sum to nr.

rho

A vector of the same length as ncol(con), the block mixture for the column species. If method = "gnm", then rho is a probability vector, if method = "gnm", then rho is the number of species per block, must sum to nc.

nr

The number of row Species

nc

The number of column Species

method

One of "gnp" (the default) where the blocks size and number of interactions is random and "gnm" where the blocks size and number of interactions are fixed.

Value

A list of 3 elements:

Examples

# For a random number of interactions and blocks sizes
con <- matrix(c(.5,.3,.3,.1), 2, 2)
pi  <- c(.25,.75)
rho <- c(1/3, 2/3)
nr <- 50
nc <- 30
simulate_lbm(con, pi, rho, nr, nc, method = "gnp")

# For a fixed number of ineractions and blocks sizes
con <- matrix(c(50, 120, 60, 80), 2, 2)
pi  <- c(10, 40)
rho <- c(10, 20)
nr <- 50
nc <- 30
simulate_lbm(con, pi, rho, nr, nc, method = "gnm")

Compute the Conditional variance of the AUC of the LBM Robustness

Description

Compute the Conditional variance of the AUC of the LBM Robustness

Usage

var_auc_unif_lbm(con, pi, rho, nr, nc)

Arguments

con

A matrix, the connectivity parameter

pi

A vector of length nrow(con), the proportion of row blocks

rho

A vector of length ncol(con), the proportion of column blocks

nr

An integer, the number of row (primary) species

nc

An integer, the number of column (secondary) species

Value

A numeric, the variance

Examples

con <- matrix(c(.5,.3,.3,.1), 2, 2)
pi  <- c(.25,.75)
rho <- c(1/3, 2/3)
nr <- 50
nc <- 30
var_auc_unif_lbm(con, pi, rho, nr, nc)

Compute the Conditional variance of the LBM Robustness term by term

Description

Compute the Conditional variance of the LBM Robustness term by term

Usage

var_fun_unif_lbm(con, pi, rho, nr, nc)

Arguments

con

A matrix, the connectivity parameter

pi

A vector of length nrow(con), the proportion of row blocks

rho

A vector of length ncol(con), the proportion of column blocks

nr

An integer, the number of row (primary) species

nc

An integer, the number of column (secondary) species

Value

A vector, the variance after m extinctions

Examples

con <- matrix(c(.5,.3,.3,.1), 2, 2)
pi  <- c(.25,.75)
rho <- c(1/3, 2/3)
nr <- 50
nc <- 30
var_fun_unif_lbm(con, pi, rho, nr, nc)