diff --git a/man/predict.cube.Rd b/man/predict.cube.Rd index 540bfe1..ef9b1ee 100644 --- a/man/predict.cube.Rd +++ b/man/predict.cube.Rd @@ -2,33 +2,34 @@ % Please edit documentation in R/predict.R \name{predict.cube} \alias{predict.cube} -\title{Predict values based on a trained model to all pixels of a data cube.} +\title{Model prediction} \usage{ \method{predict}{cube}(object, model, ..., output_names = c("pred"), keep_bands = FALSE) } \arguments{ \item{object}{a data cube proxy object (class cube)} -\item{model}{model used for prediction (e.g. from \code{caret})} +\item{model}{model used for prediction (e.g. from \code{caret} or \code{tidymodels})} -\item{...}{further arguments passed to predict} +\item{...}{further arguments passed to the model-specific predict method} \item{output_names}{optional character vector for output variable(s)} \item{keep_bands}{logical; keep bands of input data cube, defaults to FALSE, i.e. original bands will be dropped} } \description{ -Predict values based on a trained model to all pixels of a data cube. +Apply a trained model on all pixels of a data cube. } \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. } diff --git a/man/window_space.Rd b/man/window_space.Rd index e0e3919..8df4cd1 100644 --- a/man/window_space.Rd +++ b/man/window_space.Rd @@ -2,7 +2,7 @@ % Please edit documentation in R/window.R \name{window_space} \alias{window_space} -\title{Apply a moving window operation or convolution kernel over the spatial dimensions of a data cube} +\title{Apply a moving window (focal) operation or a convolution kernel over spatial dimensions of a data cube.} \usage{ window_space(x, expr, ..., kernel, window, keep_bands = FALSE, pad = NA) } @@ -13,32 +13,37 @@ window_space(x, expr, ..., kernel, window, keep_bands = FALSE, pad = NA) \item{...}{optional additional expressions (if expr is not a vector)} -\item{kernel}{two dimensional kernel (matrix) applied as convolution (must have odd number of rows and columns)} +\item{kernel}{two dimensional kernel (matrix) applied as convolution (with odd number of rows and columns)} -\item{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]} +\item{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]} \item{keep_bands}{logical; if FALSE (the default), original data cube bands will be dropped.} -\item{pad}{Padding method applied to the borders; use NULL for no padding, a numeric a fill value, or one of "REPLICATE", "REFLECT", "REFLECT_PIXEL"} +\item{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"} } \value{ proxy data cube object } \description{ -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). } \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. -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". +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". + +Padding methods "REPLICATE", "REFLECT", "REFLEX_PIXEL" are defined according to +\url{https://openeo.org/documentation/1.0/processes.html#apply_kernel}. } \note{ Implemented reducers will ignore any NAN values (as \code{na.rm = TRUE} does). @@ -65,8 +70,15 @@ L8.cube = select_bands(L8.cube, c("B04", "B05")) 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) +} } diff --git a/man/window_time.Rd b/man/window_time.Rd index 03ce65c..525e295 100644 --- a/man/window_time.Rd +++ b/man/window_time.Rd @@ -2,7 +2,7 @@ % Please edit documentation in R/window.R \name{window_time} \alias{window_time} -\title{Apply a moving window function over the time dimension of a data cube} +\title{Apply a moving window operations over the time dimension of a data cube} \usage{ window_time(x, expr, ..., kernel, window) }