From 9385dda75d8022034d785a826493529292efc52f Mon Sep 17 00:00:00 2001 From: "michael d. catchen" Date: Fri, 19 Apr 2024 16:00:57 -0400 Subject: [PATCH] :pencil: docs using DocumenterMarkdown --- docs/BONs.bib | 0 docs/Project.toml | 13 ++++- docs/make.jl | 45 ++++++--------- docs/mkdocs.yml | 36 ++++++++++++ docs/src/vignettes/entropize.jl | 47 ---------------- docs/src/vignettes/overview.jl | 77 -------------------------- docs/src/vignettes/uniqueness.jl | 50 ----------------- src/BiodiversityObservationNetworks.jl | 4 +- 8 files changed, 64 insertions(+), 208 deletions(-) create mode 100644 docs/BONs.bib create mode 100644 docs/mkdocs.yml delete mode 100644 docs/src/vignettes/entropize.jl delete mode 100644 docs/src/vignettes/overview.jl delete mode 100644 docs/src/vignettes/uniqueness.jl diff --git a/docs/BONs.bib b/docs/BONs.bib new file mode 100644 index 0000000..e69de29 diff --git a/docs/Project.toml b/docs/Project.toml index de913ce..90bca82 100644 --- a/docs/Project.toml +++ b/docs/Project.toml @@ -1,11 +1,18 @@ [deps] +Distributions = "31c24e10-a181-5473-b8eb-7969acd0382f" Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4" +DocumenterCitations = "daee34ce-89f3-4625-b898-19384cb65244" +DocumenterMarkdown = "997ab1e6-3595-5248-9280-8efb232c3433" DocumenterTools = "35a29f4d-8980-5a13-9543-d66fff28ecb8" -Literate = "98b081ad-f1c9-55d3-8b20-4c87d4299306" +HaltonSequences = "13907d55-377f-55d6-a9d6-25ac19e11b95" +HiGHS = "87dc4568-4c63-4d18-b0c0-bb2238e4078b" +JuMP = "4076af6c-e467-56ae-b986-b466b2749572" +LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e" NeutralLandscapes = "71847384-8354-4223-ac08-659a5128069f" -Optim = "429524aa-4258-5aef-a3af-852621145aeb" Plots = "91a5bcdd-55d7-5caf-9e0b-520d859cae80" +ProgressMeter = "92933f4c-e287-5a05-a399-4b506db050ca" +Random = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c" SliceMap = "82cb661a-3f19-5665-9e27-df437c7e54c8" +SpecialFunctions = "276daf66-3868-5448-9aa4-cd146d93841b" SpeciesDistributionToolkit = "72b53823-5c0b-4575-ad0e-8e97227ad13b" StatsBase = "2913bbd2-ae8a-5f71-8c99-4fb6c76f3a91" -Zygote = "e88e6eb3-aa80-5325-afca-941959d7151f" diff --git a/docs/make.jl b/docs/make.jl index 3c5f1de..89eee49 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -1,40 +1,27 @@ -using Documenter, BiodiversityObservationNetworks -import Literate +push!(LOAD_PATH, "../src/") -# For GR docs bug -ENV["GKSwstype"] = "100" +using Documenter +using DocumenterCitations +using DocumenterMarkdown +using BiodiversityObservationNetworks -vignettes = filter( - endswith(".jl"), - readdir(joinpath(@__DIR__, "src", "vignettes"); join = true, sort = true), -) -for vignette in vignettes - Literate.markdown( - vignette, - joinpath(@__DIR__, "src", "vignettes"); - config = Dict("credit" => false, "execute" => true), - ) -end +bibliography = CitationBibliography(joinpath(@__DIR__, "BONs.bib")) -makedocs(; - sitename = "BiodiversityObservationNetworks", - authors = "M.D. Catchen, Timothée Poisot, Kari Norman, Hana Mayall, Tom Malpas", +makedocs( + bibliography; + sitename = "BiodiversityObservationNetwork.jl", + authors = "Michael D. Catchen, Timothée Poisot, Kari Norman, Hana Mayall, Tom Malpas", modules = [BiodiversityObservationNetworks], - pages = [ - "Index" => "index.md", - "Vignettes" => [ - "Overview" => "vignettes/overview.md", - "Entropy" => "vignettes/entropize.md", - "Environmental uniqueness" => "vignettes/uniqueness.md", - ], - ], - checkdocs = :all, - warnonly = true, - format = Documenter.HTMLWriter.HTML(;size_threshold= nothing) + format = Markdown(), + ) + deploydocs(; + deps = Deps.pip("mkdocs", "pygments", "python-markdown-math", "mkdocs-material"), repo = "github.com/PoisotLab/BiodiversityObservationNetworks.jl.git", devbranch = "main", + make = () -> run(`mkdocs build`), + target = "site", push_preview = true, ) diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml new file mode 100644 index 0000000..ccf1cc0 --- /dev/null +++ b/docs/mkdocs.yml @@ -0,0 +1,36 @@ +site_name: BiodiversityObservationNetworks.jl +repo_url: https://github.com/PoisotLab/BiodiversityObservationNetworks.jl +site_description: Julia package +site_author: Michael D. Catchen + +theme: + name: material + logo: assets/logo.png + palette: + scheme: default + primary: teal + accent: light blue + +extra_css: + - assets/Documenter.css + +extra_javascript: + - https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js?config=TeX-AMS_HTML + - assets/mathjaxhelper.js + +markdown_extensions: + - extra + - tables + - fenced_code + - admonition + - pymdownx.details + - pymdownx.superfences + +docs_dir: 'build' + +nav: + - Home: index.md + - Vignettes: + - Overview: assets/overview.md + - Entropize: assets/entropize.md + - Uniqueness.jl: assets/uniqueness.md \ No newline at end of file diff --git a/docs/src/vignettes/entropize.jl b/docs/src/vignettes/entropize.jl deleted file mode 100644 index aaddf68..0000000 --- a/docs/src/vignettes/entropize.jl +++ /dev/null @@ -1,47 +0,0 @@ -# # Getting the entropy matrix - -# For some applications, we want to place points to capture the maximum amount -# of information, which is to say that we want to sample a balance of *entropy* -# 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. - -using BiodiversityObservationNetworks -using NeutralLandscapes -using Plots - -# !!! warning "Entropy is problem-specific" -# The solution presented in this vignette is a least-assumption solution -# based on the empirical values given in a matrix of measurements. In a lot -# of situations, this is not the entropy that you want. For example, if your -# pixels are storing probabilities of Bernoulli events, you can directly use -# the entropy of the events in the entropy matrix. - -# We start by generating a random matrix of measurements: - -measurements = rand(MidpointDisplacement(), (200, 200)) .* 100 -heatmap(measurements') - -# Using the `entropize` function will convert these values into entropy at the -# pixel scale: - -U = entropize(measurements) -heatmap(U') - -# The values closest to the median of the distribution have the highest entropy, -# and the values closest to its extrema have an entropy of 0. The entropy matrix -# is guaranteed to have values on the unit interval. - -# We can use `entropize` as part of a pipeline, and overlay the points optimized -# based on entropy on the measurement map: - -locations = - measurements |> entropize |> seed(BalancedAcceptance(; numpoints = 100)) |> first -heatmap(U') -scatter!( - [x[1] for x in locations], - [x[2] for x in locations]; - ms = 2.5, - mc = :white, - label = "", -) \ No newline at end of file diff --git a/docs/src/vignettes/overview.jl b/docs/src/vignettes/overview.jl deleted file mode 100644 index 0cdeec0..0000000 --- a/docs/src/vignettes/overview.jl +++ /dev/null @@ -1,77 +0,0 @@ -# # An introduction to BiodiversityObservationNetworks - -# In this vignette, we will walk through the basic functionalities of the -# package, 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. - -using BiodiversityObservationNetworks -using NeutralLandscapes -using Plots - -# 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: - -U = rand(MidpointDisplacement(0.5), (100, 100)) -heatmap(U'; aspectratio = 1, frame = :none, c = :lapaz) - -# In practice, this uncertainty matrix is likely to be derived from an -# application of the hyper-parameters optimization step, which is detailed in -# other vignettes. - -# The first step of defining a series of locations to sample is to use a -# `BONSeeder`, which will generate a number of relatively coarse proposals that -# cover the entire landscape, and have a balanced distribution in space. We do -# so using the `BalancedAcceptance` sampler, which can be tweaked to capture -# more (or less) uncertainty. To start with, we will extract 200 candidate -# points, *i.e.* 200 possible locations which will then be refined. - -pack = seed(BalancedAcceptance(; numpoints = 200), U); - -# The output of a `BONSampler` (whether at the seeding or refinement step) is -# 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: - -first(pack)[1:5] - -# Although returning the input matrix may seem redundant, it actually allows to -# chain samplers together to build pipelines that take a matrix as input, and -# return a set of places to sample as outputs; an example is given below. - -# The positions of locations to sample are given as a vector of -# `CartesianIndex`, which are coordinates in the uncertainty matrix. Once we -# have generated a 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). - -candidates, uncertainty = pack -locations, _ = refine(candidates, AdaptiveSpatial(; numpoints = 50), uncertainty) -locations[1:5] - -# The reason we start from a candidate set of points is that some algorithms -# struggle with full landscapes, and work much better with a sub-sample of them. -# There is no hard rule (or no heuristic) to get a sense for how many points -# should be generated at the seeding step, and so experimentation is a must! - -# The previous code examples used a version of the `seed` and `refine` functions -# that is very useful if you want to change arguments between steps, or examine -# 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 (`|>`): - -locations = - U |> - seed(BalancedAcceptance(; numpoints = 200)) |> - refine(AdaptiveSpatial(; numpoints = 50)) |> - first - -locations[1:5] - -# 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: - -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="") \ No newline at end of file diff --git a/docs/src/vignettes/uniqueness.jl b/docs/src/vignettes/uniqueness.jl deleted file mode 100644 index 0a7e27f..0000000 --- a/docs/src/vignettes/uniqueness.jl +++ /dev/null @@ -1,50 +0,0 @@ -# # Selecting environmentally unique locations - -# For some applications, we want to sample a set of locations that cover a broad -# range of values in environment space. Another way to rephrase this problem is -# to say we want to find the set of points with the _least_ covariance in their -# environmental values. - -# To do this, we use a `BONRefiner` called `Uniqueness`. We'll start by loading -# the required packages. - -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.) - -bbox = (left=-83.0, bottom=46.4, right=-55.2, top=63.7); -temp, precip, elevation = - convert(Float32, SimpleSDMPredictor(RasterData(WorldClim2, AverageTemperature); bbox...)), - convert(Float32, SimpleSDMPredictor(RasterData(WorldClim2, Precipitation); bbox...)), - convert(Float32, SimpleSDMPredictor(RasterData(WorldClim2, Elevation); bbox...)); - -# 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. - -layers = BiodiversityObservationNetworks.stack([temp,precip,elevation]); - - -# this requires NeutralLandscapes v0.1.2 -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. -candpts, uncert = uncert |> seed(BalancedAcceptance(numpoints=100, α=0.0)); - -# Now we'll `refine` our `100` candidate points down to the 30 most -# environmentally unique. -finalpts, uncert = refine(candpts, Uniqueness(;numpoints=30, layers=layers), uncert) - -heatmap(uncert) -scatter!([p[2] for p in candpts], [p[1] for p in candpts], fa=0.0, msc=:white, label="Candidate Points") -scatter!([p[2] for p in finalpts], [p[1] for p in finalpts], c=:dodgerblue, msc=:white, label="Selected Points") \ No newline at end of file diff --git a/src/BiodiversityObservationNetworks.jl b/src/BiodiversityObservationNetworks.jl index fe384eb..0b1942a 100644 --- a/src/BiodiversityObservationNetworks.jl +++ b/src/BiodiversityObservationNetworks.jl @@ -42,11 +42,11 @@ export optimize include("utils.jl") export stack, squish, _squish, _norm -using Requires +#=using Requires function __init__() @require SpeciesDistributionToolkit="72b53823-5c0b-4575-ad0e-8e97227ad13b" include(joinpath("integrations", "simplesdms.jl")) @require Zygote="e88e6eb3-aa80-5325-afca-941959d7151f" include(joinpath("integrations", "zygote.jl")) -end +end=#