Merge branch 'main' into cf

.github/ISSUE_TEMPLATE/bug-report.md → .github/ISSUE_TEMPLATE/bug_report.md

@@ -1,15 +1,19 @@
 ---
-name: Bug Report
-about: Describe your issue here, including a minimum working example and all file downloads without authentication.
-We cant fix your problem unless you help us by filling out the code blocks below.
-
+name: Bug report
+about: Describe your issue here, including a minimum working example all files.
 title: ''
-labels: ''
+labels: bug
 assignees: ''
 
 ---
 
-Your problem. You don't have to write anything here for a bug, the code and error are what is important.
+########################
+Pleas fill all code blocks below, then read and remove this message.
+
+Its important that your example *just runs*, and we can copy and paste the code into Julia and it does that same thing for us that it does for you. 
+
+That means either generating or downloading data inside the script, e.g. with `download`. 
+########################
 
 ```julia
 All the julia code needed to make the error goes here including download or generation of all data used

.github/workflows/ci.yml

@@ -8,6 +8,9 @@ defaults:
 jobs:
   test:
     name: Julia ${{ matrix.version }} - ${{ matrix.os }} - ${{ matrix.arch }}
+    permissions:
+      actions: write
+      contents: read
     runs-on: ${{ matrix.os }}
     strategy:
       fail-fast: true
@@ -26,6 +29,7 @@ jobs:
         with:
           version: ${{ matrix.version }}
           arch: ${{ matrix.arch }}
+      - uses: julia-actions/cache@v2
       - uses: julia-actions/julia-buildpkg@latest
       - uses: julia-actions/julia-runtest@latest
         env:

Project.toml

@@ -1,7 +1,7 @@
 name = "Rasters"
 uuid = "a3a2b9e3-a471-40c9-b274-f788e487c689"
 authors = ["Rafael Schouten <[email protected]>"]
-version = "0.11.8"
+version = "0.12.1"
 
 [deps]
 Adapt = "79e6a3ab-5dfb-504d-930d-738a2a938a0e"
@@ -16,21 +16,26 @@ FillArrays = "1a297f60-69ca-5386-bcde-b61e274b549b"
 Flatten = "4c728ea3-d9ee-5c9a-9642-b6f7d7dc04fa"
 GeoFormatTypes = "68eda718-8dee-11e9-39e7-89f7f65f511f"
 GeoInterface = "cf35fbd7-0cd7-5166-be24-54bfbe79505f"
+GeometryOpsCore = "05efe853-fabf-41c8-927e-7063c8b9f013"
+LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
 Missings = "e1d29d7a-bbdc-5cf2-9ac0-f12de2c33e28"
 Mmap = "a63ad114-7e13-5084-954f-fe012c677804"
 OffsetArrays = "6fe1bfb0-de20-5000-8ca7-80f57d26f881"
 ProgressMeter = "92933f4c-e287-5a05-a399-4b506db050ca"
 RecipesBase = "3cdcf5f2-1ef4-517c-9805-6587b60abb01"
 Reexport = "189a3867-3050-52da-a836-e630ba90ab69"
 Setfield = "efcf1570-3423-57d1-acb7-fd33fddbac46"
+Statistics = "10745b16-79ce-11e8-11f9-7d13ad32a3b2"
 
 [weakdeps]
 ArchGDAL = "c9ce4bd3-c3d5-55b8-8973-c0e20141b8c3"
 CoordinateTransformations = "150eb455-5306-5404-9cee-2592286d6298"
 GRIBDatasets = "82be9cdb-ee19-4151-bdb3-b400788d9abc"
 Makie = "ee78f7c6-11fb-53f2-987a-cfe4a2b5a57a"
 NCDatasets = "85f8d34a-cbdd-5861-8df4-14fed0d494ab"
+Proj = "c94c279d-25a6-4763-9509-64d165bea63e"
 RasterDataSources = "3cb90ccd-e1b6-4867-9617-4276c8b2ca36"
+StatsBase = "2913bbd2-ae8a-5f71-8c99-4fb6c76f3a91"
 ZarrDatasets = "519a4cdf-1362-424a-9ea1-b1d782dbb24b"
 
 [extensions]
@@ -39,7 +44,9 @@ RastersCoordinateTransformationsExt = "CoordinateTransformations"
 RastersGRIBDatasetsExt = "GRIBDatasets"
 RastersMakieExt = "Makie"
 RastersNCDatasetsExt = "NCDatasets"
+RastersProjExt = "Proj"
 RastersRasterDataSourcesExt = "RasterDataSources"
+RastersStatsBaseExt = "StatsBase"
 RastersZarrDatasetsExt = "ZarrDatasets"
 
 [compat]
@@ -52,26 +59,32 @@ CommonDataModel = "0.2.3, 0.3"
 ConstructionBase = "1"
 CoordinateTransformations = "0.6.2"
 DataFrames = "1"
-DimensionalData = "0.27.3"
+DimensionalData = "0.29.4"
 DiskArrays = "0.3, 0.4"
 Extents = "0.1"
 FillArrays = "0.12, 0.13, 1"
 Flatten = "0.4"
 GRIBDatasets = "0.2, 0.3"
+GeoDataFrames = "0.3"
 GeoFormatTypes = "0.4"
-GeoInterface = "1"
-Makie = "0.19, 0.20, 0.21"
+GeoInterface = "1.0"
+GeometryBasics = "0.4"
+GeometryOpsCore = "0.1.1"
+Makie = "0.20, 0.21"
 Missings = "0.4, 1"
 NCDatasets = "0.13, 0.14"
 OffsetArrays = "1"
+Plots = "1"
 ProgressMeter = "1"
-RasterDataSources = "0.5.7, 0.6"
+Proj = "1.7.2"
+RasterDataSources = "0.7"
 RecipesBase = "0.7, 0.8, 1.0"
 Reexport = "0.2, 1.0"
 SafeTestsets = "0.1"
 Setfield = "0.6, 0.7, 0.8, 1"
 Shapefile = "0.10, 0.11"
 Statistics = "1"
+StatsBase = "0.34"
 Test = "1"
 ZarrDatasets = "0.1"
 julia = "1.10"
@@ -82,17 +95,19 @@ ArchGDAL = "c9ce4bd3-c3d5-55b8-8973-c0e20141b8c3"
 CFTime = "179af706-886a-5703-950a-314cd64e0468"
 CoordinateTransformations = "150eb455-5306-5404-9cee-2592286d6298"
 DataFrames = "a93c6f00-e57d-5684-b7b6-d8193f3e46c0"
-GeoDataFrames = "62cb38b5-d8d2-4862-a48e-6a340996859f"
 GRIBDatasets = "82be9cdb-ee19-4151-bdb3-b400788d9abc"
+GeoDataFrames = "62cb38b5-d8d2-4862-a48e-6a340996859f"
 GeometryBasics = "5c1252a2-5f33-56bf-86c9-59e7332b4326"
 Makie = "ee78f7c6-11fb-53f2-987a-cfe4a2b5a57a"
 NCDatasets = "85f8d34a-cbdd-5861-8df4-14fed0d494ab"
 Plots = "91a5bcdd-55d7-5caf-9e0b-520d859cae80"
+Proj = "c94c279d-25a6-4763-9509-64d165bea63e"
 RasterDataSources = "3cb90ccd-e1b6-4867-9617-4276c8b2ca36"
 SafeTestsets = "1bc83da4-3b8d-516f-aca4-4fe02f6d838f"
 Shapefile = "8e980c4a-a4fe-5da2-b3a7-4b4b0353a2f4"
-Statistics = "10745b16-79ce-11e8-11f9-7d13ad32a3b2"
+StableRNGs = "860ef19b-820b-49d6-a774-d7a799459cd3"
+StatsBase = "2913bbd2-ae8a-5f71-8c99-4fb6c76f3a91"
 Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
 
 [targets]
-test = ["Aqua", "ArchGDAL", "CFTime", "CoordinateTransformations", "DataFrames", "GeoDataFrames", "GeometryBasics", "GRIBDatasets", "NCDatasets", "Plots", "RasterDataSources", "SafeTestsets", "Shapefile", "Statistics", "Test", "ZarrDatasets"]
+test = ["Aqua", "ArchGDAL", "CFTime", "CoordinateTransformations", "DataFrames", "GeoDataFrames", "GeometryBasics", "GRIBDatasets", "NCDatasets", "Plots", "Proj", "RasterDataSources", "SafeTestsets", "Shapefile", "StableRNGs", "StatsBase", "Test", "ZarrDatasets"]

README.md

@@ -16,36 +16,6 @@ manipulating rasterized spatial data.
 These currently include raster arrays like GeoTIFF and NetCDF, R grd files, 
 multi-layered stacks, and multi-file series of arrays and stacks. 
 
-
-## :warning: Packages extensions and Rasters 0.8 and onwards 
-
-On Julia 1.9 we can put additional packages in extensions, so the code only loads when
-you load a specific package. Rasters.jl was always intended to work like this,
-and its finally possible. This reduced package `using` time from many seconds to well under a second.
-
-But, it means you have to manually load packages you need for each backend or additional
-functionality.
-
-For example, to use the GDAL backend, and download files, you now need to do:
-
-```julia
-using Rasters, ArchGDAL, RasterDataSources
-```
-
-where previously it was just `using Rasters`.
-
-Sources and packages needed:
-- `:gdal`: `using ArchGDAL`
-- `:netcdf`: `using NCDatasets`
-- `:grd`: built-in.
-- `:smap`: `using HDF5`
-- `:grib`: `using GRIBDatasets`.
-
-Other functionality in extensions:
-- Raster data downloads, like `Worldclim{Climate}`: `using RasterDataSources`
-- Makie plots: `using Makie`
-- Coordinate transformations for gdal rasters: `using CoordinateTransformations`
-
 # Quick start
 Install the package by typing:
 
@@ -54,6 +24,7 @@ Install the package by typing:
 add Rasters
 ```
 
