Merge pull request #142 from PoisotLab/fix-doc-null

update the null doc

.gitignore

@@ -2,3 +2,4 @@ EcologicalNetwork.tar.gz
 docs/build/
 docs/site/
 network.png
+Manifest.toml

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"]

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 <[email protected]>"]
+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"]

docs/make.jl

@@ -1,6 +1,6 @@
 using Pkg
 
-tmp_packages = ["EcologicalNetworksPlots", "Plots"]
+tmp_packages = ["EcologicalNetworksPlots", "Plots", "Documenter"]
 
 push!(LOAD_PATH,"../src/")
 
@@ -11,38 +11,42 @@ Pkg.add.(tmp_packages) # IMPORTANT
 using Documenter
 using EcologicalNetworks
 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

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
 

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.