`EcologicalNetworks.BinaryNetwork`

— TypeThis is a union type for both Bipartite and Unipartite deterministic networks. All networks from these class have adjacency matrices represented as arrays of Boolean values.

`EcologicalNetworks.DeterministicNetwork`

— TypeAll non-probabilistic networks

`EcologicalNetworks.ProbabilisticNetwork`

— TypeThis is a union type for both Bipartite and Unipartite probabilistic networks. Probabilistic networks are represented as arrays of floating point values ∈ [0;1].

`EcologicalNetworks.QuantitativeNetwork`

— TypeThis is a union type for both unipartite and bipartite quantitative networks. All networks of this type have adjancency matrices as two-dimensional arrays of numbers.

`EcologicalNetworks.AbstractBipartiteNetwork`

— TypeThis abstract type groups all bipartite networks, regardless of the type of information. Bipartite networks have *two* fields for species, named `T`

(for top, corresponding to matrix *rows*), and `B`

(for bottom, matrix *columns*).

Any bipartite network can be declared (we'll use the example of a binary network) either using `BipartiteNetwork(A, T, B)`

(assuming `A`

is a matrix of interactions and `T`

and `B`

are vectors of species names for the top and bottom level), or `BipartiteNetwork(A)`

, in which case the species will be named automatically.

`EcologicalNetworks.AbstractEcologicalNetwork`

— TypeAll networks in the package belong to the `AbstractEcologicalNetwork`

type. They all have a field `A`

to represent interactions as a *matrix*, and a number of fields for species. See the documentation for `AbstractBipartiteNetwork`

and `AbstractUnipartiteNetwork`

, as well as `AllowedSpeciesTypes`

for the allowed types for species.

Note that *all* species in a network (including both levels of a bipartite network) *must* have the same type. For example, `["a", :b, "c"]`

is not a valid array of species, as not all its elements have the same type.

`EcologicalNetworks.AbstractUnipartiteNetwork`

— TypeThis abstract type groups all unipartite networks, regardless of the type of information. Unipartite networks have *a single* field for species, named `S`

, which has the same number of elements as the size of the matrix.

Any unipartite network can be declared (we'll use the example of a binary network) either using `UnipartiteNetwork(A, S)`

(assuming `A`

is a matrix of interactions and `S`

is a vector of species names), or `UnipartiteNetwork(A)`

, in which case the species will be named automatically.

`EcologicalNetworks.BipartiteNetwork`

— TypeA bipartite deterministic network is a matrix of boolean values.

`EcologicalNetworks.BipartiteProbabilisticNetwork`

— TypeA bipartite probabilistic network is a matrix of floating point numbers, all of which must be between 0 and 1.

`EcologicalNetworks.BipartiteQuantitativeNetwork`

— TypeA bipartite quantitative network is matrix of numbers. It is assumed that the interaction strength are *positive*.

`EcologicalNetworks.UnipartiteNetwork`

— TypeAn unipartite deterministic network is a matrix of boolean values.

`EcologicalNetworks.UnipartiteProbabilisticNetwork`

— TypeA unipartite probabilistic network is a square matrix of floating point numbers, all of which must be between 0 and 1.

`EcologicalNetworks.UnipartiteQuantitativeNetwork`

— TypeA unipartite quantitative network is a square matrix of numbers.

`Base.:!`

— Method`Base.:!{T<:DeterministicNetwork}(N::T)`

Returns the inverse of a binary network – interactions that were `false`

become `true`

, and conversely.

`Base.:+`

— Method`+(n1::T, n2::T) where {T <: BipartiteQuantitativeNetwork}`

Adds two quantitative bipartite networks. TODO

`Base.convert`

— Method`convert(::Type{AbstractUnipartiteNetwork}, N::AbstractBipartiteNetwork)`

Projects any bipartite network in its unipartite representation. This function will call the correct type-to-type `convert`

function depending on the type of the input network.

The type to be converted to *must* be `AbstractUnipartiteNetwork`

– for example, converting a bipartite probabilistic network to a probabilistic unipartite network is not a meaningful operation.

`Base.convert`

— Method`convert(::Type{BinaryNetwork}, N::QuantitativeNetwork)`

Projects any bipartite network in its unipartite representation. This function will call the correct type-to-type `convert`

function depending on the type of the input network.

This function does *not* work for probabilistic networks. The operation of generating a deterministic network from a probabilistic one is different from a simple conversion: it can be done either through random draws, or by selecting only interactions with a probability greater than 0 (`N>0.0`

will do this).

`Base.convert`

— Method`convert(::Type{BipartiteNetwork}, N::T) where {T <: BipartiteQuantitativeNetwork}`

Convert a bipartite quantitative network to a bipartite binary network. This amounts to *removing* the quantitative information.

`Base.convert`

— Method`convert(::Type{BipartiteNetwork}, N::T) where {T <: UnipartiteNetwork}`

Projects a unipartite network (specifically, a `BipartiteNetwork`

) to its bipartite representation. The following checks are performed.

First, the network *cannot* be degenerate, since species with no interactions cannot be assigned to a specific level. Second, the species cannot have both in and out degree. If these conditions are met, the bipartite network will be returned.

`Base.convert`

— Method`convert(::Type{BipartiteProbabilisticNetwork}, N::T) where {T <: UnipartiteProbabilisticNetwork}`

Projects a unipartite network (specifically, a `BipartiteProbabilisticNetwork`

) to its bipartite representation. The following checks are performed.

First, the network *cannot* be degenerate, since species with no interactions cannot be assigned to a specific level. Second, the species cannot have both in and out degree. If these conditions are met, the bipartite network will be returned.

`Base.convert`

— Method`convert(::Type{BipartiteQuantitativeNetwork}, N::T) where {T <: UnipartiteQuantitativeNetwork}`

Projects a unipartite network (specifically, a `BipartiteQuantitativeNetwork`

) to its bipartite representation. The following checks are performed.

First, the network *cannot* be degenerate, since species with no interactions cannot be assigned to a specific level. Second, the species cannot have both in and out degree. If these conditions are met, the bipartite network will be returned.

`Base.convert`

— Method`convert(::Type{UnipartiteNetwork}, N::T) where {T <: BipartiteNetwork}`

Projects a deterministic bipartite network in its unipartite representation.

`Base.convert`

— Method`convert(::Type{UnipartiteNetwork}, N::T) where {T <: UnipartiteQuantitativeNetwork}`

Convert a unipartite quantitative network to a unipartite binary network. This amounts to *removing* the quantitative information.

`Base.convert`

— Method`convert(::Type{UnipartiteProbabilisticNetwork}, N::T) where {T <: BipartiteProbabilisticNetwork}`

Projects a probabilistic bipartite network in its unipartite representation.

`Base.convert`

— Method`convert(::Type{UnipartiteQuantitativeNetwork}, N::T) where {T <: BipartiteQuantitativeNetwork}`

Projects a quantitative bipartite network in its unipartite representation.

`Base.copy`

— MethodCreates a copy of a network – this returns an object with the same type, and the same content.

`Base.getindex`

— Method`getindex{T}(N::AbstractBipartiteNetwork, ::Colon, sp::Array{T})`

TODO

`Base.getindex`

— Method`getindex{T}(N::AbstractBipartiteNetwork, sp::Array{T}, ::Colon)`

TODO

`Base.getindex`

— Method`getindex{T}(N::AbstractBipartiteNetwork, sp1::Array{T}, sp2::Array{T})`

TODO

`Base.getindex`

— Method`getindex{T}(N::AbstractBipartiteNetwork, sp1::Array{T}, sp2::Array{T})`

TODO

`Base.getindex`

— Method`getindex{T}(N::AbstractBipartiteNetwork, ::Colon, sp::T)`

Gets the predecessors (*i.e.* species that interacts with / consume) of a focal species. This returns the list of species as a `Set`

object, in which ordering is unimportant.

`Base.getindex`

— Method`getindex(N::AbstractEcologicalNetwork, ::Colon, j::T)`

Get the value of an interaction based on the position of the species.

`Base.getindex`

— Method`getindex{T}(N::AbstractEcologicalNetwork, sp::T, ::Colon)`

Gets the successors (*i.e.* species that are interacted with / consumed) of a focal species. This returns the list of species as a `Set`

object, in which ordering is unimportant.

`Base.getindex`

— Method`getindex(N::AbstractEcologicalNetwork, i::T, ::Colon)`

Get the value of an interaction based on the position of the species.

`Base.getindex`

— Method`getindex{T}(N::AbstractEcologicalNetwork, s1::T, s2::T)`

Get the value of an interaction based on the *name* of the species. This is the recommended way to look for things in a network.

`Base.getindex`

— Method`getindex(N::AbstractEcologicalNetwork, i::T, j::T)`

Get the value of an interaction based on the position of the species.

`Base.getindex`

— Method`getindex(N::AbstractEcologicalNetwork, i::T)`

Get the value of an interaction based on the position of the species.

`Base.getindex`

— Method`getindex{T}(N::AbstractUnipartiteNetwork, sp::Array{T})`

Induce a unipartite network based on a list of species, all of which must be in the original network. This function takes a single argument (as opposed to two arrays, or an array and a colon) to ensure that the returned network is unipartite.

The network which is returned by this function may not have the species in the order specified by the user for performance reasons.

`Base.intersect`

— Method`intersect(X::T, Y::T) where {T<:BipartiteNetwork}`

Intersect between two bipartite networks. The resulting network has the *species and interactions* common to both networks. This can result in species being disconnected, if they are found in both networks but with no operations in common.

`Base.intersect`

— Method`intersect(X::T, Y::T) where {T<:UnipartiteNetwork}`

Intersect between two unipartite networks. The resulting network has the *species and interactions* common to both networks. This can result in species being disconnected, if they are found in both networks but with no operations in common.

`Base.iterate`

— Method`Base.iterate(N::T) where {T <: AbstractEcologicalNetwork}`

Returns the interactions in a network (this uses less memory than `interactions`

but is a bit slower).

`Base.iterate`

— Method`Base.iterate(N::T) where {T <: AbstractEcologicalNetwork}`

Returns the interactions in a network (this uses less memory than `interactions`

but is a bit slower).

`Base.length`

— Method`Base.length(N::T) where {T <: AbstractEcologicalNetwork}`

The length of a network is the number of non-zero elements in it.

`Base.permutedims`

— Method`permutedims(N::AbstractBipartiteNetwork)`

Tranposes the network and returns a copy

`Base.rand`

— Method`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

`Base.rand`

— Method`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

`Base.rand`

— Method`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

`Base.setdiff`

— Method`setdiff(X::T, Y::T) where {T<:BipartiteNetwork}`

Difference between two bipartite networks. This operation is *sensitive* to the order of arguments, as the resulting network will have the species present in the first network (and their interactions) only.

`Base.setdiff`

— Method`setdiff(X::T, Y::T) where {T<:UnipartiteNetwork}`

Difference between two unipartite networks. This operation is *sensitive* to the order of arguments, as the resulting network will have the species present in the first network (and their interactions) only.

`Base.setindex!`

— Method`setindex!(N::T, A::K, i::E, j::E) where {T <: AbstractEcologicalNetwork, K <: _interaction_type(N), E <: Int}`

Changes the value of the interaction at the specificied position, where `i`

and `j`

are species *positions*. Note that this operation **changes the network**.

`Base.setindex!`

— Method`setindex!(N::T, A::Any, i::E, j::E) where {T <: AbstractEcologicalNetwork, E}`

Changes the value of the interaction at the specificied position, where `i`

and `j`

are species *names*. Note that this operation **changes the network**.

`Base.show`

— Method`show(io::IO, N::AbstractEcologicalNetwork)`

`Base.similar`

— Method`similar(N::T) where {T <: AbstractEcologicalNetwork}`

Returns a network with the same species, but an empty interaction matrix. This is useful if you want to generate a "blank slate" for some analyses.

`Base.size`

— Method`size(N::AbstractEcologicalNetwork, i::Int64)`

Return the size of the adjacency matrix of an `AbstractEcologicalNetwork`

object.

`Base.size`

— Method`size(N::AbstractEcologicalNetwork)`

Return the size of the adjacency matrix of an `AbstractEcologicalNetwork`

object.

`Base.sum`

— Method`sum(N::AbstractEcologicalNetwork; dims=nothing)`

This function will return the sum of all interactions in the network. For quantitative networks, this is the sum of interaction strengths. For binary networks, this is the number of interactions. For probabilistic networks, this is the expected number of realized interactions.

Optionally, one can give the argument dims, simular to the native `sum`

, which computes the sum of the interactions for the lower (`dims=2`

) or higher (`dims=1`

) level.

**References**

Delmas, E., Besson, M., Brice, M.-H., Burkle, L.A., Dalla Riva, G.V., Fortin, M.-J., Gravel, D., Guimarães, P.R., Hembry, D.H., Newman, E.A., Olesen, J.M., Pires, M.M., Yeakel, J.D., Poisot, T., 2018. Analysing ecological networks of species interactions. Biological Reviews 112540. https://doi.org/10.1111/brv.12433

Dunne, J.A., 2006. The Network Structure of Food Webs, in: Dunne, J.A., Pascual, M. (Eds.), Ecological Networks: Linking Structure and Dynamics. Oxford University Press, pp. 27–86.

Martinez, N.D., 1992. Constant Connectance in Community Food Webs. The American Naturalist 139, 1208–1218.

`Base.union`

— Method`union(X::T, Y::T) where {T<:BipartiteNetwork}`

Union of two bipartite networks – interactions *and* species which are present in either networks are also present in the final network.

`Base.union`

— Method`union(X::T, Y::T) where {T<:UnipartiteNetwork}`

Union of two unipartite networks – interactions *and* species which are present in either networks are also present in the final network.

`EcologicalNetworks.AJS`

— Method`AJS(N::T; dims::Union{Nothing,Integer}=nothing) where {T <: UnipartiteNetwork}`

Additive Jaccard Similarity for pairs of species in the network. AJS varies between 0 (no common species) to 1 (same profiles). This function can be used to measure AJS based on only successors or predecessors, using the `dims`

argument.

Note that this function uses all *direct* preys and predators to measure the similarity (and so does not go beyond the immediate neighbors).

**References**

Gao, P., Kupfer, J.A., 2015. Uncovering food web structure using a novel trophic similarity measure. Ecological Informatics 30, 110–118. https://doi.org/10.1016/j.ecoinf.2015.09.013

`EcologicalNetworks.EAJS`

— Method`EAJS(N::T; dims::Union{Nothing,Integer}=nothing) where {T <: UnipartiteNetwork}`

Extended Additive Jaccard Similarity for pairs of species in the network. AJS varies between 0 (no common species) to 1 (same profiles). This function can be used to measure AJS based on only successors or predecessors, using the `dims`

argument.

Note that this function counts all interactions up to a distance of 50 to define the neighbourhood of a species. This should be more than sufficient for most ecological networks.

**References**

Gao, P., Kupfer, J.A., 2015. Uncovering food web structure using a novel trophic similarity measure. Ecological Informatics 30, 110–118. https://doi.org/10.1016/j.ecoinf.2015.09.013

`EcologicalNetworks.KGL01`

— Method`KGL01(S::T)`

Whittaker

`EcologicalNetworks.Q`

— Method`Q(N::T, L::Dict{E,Int64}) where {T<:AbstractEcologicalNetwork,E}`

Modularity of a network and its partition. The second argument is a dictionary where every species of `N`

is associated to an `Int64`

value representing the identity of the module. This function returns the same value of bipartite networks and their unipartite projection.

**References**

Barber, M.J., 2007. Modularity and community detection in bipartite networks. Phys. Rev. E 76, 066102. https://doi.org/10.1103/PhysRevE.76.066102

Newman, M.E., 2006. Modularity and community structure in networks. Proceedings of the national academy of sciences 103, 8577–8582.

`EcologicalNetworks.Qr`

— Method`Qr(N::T, L::Dict{E,Int64}) where {T<:AbstractEcologicalNetwork,E}`

Realized modularity – this function returns a value giving the proportion of all links that are within the same module. Higher values reflect a more strongly modular partition (whereas `Q`

represents the deviation of modularity from the random expectation).

**References**

- Poisot, T., 2013. An a posteriori measure of network modularity. F1000Research
- https://doi.org/10.12688/f1000research.2-130.v3

`EcologicalNetworks.RDPG`

— Method`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

`EcologicalNetworks._additive_bernoulli_variance`

— MethodVariance of a series of additive Bernoulli events

f(p): ∑(p(1-p))

`EcologicalNetworks._multiplicative_bernoulli_variance`

— MethodVariance of a series of multiplicative Bernoulli events

`EcologicalNetworks._permute_motif`

— MethodInternal function

Returns all permutations of the adjacency matrix of a motif.

`EcologicalNetworks._permute_motif`

— MethodInternal function

Returns all permutations of the adjacency matrix of a motif.

`EcologicalNetworks._single_bernoulli_expectation`

— MethodExpected value of a single Bernoulli event

Simply f(p): p

`EcologicalNetworks._single_bernoulli_variance`

— MethodVariance of a single Bernoulli event

f(p): p(1-p)

`EcologicalNetworks._value_is_a_probability`

— MethodQuite crude way of checking that a number is a probability

The two steps are

- The number should be of the
`Float64`

type - The number should belong to [0.0,1.0]

`EcologicalNetworks.bellman_ford`

— Method`bellman_ford(N::T) where {T <: DeterministicNetwork}`

Bellman-ford algorithm to return the shortest / easiest paths between all pairs of species in the networks, as long as paths exists. This function will return a tuple, with fields `from`

, `to`

and `weight`

. The number of elements in the tuple is the number of paths. This function works with quantitative and binary networks, and assumes that no interactions are negative.

Currently, the Bellman-Ford algorithm is *slower* than the `shortest_path`

function, but the arguments are returned in a more usable way. Note that the speed penalty is only valid when measuring the shortest paths in the entire network (and will be fixed relatively soon), and does not apply as much for the shortest paths from a single source node.

`EcologicalNetworks.bellman_ford`

— Method`bellman_ford(N::T, source::K) where {T <: DeterministicNetwork, K}`

Bellman-Ford algorithm to return the shortest / easiest paths from a source species. Refer to the `bellman_ford`

global documentation for the output format.

`EcologicalNetworks.brim`

— Method`brim(N::NT, L::Dict{E,Int64}) where {NT<:AbstractEcologicalNetwork,E}`

Uses BRIM to optimize the modularity of an ecological network. The `L`

argument is a dictionary mapping every species in the network to its module. This function returns a tuple of the network and its module assignment.

**References**

Barber, M.J., 2007. Modularity and community detection in bipartite networks. Phys. Rev. E 76, 066102. https://doi.org/10.1103/PhysRevE.76.066102

Newman, M.E., 2006. Modularity and community structure in networks. Proceedings of the national academy of sciences 103, 8577–8582.

Thébault, E., 2013. Identifying compartments in presence–absence matrices and bipartite networks: insights into modularity measures. Journal of Biogeography 40, 759–768. https://doi.org/10.1111/jbi.12015

`EcologicalNetworks.cascademodel`

— Method`cascademodel(S::Int64, Co::Float64)`

Return matrix of the type `UnipartiteNetwork`

randomly assembled according to the cascade model for a given nuber of `S`

and connectivity `Co`

.

See also: `nichemodel`

, `mpnmodel`

, `nestedhierarchymodel`

**References**

Cohen, J.E., Newman, C.M., 1985. A stochastic theory of community food webs I. Models and aggregated data. Proceedings of the Royal Society of London. Series B. Biological Sciences 224, 421–448. https://doi.org/10.1098/rspb.1985.0042

`EcologicalNetworks.cascademodel`

— Method`cascademodel(S::Int64, L::Int64)`

Number of links can be specified instead of connectance.

**References**

Cohen, J.E., Newman, C.M., 1985. A stochastic theory of community food webs I. Models and aggregated data. Proceedings of the Royal Society of London. Series B. Biological Sciences 224, 421–448. https://doi.org/10.1098/rspb.1985.0042

`EcologicalNetworks.cascademodel`

— Method`cascademodel(parameters::Tuple)`

Parameters tuple can also be provided in the form (S::Int64, Co::Float64) or (S::Int64, L::Int64).

**References**

Cohen, J.E., Newman, C.M., 1985. A stochastic theory of community food webs I. Models and aggregated data. Proceedings of the Royal Society of London. Series B. Biological Sciences 224, 421–448. https://doi.org/10.1098/rspb.1985.0042

`EcologicalNetworks.cascademodel`

— Method`cascademodel(N::T) where {T <: UnipartiteNetwork}`

Applied to a `UnipartiteNetwork`

return its randomized version.

**References**

`EcologicalNetworks.centrality_closeness`

— Method`centrality_closeness(N::UnipartiteNetwork; nmax::Int64=20)`

The function calls `shortest_path`

internally – the `nmax`

argument is the maximal path length that will be tried.

**References**

- Bavelas, A., 1950. Communication Patterns in Task‐Oriented Groups. The Journal of the Acoustical Society of America 22, 725–730. doi:10.1121/1.1906679

`EcologicalNetworks.centrality_degree`

— Method`centrality_degree(N::UnipartiteNetwork)`

Degree centrality, corrected by the maximum degree (the most central species has a degree of 1).

`EcologicalNetworks.centrality_eigenvector`

— Method`centrality_eigenvector(N::AbstractUnipartiteNetwork)`

Eigen centrality, corrected by the maximum degree (the most central species has a degree of 1).

`EcologicalNetworks.centrality_harmonic`

— Method`centrality_harmonic(N::UnipartiteNetwork; nmax::Int64=20)`

The function calls `shortest_path`

internally – the `nmax`

argument is the maximal path length that will be tried.

`EcologicalNetworks.centrality_katz`

— Method`centrality_katz(N::Unipartite; a::Float64=0.1, k::Int64=5)`

This measure can work on different path length (`k`

), and give a different weight to every subsequent connection (`a`

). `k`

must be at least 1 (only immediate neighbors are considered). `a`

(being a weight), must be positive.

Katz, L., 1953. A new status index derived from sociometric analysis. Psychometrika 18, 39–43. doi:10.1007/bf02289026

`EcologicalNetworks.conditional_entropy`

— Method`conditional_entropy(P::AbstractArray, given::I)`

Computes the conditional entropy of probability matrix. If `given = 1`

, it is the entropy of the columns, and vise versa when `given = 2`

. Output in bits.

Does not check whether `P`

is a valid probability matrix.

`EcologicalNetworks.conditional_entropy`

— Method`conditional_entropy(N::AbstractEcologicalNetwork, given::I)`

Computes the conditional entropy of an ecological network. If `given = 1`

, it is the entropy of the columns, and vise versa when `given = 2`

.

`EcologicalNetworks.connectance`

— Method`connectance(N::AbstractEcologicalNetwork)`

Number of links divided by the number of possible interactions. In unipartite networks, this is $L/S^2$. In bipartite networks, this is $L/(T × B)$. It is worth noting that while the maximal connectance is always 1 (i.e. the graph is complete), the minimum value (assuming that the network is not degenerate) is *not* 0. Instead, the minimum number of interactions in a unipartite network is `S-1`

, and in a bipartite network it is `max(T,B)`

.

Connectance can therefore be transformed between 0 and 1, using the following approach: let `m`

be the minimum number of interactions, and Co be the measured connectance, then the corrected value is `(Co-m)/(1-m)`

. To our best knowledge, this is not standard practice, and therefore is not suggested as a function in the package.

**References**

Delmas, E., Besson, M., Brice, M.-H., Burkle, L.A., Dalla Riva, G.V., Fortin, M.-J., Gravel, D., Guimarães, P.R., Hembry, D.H., Newman, E.A., Olesen, J.M., Pires, M.M., Yeakel, J.D., Poisot, T., 2018. Analysing ecological networks of species interactions. Biological Reviews 112540. https://doi.org/10.1111/brv.12433

Dunne, J.A., 2006. The Network Structure of Food Webs, in: Dunne, J.A., Pascual, M. (Eds.), Ecological Networks: Linking Structure and Dynamics. Oxford University Press, pp. 27–86.

Martinez, N.D., 1992. Constant Connectance in Community Food Webs. The American Naturalist 139, 1208–1218.

`EcologicalNetworks.connectance_var`

— Method`connectance_var(N::ProbabilisticNetwork)`

Expected variance of the connectance for a probabilistic matrix, measured as the variance of the number of links divided by the squared size of the matrix.

**References**

`EcologicalNetworks.convert2effective`

— Method`convert2effective(indice::Real)`

Convert an information theory indices in an effective number (i.e. number of corresponding interactions). Assumes an input in bits (i.e. log with base 2 is used).

`EcologicalNetworks.degree`

— Method`degree(N::AbstractEcologicalNetwork; dims::Union{Nothing,Integer}=nothing)`

Returns the degrees of nodes in a network; `dims`

can be `1`

for out degree, or `2`

for in degree.

**References**

Delmas, E., Besson, M., Brice, M.-H., Burkle, L.A., Dalla Riva, G.V., Fortin, M.-J., Gravel, D., Guimarães, P.R., Hembry, D.H., Newman, E.A., Olesen, J.M., Pires, M.M., Yeakel, J.D., Poisot, T., 2018. Analysing ecological networks of species interactions. Biological Reviews 112540. https://doi.org/10.1111/brv.12433

Williams, R.J., 2011. Biology, Methodology or Chance? The Degree Distributions of Bipartite Ecological Networks. PLoS One 6, e17645. https://doi.org/10.1371/journal.pone.0017645

`EcologicalNetworks.degree_in`

— Method`degree_in(N::AbstractEcologicalNetwork)`

`EcologicalNetworks.degree_in_var`

— Method**Variance in the ingoing degree**

`degree_in_var(N::ProbabilisticNetwork)`

`EcologicalNetworks.degree_out`

— Method`degree_out(N::AbstractEcologicalNetwork)`

`EcologicalNetworks.degree_out_var`

— Method**Variance in the outgoing degree**

`degree_out_var(N::ProbabilisticNetwork)`

`EcologicalNetworks.degree_var`

— Method`degree_var(N::ProbabilisticNetwork; dims::Union{Nothing,Integer}=nothing)`

Variance in the degree of species in a probabilistic network.

`EcologicalNetworks.diff_entropy_uniform`

— Method`diff_entropy_uniform(P::AbstractArray; [dims])`

Computes the difference in entropy of the marginals compared to the entropy of an uniform distribution. The parameter `dims`

indicates which marginals are used, with both if no value is provided. Output in bits.

`EcologicalNetworks.diff_entropy_uniform`

— Method`diff_entropy_uniform(N::AbstractEcologicalNetwork, dims::I=nothing)`

Computes the difference in entropy of the marginals compared to the entropy of an uniform distribution. The parameter `dims`

indicates which marginals are used, with both if no value is provided. Output in bits.

`EcologicalNetworks.dijkstra`

— Method`dijkstra(N::T) where {T <: DeterministicNetwork}`

Dijkstra algorithm to return the shortest / easiest paths between all pairs of species in the networks, as long as paths exists. This function will return a tuple, with fields `from`

, `to`

and `weight`

. The number of elements in the tuple is the number of paths. This function works with quantitative and binary networks, and assumes that no interactions are negative.

`EcologicalNetworks.dijkstra`

— Method`dijkstra(N::T, source::K) where {T <: DeterministicNetwork, K}`

Dijkstra's algorithm to return the shortest / easiest paths from a source species. Refer to the `bellman_ford`

global documentation for the output format.

`EcologicalNetworks.distance_to_producer`

— Method`distance_to_producer(N::UnipartiteNetwork; f=maximum)`

Returns the distance from a primary producert of every species in the food web. Primary producers have a trophic level of 1, after that, it's complicated (see *e.g.* Williams & Martinez 2004, Thompson et al. 2007).

Post (2002) notes that the trophic level can be obtained from the maximum, mean, or minimum distance to a producer. Given that consumers may be connected to more than one producer, one might argue that the *mode* of this distribution is also relevant.

In favor of the minimum, one can argue that most energy transfer should happen along short chains; but imagining a consumer atop a chain of length 5, also connected directly to a producer, the minimum would give it a trophic level of 2, hiding its position at the top of the food web.

In favor of the maximum, one can argue that the higher chains give a better idea of how far energy coming from the bottom of the food web can go. This is a strong indication of how *vertically* diverse it is.

In this package, the keyword `f`

defaults to `maximum`

. Using any other function, as long as it accepts an array (of chain distances) and return a scalar, will work; `minimum`

and `Statistics.mean`

are natural alternatives, as is `StatsBase.mode`

or `Statistics.median`

.

The chain length from any species to any producer is taken as the shortest possible path between these two species, as identified by the Dijkstra algorithm.

`EcologicalNetworks.each_species_its_module`

— Method`each_species_its_module(N::T) where {T<:AbstractEcologicalNetwork}`

Returns a dictionary in which each species is its own module. This is used as a starting point for `lp`

and `salp`

internally. This is often a very poor starting point for `brim`

, and should probably not be used on its own.

**References**

Thébault, E., 2013. Identifying compartments in presence–absence matrices and bipartite networks: insights into modularity measures. Journal of Biogeography 40, 759–768. https://doi.org/10.1111/jbi.12015

`EcologicalNetworks.entropy`

— Method`entropy(P::AbstractArray; [dims])`

Computes the joint entropy of a probability matrix. Does not perform any checks whether the matrix is normalized. Output in bits.

If the `dims`

keyword argument is provided, the marginal entropy of the matrix is computed. `dims`

indicates whether to compute the entropy for the rows (`dims=1`

) or columns (`dims=2`

).

`EcologicalNetworks.entropy`

— Method`entropy(N::AbstractEcologicalNetwork; [dims])`

Computes the joint entropy of an ecological network. If `dims`

is specified, The marginal entropy of the ecological network is computed. `dims`

indicates whether to compute the entropy for the rows (`dims=1`

) or columns (`dims=2`

). Output in bits.

`EcologicalNetworks.expected_motif_count`

— Method`expected_motif_count(s)`

Get the expected number of motifs (and variance) from the output of `find_motif`

on a probabilistic network.

**References**

`EcologicalNetworks.find_motif`

— Method`find_motif(N::T1, m::T2) where {T1<:AbstractEcologicalNetwork, T2<:BinaryNetwork}`

Returns an array of tuples, in which each tuple contains the species that are part of the motif. The length of the array gives the number of times the motif was found. For probabilistic networks, the tuple also contains the probability of observing the species in the correct conformation for the motif, as well as the variance.

**References**

Milo, R., Shen-Orr, S., Itzkovitz, S., Kashtan, N., Chklovskii, D., Alon, U.,

- Network motifs: simple building blocks of complex networks. Science 298,

824–7. https://doi.org/10.1126/science.298.5594.824

`EcologicalNetworks.functional_cartography`

— Method`functional_cartography(N::T, L::Dict{E,Int64}) where {T<:BinaryNetwork, E}`

This function will take the output of a modularity analysis (*i.e.* a network and a partition), and return a dictionary where every species is associated to its functional role, as defined in Olesen et al (2005). The first element is the within-module degree z-score, and the second is the participation coefficient.

**References**

Guimerà, R., Amaral, L.A.N., 2005. Cartography of complex networks: modules and universal roles. Journal of Statistical Mechanics: Theory and Experiment 2005, P02001. https://doi.org/10.1088/1742-5468/2005/02/P02001

Guimerà, R., Nunes Amaral, L.A., 2005. Functional cartography of complex metabolic networks. Nature 433, 895–900. https://doi.org/10.1038/nature03288

Olesen, J.M., Bascompte, J., Dupont, Y.L., Jordano, P., 2007. The modularity of pollination networks. Proceedings of the National Academy of Sciences 104, 19891–19896. https://doi.org/10.1073/pnas.0706375104

`EcologicalNetworks.has_interaction`

— Method`has_interaction(N::AbstractEcologicalNetwork, i::Int64, j::Int64)`

This function returns `true`

if the interaction between `i`

and `j`

is not 0. This refers to species by their position instead of their name, and is not recommended as the main solution. This is used internally by a few functions, but is exported because it may be of general use.

`EcologicalNetworks.has_interaction`

— Method`has_interaction{(N::AbstractEcologicalNetwork, i::NT, j::NT)`

This function returns `true`

if the interaction between `i`

and `j`

is not 0. This refers to species by their names/values, and is the recommended way to test for the presence of an interaction.

Use `N[i,j]`

if you need to get the value of the interaction.

`EcologicalNetworks.heterogeneity`

— Method`heterogeneity(N::AbstractUnipartiteNetwork)`

Computes the heterogeneity for an unipartite network, a topological characteristic which quantifies the difference in in- and outgoing degrees between species. It is computed as σ*in * σ*out / s_mean. A value of 0 indicates that all species have the same (weighted) in- and outdegrees.

Goa, J., Barzael, B. and Barabási 2016. Universal resilience patterns in complex networks. Nature 530(7590), 307-312. doi:10.1038/nature16948

`EcologicalNetworks.information_decomposition`

— Method`information_decomposition(N::AbstractEcologicalNetwork; norm::Bool=false, dims=nothing)`

Performs an information theory decomposition of a given ecological network, i.e. the information content in the normalized adjacency matrix is split in:

`:D`

: difference in entropy of marginals compared to an uniform distribition`:I`

: mutual information`:V`

: variation of information / conditional entropy

If `norm=true`

, the components are normalized such that their sum is equal to 1. One can optinally give the dimision, indicating whether to compute the indices for the rows (`dims=1`

), columns (`dims=2`

) or the whole matrix (default).

Result is returned in a Dict. Outputs in bits.

Stock, M.; Hoebeke, L.; De Baets, B. « Disentangling the Information in Species Interaction Networks ». Entropy 2021, 23, 703. https://doi.org/10.3390/e23060703

`EcologicalNetworks.interactions`

— Method`interactions(N::AbstractEcologicalNetwork)`

Returns the interactions in the ecological network. Interactions are returned as an array of named tuples. *A minima*, these have fields `from`

and `to`

. For networks that are probabilistic, there is a `probability`

field. For networks that are quantitative, there is a `strength`

field. This functions allows to iterate over interactions in a network in a convenient way.

`EcologicalNetworks.isdegenerate`

— Method`isdegenerate(N::AbstractEcologicalNetwork)`

Networks are called degenerate if some species have no interactions, either at all, or with any species other than themselves. This is particularly useful to decide the networks to keep when generating samples for null models.

`EcologicalNetworks.linearfilter`

— Method`linearfilter(N::BinaryNetwork, α::Vector{Float64}=[0.25, 0.25, 0.25, 0.25])`

Given a network `N`

compute the linear filter scores according to Stock et al. (2017). High scores for negative interactions indicate potential false negative or missing interactions. Though this it returned as a probabilistic network, score do not necessary convey a probabilistic interpretation.

The values of α give the *relative* weight of, in order, the measured interaction value, the out-degree of the species, the in-degree of the species, and of network connectance. The default parameterization is to have all four at equal importance.

**References**

Stock, M., Pahikkala, T., Airola, A., Waegeman, W., Baets, B.D., 2018. Algebraic Shortcuts for Leave-One-Out Cross-Validation in Supervised Network Inference. bioRxiv 242321. https://doi.org/10.1101/242321

Stock, M., Poisot, T., Waegeman, W., Baets, B.D., 2017. Linear filtering reveals false negatives in species interaction data. Scientific Reports 7, 45908. https://doi.org/10.1038/srep45908

`EcologicalNetworks.linearfilterzoo`

— Method`linearfilterzoo(N::BinaryNetwork, α::Vector{Float64}=[0.25, 0.25, 0.25, 0.25])`

Compute the zero-one-out version of the linear filter (`linearfilter`

), i.e. the score for each interaction if that interaction would not occur in the network. For example, if N[4, 6] = 1 (interaction between species 4 and 6), the result at postion (4, 6) is the score of the filter using a network in which that interaction did not occur. This function is useful for validating the filter whether it can detect false negative (missing) interactions.

**References**

Stock, M., Pahikkala, T., Airola, A., Waegeman, W., Baets, B.D., 2018. Algebraic Shortcuts for Leave-One-Out Cross-Validation in Supervised Network Inference. bioRxiv 242321. https://doi.org/10.1101/242321

Stock, M., Poisot, T., Waegeman, W., Baets, B.D., 2017. Linear filtering reveals false negatives in species interaction data. Scientific Reports 7, 45908. https://doi.org/10.1038/srep45908

`EcologicalNetworks.linkage_density`

— Method`linkage_density(N::AbstractEcologicalNetwork)`

Number of links divided by species richness.

**References**

Dunne, J.A., 2006. The Network Structure of Food Webs, in: Dunne, J.A., Pascual, M. (Eds.), Ecological Networks: Linking Structure and Dynamics. Oxford University Press, pp. 27–86.

`EcologicalNetworks.links`

— Method`links(N::BinaryNetwork)`

Number of non-zero interactions in a deterministic network.

**References**

Martinez, N.D., 1992. Constant Connectance in Community Food Webs. The American Naturalist 139, 1208–1218.

`EcologicalNetworks.links`

— Method`links(N::ProbabilisticNetwork)`

Expected number of interactions in a probabilistic network. To get the number of interactions that have a non-zero probability, use *e.g.* `links(N>0.0)`

.

**References**

`EcologicalNetworks.links`

— Method`links(N::QuantitativeNetwork)`

Number of non-zero interactions in a quantitative network (use `sum`

to get the sum of interaction strengths).

**References**

`EcologicalNetworks.links_var`

— Method`links_var(N::ProbabilisticNetwork)`

Expected variance of the number of links for a probabilistic network.

**References**

`EcologicalNetworks.lp`

— Method`lp(N::T) where {T<:AbstractEcologicalNetwork}`

Uses label propagation to generate a first approximation of the modular structure of a network. This is usually followed by the BRIM (`brim`

) method. This method supposedly performs better for large graphs, but we rarely observed any differences between it and variations of BRIM alone on smaller graphs.

**References**

Liu, X., Murata, T., 2009. Community Detection in Large-Scale Bipartite Networks, in: 2009 IEEE/WIC/ACM International Joint Conference on Web Intelligence and Intelligent Agent Technology. Institute of Electrical & Electronics Engineers (IEEE). https://doi.org/10.1109/wi-iat.2009.15

`EcologicalNetworks.make_joint_distribution`

— Method`make_joint_distribution(N::NT) where {NT<:AbstractEcologicalNetwork}`

Returns a probability matrix computed from the adjacency or incidence matrix. Raises an error if the matrix contains negative values. Output in bits.

`EcologicalNetworks.mirror`

— Method`mirror(N::T) where {T <: AbstractUnipartiteNetwork}`

Returns a mirrored version of the adjacency matrix, required for spectral radius.

`EcologicalNetworks.mpnmodel`

— Method`mpnmodel(S::Int64, Co::Float64, forbidden::Float64)`

Return `UnipartiteNetwork`

with links assigned according to minimum potential niche model for given number of `S`

, connectivity `Co`

and probability of `forbidden`

link occurence.

**References**

Allesina, S., Alonso, D., Pascual, M., 2008. A General Model for Food Web Structure. Science 320, 658–661. https://doi.org/10.1126/science.1156269

`EcologicalNetworks.mpnmodel`

— Method`mpnmodel(mpnmodel(S::Int64, L::Int64, forbidden::Float64))`

Average number of links can be specified instead of connectance.

**References**

Allesina, S., Alonso, D., Pascual, M., 2008. A General Model for Food Web Structure. Science 320, 658–661. https://doi.org/10.1126/science.1156269

`EcologicalNetworks.mpnmodel`

— Method`mpnmodel(parameters::Tuple)`

Parameters tuple can also be provided in the form (S::Int64, Co::Float64, forbidden::Float64).

**References**

Allesina, S., Alonso, D., Pascual, M., 2008. A General Model for Food Web Structure. Science 320, 658–661. https://doi.org/10.1126/science.1156269

`EcologicalNetworks.mpnmodel`

— Method`mpnmodel(N::T) where {T<: UnipartiteNetwork}`

Applied to `UnipartiteNetwork`

return its randomized version.

**References**

`EcologicalNetworks.mutual_information`

— Method`mutual_information(P::AbstractArray)`

Computes the mutual information of a probability matrix. Output in bits.

`EcologicalNetworks.mutual_information`

— Method`mutual_information(N::NT) where {NT<:AbstractEcologicalNetwork}`

Computes the mutual information of an ecological network. Output in bits.

`EcologicalNetworks.n_random_modules`

— Method`n_random_modules(n::Int64)`

This returns *a function* which, when applied to a network, will randomly assign every species to one of `n`

modules. The correct way to apply this function to a network `N`

is, therefore `n_random_modules(4)(N)`

(with four modules).

**References**

Thébault, E., 2013. Identifying compartments in presence–absence matrices and bipartite networks: insights into modularity measures. Journal of Biogeography 40, 759–768. https://doi.org/10.1111/jbi.12015

`EcologicalNetworks.nestedhierarchymodel`

— Method`nestedhierarchymodel(S::Int64, Co::Float64)`

Connectance can be provided instead of number of links.

**References**

Cattin, M.-F., Bersier, L.-F., Banašek-Richter, C., Baltensperger, R., Gabriel, J.-P., 2004. Phylogenetic constraints and adaptation explain food-web structure. Nature 427, 835–839. https://doi.org/10.1038/nature02327

`EcologicalNetworks.nestedhierarchymodel`

— Method`nestedhierarchymodel(S::Int64, L::Int64)`

Return `UnipartiteNetwork`

where resources are assigned to consumers according to the nested hierarchy model for `S`

species and `L`

.

**References**

Cattin, M.-F., Bersier, L.-F., Banašek-Richter, C., Baltensperger, R., Gabriel, J.-P., 2004. Phylogenetic constraints and adaptation explain food-web structure. Nature 427, 835–839. https://doi.org/10.1038/nature02327

`EcologicalNetworks.nestedhierarchymodel`

— Method`nestedhierarchymodel(parameters::Tuple)`

Parameters tuple can also be provided in the form (Species::Int64, Co::Float64) or (Species::Int64, Int::Int64).

**References**

Cattin, M.-F., Bersier, L.-F., Banašek-Richter, C., Baltensperger, R., Gabriel, J.-P., 2004. Phylogenetic constraints and adaptation explain food-web structure. Nature 427, 835–839. https://doi.org/10.1038/nature02327

`EcologicalNetworks.nestedhierarchymodel`

— Method`nestedhierarchymodel(N::T) {T <: UnipartiteNetwork}`

Applied to empirical `UnipartiteNetwork`

return its randomized version.

**References**

`EcologicalNetworks.nichemodel`

— Method`nichemodel(S::Int64, C::Float64)`

**References**

Williams, R., Martinez, N., 2000. Simple rules yield complex food webs. Nature 404, 180–183.

`EcologicalNetworks.nichemodel`

— Method`nichemodel(S::Int64, L::Int64)`

Return `UnipartiteNetwork`

where resources are assign to consumers according to niche model for a network of `S`

species and `L`

links.

**References**

Williams, R., Martinez, N., 2000. Simple rules yield complex food webs. Nature 404, 180–183.

`EcologicalNetworks.nichemodel`

— Method`nichemodel(parameters::Tuple)`

Parameters tuple can also be provided in the form (Species::Int64, Co::Float64) or (Species::Int64, Int::Int64).

**References**

Williams, R., Martinez, N., 2000. Simple rules yield complex food webs. Nature 404, 180–183.

`EcologicalNetworks.nichemodel`

— Method`nichemodel(N::T) where {T <: UnipartiteNetwork}`

Applied to empirical `UnipartiteNetwork`

return its randomized version.

**References**

Williams, R., Martinez, N., 2000. Simple rules yield complex food webs. Nature 404, 180–183.

`EcologicalNetworks.nodf`

— Method`nodf(N::T; dims::Union{Nothing,Integer}=nothing) where {T <: Union{BipartiteNetwork,BipartiteQuantitativeNetwork}}`

Returns `nodf`

for a margin of the network. The `i`

argument can be 1 for top-level, 2 for bottom level, and the function will throw an `ArgumentError`

if an invalid value is used. For quantitative networks, *WNODF* is used.

**References**

Almeida-Neto, M., Guimarães, P.R., Loyola, R.D., Ulrich, W., 2008. A consistent metric for nestedness analysis in ecological systems: reconciling concept and measurement. Oikos 117, 1227–1239. https://doi.org/10.1111/j.0030-1299.2008.16644.x

Almeida-Neto, M., Ulrich, W., 2011. A straightforward computational approach for measuring nestedness using quantitative matrices. Environmental Modelling & Software 26, 173–178. https://doi.org/10.1016/j.envsoft.2010.08.003

`EcologicalNetworks.nodf_axis`

— MethodNODF of a single axis

`EcologicalNetworks.nodf_axis`

— MethodWNODF of a single axis

`EcologicalNetworks.nodiagonal!`

— Method`nodiagonal!(N::AbstractBipartiteNetwork)`

Does nothing.

`EcologicalNetworks.nodiagonal!`

— Method`nodiagonal!(N::AbstractUnipartiteNetwork)`

Modifies the network so that its diagonal is set to the appropriate zero.

`EcologicalNetworks.nodiagonal`

— Method`nodiagonal(N::AbstractBipartiteNetwork)`

Returns a *copy* of the network (because the diagonal of a bipartite network is never a meaningful notion). This function is clearly useless, but allows to write general code for all networks types when a step requires removing the diagonal.

`EcologicalNetworks.nodiagonal`

— Method`nodiagonal(N::AbstractUnipartiteNetwork)`

Returns a copy of the network with its diagonal set to zero.

`EcologicalNetworks.null1`

— Method`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`

— Method`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`

— Method`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

`EcologicalNetworks.null4`

— Method`null4(N::BinaryNetwork)`

Given a matrix `A`

, `null4(A)`

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

`EcologicalNetworks.number_of_paths`

— Method`number_of_paths(N::Unipartite; n::Int64=2)`

This returns an array, not a network.

`n`

(def. 2), the path length

`EcologicalNetworks.omnivory`

— Method`omnivory(N::T) where {T <: UnipartiteNetwork}`

Returns a vector of length richness(N) with an index of consumption across trophic levels. Note we explicitly assume that diet contribution is spread evenly across prey species, in proportion to their degree. Omnivory is measured based on the output of `trophic_level`

.

**References**

- Christensen, Villy, and Daniel Pauly. "ECOPATH II—a software for balancing steady-state ecosystem models and calculating network characteristics." Ecological modelling 61, no. 3-4 (1992): 169-185.

`EcologicalNetworks.optimaltransportation`

— Method```
optimaltransportation(M::AbstractArray;
[a, b, λ=1, ϵ=1e-10, maxiter=100])
```

Performs optimal transportation on an ecological network. Here, `M`

is treated as an utility matrix, quantifying the preference the species of the two throphic levels have for interacting with another. One can fix both, one or none of the species abundances by given `a`

(row sums, corresponding to top species) and/or `b`

(column sums, corresponding to bottom species). The strengh of entropic regularisation is set by `λ`

, where higher values indicate more utitlity and lower values more entropy.

ϵ and `maxiter`

control the number of Sinkhorn iterations. You likely won't need to change these.

This version works on arrays.

Stock, M., Poisot, T., & De Baets, B. (2021). « Optimal transportation theory for species interaction networks. » Ecology and Evolution, 00(1), ece3.7254. https://doi.org/10.1002/ece3.7254

`EcologicalNetworks.optimaltransportation`

— Method```
optimaltransportation(M::AbstractBipartiteNetwork;
[a, b, λ=1, ϵ=1e-10, maxiter=100])
```

Performs optimal transportation on an ecological network. Here, `M`

is treated as an utility matrix, quantifying the preference the species of the two throphic levels have for interacting with another. One can fix both, one or none of the species abundances by given `a`

(row sums, corresponding to top species) and/or `b`

(column sums, corresponding to bottom species). The strengh of entropic regularisation is set by `λ`

, where higher values indicate more utitlity and lower values more entropy.

ϵ and `maxiter`

control the number of Sinkhorn iterations. You likely won't need to change these.

Stock, M., Poisot, T., & De Baets, B. (2021). « Optimal transportation theory for species interaction networks. » Ecology and Evolution, 00(1), ece3.7254. https://doi.org/10.1002/ece3.7254

`EcologicalNetworks.overlap`

— Method`overlap(N::T; dims=dims::Union{Nothing,Integer}=nothing) where {T <: BipartiteNetwork}`

Returns the overlap graph for a bipartite network. The `dims`

keyword argument can be `1`

(default; overlap between top-level species) or `2`

(overlap between bottom-level species). See the documentation for `?overlap`

for the output format.

`EcologicalNetworks.overlap`

— Method`overlap(N::T; dims::Union{Nothing,Integer}=nothing) where {T <: UnipartiteNetwork}`

Returns the overlap graph for a unipartite network. The `dims`

keyword argument can be `1`

(overlap based on preys) or `2`

(overlap based on predators), or `nothing`

(default; overlap based on both predators and preys). The overlap is returned as a vector of named tuples, with elements `pair`

(a tuple of species names), and `overlap`

(the number of shared interactors). The ordering within the pair of species is unimportant, since overlap graphs are symetrical.

`EcologicalNetworks.pdi`

— Method`pdi{T<:Number}(x::Array{T, 1})`

This function will range the values of each row, so that the strongest link has a value of one. This works for deterministic and quantitative networks.

**References**

Poisot, T., Bever, J.D., Nemri, A., Thrall, P.H., Hochberg, M.E., 2011. A conceptual framework for the evolution of ecological specialisation. Ecol. Lett. 14, 841–851. https://doi.org/10.1111/j.1461-0248.2011.01645.x

Poisot, T., Canard, E., Mouquet, N., Hochberg, M.E., 2012. A comparative study of ecological specialization estimators. Methods in Ecology and Evolution 3, 537–544. https://doi.org/10.1111/j.2041-210X.2011.00174.x

`EcologicalNetworks.potential_information`

— Method`potential_information(N::NT; [dims])`

Computes the maximal potential information in a network, corresponding to every species interacting with every other species. Compute result for the marginals using the optional parameter `dims`

. Output in bits.

`EcologicalNetworks.rdpg`

— Method`svd_truncated(N::BinaryNetwork, rnk::Integer=3)`

Given a binary network `N`

which adjacency matrix `A`

is of dimension `n × m`

, `svd_truncated(A)`

returns two matrices, `Left`

and `Right`

, with dimensions respectively `n × rank`

and `rank × m`

, corresponding to the species representation in the network `N`

's RDPG space of rank `rank`

.

The singular value decomposition is computed using `LinearAlgebra`

's `svd`

, obtaining

`A = U * Diagonal(S) * V = U * Diagonal(√S) * Diagonal(√S) * V`

.

The truncation preserves the first `rank`

columns of `U * Diagonal(√S)`

and the first `rank`

rows `Diagonal(√S) * V`

.

We have that, `A ≃ Left * Right`

(and the approximation is optimal in a specified meaning).

**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

`EcologicalNetworks.resilience`

— Method`resilience(N::AbstractUnipartiteNetwork)`

A resilience parameters described by Gao et al. (2016). It is a global parameters describing the dynamics of an unipartite network as an effective 1D equation of the form

f(xeff) = F(xeff) + βeff G(xeff, xeff)

i.e. describing a second-order term representing the effect of the network on the dynamics of the 'effective state' xeff of the system.

Goa, J., Barzael, B. and Barabási 2016. Universal resilience patterns in complex networks. Nature 530(7590), 307-312. doi:10.1038/nature16948

`EcologicalNetworks.richness`

— Method`richness(N::AbstractEcologicalNetwork, i::Int64)`

Returns the number of species on either side of the network. The value of `i`

can be `1`

(top-level species) or `2`

(bottom-level species), as in the `species`

function.

`EcologicalNetworks.s`

— Method`s(N::AbstractUnipartiteNetwork; dims::Union{Nothing,Integer}=nothing)`

Computes the average weighted degree. This is proportional to the (weighted) density of interactions.

If dims is provided, the incoming (`dims=1`

) or outgoing (`dims=2`

) is computed.

`EcologicalNetworks.salp`

— Method`salp(N::T; θ::Float64=1.0, steps::Int64=10_000, λ::Float64=0.999, progress::Bool=false) where {T <: BipartiteNetwork}`

Label-propagation using simulated annealing. This function uses simulated annealing to propagate labels from neighboring nodes. It accepts a network as input. The schedule of the simulated annealing is linear: at step k+1, the temperature is θλᵏ. The initial temperature has been picked so that after 100 timesteps, using the default λ, a move decreasing modularity by 0.05 (20% of the theoretical maximum) is picked with a probability of 0.1.

Optional arguments regulating the behavior of the simulated annealing routine are:

`λ=0.999`

, the rate of temperature decay`θ=0.002`

, the initial temperature`steps=10_000`

, the number of annealing steps to perform`progress=false`

, whether to display an info message every 100 timesteps

The θ parameter can be picked using the following method: if we want to allow a maximal loss of modularity of δ, after timestep k, with a decay parameter λ, with a probability P, then θ = -δ/[λᵏ×ln(P)]⁻¹. By beibg more or less restrictive on these parameters, the user can pick a value of θ for every problem.

This function can work as a first step (like `lp`

), but in explorations during the development of the package, we found that `brim`

was rarely (if ever) able to optmize the output further. It can therefore be used on its own.

`EcologicalNetworks.shortest_path`

— Method`shortest_path(N::UnipartiteNetwork; nmax::Int64=50)`

This is not an optimal algorithm *at all*, but it will do given that most ecological networks are relatively small. The optional `nmax`

argument is the longest shortest path length you will look for.

In ecological networks, the longest shortest path tends not to be very long, so any value above 10 is probably overdoing it. Note that the default value is 50, which is above 10.

`EcologicalNetworks.shortest_path`

— Method`shortest_path(N::UnipartiteQuantiNetwork; nmax::Int64=50)`

This function will remove quantitative information, then measure the shortest path length.

`EcologicalNetworks.simplify!`

— Method`simplify!{T<:BipartiteNetwork}(N::T)`

Returns a new network in which species with no interactions have been removed.

`EcologicalNetworks.simplify!`

— Method`simplify!{T<:BipartiteNetwork}(N::T)`

Returns a new network in which species with no interactions have been removed.

`EcologicalNetworks.simplify!`

— Method`simplify!{T<:BipartiteNetwork}(N::T)`

Returns a new network in which species with no interactions have been removed.

`EcologicalNetworks.simplify!`

— Method`simplify!(N::UnipartiteNetwork)`

Modifies the network to drop all species without an interaction.

`EcologicalNetworks.simplify!`

— Method`simplify!(N::UnipartiteNetwork)`

Modifies the network to drop all species without an interaction.

`EcologicalNetworks.simplify!`

— Method`simplify!(N::UnipartiteNetwork)`

Modifies the network to drop all species without an interaction.

`EcologicalNetworks.simplify`

— Method`simplify(N::T) where {T<:AbstractEcoloigcalNetwork}`

Returns a new network in which species with no interactions have been removed.

`EcologicalNetworks.species`

— Method`species(N::AbstractBipartiteNetwork)`

Returns an array of all species in a bipartite network. The order of the species corresponds to the order of rows (top level) and columns (bottom level) of the adjacency matrix, in this order.

`EcologicalNetworks.species`

— Method`species(N::AbstractUnipartiteNetwork; dims::Int64=1)`

Returns an array of species on either side of a unipartite network. In a unipartite network, species are the same on either size. This function is nevertheless useful when you want to write code that takes either side of the network in a general way.

`EcologicalNetworks.specificity`

— Method`specificity(N::DeterministicNetwork)`

Measure of specificity in a deterministic network. This returns a value between 0 and 1, where 1 indicates maximal specificity.

**References**

Poisot, T., Bever, J.D., Nemri, A., Thrall, P.H., Hochberg, M.E., 2011. A conceptual framework for the evolution of ecological specialisation. Ecol. Lett. 14, 841–851. https://doi.org/10.1111/j.1461-0248.2011.01645.x

Poisot, T., Canard, E., Mouquet, N., Hochberg, M.E., 2012. A comparative study of ecological specialization estimators. Methods in Ecology and Evolution 3, 537–544. https://doi.org/10.1111/j.2041-210X.2011.00174.x

`EcologicalNetworks.symmetry`

— Method`symmetry(N::AbstractUnipartiteNetwork)`

Computes the symmetry between s^in and s^out (the in- and outgoing weighted degree of an unipartite network). This is computed as the Pearson correlation between the s^in and s^out. It is hence a value between -1 and 1, where high positive values indicate that species with many outgoing degrees tend to have many ingoing degrees and negative values mean the opposite. An undirected network is perfectly symmetric but, for example, a food web where predators are less likely to be prey would have a negative symmetry.

Goa, J., Barzael, B. and Barabási 2016. Universal resilience patterns in complex networks. Nature 530(7590), 307-312. doi:10.1038/nature16948

`EcologicalNetworks.trophic_level`

— Method`trophic_level(N::UnipartiteNetwork; kwargs...)`

Returns the *fractional* trophic level (after Odum & Heald 1975) of species in a binary unipartite network. The trophic level is calculated after Pauly & Christensen (1995), specifically as TLᵢ = 1 + ∑ⱼ(TLⱼ×DCᵢⱼ)/∑ⱼ(DCᵢⱼ), wherein TLᵢ is the trophic level of species i, and DCᵢⱼ is the proportion of species j in the diet of species i. Note that this function is calculated on a network where the diagonal (i.e. self loops) are removed.

This function uses a *pseudo*-inverse to solve the linear system described above *iff* the determinant of the diet matrix is 0 (it is non-invertible). Otherwise, it will use an exact inverse.

`EcologicalNetworks.unipartitemotifs`

— Method`unipartitemotifs()`

The names of the motifs come from Stouffer et al. (2007) – especially Fig. 1, available online at http://rspb.royalsocietypublishing.org/content/274/1621/1931.figures-only

The motifs are returned as a named tuple, with every motif identified by its name in the original publication. The species are named :a. :b, and :c.

`EcologicalNetworks.variation_information`

— Method`variation_information(P::AbstractArray)`

Computes the variation of information of a double stochastic matrix. Output in bits.

`EcologicalNetworks.variation_information`

— Method`variation_information(N::AbstractEcologicalNetwork)`

Computes the variation of information of an ecological network. Output in bits.

`EcologicalNetworks.βos`

— Method`βos(X::T, Y::T) where {T<:BipartiteNetwork}`

Overlapping species (bipartite)

**References**

Canard, E.F., Mouquet, N., Mouillot, D., Stanko, M., Miklisova, D., Gravel, D.,

- Empirical evaluation of neutral interactions in host-parasite networks.

The American Naturalist 183, 468–479. https://doi.org/10.1086/675363

Poisot, T., Canard, E., Mouillot, D., Mouquet, N., Gravel, D., 2012. The dissimilarity of species interaction networks. Ecol. Lett. 15, 1353–1361. https://doi.org/10.1111/ele.12002

`EcologicalNetworks.βos`

— Method`βos(X::T, Y::T) where {T<:UnipartiteNetwork}`

Overlapping species (unipartite)

**References**

Canard, E.F., Mouquet, N., Mouillot, D., Stanko, M., Miklisova, D., Gravel, D.,

- Empirical evaluation of neutral interactions in host-parasite networks.

The American Naturalist 183, 468–479. https://doi.org/10.1086/675363

Poisot, T., Canard, E., Mouillot, D., Mouquet, N., Gravel, D., 2012. The dissimilarity of species interaction networks. Ecol. Lett. 15, 1353–1361. https://doi.org/10.1111/ele.12002

`EcologicalNetworks.βs`

— Method`βs(X::T, Y::T; dims::Union{Nothing,Integer}=nothing) where {T<:BinaryNetwork}`

Components of β-diversity as measured on species.

**References**

Koleff, P., Gaston, K.J., Lennon, J.J., 2003. Measuring beta diversity for presence–absence data. Journal of Animal Ecology 72, 367–382. https://doi.org/10.1046/j.1365-2656.2003.00710.x

`EcologicalNetworks.βwn`

— Method`βwn(X::T, Y::T) where {T<:BinaryNetwork}`

Whole network

**References**

Canard, E.F., Mouquet, N., Mouillot, D., Stanko, M., Miklisova, D., Gravel, D.,

- Empirical evaluation of neutral interactions in host-parasite networks.

The American Naturalist 183, 468–479. https://doi.org/10.1086/675363

Poisot, T., Canard, E., Mouillot, D., Mouquet, N., Gravel, D., 2012. The dissimilarity of species interaction networks. Ecol. Lett. 15, 1353–1361. https://doi.org/10.1111/ele.12002

`EcologicalNetworks.η`

— Method`η(N::T, dims::Union{Nothing,Integer}=nothing) where {T <: Union{BipartiteNetwork, BipartiteProbaNetwork}}`

Returns the nestedness of a margin of the network, using η. The second argument can be `1`

(for nestedness of rows/top level) or `2`

(for nestedness of columns/bottom level). Leaving it at `nothing`

will measure the nestedness of the entire network.

**References**

Bastolla, U., Fortuna, M.A., Pascual-García, A., Ferrera, A., Luque, B., Bascompte, J., 2009. The architecture of mutualistic networks minimizes competition and increases biodiversity. Nature 458, 1018–1020. https://doi.org/10.1038/nature07950

`EcologicalNetworks.η_axis`

— MethodNestedness of a single axis (called internally by `η`

)

`EcologicalNetworks.ρ`

— Method`ρ(N::T; varargs...) where {T <: BipartiteNetwork}`

Bipartite version of the spectral radius. In practice, this casts the network into its unipartite representation, since the spectral radius only makes sense for square matrices.

`EcologicalNetworks.ρ`

— Method`ρ(N::T; range=EcologicalNetworks.ρ_ska) where {T <: UnipartiteNetwork}`

Returns the spectral radius (the absolute value of the largest real part of the eigenvalues of the adjacency matrix) of any unipartite network whose interactions are positive or null. The spectral radius is measured on the mirrored version of the matrix, so that an interaction from i to j also implies an interaction from j to i.

Note that the spectral radius has been suggested as a measure of nestedness by Staniczenko *et al.* (2013). Phillips (2011) uses it as a measure of the ability of a system to dampen or absorb perturbations.

**Maximal values**

The spectral radius is sensitive to network size, and to a certain extent to the number of links. The keyword argument `range`

will divide return a ranged version of the spectral radius, so that it is expressed relatively to its maximal value. The `range`

argument takes a *function*, which requires two arguments: the network (which must be unipartite), and the value of the spectral radius.

Options that come with `EcologicalNetworks.jl`

(where L is the number of links and S the number of nodes) are:

`EcologicalNetworks.ρ_phillips`

: divides by the square root of (2L(S-1))/S, as in Phillips (20110)`EcologicalNetworks.ρ_ska`

: divides by the square root of L, as in Staniczenko*et al.*(2013) - this is the**default**, and has an upper bound of the square root of the number of links`EcologicalNetworks.ρ_raw`

: returns the raw value

**References**

Phillips, J.D., 2011. The structure of ecological state transitions: Amplification, synchronization, and constraints in responses to environmental change. Ecological Complexity, 8, 336–346. https://doi.org/10.1016/j.ecocom.2011.07.004

Staniczenko, P.P.A., Kopp, J.C., Allesina, S., 2013. The ghost of nestedness in ecological networks. Nat Commun 4, 1391. https://doi.org/10.1038/ncomms2422

`EcologicalNetworks.σ_in`

— Method`σ_in(N::AbstractUnipartiteNetwork)`

Computes the standard deviation of the ingoing weighted degree of an unipartite network.

`EcologicalNetworks.σ_out`

— Method`σ_out(N::AbstractUnipartiteNetwork)`

Computes the standard deviation of the outgoing weighted degree of an unipartite network.

`LinearAlgebra.svd`

— Method`LinearAlgebra.svd(N::T) where {T <: AbstractEcologicalNetwork}`

SVD of a network (i.e. SVD of the adjacency matrix)

`Random.shuffle!`

— Method`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`

— Method`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

`StatsBase.sample`

— Method`sample(N::T, n::Int64) where {T<:AbstractBipartiteNetwork}`

Same thing as `sample`

but with a single species number, to return a bipartite network of equal richness on both sides. This is not a very good way to sample a bipartite network.

`StatsBase.sample`

— Method`sample(N::T, n::Int64) where {T<:AbstractUnipartiteNetwork}`

Samples a sub-network from a unipartite network. `n`

is the number of species to have in the sampled network. This functions makes *no* attempt to ensure that the network is not degenerate, or even has a single interaction. This is the recommended way to sample a unipartite network.

`StatsBase.sample`

— Method`sample(N::T, n::Tuple{Int64,Int64}) where {T<:AbstractBipartiteNetwork}`

Samples a sub-network from a bipartite network. `n`

is the size of the network to return, *i.e.* number of top and bottom species. This functions makes *no* attempt to ensure that the network is not degenerate, or even has a single interaction.

This is the recommended way to sample a bipartite network.

`StatsBase.sample`

— Method`sample(N::T, n::Tuple{Int64,Int64}) where {T<:AbstractUnipartiteNetwork}`

Same as `sample`

but called with `(n,n)`

instead of a species number. Note that this will fail if the size requested is not square. This is not a really good way to sample a unipartite network.

`StatsBase.sample`

— Method`sample(N::T, n::Tuple{Int64}) where {T<:AbstractBipartiteNetwork}`

Same as `sample`

but with a single species number given as `(n,)`

, to return a bipartite network of equal richness on both sides. This is not a very good way to sample a bipartite network.

`StatsBase.sample`

— Method`sample(N::T, n::Tuple{Int64}) where {T<:AbstractUnipartiteNetwork}`

Same as `sample`

, but work when called with `(n,)`

instead of a species number. This is an accepted way to sample a unipartite network.