Merge pull request #120 from EcoJulia/interfaces-iteration

v0.8.0

.github/ISSUE_TEMPLATE/bug.yaml

@@ -0,0 +1,34 @@
+name: Bug Report
+description: File a bug report - this is the type of issue to use if you are fairly sure something is going awfully wrong with the package.
+title: "[Bug]: "
+labels: ["bug", "triage"]
+assignees:
+  - tpoisot
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to fill out this bug report! This is one of the most effective steps in making the project better.
+  - type: input
+    id: contact
+    attributes:
+      label: Contact Details
+      description: How can we get in touch with you if we need more info? This is mostly important if the bug can be reproduced only when using data you are not able to share publicly.
+      placeholder: ex. [email protected]
+    validations:
+      required: false
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened?
+      description: Also tell us, what did you expect to happen?
+      placeholder: Tell us what you see!
+      value: "A bug happened!"
+    validations:
+      required: true
+  - type: textarea
+    id: logs
+    attributes:
+      label: Stacktrace
+      description: Please copy and paste the stacktrace that give the error message.
+      render: shell

.github/workflows/CI.yml

@@ -30,6 +30,9 @@ jobs:
           arch: ${{ matrix.arch }}
       - uses: julia-actions/julia-buildpkg@latest
       - uses: julia-actions/julia-runtest@latest
+        env:
+          PYTHON: ""
+          GKSwstype: "100"
       - uses: julia-actions/julia-processcoverage@v1
       - uses: codecov/codecov-action@v1
         with:

.github/workflows/CompatHelper.yml

@@ -9,7 +9,7 @@ jobs:
     runs-on: ${{ matrix.os }}
     strategy:
       matrix:
-        julia-version: [1.5.0]
+        julia-version: [1.6.3]
         julia-arch: [x86]
         os: [ubuntu-latest]
     steps:

.github/workflows/Documentation.yml

@@ -15,10 +15,14 @@ jobs:
       - uses: actions/checkout@v2
       - uses: julia-actions/setup-julia@latest
         with:
-          version: '1.5'
+          version: '1.6'
       - name: Install dependencies
         run: julia --project=docs/ -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate()'
+        env: 
+          PYTHON: ""
+          GKSwstype: "100"
       - name: Build and deploy
         env:
+          GKSwstype: "100"
           GITHUB_TOKEN: ${{ secrets.TOKEN }} # For authentication with GitHub Actions token
         run: julia --project=docs/ docs/make.jl

Project.toml

@@ -1,20 +1,30 @@
 name = "SimpleSDMLayers"
 uuid = "2c645270-77db-11e9-22c3-0f302a89c64c"
 authors = ["Timothée Poisot <[email protected]>", "Gabriel Dansereau <[email protected]>"]
-version = "0.7.1"
+version = "0.8.0"
 
 [deps]
 ArchGDAL = "c9ce4bd3-c3d5-55b8-8973-c0e20141b8c3"
+ColorBlendModes = "60508b50-96e1-4007-9d6c-f475c410f16b"
+Colors = "5ae59095-9a9b-59fe-a467-6f913c188581"
+Distances = "b4f34e82-e78d-54a5-968a-f98e89d6e8f7"
 Downloads = "f43a241f-c20a-4ad4-852c-f6b1247861c6"
+GeometryBasics = "5c1252a2-5f33-56bf-86c9-59e7332b4326"
+PolygonOps = "647866c9-e3ac-4575-94e7-e3d426903924"
 RecipesBase = "3cdcf5f2-1ef4-517c-9805-6587b60abb01"
 Requires = "ae029012-a4dd-5104-9daa-d747884805df"
 Statistics = "10745b16-79ce-11e8-11f9-7d13ad32a3b2"
+StatsBase = "2913bbd2-ae8a-5f71-8c99-4fb6c76f3a91"
 ZipFile = "a5390f91-8eb1-5f08-bee0-b1d1ffed6cea"
 
 [compat]
-ArchGDAL = "0.6, 0.7"
+ArchGDAL = "0.7"
+Distances = "0.10"
 Downloads = "1.4"
