Merge pull request #844 from rafaqz/la/resample_continue

resample cellarea continue
rafaqz · Dec 30, 2024 · f59901a · f59901a
2 parents 9bc60db + e50815c
commit f59901a
Show file tree

Hide file tree

Showing 12 changed files with 587 additions and 23 deletions.
diff --git a/docs/Project.toml b/docs/Project.toml
@@ -11,18 +11,23 @@ DocumenterVitepress = "4710194d-e776-4893-9690-8d956a29c365"
 GBIF2 = "dedd4f52-e074-43bf-924d-d6bce14ad628"
 GLMakie = "e9467ef8-e4e7-5192-8a1a-b1aee30e663a"
 GeoInterface = "cf35fbd7-0cd7-5166-be24-54bfbe79505f"
+GeoMakie = "db073c08-6b98-4ee5-b6a4-5efafb3259c6"
 HDF5 = "f67ccb44-e63f-5c2f-98bd-6dc0ccc4ba2f"
 Literate = "98b081ad-f1c9-55d3-8b20-4c87d4299306"
 MLJBase = "a7f614a8-145f-11e9-1d2a-a57a1082229d"
 MLJGLMInterface = "caf8df21-4939-456d-ac9c-5fefbfb04c0c"
 Makie = "ee78f7c6-11fb-53f2-987a-cfe4a2b5a57a"
 Maxnet = "81f79f80-22f2-4e41-ab86-00c11cf0f26f"
 NCDatasets = "85f8d34a-cbdd-5861-8df4-14fed0d494ab"
+NaNStatistics = "b946abbf-3ea7-4610-9019-9858bfdeaf2d"
+NaturalEarth = "436b0209-26ab-4e65-94a9-6526d86fea76"
 Plots = "91a5bcdd-55d7-5caf-9e0b-520d859cae80"
+Proj = "c94c279d-25a6-4763-9509-64d165bea63e"
 RasterDataSources = "3cb90ccd-e1b6-4867-9617-4276c8b2ca36"
 Rasters = "a3a2b9e3-a471-40c9-b274-f788e487c689"
 Shapefile = "8e980c4a-a4fe-5da2-b3a7-4b4b0353a2f4"
 SpeciesDistributionModels = "3ef73bbf-0321-4d3b-9a2e-5fbebc8e35da"
+StatsBase = "2913bbd2-ae8a-5f71-8c99-4fb6c76f3a91"
 
 [sources]
 SpeciesDistributionModels = {url = "https://github.com/tiemvanderdeure/SpeciesDistributionModels.jl/"}
