Resilience

Manifest.toml

@@ -16,10 +16,10 @@ uuid = "9e28174c-4ba2-5203-b857-d8d62c4213ee"
 version = "0.8.10"
 
 [[BinaryProvider]]
-deps = ["Libdl", "Pkg", "SHA", "Test"]
-git-tree-sha1 = "055eb2690182ebc31087859c3dd8598371d3ef9e"
+deps = ["Libdl", "SHA"]
+git-tree-sha1 = "c7361ce8a2129f20b0e05a89f7070820cfed6648"
 uuid = "b99e7846-7c00-51b0-8f62-c81ae34c0232"
-version = "0.5.3"
+version = "0.5.4"
 
 [[Combinatorics]]
 deps = ["LinearAlgebra", "Polynomials", "Test"]
@@ -95,9 +95,9 @@ version = "1.1.0"
 
 [[PDMats]]
 deps = ["Arpack", "LinearAlgebra", "SparseArrays", "SuiteSparse", "Test"]
-git-tree-sha1 = "b6c91fc0ab970c0563cbbe69af18d741a49ce551"
+git-tree-sha1 = "8b68513175b2dc4023a564cb0e917ce90e74fd69"
 uuid = "90014a1f-27ba-587c-ab20-58faa44d9150"
-version = "0.9.6"
+version = "0.9.7"
 
 [[Pkg]]
 deps = ["Dates", "LibGit2", "Markdown", "Printf", "REPL", "Random", "SHA", "UUIDs"]

docs/make.jl

@@ -26,8 +26,9 @@ makedocs(
             "Centrality and paths" => "properties/paths.md",
             "Overlap and similarity" => "properties/overlap.md",
             "Null models" => "properties/nullmodels.md",
+            "Beta-diversity" => "properties/betadiversity.md",
+            "Resilience" => "properties/resilience.md"
             "Information theory" => "properties/information.md",
-            "Beta-diversity" => "properties/betadiversity.md"
         ]
     ]
 )

docs/src/properties/resilience.md

@@ -0,0 +1,52 @@
+# Resilience
+
+We provide the metrics proposed by Gao et al (2016) which summarize the global
+behaviour of complex unipartite networks. The dynamics of a system of N components
+(nodes/species) can follow the coupled nonlinear differential equation
+
+$$
+\frac{\text{d}x_i}{\text{d}t} = F(x_i) + \sum_{j=1}^N A_{ij}G(x_i, x_j)
+$$
+
+where the adjacency matrix $$A$$ captures the interaction between the components.
+
+This system can be descibed in 1-D using an effective term
+
+$$
+\frac{\text{d}x_\text{eff}}{\text{d}t} = F(x_\text{eff}) + \beta_\text{eff}G(x_\text{eff}, x_\text{eff})
+$$
+
+with $$\beta_\text{eff}$$ a single resilience parameter which can capture
+the effect of perturbating the system (node/link removal, weight change...).
+This resience parameter can be computed from an `AbstractUnipartiteNetwork`
+using the functions `βeff` or `resilience`.
+
+It can be shown that
+
+$$
+\beta_\text{eff} = \langle s \rangle + \mathcal{S}  \mathcal{H}\,,
+$$
+
+with
+
+- $$\langle s \rangle$$ the average weighted degree (computed using `s_mean`),
+- $$\mathcal{S}$$ the symmetry(computed using `symmetry`),
+- $$\mathcal{H}$$ the heterogenity (computed using `heterogenity`).
+
+
+> Goa, J., Barzael, B. and Barabási 2016. Universal resilience patterns in complex networks.
+> Nature 530(7590), 307-312. doi:10.1038/nature16948
+
+## Available functions
+
+```@docs
+s_in
+s_out
+s_mean
+σ_in
+σ_out
+symmetry
+heterogenity
+βeff
+resilience
+```

src/EcologicalNetworks.jl

@@ -108,6 +108,13 @@ include(joinpath(".", "community/overlap.jl"))
 export overlap
 export AJS, EAJS
 
+# Overlap
+include(joinpath(".", "community/resilience.jl"))
+export βeff, resilience
+export symmetry, heterogenity
+export s_in, s_out, s_mean
+export σ_in, σ_out
+
 # Modularity
 include(joinpath(".", "modularity/utilities.jl"))
 export Q, Qr

