Merge pull request #13 from PoisotLab/doc/annotations

Update the documentation with annotations

docs/src/examples.md

@@ -29,8 +29,8 @@ scatter!(I, Unes, bipartite=true)
 ```@example default
 Umod = web_of_life("M_PA_003")
 I = initial(RandomInitialLayout, Umod)
-for step in 1:4000
-  position!(ForceDirectedLayout(2.5), I, Umod)
+for step in 1:2000
+  position!(ForceDirectedLayout(1.5), I, Umod)
 end
 plot(I, Umod, aspectratio=1)
 scatter!(I, Umod, bipartite=true)
@@ -80,15 +80,18 @@ scatter!(I, Unes, bipartite=true, nodefill=degree(Unes))
 
 ### Size
 
+The size of the nodes can be changed using the `nodesize` argument, which is a
+dictionary mapping species to values. These values are scaled when making the
+figures. Note that in this example we also label the number of the node.
+
 ```@example default
 Unes = web_of_life("M_SD_033")
 I = initial(BipartiteInitialLayout, Unes)
 position!(NestedBipartiteLayout(0.4), I, Unes)
 plot(I, Unes, aspectratio=1)
-scatter!(I, Unes, bipartite=true, nodesize=degree(Unes))
+scatter!(I, Unes, bipartite=true, nodesize=degree(Unes), series_annotations = string.(1:richness(Unes)))
 ```
 
-
 ## Network subsets
 
 One important feature of the package is that the layout can contain *more* nodes
@@ -123,9 +126,38 @@ heatmap(convert(UnipartiteNetwork, Umod))
 
 ## Unravelled layout
 
+The unravelled layout is essentially a scatterplot of network properties with
+interactions drawn as well. This is inspired by [the work of Giulio Valentina
+Dalla Riva on this visualisation][gvdr]. By default, it will compare the
+omnivory index and the trophic level:
+
+[gvdr]: https://github.com/gvdr/unravel
+
 ```@example default
 N = nz_stream_foodweb()[10]
 I = initial(UnravelledInitialLayout, N)
 plot(I, N, lab="", framestyle=:box)
 scatter!(I, N, nodefill=degree(N), colorbar=true, framestyle=:box)
 ```
+
+Because a lot of species will have the same omnivory index, we might want to use
+a slightly different function, which adds some randomness to the omnivory:
+
+```@example default
+N = nz_stream_foodweb()[10]
+I = initial(UnravelledInitialLayout, N)
+
+function random_omnivory(N::T) where {T <: UnipartiteNetwork}
+  o = omnivory(N)
+  for s in species(N)
+    o[s] += (rand()-0.5)*0.1
+  end
+  return o
+end
+
+UL = UnravelledLayout(x=random_omnivory, y=trophic_level)
+position!(UL, I, N)
+
+plot(I, N, lab="", framestyle=:box)
+scatter!(I, N, nodefill=degree(N), colorbar=true, framestyle=:box, mc=:viridis)
+```

src/static.jl

@@ -16,7 +16,13 @@ struct UnravelledLayout{TX<:Function,TY<:Function}
 end
 
 UnravelledLayout() = UnravelledLayout(omnivory, fractional_trophic_level)
+UnravelledLayout(;x=omnivory, y=fractional_trophic_level) = UnravelledLayout(x, y)
 
+"""
+    position!(LA::LT, L::Dict{K,NodePosition}, N::T) where {LT <: UnravelledLayout, T <: AbstractEcologicalNetwork} where {K}
+
+Position species according to the function defined in the `UnravelledLayout`.
+"""
 function position!(LA::LT, L::Dict{K,NodePosition}, N::T) where {LT <: UnravelledLayout, T <: AbstractEcologicalNetwork} where {K}
   X = LA.x(N)
   Y = LA.y(N)
@@ -54,6 +60,11 @@ By default, a `NestedBipartiteLayout` is aligned, centered, and with a spread of
 NestedBipartiteLayout() = NestedBipartiteLayout(true, true, 1.0)
 NestedBipartiteLayout(spread::Float64) = NestedBipartiteLayout(true, true, spread)
 
+"""
+    position!(LA::NestedBipartiteLayout, L::Dict{K,NodePosition}, N::T) where {T <: AbstractBipartiteNetwork} where {K}
+
+Rank species according to their degree.
+"""
 function position!(LA::NestedBipartiteLayout, L::Dict{K,NodePosition}, N::T) where {T <: AbstractBipartiteNetwork} where {K}
     r_top = ordinalrank(collect(values(degree(N; dims=1))); rev=true).-1
     r_bot = ordinalrank(collect(values(degree(N; dims=2))); rev=true).-1