diff --git a/docs/src/.vitepress/config.mts b/docs/src/.vitepress/config.mts
@@ -18,19 +18,46 @@ const navTemp = {
     { text: 'Get Started', link: '/get_started' },
     { text: 'Manual',
       items: [
-        { text: 'Methods', link: '/manual/methods' },
-        { text: 'Array Operations', link: '/manual/array_operations' },
-        { text: 'Data Sources', link: '/manual/data_sources' },
-        { text: 'Plots',
+        { text: 'Data Sources', link: '/manual/data_sources' }, 
+        { text: 'Methods',
           items: [
-            { text: 'Plots.jl', link: '/manual/plotting' },
-            { text: 'Makie.jl', link: 'manual/plot_makie' },
+            { text: 'Overview', link: '/manual/methods' },
+            { text: 'rasterize', link: '/api#Rasters.rasterize' },
+            { text: 'extract', link: '/api#Rasters.extract' },
+            { text: 'zonal', link: '/api#Rasters.zonal-Tuple{Any,%20Union{AbstractRaster,%20AbstractRasterStack}}'},
+            { text: 'aggregate', link: '/api#Rasters.aggregate' },
+            { text: 'disaggregate', link: '/api#Rasters.disaggregate' },
+            { text: 'cellarea', link: '/manual/cellarea' },
+            { text: 'mosaic', link: '/api#Rasters.mosaic-Tuple{Function,%20Union{AbstractRaster,%20AbstractRasterStack},%20Vararg{Union{AbstractRaster,%20AbstractRasterStack}}}' },
+            { text: 'crop', link: '/api#Rasters.crop' },
+            { text: 'extend', link: '/api#Rasters.extend' },
+            { text: 'trim', link: '/api#Rasters.trim-Tuple{Union{AbstractRaster,%20AbstractRasterStack}}' },
+            { text: 'resample', link: '/api#Rasters.resample-Tuple' },
+            { text: 'warp', link: '/api#Rasters.warp-Tuple' },
+            { text: 'classify', link: '/api#Rasters.classify' },
+            { text: 'mask', link: '/api#Rasters.mask-Tuple{Any}' },
+            { text: 'replace_missing', link: '/api#Rasters.replace_missing-Tuple{Any}' },
+            { text: 'modify', link: '/api#DimensionalData.modify-Tuple{Any,%20AbstractRasterSeries}' },
+            { text: 'read', link: '/api#Base.read-Tuple{Union{AbstractRaster,%20AbstractRasterSeries,%20AbstractRasterStack}}' },
+            { text: 'read!', link: '/api#Base.read!-Tuple{AbstractRaster,%20AbstractArray}' },
+            { text: 'open', link: '/api#Base.open-Tuple{Function,%20AbstractRaster}' },
+            { text: 'write', link: '/api#Base.write-Tuple{AbstractString,%20AbstractRasterSeries}' },
           ]
-        },  
+         },
       ]
     },
     { text: 'Tutorials',
       items: [
+        { text: 'Plotting',
+          collapsed: true,
+          items: [
+            { text: 'Plots.jl', link: '/tutorials/plotting' },
+            { text: 'Makie.jl', link: '/tutorials/plot_makie' },
+          ]
+        }, 
+        { text: 'Array Operations', link: '/tutorials/array_operations' },
+        { text: 'Spatial mean', link: '/tutorials/spatial_mean' },
+        { text: 'Reprojection and resampling', link: '/tutorials/resample'},
         { text: 'Species Distribution Modelling', link: '/tutorials/gbif_wflow' },
       ]
     },
@@ -98,19 +125,47 @@ export default defineConfig({
       { text: 'Get Started', link: '/get_started' },
       { text: 'Manual',
         items: [
-          { text: 'Methods', link: '/manual/methods' },
-          { text: 'Array Operations', link: '/manual/array_operations' },
           { text: 'Data Sources', link: '/manual/data_sources' },
-          { text: 'Plots',
+          { text: 'Methods',
+            collapsed: true,
             items: [
-              { text: 'Plots.jl', link: '/manual/plotting' },
-              { text: 'Makie.jl', link: '/manual/plot_makie' },
+              { text: 'Overview', link: '/manual/methods' },
+              { text: 'rasterize', link: '/api#Rasters.rasterize' },
+              { text: 'extract', link: '/api#Rasters.extract' },
+              { text: 'zonal', link: '/api#Rasters.zonal-Tuple{Any,%20Union{AbstractRaster,%20AbstractRasterStack}}'},
+              { text: 'aggregate', link: '/api#Rasters.aggregate' },
+              { text: 'disaggregate', link: '/api#Rasters.disaggregate' },
+              { text: 'cellarea', link: '/manual/cellarea' },
+              { text: 'mosaic', link: '/api#Rasters.mosaic-Tuple{Function,%20Union{AbstractRaster,%20AbstractRasterStack},%20Vararg{Union{AbstractRaster,%20AbstractRasterStack}}}' },
+              { text: 'crop', link: '/api#Rasters.crop' },
+              { text: 'extend', link: '/api#Rasters.extend' },
+              { text: 'trim', link: '/api#Rasters.trim-Tuple{Union{AbstractRaster,%20AbstractRasterStack}}' },
+              { text: 'resample', link: '/api#Rasters.resample-Tuple' },
+              { text: 'warp', link: '/api#Rasters.warp-Tuple' },
+              { text: 'classify', link: '/api#Rasters.classify' },
+              { text: 'mask', link: '/api#Rasters.mask-Tuple{Any}' },
+              { text: 'replace_missing', link: '/api#Rasters.replace_missing-Tuple{Any}' },
+              { text: 'modify', link: '/api#DimensionalData.modify-Tuple{Any,%20AbstractRasterSeries}' },
+              { text: 'read', link: '/api#Base.read-Tuple{Union{AbstractRaster,%20AbstractRasterSeries,%20AbstractRasterStack}}' },
+              { text: 'read!', link: '/api#Base.read!-Tuple{AbstractRaster,%20AbstractArray}' },
+              { text: 'open', link: '/api#Base.open-Tuple{Function,%20AbstractRaster}' },
+              { text: 'write', link: '/api#Base.write-Tuple{AbstractString,%20AbstractRasterSeries}' },
             ]
-          },  
+           },
         ]
       },
       { text: 'Tutorials',
         items: [
+          { text: 'Plotting',
+            collapsed: true,
+            items: [
+              { text: 'Plots.jl', link: '/tutorials/plotting' },
+              { text: 'Makie.jl', link: '/tutorials/plot_makie' },
+            ]
+          },
+          { text: 'Array Operations', link: '/tutorials/array_operations' },
+          { text: 'Spatial mean', link: '/tutorials/spatial_mean' },
+          { text: 'Reprojection and resampling', link: '/tutorials/resample'},
           { text: 'Species Distribution Modelling', link: '/tutorials/gbif_wflow' },
         ]
       },

diff --git a/docs/src/manual/cellarea.md b/docs/src/manual/cellarea.md
@@ -0,0 +1,67 @@
+## `cellarea`
+
+```@meta
+CollapsedDocStrings=true
+```
+
+```@docs; canonical=false
+cellarea
+```
+
+Computing the area of each cell in a raster is useful for a number of reasons - if you have a variable like 
+population per cell, or elevation ([spatially extensive variables](https://r-spatial.org/book/05-Attributes.html#sec-extensiveintensive)),
+you'll want to account for the fact that different cells have different areas.
+
+Let's construct a raster and see what this looks like!  We'll keep it in memory.
+
+The spherical method relies on the [Proj.jl](https://github.com/JuliaGeo/Proj.jl) package to perform coordinate transformation, so that has to be loaded explicitly.
+
+````@example cellarea
+using Rasters, Proj
+````
+
+To construct a raster, we'll need to specify the `x` and `y` dimensions.  These are called `lookups` in `Rasters.jl.`
+
+````@example cellarea
+using Rasters.Lookups
+````
+
+We can now construct the x and y lookups.  Here we'll use a start-at-one, step-by-five grid.
+Note that we're specifying that the "sampling", i.e., what the coordinates actually mean, 
+is `Intervals(Start())`, meaning that the coordinates are the starting point of each interval.
+
+This is in contrast to `Points()` sampling, where each index in the raster represents the value at a sampling point;
+here, each index represents a grid cell, which is defined by the coordinate being at the start.
+
+````@example cellarea
+x = X(1:5:30; sampling = Intervals(Start()), crs = EPSG(4326))
+y = Y(50:5:80; sampling = Intervals(Start()), crs = EPSG(4326));
+nothing # hide
+````
+
+I have chosen the y-range here specifically so we can show the difference between spherical and planar `cellarea`.
+
+````@ansi cellarea
+ras = Raster(ones(x, y); crs = EPSG(4326))
+````
+
+We can just call `cellarea` on this raster, which returns cell areas in meters, on Earth, assuming it's a sphere:
+
+````@ansi cellarea
+cellarea(ras)
+````
+
+and if we plot it, you can see the difference in cell area as we go from the equator to the poles:
+
+````@example cellarea
+using CairoMakie
+heatmap(cellarea(ras); axis = (; aspect = DataAspect()))
+````
+
+We can also try this using the planar method, which simply computes the area of the rectangle using `area = x_side_length * y_side_length`:
+
+````@ansi cellarea
+cellarea(Planar(), ras)
+````
+
+Note that this is of course wildly inaccurate for a geographic dataset - but if you're working in a projected coordinate system, like polar stereographic or Mercator, this can be very useful (and a _lot_ faster)!
diff --git a/docs/src/manual/data_sources.md b/docs/src/manual/data_sources.md
@@ -43,10 +43,6 @@ They are always 3 dimensional, and have `Y`, `X` and [`Band`](@ref) dimensions.
 using Rasters
 ````
 
-````@docs
-smapseries
-````
-
 ## Writing file formats to disk
 
 Files can be written to disk with ArchGDAL.jl and NCDatasets.jl backends using

diff --git a/docs/src/manual/array_operations.md → docs/src/tutorials/array_operations.md b/docs/src/manual/array_operations.md → docs/src/tutorials/array_operations.md
@@ -1,3 +1,5 @@
+# Array operations
+
 Most base methods work as for regular julia `Array`s, such as `reverse` and
 rotations like `rotl90`. Base, statistics and linear algebra methods like `mean`
 that take a `dims` argument can also use the dimension name. 

diff --git a/docs/src/tutorials/gbif_wflow.md b/docs/src/tutorials/gbif_wflow.md
@@ -2,7 +2,7 @@
 
 This example shows a full Species distribution modelling workflow, from loading data, to cleaning it, to fitting an ensemble and generating predictions.
 
-It uses GBIF and WorldClim data, which are common datasets in ecology.
+It uses GBIF and WorldClim data, which are common datasets in ecology. We'll load occurrences for the Mountain Pygmy Possum species using [GBIF2.jl](https://github.com/rafaqz/GBIF2.jl), an interface to the [Global Biodiversity Information Facility](https://www.gbif.org/), and extract environmental variables using BioClim data from [RasterDataSources.jl](https://github.com/EcoJulia/RasterDataSources.jl).
 
 ## Load Rasters, ArchGDAL, RasterDataSources and GBIF
 The GBIF2 library is used to download occurrence data, RasterDataSources to conveniently access Bioclim data. ArchGDAL is necessary to load in the Bioclim data.

diff --git a/docs/src/manual/plot_makie.md → docs/src/tutorials/plot_makie.md b/docs/src/manual/plot_makie.md → docs/src/tutorials/plot_makie.md
diff --git a/docs/src/manual/plotting.md → docs/src/tutorials/plotting.md b/docs/src/manual/plotting.md → docs/src/tutorials/plotting.md