src/community/resilience.jl

@@ -0,0 +1,111 @@
+#=
+Some functions from *Universal resilience patterns in complex networks*
+by Gao et al. (2016)
+=#
+
+using StatsBase: mean, std
+
+"""
+    s_in(N::AbstractUnipartiteNetwork)
+
+Computes the vector of incoming weighted degrees of an unipartite network.
+"""
+s_in(N::AbstractUnipartiteNetwork) = sum(N.A, dims=2)
+
+"""
+    s_out(N::AbstractUnipartiteNetwork)
+
+Computes the vector of outgoing weighted degrees of an unipartite network.
+"""
+s_out(N::AbstractUnipartiteNetwork) = sum(N.A, dims=1)'
+
+"""
+    s_mean(N::AbstractUnipartiteNetwork)
+
+Computes the average weighted degree. This is proportional to the (weighted)
+density of interactions.
+"""
+s_mean(N::AbstractUnipartiteNetwork) = sum(N.A) / size(N.A, 1)
+
+"""
+    σ_in(N::AbstractUnipartiteNetwork)
+
+Computes the standard deviation of the ingoing weighted degree of an unipartite
+network.
+"""
+σ_in(N::AbstractUnipartiteNetwork) = std(s_in(N), corrected=false)
+
+"""
+    σ_out(N::AbstractUnipartiteNetwork)
+
+Computes the standard deviation of the outgoing weighted degree of an unipartite
+network.
+"""
+σ_out(N::AbstractUnipartiteNetwork) = std(s_out(N), corrected=false)
+
+"""
+    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
+
+"""
+symmetry(N::AbstractUnipartiteNetwork) = (mean(s_in(N) .* s_out(N)) - mean(s_in(N)) * mean(s_out(N))) / (σ_in(N) * σ_out(N))
+
+"""
+    heterogenity(N::AbstractUnipartiteNetwork)
+
+Computes the heterogenity 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
+
+"""
+heterogenity(N::AbstractUnipartiteNetwork) = (σ_in(N) * σ_out(N)) / s_mean(N)
+
+"""
+    βeff(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
+
+"""
+βeff(N::AbstractUnipartiteNetwork) = dot(s_in(N), s_out(N)) / sum(N.A)
+
+"""
+    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
+
+"""
+resilience(N::AbstractUnipartiteNetwork) = βeff(N)

test/community/resilience.jl

@@ -0,0 +1,42 @@
+module TestResilience
+    using Test, EcologicalNetworks
+
+    A = rand([0, 1, 0.5], 10, 10)
+    N = UnipartiteQuantitativeNetwork(A)
+
+    @assert s_mean(N) ≈ sum(A) / 10
+    @assert s_in(N) ≈ sum(A, dims=2)
+    @assert s_out(N) ≈ sum(A, dims=1)'
+
+    @assert βeff(N) ≈ s_mean(N) + symmetry(N) * heterogenity(N)
+
+    # species only interact with themselves
+    Nid = UnipartiteNetwork([true false false false;
+                              false true false false;
+                              false false true false;
+                              false false false true])
+
+    @assert heterogenity(Nid) ≈ 0.0
+    # @assert symmetry(Nid)   NAN
+
+    # symetric network
+    Nsym = UnipartiteNetwork([false true true true;
+                               true false false false;
+                               true false false false;
+                               true false false false])
+    @assert symmetry(Nsym) ≈ 1.0  # in- and out degree is same
+    @assert heterogenity(Nsym) ≈ 0.5
+
+
+    # asymetric network
+    Nasym = UnipartiteNetwork([false true true true;
+                               false false false false;
+                               false false false false;
+                               false false false false])
+    @assert symmetry(Nasym) ≈ -1.0  # in- and out degree is same
+    @assert heterogenity(Nasym) ≈ 0.75
+
+    v = ones(10) / 10
+    Nhomo = UnipartiteProbabilisticNetwork(v * v')
+    @assert isapprox(heterogenity(Nhomo), 0.0, atol=1e-10)
+end

test/runtests.jl

@@ -25,6 +25,7 @@ my_tests = [
    "community/centrality.jl",
    "community/motifs.jl",
    "community/foodwebs.jl",
+   "community/resilience.jl",
    "betadiversity/operations.jl",
    "betadiversity/partitions.jl",
    "modularity/utilities.jl",