README.Rmd

---
output: github_document
bibliography: vignettes/biblio.bib
---

<!-- README.md is generated from README.Rmd. Please edit that file -->

<!-- badges: start -->

[![DOI](https://zenodo.org/badge/116978043.svg)](https://zenodo.org/badge/latestdoi/116978043)
[![codecov](https://codecov.io/gh/derek-corcoran-barrios/NetworkExtinction/branch/master/graph/badge.svg?token=BqPVAVQVBv)](https://codecov.io/gh/derek-corcoran-barrios/NetworkExtinction)
[![CRAN status](https://www.r-pkg.org/badges/version/NetworkExtinction)](https://CRAN.R-project.org/package=NetworkExtinction)
[![R-CMD-check](https://github.com/derek-corcoran-barrios/NetworkExtinction/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/derek-corcoran-barrios/NetworkExtinction/actions/workflows/R-CMD-check.yaml)
<!-- badges: end -->

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%",
  warning = FALSE,
  message = FALSE
)
```

# NetworkExtinction

# pkgdown <img src="pkgdown/favicon/apple-touch-icon-180x180.png" align="right" />



The goal of NetworkExtinction is to Simulate the extinction of species in the food web and to analyze its cascading effects, as described in Dunne et al. (2002) \doi{10.1073/pnas.192407699}

## Installation

You can install the released version of NetworkExtinction from [CRAN](https://CRAN.R-project.org) with:

``` r
install.packages("NetworkExtinction")
```

And the development version from [GitHub](https://github.com/) with:

``` r
# install.packages("devtools")
devtools::install_github("derek-corcoran-barrios/NetworkExtinction")
```

## Network Encoding

Within `NetworkExtinction`, ecological networks are recognized either as adjacency matrices or as `network` objects. Furthermore, `NetworkExtinction` functions support both binary (whether an interaction is present or not) as well as weighted (importance of an interaction for partners) network specifications. For the demonstration of the package in front of you, we use both types. 

To ensure your network representations work well with `NetworkExtinction` you should ensure that they match the structure of the following objects.

### Binary Networks

Binary networks simply denote whether two partners (i.e., nodes) interact with each other (link is present) or not (link is absent). Within a matrix, presence and absence are encoded as 1 and 0, respectively:

```{r}
set.seed(42)
bin_mat <- matrix(
  rbinom(n = 1e2, size = 1, prob = 0.5),
  ncol = 10, nrow = 10)
bin_mat
```

To express this network matrix as a `network` object, simply run:

```{r}
library(network)
bin_net <- as.network(bin_mat)
summary(bin_net)
```

### Weighted Networks

Weighted networks allow for quantification of relative importance of interactions to interaction partners. Thus, the network matrices of weighted networks are not bound to values of exactly 0 and 1, but rather to ranges:

```{r}
set.seed(42)
weight_mat <- matrix(
  round(
    runif(n = 1e2, min = 0, max = 1), 
    2),
  ncol = 10, nrow = 10)
weight_mat
```
To express these matrices as `network` objects ready for use with `NetworkExtinction` functions, run the following (this is what `NetworkExtinction` attempts when it detects a matrix input):

```{r}
weight_net <- as.network(weight_mat, matrix.type = "adjacency", 
                         ignore.eval = FALSE, names.eval = 'weight')
summary(weight_net)
```

**NOTE:** `NetworkExtinction` functions do not require `network` objects and can work just fine with matrix objects.

## Extinctions functions 

### Extinctions from most to less conected species in the network

The `Mostconnected()` function sorts the species from the most connected node to the least connected node, using total degree. Then, it removes the most connected node in the network, simulating its extinction, and recalculates the topological indexes of the network and counts how many species have indegree 0 (secondary extinction), not considering primary producers. Then, it removes the nodes that were secondarily extinct in the previous step and recalculates which node is the new most connected species. This step is repeated until the number of links in the network is zero [@sole2001complexity; @dunne2002food; @dunne2009cascading].

```{r mostconnected1, eval=FALSE}
library(NetworkExtinction)
data("net")
SimulateExtinctions(Network = net, Method = "Mostconnected")
```

```{r mostconnected2, echo=FALSE, results='hide', fig.keep='all', message = FALSE}
library(NetworkExtinction)
data("net")
knitr::kable(
  SimulateExtinctions(Network = net, Method = "Mostconnected")[[1]],
  caption = "Table 1: The resulting dataframe of the SimulateExtinctions in Mostconnected method")
```

The result of this function is a list which contains the dataframe shown in table 1. The first column called *Spp* indicates the order in which the species were removed simulating an extinction. The column *Secondary_extinctions* represents the numbers of species that become extinct given that they do not have any food items left in the food web, while the *AccSecondaryExtinction* column represents the accumulated secondary extinctions. (To plot the results, see function `ExtinctionPlot()`.)

```{r mostconnected3, fig.cap="Figure 3. The graph shows the number of accumulated secondary extinctions that occur when removing species from the most to the least connected species", results='hide', fig.keep='all', message = FALSE}
data("More_Connected")
history <- SimulateExtinctions(Network = net, Method = "Mostconnected")
ExtinctionPlot(History = history[[1]], Variable = "AccSecExt")
```

In addition, the list returned by `SimulateExtinctions()` also contains the final Network that remains after all primary extinctions have been finished:

```{r, echo=FALSE, results='hide', fig.keep='all', message = FALSE}
SimulateExtinctions(Network = net, Method = "Mostconnected")[[2]]
```


### Extinctions using a customized order

The `ExtinctionOrder()` function takes a network and extinguishes nodes using a customized order. Then, it calculates the topological network indexes and the secondary extinctions. In our toy network, nodes 1-4 are primary producers while nodes 9 and 10 represent apex predators. Let's see what happens when we sequentially remove all but the apex predators:

```{r, eval=FALSE}
data("net")
SimulateExtinctions(Network = net, Order = 1:8, Method = "Ordered")
```

```{r, echo=FALSE, results='hide', fig.keep='all', message = FALSE}
data("net")
knitr::kable(SimulateExtinctions(Network = net, Order = 1:8, Method = "Ordered"), caption = "Table 2: The resulting dataframe of the ExtinctionOrder function")
```

Already at the removal of node 5, we loose support for all other species in the network.

```{r, echo=FALSE, fig.cap= "Figure 4. The graph shows the number of accumulated secondary extinctions that occur when removing species in a custom order.", results='hide', fig.keep='all', message = FALSE}
data("net")
Order <- SimulateExtinctions(Network = net, Order = 1:8, Method = "Ordered")
ExtinctionPlot(History = Order[[1]], Variable = "AccSecExt")
```

The results of this function are a dataframe with the topological indexes of the network calculated from each extinction step (Table 2), and a plot that shows the number of accumulated secondary extinctions that occurred with each removed node (Figure 4).

### Random extinction

The `RandomExtinctions()` function generates n random extinction orders, determined by the argument `nsim`. The first result of this function is a dataframe (table 3). With the `SimNum` argument, you can control how many of the nodes in the network should be simulated to go extinct for each random extinction order. Here, we choose the same number as we set for our custom order example above.

The column *NumExt* represents the number of species removed, *AccSecondaryExtinction* is the average number of secondary extinctions for each species removed, and *SdAccSecondaryExtinction* is its standard deviation. The second result is a graph (figure 5), where the x axis is the number of species removed and the y axis is the number of accumulated secondary extinctions. The solid line is the average number of secondary extinctions for every simulated primary extinction, and the red area represents the mean $\pm$ the standard deviation of the simulations.

```{r, eval = FALSE}
data(net)
set.seed(707)
RandomExtinctions(Network= net, nsim= 100, SimNum = 8)
```

```{r, echo = FALSE, results='hide', fig.keep='all', message = FALSE}
data(net)
set.seed(707)
Test <- RandomExtinctions(Network= net, nsim= 100, SimNum = 8)
knitr::kable(Test[[1]], caption = "Table 3: The resulting dataframe of the RandomExtinctions function")
```

```{r, echo = FALSE, fig.cap= "Figure 5. The resulting graph of the RandomExtinctions function", results='hide', fig.keep='all', message = FALSE}
data(net)
set.seed(707)
Test <- RandomExtinctions(Network= net, nsim= 100, plot = TRUE, SimNum = 8)
```


### Comparison of Null hypothesis with other extinction histories

The `RandomExtinctons()` function generates a null hypothesis for us to compare it with either an extinction history generated by the `ExtinctionOrder()` function or the `Mostconnected()` function. In order to compare the expected extinctions developed by our null hypothesis with the observed extinction history, we developed the `CompareExtinctions()` function. The way to use this last function is to first create the extinction history and the null hypothesis, and then the `CompareExtinctions()` function to compare both extinction histories.

```{r,message=FALSE, warning=FALSE}
data("net")
Comparison <- CompareExtinctions(Nullmodel = Test, Hypothesis = Order)
```

The result will be a graph (Figue 6) with a dashed line showing the observed extinction history and a solid line showing the expected value of secondary extinctions randomly generated.

```{r, echo=FALSE, fig.cap= "Figure 6. The resulting graph of the CompareExtinctions function, where the dashed line shows the observed extinction history, and a solid line shows the expected value of secondary extinctions originated at random"}
Comparison
```

## Plotting the extinction histories of a network

The `ExtinctionPlot()` function takes a NetworkTopology class object and plots the index of interest after every extinction. By default, the function plots the number of accumulated secondary extinctions after every primary extinction (Figure 7), but any of the indexes can be plotted with the function by changing the Variable argument (Figure 8).

```{r, fig.cap= "Figure 7. Example of the use of the ExtinctionPlot function showing the accumulated secondary extinctions against number of extinctions"}
data(net)
ExtinctionPlot(History = Order[[1]])
```

```{r, fig.cap= "Figure 8. Another example of the use of the ExtinctionPlot function showing the number of links per species against number of extinctions"}
ExtinctionPlot(History = Order[[1]], Variable = "Link_density")
```


## Degree distribution function

The `DegreeDistribution()` function calculates the cumulative distribution of the number of links that each species in the food network has [@estrada2007food]. Then, the observed distribution is fitted to the exponential, and power law models.

The results of this function are shown in figure 9 and table 4. The graph shows the observed degree distribution in a log log scale fitting the three models mentioned above, for this example we use an example dataset of Chilean litoral rocky shores [@kefi2015network].
The table shows the fitted model information ordered by descending AIC, that is, the model in the first row is the most probable distribution, followed by the second an finally the third distribution in this case (Table 3), the Exponential distribution would be the best model, followed by the Power law model.

```{r, eval=FALSE}
data("chilean_intertidal")
DegreeDistribution(chilean_intertidal)
```

```{r, echo=FALSE}
data("chilean_intertidal")
Dist <- DegreeDistribution(chilean_intertidal)
```

```{r, echo = FALSE, fig.cap= "Figure 9: Fitted vs observed values of the degree distribution. The black line and points show the observed values, the red, green and blue lines show the fitted values for the Exponential, power law and trucated distribution, respectively"}
Dist$graph
```

```{r, echo = FALSE}
knitr::kable(Dist$models, caption = "Table 4: Model selection analysis")
```

The main objective of fitting the cumulative distribution of the degrees to those models, is to determine if the vulnerability of the network to the removal of the most connected species is related to their degree distribution. Networks that follow a power law distribution are very vulnerable to the removal of the most connected nodes, while networks that follow exponential degree distribution are less vulnerable to the removal of the most connected nodes [@albert2002statistical; @dunne2002food; @estrada2007food; @de2013topological].

# Inter-Network Dependendancy

By default, the functions in *NetworkExtinction* assume that, for a secondary extinction to happen, a node needs to loose all connections to its prey (if `NetworkType == "Trophic"`) or all other nodes (if `NetworkType == "Mutualistic"`). 

One may also want to assume that species are only capable of sustaining existence given a threshold of remaining interaction strengths. This is implemented with the `IS` argument, with which one can either set a global node-dependency on interaction strengths or, alternatively, define an `IS` value for each node in the supplied network.

As a minimal example, let's consider primary extinctions of two of the producers in our toy network not taking into account any interaction strength loss thresholds:
```{r, results='hide', fig.keep='all', message = FALSE}
IS_0 <- SimulateExtinctions(Network = net, Order = 1:2, Method = "Ordered")[[1]]
```

```{r, echo = FALSE}
knitr::kable(IS_0 , caption = "Table 5: The resulting dataframe of the basic version of SimulateExtinctions")
```

As you can see, with the base version of `SimulateExtinctions()`, we obtain two secondary extinctions.

Now, let's consider that all our species in `net` need to retain a minimum of 70% of interaction strength to not go extinct (rather than a 0% as is the default):
```{r, results='hide', fig.keep='all', message = FALSE}
IS_0.7 <- SimulateExtinctions(Network = net, Order = 1:2, Method = "Ordered", IS = 0.7)[[1]]
```

```{r, echo = FALSE}
knitr::kable(IS_0.7 , caption = "Table 6: The resulting dataframe of the interaction-strength loss version of SimulateExtinctions")
```
As you can see, this drastically changes how many secondary extinctions we estimate.


# Rewiring Potential

Ecological networks aren't static and we should assume that species may shift their connections in response to extinctions of an association/interaction partner. Rewiring processes can be simulated with *NetworkExtinction* using the `Rewiring`, `RewiringDist`, and `RewiringProb` arguments.

Let's start with `RewiringDist`. This should be a matrix that contains information about similarities or rewiring potential of species indexed by columns to those indexed by rows. The package comes with an example data set for this:
```{r}
data(dist)
dist
```

This is a random distance matrix. For the sake of this example, we assume that these values represent probabilities of rewiring. We have to tweak it a bit to make it useful for our toy example of a trophic network, we do so by setting some of the values to 0:

```{r}
dist[,1:4] <- 0 # producers don't worry about rewiring
dist[5:10,5:8] <- 0 # intermediate consumders can only rewire to producers
dist[c(1:4, 9:10), 9:10] <- 0 # apex predators can only rewire to intermediate consumers
dist
```

This matrix makes a lot more sense for our purposes. To clarify once more how to read this data: species 8 (column) has a $.663$ chance of rewiring to species 2 (row).

Next, `Rewiring` is a function argument that, just like the `IS` argument can be set globally or individually for each node. It is used to calculate probabilities of rewiring from the data in `RewiringDist`. Since we assume `RewiringDist` to already contain probabilities in this example, we simply set `RewiringDist` to return the data without changing it:

```{r}
RewiringDist <- function(x){x}
```

Lastly, `RewiringProb` is called upon to determine whether rewiring can happen among all potential rewiring partners. If no potential rewiring partner comes with a probability higher than this threshold, no rewiring happens. If multiple potential partners meet this threshold, rewiring happens only to the potential partner with the highest probability. Let's keep the default of 50% here.

Finally, let's out this all together with the `IS` example from above. Can we reduce the number of secondary extinctions when allowing for rewiring?

```{r, results='hide', fig.keep='all', message = FALSE}
Rewiring <- SimulateExtinctions(Network = net, Order = 1:2, Method = "Ordered", IS = 0.7,
                              Rewiring = function(x){x}, RewiringDist = dist, RewiringProb = 0.5)[[1]]
```

```{r, echo = FALSE}
knitr::kable(Rewiring , caption = "Table 7: The resulting dataframe of the rewiring version of SimulateExtinctions")
```

Indeed, this made it so we have one less secondary extinction at the second primary extinction!

# Bibliography