+Then to use it:
 ```julia
 using Rasters
 ```
@@ -87,6 +58,29 @@ values: [:, :, 1]
  30   0.334152   0.136551    0.183555    0.941133   0.450484    0.461862
 [and 12 more slices...]
 ```
+## Packages that work with Rasters
+
+Rasters reduces its dependencies to keep the `using` time low.
+But, it means you have to manually load packages you need for each 
+backend or additional functionality.
+
+For example, to use the GDAL backend, and download RasterDataSources files, you now need to do:
+
+```julia
+using Rasters, ArchGDAL, RasterDataSources
+```
+
+Sources and packages needed:
+- `:gdal`: `using ArchGDAL`
+- `:netcdf`: `using NCDatasets`
+- `:grd`: built-in.
+- `:grib`: `using GRIBDatasets`.
+- `:zarr`: `using ZarrDatasets`.
+
+Other functionality in extensions:
+- Raster data downloads, like `Worldclim{Climate}`: `using RasterDataSources`
+- Makie plots: `using GLMakie` (opengl interactive) or `using CairoMakie` (print) etc.
+- Coordinate transformations for gdal rasters: `using CoordinateTransformations`
 
 ## Getting the `lookup` array from dimensions
 
@@ -215,6 +209,13 @@ be used with identical syntax.
   projection, the conversion is handled automatically. This means lat/lon
   `EPSG(4326)` can be used seamlessly if you need that.
 
+# Performance
+
+Rasters should be the fastest tool available for most tasks. If you find 
+something is faster in another package, it's likely a bug - so make an issue!
+
+![image](https://github.com/user-attachments/assets/1c6c56ac-4c5a-4096-984d-15bf2783682c)
+
 
 # Bugs, errors and making issues for Rasters.jl
 
@@ -226,8 +227,11 @@ Because there are so many raster file types and variations of them, most of the
 
 To make an issue we can fix quickly (or at all) there are three key steps:
 
-1. Include the file in an accessible place on web *without authentication* or any other work on our part, so we can just get it and find your bug. You can put it on a file hosting platform (e.g. google drive, drop box, whatever you use) and share the url.
-2. Add a minimum working example to the issue template that first downloads the file, then runs the function that triggers the bug.
-3. Paste the complete stack trace of the error it produces, right to the bottom, into the issue template. Then we can be sure we reproduced the same problem.
+1. Use a RasterDataSources.jl file if you can, so there are no download hassles.
+   Otherwise store a file in an accessible place on web *without authentication* and preferably where you
+   can use `dowload` directly, so we just run the script can spend our time finding your bug.
+2. Add a minimum working example to the issue template that first downloads the file with `download`, then runs the function that triggers the bug.
+3. Paste the complete stack trace of the error it produces, right to the bottom, into the issue template.
+   Then we can be sure we have reproduced the same problem.
 
 Good issues are really appreciated, but they do take just a little extra effort with Rasters.jl because of this need for files.

docs/Project.toml

@@ -12,9 +12,16 @@ GBIF2 = "dedd4f52-e074-43bf-924d-d6bce14ad628"
 GeoInterface = "cf35fbd7-0cd7-5166-be24-54bfbe79505f"
 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"
 Plots = "91a5bcdd-55d7-5caf-9e0b-520d859cae80"
 RasterDataSources = "3cb90ccd-e1b6-4867-9617-4276c8b2ca36"
 Rasters = "a3a2b9e3-a471-40c9-b274-f788e487c689"
 Shapefile = "8e980c4a-a4fe-5da2-b3a7-4b4b0353a2f4"
+SpeciesDistributionModels = "3ef73bbf-0321-4d3b-9a2e-5fbebc8e35da"
+
+[sources]
+SpeciesDistributionModels = {url = "https://github.com/tiemvanderdeure/SpeciesDistributionModels.jl/"}

docs/src/.vitepress/config.mts

@@ -29,7 +29,7 @@ export default defineConfig({
   themeConfig: {
     outline: 'deep',
     // https://vitepress.dev/reference/default-theme-config
-    logo: 'REPLACE_ME_DOCUMENTER_VITEPRESS',
+    logo: '/logo.png',
     search: {
       provider: 'local',
       options: {
@@ -44,27 +44,30 @@ export default defineConfig({
           { text: 'Overview', link: '/methods' },
           { text: 'Array Operations', link: '/array_operations' },
         ]
-       },
-       { text: 'Data Sources',
-       items: [
-         { text: 'Overview', link: '/data_sources' },
-         { text: 'GBIF', link: '/gbif_wflow' }
-        ]
       },
+      { text: 'Data Sources', link: '/data_sources' },
       { text: 'Plots',
-      items: [
-        { text: 'Plots.jl', link: '/plotting' },
-        { text: 'Makie.jl', link: '/plot_makie' },
-      ]
-     },
-     { text: 'Ecosystem',
-      items: [
-        { text: 'DimensionalData.jl', link: 'https://rafaqz.github.io/DimensionalData.jl/dev/' },
-        { text: 'NCDatasets.jl', link: 'https://alexander-barth.github.io/NCDatasets.jl/stable/' },
-        { text: 'ArchGDAL.jl', link: 'https://yeesian.com/ArchGDAL.jl/stable/' },
-        { text: 'HDF5.jl', link: 'https://juliaio.github.io/HDF5.jl/stable/' },
-       ]
-     },
+        items: [
+          { text: 'Plots.jl', link: '/plotting' },
+          { text: 'Makie.jl', link: '/plot_makie' },
+        ]
+      },  
+      { text: 'Examples',
+        items: [
+          { text: 'Species Distribution Modelling', link: '/gbif_wflow' },
+        ]
+      },
+      { text: 'Ecosystem',
+        items: [
+          { text: 'DimensionalData.jl', link: 'https://rafaqz.github.io/DimensionalData.jl' },
+          { text: 'DiskArrays.jl', link: 'https://github.com/JuliaIO/DiskArrays.jl' },
+          { text: 'GeoInterface.jl', link: 'https://github.com/JuliaGeo/GeoInterface.jl' },
+          { text: 'NCDatasets.jl', link: 'https://alexander-barth.github.io/NCDatasets.jl/stable/' },
+          { text: 'ArchGDAL.jl', link: 'https://github.com/yeesian/ArchGDAL.jl' },
+          { text: 'GRIBDatasets.jl', link: 'https://github.com/JuliaGeo/GRIBDatasets.jl' },
+          { text: 'ZarrDatasets.jl', link: 'https://github.com/JuliaGeo/ZarrDatasets.jl' },
+        ]
+      },
       { text: 'API', link: '/api' }
     ],
 
@@ -75,20 +78,19 @@ export default defineConfig({
           { text: 'Overview', link: '/methods' },
           { text: 'Array Operations', link: '/array_operations' },
         ]
-       },
-       { text: 'Data Sources',
-       items: [
-         { text: 'Overview', link: '/data_sources' },
-         { text: 'GBIF', link: '/gbif_wflow' }
-        ]
       },
+      { text: 'Data Sources', link: '/data_sources' },
       { text: 'Plots',
-      items: [
-        { text: 'Plots.jl', link: '/plotting' },
-        { text: 'Makie.jl', link: '/plot_makie' },
-      ]
-     },
-
+        items: [
+          { text: 'Plots.jl', link: '/plotting' },
+          { text: 'Makie.jl', link: '/plot_makie' },
+        ]
+      },
+      { text: 'Examples',
+        items: [
+          { text: 'Species Distribution Modelling', link: '/gbif_wflow' },
+        ]
+      },
       { text: 'API', link: '/api' }
     ],
     editLink: {
@@ -102,4 +104,4 @@ export default defineConfig({
       copyright: `© Copyright ${new Date().getUTCFullYear()}. Released under the MIT License.`
     }
   }
-})
+})

docs/src/.vitepress/theme/style.css

@@ -279,4 +279,17 @@ kbd {
   .VPDoc {
     padding-left: 25px !important;  
   }
+}
+/* Component: Docstring Custom Block */
+
+.jldocstring.custom-block {
+  border: 1px solid var(--vp-c-gray-2);
+  color: var(--vp-c-text-1)
+}
+
+.jldocstring.custom-block summary {
+  font-weight: 700;
+  cursor: pointer;
+  user-select: none;
+  margin: 0 0 8px;
 }