update NEWS.md, README, and docs

NEWS.md

@@ -7,7 +7,7 @@
 * add support for imagery with spatial reference from geolocation arrays (including curvilinear grids) 
 * `stac_image_collection()` now accepts STACItemCollection objects directly and should be more robust
 * Windows build uses pkg-config if available
-
+* Improved error reporting for inaccessible imagery
 
 # gdalcubes 0.6.4 (2023-04-14)
 

R/predict.R

@@ -1,19 +1,22 @@
-#' Predict values based on a trained model to all pixels of a data cube.
+#' Model prediction
+#'
+#' Apply a trained model on all pixels of a data cube.
 #'
 #' @param object a data cube proxy object (class cube)
-#' @param model model used for prediction (e.g. from \code{caret})
-#' @param ... further arguments passed to predict
+#' @param model model used for prediction (e.g. from \code{caret} or \code{tidymodels})
+#' @param ... further arguments passed to the model-specific predict method
 #' @param output_names optional character vector for output variable(s)
 #' @param keep_bands logical; keep bands of input data cube, defaults to FALSE, i.e. original bands will be dropped
 #' @details 
-#' The predict method will be automatically chosen based on the class of the provided model. It aims at supporting models from the packages
-#' \code{tidymodels}, \code{caret}, and simple models as from \code{lm} or \code{glm}. 
+#' The model-specific predict method will be automatically chosen based on the class of the provided model. It aims at supporting 
+#' models from the packages \code{tidymodels}, \code{caret}, and simple models as from \code{lm} or \code{glm}. 
+#' 
 #' 
-#' For multiple output variables and/or output in list or data.frame form, \code{output_names} must be provided and match 
+#' For multiple output variables or output in form of lists or data.frames, \code{output_names} must be provided and match 
 #' names of the columns / items of the result object returned from the underlying predict method. For example, 
-#' predictions using \code{tidymodels} return a tibble (data.frame) with columns like \code{.pred_class} (lassification case).
-#' This must be explicitly provided as \code{output_names}. Similarly, \code{predict.lm} and the like produce lists
-#' if the standard error is requested by the user and  \code{output_names} hence should be set to \code{c("fit","se.fit")}.
+#' predictions using \code{tidymodels} return a tibble (data.frame) with columns like \code{.pred_class} (classification case).
+#' This must be explicitly provided as \code{output_names}. Similarly, \code{predict.lm} and the like return lists
+#' if the standard error is requested by the user and \code{output_names} hence should be set to \code{c("fit","se.fit")}.
 #' 
 #' For more complex cases or when predict expects something else than a \code{data.frame}, this function may not work at all. 
 #' @note This function returns a proxy object, i.e., it will not immediately start any computations. 

R/window.R

@@ -1,4 +1,4 @@
-#' Apply a moving window function over the time dimension of a data cube
+#' Apply a moving window operations over the time dimension of a data cube
 #' 
 #' Create a proxy data cube, which applies one ore more moving window functions to selected bands over pixel time series of a data cube.
 #' The fuction can either use a predefined agggregation function or apply a custom convolution kernel. 