-RecipesBase = "0.7, 0.8, 1.0"
+GeometryBasics = "0.4"
+PolygonOps = "0.1"
+RecipesBase = "1.0"
 Requires = "1.0"
-ZipFile = "0.8, 0.9"
-julia = "1.5"
+StatsBase = "0.33"
+ZipFile = "0.9"
+julia = "1.6"

docs/Project.toml

@@ -1,8 +1,14 @@
 [deps]
+ColorBlendModes = "60508b50-96e1-4007-9d6c-f475c410f16b"
+Colors = "5ae59095-9a9b-59fe-a467-6f913c188581"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
-Plots = "91a5bcdd-55d7-5caf-9e0b-520d859cae80"
-StatsPlots = "f3b207a7-027a-5e70-b257-86293d7955fd"
+EvoTrees = "f6006082-12f8-11e9-0c9c-0d5d367ab1e5"
 GBIF = "ee291a33-5a6c-5552-a3c8-0f29a1181037"
+GLM = "38e38edf-8417-5370-95a0-9cbb8c7f171a"
+GeometryBasics = "5c1252a2-5f33-56bf-86c9-59e7332b4326"
+JSON = "682c06a0-de6a-54ab-a142-c8b1cf79cde6"
+Literate = "98b081ad-f1c9-55d3-8b20-4c87d4299306"
+Plots = "91a5bcdd-55d7-5caf-9e0b-520d859cae80"
 Statistics = "10745b16-79ce-11e8-11f9-7d13ad32a3b2"
 StatsBase = "2913bbd2-ae8a-5f71-8c99-4fb6c76f3a91"
-DataFrames = "a93c6f00-e57d-5684-b7b6-d8193f3e46c0"
+StatsPlots = "f3b207a7-027a-5e70-b257-86293d7955fd"

docs/make.jl

@@ -3,6 +3,22 @@ push!(LOAD_PATH, joinpath("..", "src"))
 using Documenter, SimpleSDMLayers
 using GBIF
 using Statistics
