From 394d1a4c983a0a062379fabf35dfb7d61ab4ca6b Mon Sep 17 00:00:00 2001 From: Jakub Nowosad Date: Fri, 30 Aug 2024 16:01:29 +0200 Subject: [PATCH] improves docs (related to #41) --- R/supercells.R | 7 +++++-- man/supercells.Rd | 5 ++++- 2 files changed, 9 insertions(+), 3 deletions(-) diff --git a/R/supercells.R b/R/supercells.R index d27fdb1..17def1d 100644 --- a/R/supercells.R +++ b/R/supercells.R @@ -9,7 +9,7 @@ #' @param compactness A compactness value. Larger values cause clusters to be more compact/even (square). #' A compactness value depends on the range of input cell values and selected distance measure. #' @param dist_fun A distance function. Currently implemented distance functions are `"euclidean"`, `"jsd"`, `"dtw"` (dynamic time warping), name of any distance function from the `philentropy` package (see [philentropy::getDistMethods()]; "log2" is used in this case), or any user defined function accepting two vectors and returning one value. Default: `"euclidean"` -#' @param avg_fun An averaging function - how the values of the supercells' centers are calculated? The algorithm internally implements common functions `"mean"` and `"median"` (provided with quotation marks), but also accepts any fitting R function (e.g., `base::mean()` or `stats::median()`, provided as plain function name: `mean`). Default: `"mean"`. +#' @param avg_fun An averaging function - how the values of the supercells' centers are calculated? The algorithm internally implements common functions `"mean"` and `"median"` (provided with quotation marks), but also accepts any fitting R function (e.g., `base::mean()` or `stats::median()`, provided as plain function name: `mean`). Default: `"mean"`. See details for more information. #' @param clean Should connectivity of the supercells be enforced? #' @param iter The number of iterations performed to create the output. #' @param minarea Specifies the minimal size of a supercell (in cells). Only works when `clean = TRUE`. @@ -22,6 +22,9 @@ #' @param future Should the future package be used for parallelization of the calculations? Default: `FALSE`. If `TRUE`, you also need to specify `future::plan()`. #' @param verbose An integer specifying the level of text messages printed during calculations. 0 means no messages (default), 1 provides basic messages (e.g., calculation stage). #' +#' @details +#' If you want to use additional arguments for the averaging function (`avg_fun`), you can create a custom function. For example, if you want to calculate the mean by removing missing values, you can use the following code: `my_mean = function(x) mean(x, na.rm = TRUE)` and then provide `avg_fun = my_mean.` +#' #' @return An sf object with several columns: (1) supercells - an id of each supercell, (2) y and x coordinates, (3) one or more columns with average values of given variables in each supercell #' #' @references Achanta, R., Shaji, A., Smith, K., Lucchi, A., Fua, P., & Süsstrunk, S. (2012). SLIC Superpixels Compared to State-of-the-Art Superpixel Methods. IEEE Transactions on Pattern Analysis and Machine Intelligence, 34(11), 2274–2282. https://doi.org/10.1109/tpami.2012.120 @@ -146,7 +149,7 @@ run_slic_chunks = function(ext, x, step, compactness, dist_name, if (is.character(x)){ x = terra::rast(x) } - + # crops the input to the chunk extent x = x[ext[1]:ext[2], ext[3]:ext[4], drop = FALSE] # gets the number of rows and columns, and the values of the input diff --git a/man/supercells.Rd b/man/supercells.Rd index 5a7f2a7..a98abd5 100644 --- a/man/supercells.Rd +++ b/man/supercells.Rd @@ -33,7 +33,7 @@ A compactness value depends on the range of input cell values and selected dista \item{dist_fun}{A distance function. Currently implemented distance functions are \code{"euclidean"}, \code{"jsd"}, \code{"dtw"} (dynamic time warping), name of any distance function from the \code{philentropy} package (see \code{\link[philentropy:getDistMethods]{philentropy::getDistMethods()}}; "log2" is used in this case), or any user defined function accepting two vectors and returning one value. Default: \code{"euclidean"}} -\item{avg_fun}{An averaging function - how the values of the supercells' centers are calculated? The algorithm internally implements common functions \code{"mean"} and \code{"median"} (provided with quotation marks), but also accepts any fitting R function (e.g., \code{base::mean()} or \code{stats::median()}, provided as plain function name: \code{mean}). Default: \code{"mean"}.} +\item{avg_fun}{An averaging function - how the values of the supercells' centers are calculated? The algorithm internally implements common functions \code{"mean"} and \code{"median"} (provided with quotation marks), but also accepts any fitting R function (e.g., \code{base::mean()} or \code{stats::median()}, provided as plain function name: \code{mean}). Default: \code{"mean"}. See details for more information.} \item{clean}{Should connectivity of the supercells be enforced?} @@ -61,6 +61,9 @@ An sf object with several columns: (1) supercells - an id of each supercell, (2) \description{ Creates supercells based on single- or multi-band spatial raster data. It uses a modified version of the SLIC Superpixel algorithm by Achanta et al. (2012), allowing specification of a distance function. } +\details{ +If you want to use additional arguments for the averaging function (\code{avg_fun}), you can create a custom function. For example, if you want to calculate the mean by removing missing values, you can use the following code: \code{my_mean = function(x) mean(x, na.rm = TRUE)} and then provide \code{avg_fun = my_mean.} +} \examples{ library(supercells) # One variable