# Null models

Randomization of networks is mostly used to perform null hypothesis significance testing, or to draw random realizations of a probabilistic network. There are two ways to perform networks randomization: either by shuffling interactions within the networks while enforcing some constraints (`shuffle`

) or by drawing random samples from a probabilistic network (`rand`

).

## Draw a network from a probabilistic network

`Base.rand`

— Function`rand(N::ProbabilisticNetwork)`

Converts a probabilistic network into a deterministic one by performing random draws. All interactions are treated as independent Bernoulli events. Note that this network is *not* checked for degeneracy, *i.e.* species can end up with no interactions.

**References**

- Poisot, T., Cirtwill, A.R., Cazelles, K., Gravel, D., Fortin, M.-J., Stouffer, D.B., 2016. The structure of probabilistic networks. Methods in Ecology and Evolution 7, 303–312. https://doi.org/10.1111/2041-210X.12468

`rand(N::ProbabilisticNetwork, n::T) where {T<:Integer}`

Generates a number of random deterministic networks based on a probabilistic network.

**References**

- Poisot, T., Cirtwill, A.R., Cazelles, K., Gravel, D., Fortin, M.-J., Stouffer, D.B., 2016. The structure of probabilistic networks. Methods in Ecology and Evolution 7, 303–312. https://doi.org/10.1111/2041-210X.12468

`rand(N::ProbabilisticNetwork, S::Tuple{Int64,Int64})`

Generates a number of random deterministic networks based on a probabilistic network, and returns them as a matrix.

**References**

- Poisot, T., Cirtwill, A.R., Cazelles, K., Gravel, D., Fortin, M.-J., Stouffer, D.B., 2016. The structure of probabilistic networks. Methods in Ecology and Evolution 7, 303–312. https://doi.org/10.1111/2041-210X.12468

## Generate probabilistic networks from deterministic networks

These functions generate a probabilistic network from a deterministic network, where the probability of every interaction is determined by the degree distribution (or connectance) of the network.

`EcologicalNetworks.null1`

— Function`null1(N::BinaryNetwork)`

Given a network `N`

, `null1(N)`

returns a network with the same dimensions, where every interaction happens with a probability equal to the connectance of `N`

.

Note that this does not guarantee that the network is not degenerate, so the output of this analysis *should* be filtered using `is_degenerate`

, or passed to `simplify`

. The output of this approach is *always* a probabilistic network of the same partiteness as the original network.

**References**

Fortuna, M.A., Bascompte, J., 2006. Habitat loss and the structure of plantanimal mutualistic networks. Ecol. Lett. 9, 281–286. https://doi.org/10.1111/j.1461-0248.2005.00868.x

`EcologicalNetworks.null2`

— Function`null2(N::BinaryNetwork)`

Given a network `N`

, `null2(N)`

returns a network with the same dimensions, where every interaction happens with a probability equal to the degree of each species.

Note that this does not guarantee that the network is not degenerate, so the output of this analysis *should* be filtered using `is_degenerate`

, or passed to `simplify`

. The output of this approach is *always* a probabilistic network of the same partiteness as the original network.

**References**

Bascompte, J., Jordano, P., Melian, C.J., Olesen, J.M., 2003. The nested assembly of plant-animal mutualistic networks. PNAS 100, 9383–9387. https://doi.org/10.1073/pnas.1633576100

`EcologicalNetworks.null3`

— Function`null3(N::BinaryNetwork; dims::Integer=1)`

Given a network `N`

, `null3(N)`

returns a matrix with the same dimensions, where every interaction happens with a probability equal to the out-degree (`dims=1`

) or to the in-degree (`dims=2`

, number of predecessors) of each species, divided by the total number of possible predecessors/successors.

Note that this does not guarantee that the network is not degenerate, so the output of this analysis *should* be filtered using `is_degenerate`

, or passed to `simplify`

. The output of this approach is *always* a probabilistic network of the same partiteness as the original network.

**References**

Poisot, T., Stanko, M., Miklisová, D., Morand, S., 2013. Facultative and obligate parasite communities exhibit different network properties. Parasitology 140, 1340–1345. https://doi.org/10.1017/S0031182013000851

### Random Dot Product Graph model

The interaction probability in a Random Dot Product Graphs model are given by the dot product of species representations in two metric spaces of a given dimension (one describing species as consumers, one as producers – or predators and preys).

`EcologicalNetworks.RDPG`

— Function`RDPG(N::BinaryNetwork; rank::Integer=3)`

Given a binary network `N`

, `RDPG(N)`

returns a probabilistic network with the same number of species, where every interaction happens with a probability equal to the dot product of species representation in the network `N`

's RDPG space of rank `rank`

.

Because the pairwise dot product obtained by the matrix multiplication of the two spaces `Left * Right`

are not granted to be bounded between 0 and 1 (for numerical and theoric reasons), we bound the entries to be in the `[0,1]`

range.

**References**

Dalla Riva, G.V. and Stouffer, D.B., 2016. Exploring the evolutionary signature of food webs' backbones using functional traits. Oikos, 125(4), pp.446-456. https://doi.org/10.1111/oik.02305

The Random Dot Product Graph spaces are computed via a truncated Singular Value Decomposition of the food web adjacency matrix.

Missing docstring for `svd_truncated`

. Check Documenter's build log for details.

## Shuffle interactions

`Random.shuffle!`

— Function`shuffle!(N::BinaryNetwork; constraint::Symbol=:degree)`

Shuffles interactions inside a network (the network is *modified*), under the following `constraint`

:

- :degree, which keeps the degree distribution intact
- :generality, which keeps the out-degree distribution intact
- :vulnerability, which keeps the in-degree distribution intact
- :fill, which moves interactions around freely

The function will take two interactions, and swap the species establishing them. By repeating the process a large enough number of times, the resulting network should be relatively random. Note that this function will conserve the degree (when appropriate under the selected constraint) of *every* species. Calling the function will perform **a single** shuffle. If you want to repeat the shuffling a large enough number of times, you can use something like:

`[shuffle!(n) for i in 1:10_000]`

If the keyword arguments are invalid, the function will throw an `ArgumentError`

.

**References**

- Fortuna, M.A., Stouffer, D.B., Olesen, J.M., Jordano, P., Mouillot, D., Krasnov, B.R., Poulin, R., Bascompte, J., 2010. Nestedness versus modularity in ecological networks: two sides of the same coin? Journal of Animal Ecology 78, 811–817. https://doi.org/10.1111/j.1365-2656.2010.01688.x

`Random.shuffle`

— Function`shuffle(N::BinaryNetwork; constraint::Symbol=:degree)`

Return a shuffled copy of the network (the original network is not modified). See `shuffle!`

for a documentation of the keyword arguments.

**References**

- Fortuna, M.A., Stouffer, D.B., Olesen, J.M., Jordano, P., Mouillot, D., Krasnov, B.R., Poulin, R., Bascompte, J., 2010. Nestedness versus modularity in ecological networks: two sides of the same coin? Journal of Animal Ecology 78, 811–817. https://doi.org/10.1111/j.1365-2656.2010.01688.x