Merge pull request #28 from EcoJulia/ts/intro

Vignette: Introduction

.gitignore

@@ -25,3 +25,6 @@ Manifest.toml
 
 # vscode user settings
 .vscode/
+
+# MacOS nonsense
+.DS_Store

docs/make.jl

@@ -5,7 +5,9 @@ using Literate
 # Generate the vignettes using Literate
 vignettes_dir = joinpath("docs", "src", "vignettes")
 for vignette in readdir(vignettes_dir)
-    Literate.markdown(joinpath(vignettes_dir, vignette), vignettes_dir; credit=false)
+    if occursin(".jl", vignette)
+        Literate.markdown(joinpath(vignettes_dir, vignette), vignettes_dir; credit=false)
+    end
 end
 
 makedocs(
@@ -28,4 +30,8 @@ deploydocs(
     repo="github.com/EcoJulia/SpatialBoundaries.jl.git",
     devbranch="main",
     push_preview=true
-)
+)
+
+readdir(vignettes_dir)[1] == ".jl"
+
+occursin(".jl", readdir(vignettes_dir)[1])

docs/src/vignettes/introduction.jl

@@ -1,8 +1,24 @@
 # # Introduction
 
-# In this example, we will see how the `SpatialBoundaries.jl` package works, by
-# taking a random mid-point displacement landscape, and measuring its rate and
-# direction of change.
+# Broadly the Wombling algorthim traverses a 'landscape' (for example species
+# richness at different degree squares) and describes the the landscape in terms
+# of the _Rate of Change (`m`)_ (think slope/gradient) and _Direction of Change
+# (`θ`)_ (direction of slope). This process is outlined in the figure below.
+
+# ![image info](assets/fig_concept.png)
+
+# Both rate and direction of change are calculated interpolating points in a
+# given search window which (depending on how the points are arranged in space),
+# can be done in two ways. 1) **Lattice Wombling:** For points that are
+# regularly arranged in space the search window is 2 x 2 points. 2)
+# **Triangulation Wombling:** For points that irregularly arranged in space
+# nearest neigbours are found using delaunay triangualtion and interpolation is
+# between 3 points.
+
+# In this example, we will see how the `SpatialBoundaries.jl` package works (as
+# well as interpreting the rates and direction of change), by taking a random
+# mid-point displacement landscape, and measuring its rate and direction of
+# change.
 
 using SpatialBoundaries
 using NeutralLandscapes
@@ -33,14 +49,35 @@ W = wombling(landscape);
 # The resulting `LatticeWomble` object has fields for the rate of change (`m`),
 # the direction of change in degrees (`θ`), and the values of the centers of the
 # cells at `x` and `y` (note that the grid of rates of change is one cell
-# smaller than the original grid!).
+# smaller than the original grid!). These points are in a grid so the **Lattice
+# Wombling** function was used - note that `wombling()` will select the
+# appropriate algorithm based on data input. (**TK** link to a triangulation
+# vignette)
 
 # Let's have a look at the rate of change:
 
 heatmap(W.m, c=:bilbao, clim=(0, maximum(W.m)))
 
+# The rate of change informs us on the potential for there to be a boundary
+# (zone of change) within a window. Cells with a high rate of change are
+# indicative of large differences (changes) in the landscape 'topology' and are
+# suggestive of a boundary as we shift from one 'state' to another.
+
 # The *direction* of change is also given, and is expressed a *wind* direction;
 # for instance, an angle of 180° means that the value is smaller in the South,
 # and larger in the North:
 
-heatmap(W.θ, c=:brocO, clim=(0., 360.))
+heatmap(W.θ, c=:brocO, clim=(0., 360.))
+
+# The direction of change is _not_ the direction the boundary would be if you
+# were to draw it on the landscape but rather the direction the rate of change
+# is 'moving in'. This means it is possible to think of and use the direction of
+# change independently of caluclating boundaries _per se_ and can be used to
+# inform how the landscape is behaving/changing in a more 'continuous' way as
+# opposed to discrete zones/boundaries. For example if changes in species
+# richness are more gradual (rate of change is near constant) but the the
+# direction of change is consistently South-North (i.e. 180°) we can still infer
+# that species richness is 'uniformly' increasing in a South-North direction.
+
+# A note on outputs: The new *x* and *y* co-ordinates correspond to latitude and
+# longitude respectively.