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

All non-probabilistic networks

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

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

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

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

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

A bipartite deterministic network is a matrix of boolean values.

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

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

An unipartite deterministic network is a matrix of boolean values.

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

A unipartite quantitative network is a square matrix of numbers.

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

Returns the inverse of a binary network – interactions that were false become true, and conversely.

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

Adds two quantitative bipartite networks. TODO

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.

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

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.

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.

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.

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.

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

Projects a deterministic bipartite network in its unipartite representation.

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.

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

Projects a probabilistic bipartite network in its unipartite representation.

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

Projects a quantitative bipartite network in its unipartite representation.

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

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

TODO

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

TODO

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

TODO

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

TODO

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.

getindex(N::AbstractEcologicalNetwork, ::Colon, j::T)

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

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.

getindex(N::AbstractEcologicalNetwork, i::T, ::Colon)

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

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.

getindex(N::AbstractEcologicalNetwork, i::T, j::T)

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

getindex(N::AbstractEcologicalNetwork, i::T)

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

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.

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.

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(N::T) where {T <: AbstractEcologicalNetwork}

Returns the interactions in a network (this uses less memory than interactions but is a bit slower).

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(N::T) where {T <: AbstractEcologicalNetwork}

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

permutedims(N::AbstractBipartiteNetwork)

Tranposes the network and returns a copy

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

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

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.

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.

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.

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.

show(io::IO, N::AbstractEcologicalNetwork)

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.

size(N::AbstractEcologicalNetwork, i::Int64)

Return the size of the adjacency matrix of an AbstractEcologicalNetwork object.

size(N::AbstractEcologicalNetwork)

Return the size of the adjacency matrix of an AbstractEcologicalNetwork object.

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.

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.

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.

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

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

KGL01(S::T)

Whittaker

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.

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
  1. https://doi.org/10.12688/f1000research.2-130.v3

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

Variance of a series of additive Bernoulli events

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

Variance of a series of multiplicative Bernoulli events

Internal function

Returns all permutations of the adjacency matrix of a motif.

Internal function

Returns all permutations of the adjacency matrix of a motif.

Expected value of a single Bernoulli event

Simply f(p): p

Variance of a single Bernoulli event

f(p): p(1-p)

Quite crude way of checking that a number is a probability

The two steps are

1. The number should be of the Float64 type
2. The number should belong to [0.0,1.0]

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.

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.

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

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

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

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

cascademodel(N::T) where {T <: UnipartiteNetwork}

Applied to a UnipartiteNetwork return its randomized version.

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

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

centrality_degree(N::UnipartiteNetwork)

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

centrality_eigenvector(N::AbstractUnipartiteNetwork)

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

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.

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

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.

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.

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.

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

• 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

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

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

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

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

degree_in(N::AbstractEcologicalNetwork)

Variance in the ingoing degree

degree_in_var(N::ProbabilisticNetwork)

degree_out(N::AbstractEcologicalNetwork)

Variance in the outgoing degree

degree_out_var(N::ProbabilisticNetwork)

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

Variance in the degree of species in a probabilistic network.

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.

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.

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.

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.

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.

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

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

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.

expected_motif_count(s)

Get the expected number of motifs (and variance) from the output of find_motif 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

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

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

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

• 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

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

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.

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.

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

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

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.

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.

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

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

linkage_density(N::AbstractEcologicalNetwork)

Number of links divided by species richness.

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.

links(N::BinaryNetwork)

Number of non-zero interactions in a deterministic network.

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.

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

• 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

links(N::QuantitativeNetwork)

Number of non-zero interactions in a quantitative network (use sum to get the sum of interaction strengths).

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.

links_var(N::ProbabilisticNetwork)

Expected variance of the number of links for 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

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

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.

mirror(N::T) where {T <: AbstractUnipartiteNetwork}

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

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

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

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

mpnmodel(N::T) where {T<: UnipartiteNetwork}

Applied to UnipartiteNetwork return its randomized version.

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

mutual_information(P::AbstractArray)

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

mutual_information(N::NT) where {NT<:AbstractEcologicalNetwork}

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

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

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

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

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

nestedhierarchymodel(N::T) {T <: UnipartiteNetwork}

Applied to empirical UnipartiteNetwork return its randomized version.

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

nichemodel(S::Int64, C::Float64)

References

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

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.

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.

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.

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

NODF of a single axis

WNODF of a single axis

nodiagonal!(N::AbstractBipartiteNetwork)

Does nothing.

nodiagonal!(N::AbstractUnipartiteNetwork)

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

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.

nodiagonal(N::AbstractUnipartiteNetwork)

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

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

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

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

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.

number_of_paths(N::Unipartite; n::Int64=2)

This returns an array, not a network.

• n (def. 2), the path length

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.

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

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

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.

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.

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

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.

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

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

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.

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.

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.

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.

shortest_path(N::UnipartiteQuantiNetwork; nmax::Int64=50)

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

simplify!{T<:BipartiteNetwork}(N::T)

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

simplify!{T<:BipartiteNetwork}(N::T)

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

simplify!{T<:BipartiteNetwork}(N::T)

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

simplify!(N::UnipartiteNetwork)

Modifies the network to drop all species without an interaction.

simplify!(N::UnipartiteNetwork)

Modifies the network to drop all species without an interaction.

simplify!(N::UnipartiteNetwork)

Modifies the network to drop all species without an interaction.

simplify(N::T) where {T<:AbstractEcoloigcalNetwork}

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

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.

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.

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

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

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.

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.

variation_information(P::AbstractArray)

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

variation_information(N::AbstractEcologicalNetwork)

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

β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.,

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

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

β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.,

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

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

β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

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

Whole network

References

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

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

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

η(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

• 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

Nestedness of a single axis (called internally by η)

ρ(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.

ρ(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:

1. EcologicalNetworks.ρ_phillips: divides by the square root of (2L(S-1))/S, as in Phillips (20110)
2. 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
3. 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

σ_in(N::AbstractUnipartiteNetwork)

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

σ_out(N::AbstractUnipartiteNetwork)

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

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

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

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

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

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.

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.

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.

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.

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.

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.