+using Literate
+
+# Literate files
+for ENDING in ["examples", "sdm"]
+    expl = joinpath("docs", "src", ENDING)
+    corefiles = [joinpath(expl, f) for f in readdir(expl)]
+    filter!(f -> endswith(f, "jl"), corefiles)
+    vignetteconfig = Dict(
+        "repo_root_url" => "https://github.com/EcoJulia/SimpleSDMLayers.jl",
+        "flavor" => Literate.DocumenterFlavor(),
+        "credit" => false
+    )
+    for corefile in corefiles
+        Literate.markdown(corefile, expl; config=vignetteconfig)
+    end
+end
 
 makedocs(
     sitename = "Simple SDM Layers",
@@ -11,22 +27,28 @@ makedocs(
         "Home" => "index.md",
         "Manual" => [
             "Types" => "man/types.md",
+            "Indexing" => "man/indexing.md",
+            "Clipping" => "man/clip.md",
+            "Operations on values" => "man/changevalues.md",
             "Overloads" => "man/overloads.md",
             "Other operations" => "man/operations.md",
-            "Data" => "man/data.md",
+            "Data access" => "man/data.md",
+            "IO" => "man/io.md"
         ],
-        "Examples" => [
-            "Temperature data" => "examples/temperature.md",
-            "DataFrames integration" => "examples/dataframes.md",
+        "General examples" => [
+            "Introduction: elevation data" => "examples/elevation.md",
+            "Geometry for clipping" => "examples/geometry.md",
             "Sliding window analysis" => "examples/slidingwindow.md",
             "Landcover data" => "examples/landcover.md",
-            "Landcover consensus" => "examples/consensus.md",
-            "Importing and exporting" => "examples/import.md",
+            "Bivariate mapping" => "examples/bivariate.md"
         ],
-        "Building SDMs" => [
+        "SDM case studies" => [
             "GBIF integration" => "sdm/gbif.md",
-            "BIOCLIM from scratch" => "sdm/bioclim.md",
-            "Future data" => "sdm/future.md"
+            "Variable selection (VIF)" => "sdm/vif.md",
+            "Building the BIOCLIM model" => "sdm/bioclim.md",
+            "Pseudo-absences" => "sdm/pseudoabsences.md",
+            "Dealing with future data" => "sdm/future.md",
+            "BRTs and climate change" => "sdm/brt.md"
         ]
     ]
 )

docs/src/examples/bivariate.jl

@@ -0,0 +1,75 @@
+# # Bivariate maps
+
+using SimpleSDMLayers
+using StatsPlots
+using StatsPlots.PlotMeasures
+
+# **Justification for this use case:** We can show more than one (specifically,
+# two) variables on a single map, using a bivariate color scale. In order to
+# illustrate bivariate mapping, we will look at the joint distribution of two
+# measures: eveness of land use, and terrain roughness.
+
+boundaries = (left=-12.0, right=30.0, bottom=36.0, top=72.0)
+layer1 = convert(
+    Float16,
+    SimpleSDMPredictor(EarthEnv, HabitatHeterogeneity, 2; resolution=5, boundaries...),
+)
+layer2 = convert(
+    Float16, SimpleSDMPredictor(EarthEnv, Topography, 7; resolution=5, boundaries...)
+)
+layer2 = mask(layer1, layer2);
+
+# Note that bivariate maps usually work best when used with 9 classes in total
+# (so 3 for each side). The next decision is to take a bivaraite color palette,
+# and the combinations below are [commonly
+# used](https://www.joshuastevens.net/cartography/make-a-bivariate-choropleth-map/).
+# Note that you can definitely use [diverging
+# colors](https://www.personal.psu.edu/cab38/ColorSch/Schemes.html) if you want.
+
+p0 = colorant"#e8e8e8"
+bv_pal_1 = (p0=p0, p1=colorant"#64acbe", p2=colorant"#c85a5a")
+bv_pal_2 = (p0=p0, p1=colorant"#73ae80", p2=colorant"#6c83b5")
+bv_pal_3 = (p0=p0, p1=colorant"#9972af", p2=colorant"#c8b35a")
+bv_pal_4 = (p0=p0, p1=colorant"#be64ac", p2=colorant"#5ac8c8")
+
+# The bivariate map itself is a call to plot. Internally, this will transform
+# the layers into quantiles (determined by the `classes` keyword, defaults to
+# 3):
+
+plot(layer1, layer2; st=:bivariate, bv_pal_3...)
+
+# Note that you can use the `bivariate` shorthand as well:
+
+pl1 = bivariate(layer1, layer2; classes=3, frame=:box, bv_pal_4...)
+xaxis!(pl1, "Longitude")
+yaxis!(pl1, "Latitude")
+
+# We can repeat essentially the same process for the legend:
+
+pl2 = bivariatelegend(layer1, layer2; classes=3, bv_pal_4...)
+xaxis!(pl2, layernames(EarthEnv, HabitatHeterogeneity, 2))
+yaxis!(pl2, layernames(EarthEnv, Topography, 7))
+
+# And now, we can plot the legend next to the map - future releases of the
+# package will hopefully offer this in a far more user friendly way.
+
+plot(pl1, pl2; layout=@layout [a{0.75w} b])
+
+# Using the `subplot` and `inset` arguments of Plots.jl, we can have the legend
+# within the figure. Note how in this example we expand the limits on the x axis
+# to make the legend fit, but also use more classes in the map to have a
+# smoother result.
+
+p1 = bivariate(layer1, layer2; classes=6, bv_pal_2..., frame=:box, xlim=(-24, maximum(longitudes(layer1))))
+xaxis!(p1, "Longitude")
+yaxis!(p1, "Latitude")
+p2 = bivariatelegend!(
+    layer1,
+    layer2;
+    bv_pal_2...,
+    inset=(1, bbox(0.04, 0.05, 0.28, 0.28, :top, :left)),
+    subplot=2,
+    xlab=layernames(EarthEnv, HabitatHeterogeneity)[2],
+    ylab=layernames(EarthEnv, Topography)[7],
+    guidefontsize=7,
+)