Merge pull request #62 from PoisotLab/mdc/docs

Docs code runs with @example macro

docs/src/bibliography.md

@@ -0,0 +1,4 @@
+# References
+
+```@bibliography
+```

docs/src/vignettes/entropize.md

@@ -6,7 +6,7 @@ values, as opposed to *absolute* values. In this vignette, we will walk through
 an example using the `entropize` function to convert raw data to entropy values. 
 
 
-```
+```@example 1
 using BiodiversityObservationNetworks
 using NeutralLandscapes
 using Plots
@@ -19,15 +19,15 @@ using Plots
 
 We start by generating a random matrix of measurements:
 
-```
+```@example 1
 measurements = rand(MidpointDisplacement(), (200, 200)) .* 100
 heatmap(measurements)
 ```
 
 Using the `entropize` function will convert these values into entropy at the
 pixel scale: 
 
-```
+```@example 1
 U = entropize(measurements)
 heatmap(U')
 ```
@@ -36,7 +36,7 @@ The values closest to the median of the distribution have the highest entropy, a
 
 We can use `entropize` as part of a pipeline, and overlay the points optimized based on entropy on the measurement map:
 
-```
+```@example 1
 locations =
     measurements |> entropize |> seed(BalancedAcceptance(; numpoints = 100)) |> first
 heatmap(U')

docs/src/vignettes/overview.md

@@ -5,7 +5,7 @@ by generating a random uncertainty matrix, and then using a *seeder* and a
 *refiner* to decide which locations should be sampled in order to gain more
 insights about the process generating this entropy. 
 
-```
+```@example 1
 using BiodiversityObservationNetworks
 using NeutralLandscapes
 using Plots
@@ -15,7 +15,7 @@ In order to simplify the process, we will use the *NeutralLandscapes* package to
 generate a 100×100 pixels landscape, where each cell represents the entropy (or
 information content) in a unit we can sample:
 
-```
+```@example 1
 U = rand(MidpointDisplacement(0.5), (100, 100))
 heatmap(U'; aspectratio = 1, frame = :none, c = :lapaz)
 ```
@@ -30,7 +30,7 @@ less) uncertainty. To start with, we will extract 200 candidate points, *i.e.*
 200 possible locations which will then be refined. 
 
 
-```
+```@example 1
 pack = seed(BalancedAcceptance(; numpoints = 200), U);
 ```
 
@@ -39,7 +39,7 @@ always a tuple, storing in the first position a vector of `CartesianIndex`
 elements, and in the second position the matrix given as input. We can have a
 look at the first five points: 
 
-```
+```@example 1
 first(pack)[1:5]
 ```
 
@@ -53,7 +53,7 @@ candidate proposal, we can further refine it using a `BONRefiner` -- in this
 case, `AdaptiveSpatial`, which performs adaptive spatial sampling (maximizing
 the distribution of entropy while minimizing spatial auto-correlation).
 
-```
+```@example 1
 candidates, uncertainty = pack
 locations, _ = refine(candidates, AdaptiveSpatial(; numpoints = 50), uncertainty)
 locations[1:5]
@@ -70,7 +70,7 @@ the content of the candidate pool of points. In addition to this syntax, both
 functions have a curried version that allows chaining them together using pipes
 (`|>`):
 
-```
+```@example 1
 locations =
     U |>
     seed(BalancedAcceptance(; numpoints = 200)) |>
@@ -82,7 +82,7 @@ This works because `seed` and `refine` have curried versions that can be used
 directly in a pipeline. Proposed sampling locations can then be overlayed onto
 the original uncertainty matrix: 
 
-```
+```@example 1
 plt = heatmap(U'; aspectratio = 1, frame = :none, c = :lapaz)
 scatter!(plt, [x[1] for x in locations], [x[2] for x in locations], ms=2.5, mc=:white, label="")
 ```

docs/src/vignettes/uniqueness.md

@@ -7,22 +7,18 @@ environmental values.
 
 To do this, we use a `BONRefiner` called `Uniqueness`. We'll start by loading the required packages. 
 
-```
+```@example 1
 using BiodiversityObservationNetworks
 using SpeciesDistributionToolkit
 using StatsBase
 using NeutralLandscapes
 using Plots
 ```
 
-!!! warning "Consider setting your SDMLAYERS_PATH" When accessing data using
-    `SimpleSDMDatasets.jl`, it is best to set the `SDM_LAYERSPATH` environmental
-    variable to tell `SimpleSDMDatasets.jl` where to download data. This can be
-    done by setting `ENV["SDMLAYERS_PATH"] = "/home/user/Data/"` or similar in
-    the `~/.julia/etc/julia/startup.jl` file. (Note this will be different
-    depending on where `julia` is installed.)
+!!! warning "Consider setting your SDMLAYERS_PATH" 
+    When accessing data using `SimpleSDMDatasets.jl`, it is best to set the `SDM_LAYERSPATH` environmental variable to tell `SimpleSDMDatasets.jl` where to download data. This can be done by setting `ENV["SDMLAYERS_PATH"] = "/home/user/Data/"` or similar in the `~/.julia/etc/julia/startup.jl` file. (Note this will be different depending on where `julia` is installed.)
 
-```
+```@example 1
 bbox = (left=-83.0, bottom=46.4, right=-55.2, top=63.7);
 temp, precip, elevation = 
     convert(Float32, SimpleSDMPredictor(RasterData(WorldClim2, AverageTemperature); bbox...)),
@@ -32,26 +28,26 @@ temp, precip, elevation =
 
 Now we'll use the `stack` function to combine our four environmental layers into a single, 3-dimensional array, which we'll pass to our `Uniqueness` refiner.
 
-```
+```@example 1
 layers = BiodiversityObservationNetworks.stack([temp,precip,elevation]);
 ```
 
 this requires NeutralLandscapes v0.1.2
 
-```
+```@example 1
 uncert = rand(MidpointDisplacement(0.8), size(temp), mask=temp);
 heatmap(uncert, aspectratio=1, frame=:box) 
 ```
 
 Now we'll get a set of candidate points from a BalancedAcceptance seeder that has no bias toward higher uncertainty values.
 
-```
+```@example 1
 candpts, uncert = uncert |> seed(BalancedAcceptance(numpoints=100, α=0.0)); 
 ```
 
 Now we'll `refine` our `100` candidate points down to the 30 most environmentally unique.
 
-```
+```@example 1
 finalpts, uncert = refine(candpts, Uniqueness(;numpoints=30, layers=layers), uncert)
 
 heatmap(uncert)