VignetteNetworkExt.Rmd

---
title: "How to use the NetworExtinction Package"
author: "Isidora Avila and Derek Corcoran"
date: "`r Sys.Date()`"
output: 
      html_document:
        fig_caption: yes
        toc: true
        toc_depth: 3 
        number_sections: true 
bibliography: biblio.bib

---
```{r setup, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
knitr::opts_chunk$set(fig.width=6, fig.height=4)
knitr::opts_chunk$set(cache = TRUE, message = FALSE, warning = FALSE)
```

#Introduction

The objectives of the *NetworkExtinction* package is to analyze and visualize the topology of food-webs and its responses to the simulated extinction of species.

The main indexes used for these analyzes are: 

1. Number of nodes: Total number of species in the network [@dunne2002food].

2. Number of links: Number of trophic relationships represented in the food web [@dunne2002food].

3. Connectance: Proportion of all possible trophic links that are completed [@dunne2002food].

4. Primary removals: It occurs when the researcher intentionally removes one species, simulating a single extinction.

5. Secondary extinctions: A secondary extinction occurs when a non-basal species loses all of its prey items due to the removal of another species. In this context, basal species can experience primary removal, but not secondary extinctions [@dunne2002food].

6. Total extinctions: The sum of primary removal and secondary extinctions in one simulation.

This package was built with a total of six functions. There are four functions to analyze the cascading effect of extinctions in a food-web, one function to plot the results of any of the extinction analysis, and another to analize the degree distribution in the network.

Functions to analyze the cascading effect of extinctions are the following:

* *Mostconnected:* To simulate extinctions from the most connected species to less connected in the network.

* *ExtinctionOrder:* To simulate extinctions in a customized order.  

* *RandomExtinctions:* To develop a null hypothesis by generating random orders of simulated extinctions.

* *CompareExtinctions:* To compare the observed secondary extinctions with the expected secondary extinction generated by random extinction.


The function to plot results is:

* *ExtinctionPlot:* To plot the results of any of the extinction functions

The function to analize the degree distribution is:

* *degree_distribution:* To test if the degrees in the network follow a power law, exponential, or truncated distribution.

## How to install the package

As any package in cran the *install.packages* function can be used to intall de *NetworkExtinction* package as shown in the following code.

```{r, eval=FALSE}
install.packages(NetworkExtinction)
library(NetworkExtinction)
```

## How to represent a food-web in R

The first step to make any analysis in the *NetworkExtinction* package is to build a representation of a food-web, using the network package [@butts2008network].

In order to create a network object you can start with a matrix or an edgelist object (for more details see the [network package vignette]((https://cran.r-project.org/web/packages/network/vignettes/networkVignette.pdf))).

As an example of how to build a food-web we will explain how to create the network shown in figure 1.

![Figure 1. Food-web to be contructed in R](toymodel_trophic-network5.jpg) 


This network has ten nodes where each node represents one species. Here, four nodes are basal species (primary producers, from sp.1 to sp.4), three nodes are intermediate (primary consumers, from sp.5 to sp.7), and the remaining three are top predators (from sp.8 to sp.10).

In order to build an interaction matrix (Figure 2) that represent the food-web, we create a square matrix with a column and a row representing each species. Columns represent the consumers and the rows the resources, where 1 represents a trophic interaction and 0 its absence. Note that in the columns, the first four species only have zeros because they are not consumers. For example, if we look at species 7, it feeds on species 4 and 3. In order to represent that, we would go to column 7 and put a 1 in rows 3 and 4.

![Figure 2. Matrix representation of the food-web](matrix.jpg)

The following code is an example of how to build the matrix in figure 2 using R:

```{r}
a<- matrix(c(0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 1, 0, 0),nrow=10, ncol=10)

a
```

Once the matrix is ready, we use the *as.network* function from the *network* package to build a network object.

```{r}
library(network)
net <- as.network(a, loops = TRUE)
net
```


# Functions

## 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, eval=FALSE}
library(NetworkExtinction)
data("net")
Mostconnected(Network = net)
```

```{r, echo=FALSE, message=FALSE}
library(NetworkExtinction)
data("net")
knitr::kable(Mostconnected(Network = net), caption = "Table 1: The resulting dataframe of the Mostconnected function")
```

The result of this function is 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, 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"}
data("net")
history <- Mostconnected(Network = net)
ExtinctionPlot(History = history, Variable = "AccSecondaryExtinction")

```


### 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.

```{r, eval=FALSE}
data("net")
ExtinctionOrder(Network = net, Order = c(2,4,7))
```

```{r, echo=FALSE}
data("net")
knitr::kable(ExtinctionOrder(Network = net, Order = c(2,4,7))$DF, caption = "Table 2: The resulting dataframe of the ExtinctionOrder function")
```

```{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. In this example species 2 is removed followed by 4 and lastly species 7 is removed"}
data("net")
ExtinctionOrder(Network = net, Order = c(2,4,7))$Graph
```

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 occured 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). 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)
RandomExtinctions(Network= net, nsim= 500)
```

```{r, echo = FALSE}
data(net)
set.seed(123)
Test <- RandomExtinctions(Network= net, nsim= 500)
knitr::kable(Test$sims, caption = "Table 3: The resulting dataframe of the RandomExtinctions function")
```

```{r, echo = FALSE, fig.cap= "Figure 5. The resulting graph of the RandomExtinctions function"}
data(net)
set.seed(123)
Test$graph
```

 
###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 *CompareExtinctins* function to compare both extinction histories.

```{r,message=FALSE, warning=FALSE}
data("net")
History <- ExtinctionOrder(Network = net, Order = c(1,2,3,4,5,6,7,8,9,10))

set.seed(2)
NullHyp <- RandomExtinctions(Network = net, nsim = 500)

Comparison <- CompareExtinctions(Nullmodel = NullHyp, Hypothesis = History)
```

The first 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. 

The second result will be a Test object which will show the goodness of fit statistics of the comparison. In this case, since the p value is `r round(Comparison$Test$p.value, 2)` which is larger than 0.05, we consider that the generated extinction history is significantly different than the null hypothesis.

```{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$graph
```


```{r, warning= FALSE}
Comparison$Test
```

## 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 ploted 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)
history <- Mostconnected(Network = net)
ExtinctionPlot(History = history)
```

```{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 = history, Variable = "LinksPerSpecies")

```


## Degree distribution function

The *degree_distribution* 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, power-law and truncated power-law distribution 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 and finally the Truncated power-law model.

```{r, eval=FALSE}
data("chilean_intertidal")
degree_distribution(chilean_intertidal, name = "Test")
```

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

```{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 [see @albert2002statistical, @dunne2002food, @estrada2007food, @de2013topological].

#Bibliography