@@ -115,19 +115,19 @@ is.window_time_cube  <- function(obj) {
 
 
 
-#' Apply a moving window operation or convolution kernel over the spatial dimensions of a data cube
+#' Apply a moving window (focal) operation or a convolution kernel over spatial dimensions of a data cube.
 #' 
-#' Create a proxy data cube, which applies a convolution kernel or an aggregation functions on two-dimensional moving 
-#' windows sliding over spatial slices of a data cube. The function can either execute a predefined agggregation function or 
-#' apply a custom convolution kernel. Among others, use cases include image processing (edge detection, median filter noise reduction, etc.) and
+#' Create a proxy data cube, which applies a convolution kernel or aggregation functions over two-dimensional moving 
+#' windows sliding over spatial slices of a data cube. The function can either execute one or more predefined aggregation functions or 
+#' apply a custom convolution kernel. Among others, use cases include image processing (edge detection, noise reduction, etc.) and
 #' enriching pixel values with local neighborhood properties (e.g. to use as predictor variables in ML models).
 #'
 #' @param x source data cube
-#' @param kernel two dimensional kernel (matrix) applied as convolution (must have odd number of rows and columns)
+#' @param kernel two dimensional kernel (matrix) applied as convolution (with odd number of rows and columns)
 #' @param expr either a single string, or a vector of strings, defining which reducers will be applied over which bands of the input cube
-#' @param window integer vector with two elements defining the size of the window before and after a cell, the total size of the window is window[1] + 1 + window[2]
+#' @param window integer vector with two elements defining the size (number of pixels) of the window in y and x direction, the total size of the window is window[1] *  window[2]
 #' @param keep_bands logical; if FALSE (the default), original data cube bands will be dropped. 
-#' @param pad Padding method applied to the borders; use NULL for no padding, a numeric a fill value, or one of "REPLICATE", "REFLECT", "REFLECT_PIXEL"
+#' @param pad padding method applied to the borders; use NULL for no padding (NA), a numeric a fill value, or one of "REPLICATE", "REFLECT", "REFLECT_PIXEL"
 #' @param ... optional additional expressions (if expr is not a vector)
 #' @return proxy data cube object
 #' @note Implemented reducers will ignore any NAN values (as \code{na.rm = TRUE} does).
@@ -150,26 +150,37 @@ is.window_time_cube  <- function(obj) {
 #' L8.cube.mean5x5 = window_space(L8.cube, kernel = matrix(1/25, 5, 5))
 #' L8.cube.mean5x5
 #' 
+#' \donttest{
+#' plot(L8.cube.mean5x5, key.pos=1)
+#' }
+#' 
 #' L8.cube.med_sd = window_space(L8.cube, "median(B04)" ,"sd(B04)", "median(B05)", "sd(B05)", 
 #'                               window = c(5,5), keep_bands = TRUE)
 #' L8.cube.med_sd
+#' \donttest{
+#' plot(L8.cube.med_sd, key.pos=1)
+#' }
 #' 
 #' @note This function returns a proxy object, i.e., it will not start any computations besides deriving the shape of the result.
 #' @details 
 #' The function either applies a kernel convolution (if the \code{kernel} argument is provided) or one or more built-in reducer function 
-#' over moving windows. In the former case, the kernel convolution will be applied over all bands of the input 
-#' cube, i.e., the output cube will have the same number of bands as the input cubes. 
-#' To apply one or more reducer functions, the window argument must be provided as a vector with two integer sizes in the order y, x.
-#' Several string expressions can be provided to create multiple bands in the output cube.
+#' over moving windows. 
+#' 
+#' In the former case, the kernel convolution will be applied over all bands of the input 
+#' cube, i.e., the output cube will have the same number of bands as the input cubes.
+#'  
+#' To apply one or more aggregation functions over moving windows, the window argument must be provided as a vector with two integer sizes 
+#' in the order y, x. Several string expressions can be provided to create multiple bands in the output cube. 
+#' Notice that expressions have a very simple format: the reducer is followed by the name of a band in parentheses, e.g, "mean(band1)".
+#' Possible reducers include "min", "max", "sum", "prod", "count", "mean", "median", "var", and "sd".
 #' 
-#' Notice that expressions have a very simple format: the reducer is followed by the name of a band in parentheses. You cannot add
-#' more complex functions or arguments. Possible reducers currently include "min", "max", "sum", "prod", "count", "mean", "median", "var", and "sd".
+#' Padding methods "REPLICATE", "REFLECT", "REFLEX_PIXEL" are defined according to 
+#' \url{https://openeo.org/documentation/1.0/processes.html#apply_kernel}.
 #'
 #' @export
 window_space <- function(x, expr,  ..., kernel, window, keep_bands = FALSE, pad = NA) {
   stopifnot(is.cube(x))
 
-
   pad_fill = as.numeric(0)
   pad_mode = ""
   if (is.na(pad)) {

README.Rmd

@@ -29,7 +29,7 @@ The package represents the data as _regular raster data cubes_ with dimensions `
 - Execute data cube operation chains using parallel processing and lazy evaluation.
 
 
-Among others, the package has been successfully used to process data from the Sentinel-2, Landsat, PlanetScope, MODIS, and Global Precipitation Measurement Earth observation satellites / missions.
+Among others, the package has been successfully used to process data from the Sentinel-2, Sentinel-5P, Landsat, PlanetScope, MODIS, and Global Precipitation Measurement Earth observation satellites / missions.
 
 # Installation
 
@@ -54,19 +54,19 @@ The package builds on the external libraries [GDAL](https://www.gdal.org), [NetC
 
 ## Windows
 
-On Windows, you will need [Rtools](https://cran.r-project.org/bin/windows/Rtools). System libraries are automatically downloaded from [rwinlib](https://github.com/rwinlib).
+On Windows, you will need [Rtools](https://cran.r-project.org/bin/windows/Rtools) to build the package from sources.
 
 
 ## Linux
-Please install the system libraries e.g. with the package manager of your Linux distribution. Also make sure that you are using a recent version of GDAL (>2.3.0). On Ubuntu, the following commands install all libraries.
+Please install the system libraries e.g. with the package manager of your Linux distribution. Also make sure that you are using a recent version of GDAL (>2.3.0). On Ubuntu, the following commands will install all neccessary libraries.
 
 ```
 sudo add-apt-repository ppa:ubuntugis/ppa && sudo apt-get update
 sudo apt-get install libgdal-dev libnetcdf-dev libcurl4-openssl-dev libsqlite3-dev libudunits2-dev
 ```
 
 ## MacOS
-Use [Homebrew](https://brew.sh) to install system libraries with
+Using [Homebrew](https://brew.sh), required system libraries can be installed with
 
 ```
 brew install pkg-config
@@ -86,7 +86,7 @@ brew install protobuf
 ## Download example data
 ```{r download}
 if (!dir.exists("L8_Amazon")) {
-  download.file("http://data.gdalcubes.org/L8_Amazon.zip", destfile = "L8_Amazon.zip",mode = "wb")
+  download.file("https://hs-bochum.sciebo.de/s/8XcKAmPfPGp2CYh/download", destfile = "L8_Amazon.zip",mode = "wb")
   unzip("L8_Amazon.zip", exdir = "L8_Amazon")
 }
 ```
@@ -168,7 +168,7 @@ raster_cube(L8.col, v.subarea.yearly) |>
 
 ## Data cube export
 
-Data cubes can be exported as single netCDF files with `write_ncdf()`, or as a collection of (possibly cloud-optimized) GeoTIFF files with `write_tif()`, where each time slice of the cube yields one GeoTIFF file. Data cubes can also be converted to `raster` or `stars`objects:
+Data cubes can be exported as single netCDF files with `write_ncdf()`, or as a collection of (possibly cloud-optimized) GeoTIFF files with `write_tif()`, where each time slice of the cube yields one GeoTIFF file. Data cubes can also be converted to `terra` or `stars`objects:
 
 ```{r extpkgload, include=FALSE} 
 library(raster)
@@ -180,7 +180,7 @@ raster_cube(L8.col, v.overview) |>
   select_bands(c("B04","B05")) |>
   apply_pixel(c("(B05-B04)/(B05+B04)"), names="NDVI") |>
   write_tif() |>
-  raster::stack() -> x
+  terra::rast() -> x
 x
 
 raster_cube(L8.col, v.overview) |>
@@ -281,22 +281,13 @@ hence makes it easy to create training data for machine learning models.
 
 **Cloud support with STAC**: `gdalcubes` can be used directly on cloud computing platforms including Amazon Web Services, Google Cloud Platform, and Microsoft Azure. Imagery can be read from their open data catalogs and discovered by connecting to STAC API endpoints using the [`rstac` package](https://cran.r-project.org/package=rstac) (see links at the end of this page).
 
-**Masks**: Mask bands (e.g. general pixel quality measures or cloud masks) can be applied during the construction of the raster data cube, such that masked values will not contribute to the data cube values. 
+**Machine learning**: The built-in functions `extract_geom` and `predict` help to create training data and apply predictions on data cubes using machine learning models as created from packages `caret` or `tidymodels`. 
 
-**Further operations**: The previous examples covered only a limited set of built-in functions. Further data cube operations for example include spatial and/or temporal slicing (`slice_time`, `slice_space`), cropping (`crop`), apply moving window filters over time series (`window_time`), filtering by arithmetic expressions on pixel values and spatial geometries (`filter_pixel`, `filter_geom`), and combining two or more data cubes with identical shape (`join_bands`).
+**Further operations**: The previous examples covered only a limited set of built-in functions. Further data cube operations for example include spatial and/or temporal slicing (`slice_time`, `slice_space`), cropping (`crop`), application of moving window / focal operations  (`window_time`, `window_space`), filtering by arithmetic expressions on pixel values and spatial geometries (`filter_pixel`, `filter_geom`), and combining two or more data cubes with identical shape (`join_bands`).
 
 
 
 
-# Limitations
-
-* Data cubes are limited to four dimensions ([stars](https://cran.r-project.org/package=stars) has cubes with any number of dimensions). 
-* Some operations such as `window_time()` do not support user-defined R functions at the moment.
-* Images must be orthorectified / regularly gridded; there is no support for curvilinear grids.
-* There is no support for vector data cubes ([stars](https://cran.r-project.org/package=stars) has vector data cubes). 
-
-
-
 # Further reading
 
 * [Official R package website](https://gdalcubes.github.io)