From 5c7cf1972c38e8d64170e4f8f5483e361bc1d1b1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Poisot?= Date: Mon, 22 Jul 2019 14:28:22 -0400 Subject: [PATCH 1/2] update the null doc --- docs/make.jl | 1 + docs/src/properties/randomization.md | 13 +++++++++++-- 2 files changed, 12 insertions(+), 2 deletions(-) diff --git a/docs/make.jl b/docs/make.jl index 520214f30..dd14bd4fb 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -11,6 +11,7 @@ Pkg.add.(tmp_packages) # IMPORTANT using Documenter using EcologicalNetworks using EcologicalNetworksPlots +using Random makedocs( sitename = "EcologicalNetworks", diff --git a/docs/src/properties/randomization.md b/docs/src/properties/randomization.md index a1ecb3000..119e8ec79 100644 --- a/docs/src/properties/randomization.md +++ b/docs/src/properties/randomization.md @@ -20,14 +20,23 @@ distribution (or connectance) of the network. ```@docs null1 +``` + +```@docs null2 +``` + +```@docs null3 +``` + +```@docs null4 ``` ## Shuffle interactions ```@docs -shuffle! -shuffle +Random.shuffle! +Random.shuffle ``` From 2e5e6060a1547c9cb5198bf85e5192cf79e272d0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Poisot?= Date: Tue, 23 Jul 2019 09:03:26 -0400 Subject: [PATCH 2/2] :memo: update doc --- .gitignore | 1 + Manifest.toml | 8 +- Project.toml | 10 ++- docs/make.jl | 63 +++++++------- docs/src/index.md | 85 ++++++------------- docs/src/properties/nullmodels.md | 74 ---------------- docs/src/properties/resilience.md | 29 +++---- .../randomization.md => random/null.md} | 18 ++-- docs/src/random/structure.md | 67 +++++++++++++++ docs/src/toc.md | 33 ------- docs/src/{ => var}/plots.md | 4 +- 11 files changed, 156 insertions(+), 236 deletions(-) delete mode 100644 docs/src/properties/nullmodels.md rename docs/src/{properties/randomization.md => random/null.md} (88%) create mode 100644 docs/src/random/structure.md delete mode 100644 docs/src/toc.md rename docs/src/{ => var}/plots.md (96%) diff --git a/.gitignore b/.gitignore index e50afcdd4..d6eb88305 100644 --- a/.gitignore +++ b/.gitignore @@ -2,3 +2,4 @@ EcologicalNetwork.tar.gz docs/build/ docs/site/ network.png +Manifest.toml diff --git a/Manifest.toml b/Manifest.toml index c02c8fa2f..90c752b7b 100644 --- a/Manifest.toml +++ b/Manifest.toml @@ -17,9 +17,9 @@ version = "0.8.10" [[BinaryProvider]] deps = ["Libdl", "Logging", "SHA"] -git-tree-sha1 = "8153fd64131cd00a79544bb23788877741f627bb" +git-tree-sha1 = "c7361ce8a2129f20b0e05a89f7070820cfed6648" uuid = "b99e7846-7c00-51b0-8f62-c81ae34c0232" -version = "0.5.5" +version = "0.5.6" [[Combinatorics]] deps = ["LinearAlgebra", "Polynomials", "Test"] @@ -53,9 +53,9 @@ uuid = "8ba89e20-285c-5b6f-9357-94700520ee1b" [[Distributions]] deps = ["LinearAlgebra", "PDMats", "Printf", "QuadGK", "Random", "SpecialFunctions", "Statistics", "StatsBase", "StatsFuns"] -git-tree-sha1 = "56a158bc0abe4af5d4027af2275fde484261ca6d" +git-tree-sha1 = "2f25cc24d4370d9395344a0b8cf7e8d98407c650" uuid = "31c24e10-a181-5473-b8eb-7969acd0382f" -version = "0.19.2" +version = "0.21.0" [[InteractiveUtils]] deps = ["Markdown"] diff --git a/Project.toml b/Project.toml index fe4f7a288..c6528c901 100644 --- a/Project.toml +++ b/Project.toml @@ -1,7 +1,11 @@ name = "EcologicalNetworks" uuid = "f03a62fe-f8ab-5b77-a061-bb599b765229" repo = "https://github.com/PoisotLab/EcologicalNetworks.jl" -version = "0.2.0" +authors = ["Timothée Poisot "] +version = "0.2.1" + +[compat] +julia = "1" [deps] Combinatorics = "861a8166-3701-5b0c-9a16-15d98fcdc6aa" @@ -13,7 +17,9 @@ Random = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c" Requires = "ae029012-a4dd-5104-9daa-d747884805df" Statistics = "10745b16-79ce-11e8-11f9-7d13ad32a3b2" StatsBase = "2913bbd2-ae8a-5f71-8c99-4fb6c76f3a91" -Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40" [extras] Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40" + +[targets] +test = ["Test"] diff --git a/docs/make.jl b/docs/make.jl index dd14bd4fb..87ca0000a 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -1,6 +1,6 @@ using Pkg -tmp_packages = ["EcologicalNetworksPlots", "Plots"] +tmp_packages = ["EcologicalNetworksPlots", "Plots", "Documenter"] push!(LOAD_PATH,"../src/") @@ -14,36 +14,39 @@ using EcologicalNetworksPlots using Random makedocs( - sitename = "EcologicalNetworks", - authors = "Timothée Poisot", - modules = [EcologicalNetworks, EcologicalNetworksPlots], - pages = [ - "Index" => "index.md", - "Interface" => [ - "Types" => "interface/types.md", - "Conversions" => "interface/conversions.md", - "Core functions" => "interface/highlevel.md" - ], - "Network measures" => [ - "Links" => "properties/links.md", - "Modularity" => "properties/modularity.md", - "Nestedness" => "properties/nestedness.md", - "Motifs" => "properties/motifs.md", - "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" - ], - "Plots" => "plots.md" - ] -) + sitename = "EcologicalNetworks", + authors = "Timothée Poisot", + modules = [EcologicalNetworks, EcologicalNetworksPlots], + pages = [ + "Index" => "index.md", + "Interface" => [ + "Types" => "interface/types.md", + "Conversions" => "interface/conversions.md", + "Core functions" => "interface/highlevel.md", + "Plotting" => "var/plots.md" + ], + "Network measures" => [ + "Links" => "properties/links.md", + "Modularity" => "properties/modularity.md", + "Nestedness" => "properties/nestedness.md", + "Motifs" => "properties/motifs.md", + "Centrality and paths" => "properties/paths.md", + "Overlap and similarity" => "properties/overlap.md", + "Beta-diversity" => "properties/betadiversity.md", + "Resilience" => "properties/resilience.md", + "Information theory" => "properties/information.md" + ], + "Random networks" => [ + "Null models" => "random/null.md", + "Structural models" => "random/structure.md" + ] + ] + ) deploydocs( - deps = Deps.pip("pygments", "python-markdown-math"), - repo = "github.com/PoisotLab/EcologicalNetworks.jl.git", - devbranch = "master" -) + deps = Deps.pip("pygments", "python-markdown-math"), + repo = "github.com/PoisotLab/EcologicalNetworks.jl.git", + devbranch = "master" + ) Pkg.rm.(tmp_packages) # IMPORTANT diff --git a/docs/src/index.md b/docs/src/index.md index e18989bf7..4442de064 100644 --- a/docs/src/index.md +++ b/docs/src/index.md @@ -1,15 +1,16 @@ # EcologicalNetworks This package provides a common interface for the analysis of ecological -networks, using `julia`. It is *very* opinionated about the "right" way to do -things, but we have documented our opinions in several publications (see the -references at the bottom of this page). +networks, using `julia`. It is *very* opinionated about the "right" way +to do things, but we have documented our opinions in several publications +(see the references at the bottom of this page, and in the documentation of +all functions). -The package is built around a typesystem for networks, which is intended to +The package is built around a type system for networks, which is intended to capture the different types of data and communities ecologists need to handle. -This makes the package extensible, both by writing additional methods with a -very fine-tuned dispatch, or by adding additional types that should work out of -the box (or be very close to). +This makes the package extensible, both by writing additional methods with +a very fine-tuned dispatch, or by adding additional types that should work +out of the box (or be very close to). This package is a *library* for the analysis of ecological networks. On purpose, we do not provide "wrapper"-type functions that would perform an entire @@ -21,10 +22,11 @@ and it's your job to build the kick-ass spaceship. We tried to avoid making the package into yet another Domain Specific Language. This means that when an operation should be expressed using the julian syntax, we made it this way. Transforming networks from a type to another is done with -`convert`. Random networks are drawn with `rand`. Swapping of interactions is -done with `shuffle`. There is support for slicing of networks, as well as the -entire operations on sets. A lot of methods from `Base` have been overloaded, -and this *should* make the code easy to write and read. +`convert`. Random networks are drawn with `rand`. Swapping of interactions +is done with `shuffle`. There is support for slicing of networks, as well +as the entire operations on sets. A lot of methods from `Base` have been +overloaded, and this *should* make the code easy to write and read, since +it looks almost exactly like any other *Julia* code on arrays. ### Why should I use this package? @@ -53,7 +55,7 @@ package is done on clusters of one sort of the other, and having fewer dependencies means that installation is easier. `EcologicalNetworksPlots` can be installed as with any other Julia package. It -is documented on this website. +is also documented on this website. ### And worse, you forgot my favorite method! @@ -75,10 +77,11 @@ you want to take the square root of a quantitative network, you can overload the import Base: √ function √(N::T) where {T <: QuantitativeNetwork} - # Take the square root of the interaction strength - sqrt_matrix = sqrt.(N.A) - # Return a new network with the correct types - return T(sqrt_matrix, EcologicalNetworks.species_objects(N)...) + @assert all(N.A .> zero(eltype(N.A))) + # Take the square root of the interaction strength + sqrt_matrix = sqrt.(N.A) + # Return a new network with the correct types + return T(sqrt_matrix, EcologicalNetworks.species_objects(N)...) end ~~~ @@ -100,56 +103,18 @@ Networks of Species Interactions ». Biological Reviews (2018), 112540. https://doi.org/10.1111/brv.12433. -We highly recommend we keep it nearby when using the package. A lot of decisions -taken during development are grounded in the analysis of the literature we -conducted over a few years. - -### Network β-diversity - -The analysis of network dissimilarity is done exactly as described in: - -Poisot, Timothée, Elsa Canard, David Mouillot, Nicolas Mouquet, and Dominique -Gravel. “The Dissimilarity of Species Interaction Networks.” Ecology Letters 15, -no. 12 (2012): 1353–1361. https://doi.org/10.1111/ele.12002. - -The measures for β-diversity (and the approach of partitioning variation in -sets) is done exactly as described in: - -Koleff, Patricia, Kevin J. Gaston, and Jack J. Lennon. “Measuring Beta -Diversity for Presence–absence Data.” Journal of Animal Ecology 72, no. 3 -(2003): 367–82. https://doi.org/10.1046/j.1365-2656.2003.00710.x. - -The functions presented in their table are implemented as `KGLXX`, where `XX` is -the number of the function on two digits (*i.e.* the second measure of -β-diversity is `KGL02`). - -### Specificity - -Poisot, Timothee, Elsa Canard, Nicolas Mouquet, and Michael E Hochberg. “A -Comparative Study of Ecological Specialization Estimators.” Methods in Ecology -and Evolution 3, no. 3 (2012): 537–44. -https://doi.org/10.1111/j.2041-210X.2011.00174.x. - -### Probabilistic networks - -Poisot, Timothée, Alyssa R. Cirtwill, Kévin Cazelles, Dominique Gravel, -Marie-Josée Fortin, and Daniel B. Stouffer. “The Structure of Probabilistic -Networks.” Methods in Ecology and Evolution 7, no. 3 (2016): 303–12. -https://doi.org/10.1111/2041-210X.12468. - -### Overlap and complementarity - -Gao, Peng, et John A. Kupfer. « Uncovering food web structure using a novel -trophic similarity measure ». Ecological Informatics 30 (2015): 110‑18. -https://doi.org/10.1016/j.ecoinf.2015.09.013. +We highly recommend we keep it nearby when using the package. A lot of +decisions taken during development are grounded in the analysis of the +literature we conducted over a few years. Anything else is now documented +in the functions themselves. ## How can I contribute? Good question! The easiest way to contribute is to use the package, and [open an issue][issue] -whenever you can't manage to do something, think the syntax is not clear, or the -documentation is confusing. This is seriously one of the best ways to help. +whenever you can't manage to do something, think the syntax is not clear, or +the documentation is confusing. This is in fact one of the best ways to help. [issue]: https://github.com/PoisotLab/EcologicalNetworks.jl/issues diff --git a/docs/src/properties/nullmodels.md b/docs/src/properties/nullmodels.md deleted file mode 100644 index a084adcd9..000000000 --- a/docs/src/properties/nullmodels.md +++ /dev/null @@ -1,74 +0,0 @@ -# Null models - -Randomization of networks is mostly used to perform null hypothesis significance -testing, or to draw random realizations of a probabilistic network. There are -two ways to perform networks randomization: either by shuffling interactions -within the networks while enforcing some constraints (`shuffle`) or by drawing -random samples from a probabilistic network (`rand`). - -## Draw a network from a probabilistic network - -```@docs -rand -``` - -## Generate probabilistic networks from deterministic networks - -These functions generate a probabilistic network from a deterministic network, -where the probability of every interaction is determined by the degree -distribution (or connectance) of the network. - -```@docs -null1 -null2 -null3 -``` - -## Shuffle interactions - -```@docs -shuffle! -shuffle -``` - -## Generate structural network models - -Structure of ecological networks is non-random. Network architecture can have a strong effect on important ecosystem properties (Mougi and Kondoh 2012, Thébault and Fontaine 2010). Many of the structural features of food-webs can be simulated using small number of simple rules. Despite this simplicity these models can often accurately reproduce some of the second order characteristics of empirical food-webs (Stouffer et al. 2005). These characteristics of phenomenological stochastic models allow for their wide applications e.g. to simulate biomass dynamics using dynamical models or study extinction cascades. - -> Mougi, A. and Kondoh, M. (2012) ‘Diversity of Interaction Types and Ecological Community Stability’, Science, 337(6092), pp. 349–351. doi: 10.1126/science.1220529. -> Thébault, E. and Fontaine, C. (2010) ‘Stability of Ecological Communities and the Architecture of Mutualistic and Trophic Networks’, Science, 329(5993), pp. 853–856. doi: 10.1126/science.1188321. -> Stouffer, D. B. et al. (2005) ‘Quantitative Patterns in the Structure of Model and Empirical Food Webs’, Ecology, 86(5), pp. 1301–1311. doi: 10.1890/04-0957. - -Many models with various interactions assignment algorithms have been proposed. `EcologicalNetworks` provides functions to generate random ecological networks of the `UnipartiteNetwork` type. Listed below are those most often used in ecological studies. - -### Cascade model - -This model uses one abstract trophic trait. For any given consumer links can be randomly assigned to a resource species with the trait value smaller than that of a consumer. - -```@docs -cascademodel -``` - -### Niche model - -Niche model extended cascade model by introducing ranges for each consumer. In this model consumers can predate on resources which trait values are within the predators' 'niche' range. - -```@docs -nichemodel -``` - -### Nested hierarchy model - -In order to reproduce more faithfully properties of complex and multidimensional natural nested hierarchy model tries to use simple rules to incorporate also the phylogenetic similarity in resource composition of predators. - -```@docs -nestedhierarchymodel -``` - -### Minimum potential niche model - -This model attempts to explicitly simulate forbidden links in empirical food webs. - -```@docs -mpnmodel -``` diff --git a/docs/src/properties/resilience.md b/docs/src/properties/resilience.md index 9e69e3199..84438eb14 100644 --- a/docs/src/properties/resilience.md +++ b/docs/src/properties/resilience.md @@ -4,34 +4,27 @@ 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) -$$ +$$\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. +where the adjacency matrix $A$ captures the interaction between the +components. This system can be described in 1-D using an effective term -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})$$ -$$ -\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` +with $\beta_\text{eff}$ a single resilience parameter which can capture +the effect of perturbing the system (node/link removal, weight change...). +This resilience 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}\,, -$$ +$$\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 heterogeneity (computed using `heterogeneity`). +- $\langle s \rangle$ the average weighted degree (computed using `s_mean`), +- $\mathcal{S}$ the symmetry(computed using `symmetry`), +- $\mathcal{H}$ the heterogeneity (computed using `heterogeneity`). > Goa, J., Barzael, B. and Barabási 2016. Universal resilience patterns in complex networks. diff --git a/docs/src/properties/randomization.md b/docs/src/random/null.md similarity index 88% rename from docs/src/properties/randomization.md rename to docs/src/random/null.md index 119e8ec79..8a65aa48c 100644 --- a/docs/src/properties/randomization.md +++ b/docs/src/random/null.md @@ -1,4 +1,4 @@ -# Randomization of networks +# Null models Randomization of networks is mostly used to perform null hypothesis significance testing, or to draw random realizations of a probabilistic network. There are @@ -20,23 +20,15 @@ distribution (or connectance) of the network. ```@docs null1 -``` - -```@docs null2 -``` - -```@docs null3 ``` -```@docs -null4 -``` - ## Shuffle interactions ```@docs -Random.shuffle! -Random.shuffle +shuffle! +shuffle ``` + + diff --git a/docs/src/random/structure.md b/docs/src/random/structure.md new file mode 100644 index 000000000..f9900affb --- /dev/null +++ b/docs/src/random/structure.md @@ -0,0 +1,67 @@ +# Structural network models + +Structure of ecological networks is non-random. Network architecture can +have a strong effect on important ecosystem properties (Mougi and Kondoh +2012, Thébault and Fontaine 2010). Many of the structural features of +food-webs can be simulated using small number of simple rules. Despite this +simplicity these models can often accurately reproduce some of the second +order characteristics of empirical food-webs (Stouffer et al. 2005). These +characteristics of phenomenological stochastic models allow for their wide +applications e.g. to simulate biomass dynamics using dynamical models or +study extinction cascades. + +> Mougi, A. and Kondoh, M. (2012) ‘Diversity of Interaction Types and +Ecological Community Stability’, Science, 337(6092), pp. 349–351. doi: +10.1126/science.1220529. + +> Thébault, E. and Fontaine, C. (2010) ‘Stability of Ecological Communities +and the Architecture of Mutualistic and Trophic Networks’, Science, +329(5993), pp. 853–856. doi: 10.1126/science.1188321. + +> Stouffer, D. B. et al. (2005) ‘Quantitative Patterns in the Structure +of Model and Empirical Food Webs’, Ecology, 86(5), pp. 1301–1311. doi: +10.1890/04-0957. + +Many models with various interactions assignment algorithms have been +proposed. `EcologicalNetworks` provides functions to generate random ecological +networks of the `UnipartiteNetwork` type. Listed below are those most often +used in ecological studies. + +## Cascade model + +This model uses one abstract trophic trait. For any given consumer links can +be randomly assigned to a resource species with the trait value smaller than +that of a consumer. + +```@docs +cascademodel +``` + +## Niche model + +Niche model extended cascade model by introducing ranges for each consumer. In +this model consumers can predate on resources which trait values are within +the predators' 'niche' range. + +```@docs +nichemodel +``` + +## Nested hierarchy model + +In order to reproduce more faithfully properties of complex and +multidimensional natural nested hierarchy model tries to use simple rules +to incorporate also the phylogenetic similarity in resource composition +of predators. + +```@docs +nestedhierarchymodel +``` + +## Minimum potential niche model + +This model attempts to explicitly simulate forbidden links in empirical food webs. + +```@docs +mpnmodel +``` diff --git a/docs/src/toc.md b/docs/src/toc.md deleted file mode 100644 index 847b2b341..000000000 --- a/docs/src/toc.md +++ /dev/null @@ -1,33 +0,0 @@ -# Table of contents - -```@contents -Pages = ["index.md"] -Depth = 5 -``` - -## Interface - -```@contents -Pages = [ - "interface/types.md", - "interface/conversions.md", - "interface/highlevel.md" - ] -Depth = 5 -``` - -## Properties - -```@contents -Pages = [ - "properties/links.md", - "properties/modularity.md", - "properties/nestedness.md", - "properties/motifs.md", - "properties/paths.md", - "properties/overlap.md", - "properties/randomization.md", - "properties/betadiversity.md" - ] -Depth = 5 -``` diff --git a/docs/src/plots.md b/docs/src/var/plots.md similarity index 96% rename from docs/src/plots.md rename to docs/src/var/plots.md index 5ff79df5f..b8a4853f4 100644 --- a/docs/src/plots.md +++ b/docs/src/var/plots.md @@ -1,6 +1,6 @@ Plotting functions are part of the `EcologicalNetworksPlot`, which requires -`Plot` to work. - +`Plot` to work. `EcologicalNetworksPlot` can be installed from the central +*Julia* package repository. ## Initial layouts