From e331a520b8dd53f7a4fd272dd77cad49fef334d5 Mon Sep 17 00:00:00 2001 From: Alex Date: Thu, 24 Aug 2023 13:29:02 -0400 Subject: [PATCH] Improve clarity of documentation for focal weights --- man/focal.Rd | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/man/focal.Rd b/man/focal.Rd index 48aa5b27e..e91c11356 100644 --- a/man/focal.Rd +++ b/man/focal.Rd @@ -40,11 +40,13 @@ Calculate focal ("moving window") values for each cell. \details{ \code{focal} -The window used must have odd dimensions. If you need even sides, you can use a matrix and add a column or row with weights of zero. +The window used must have odd dimensions. If you need even sides, you can use a matrix and add a column or row of \code{NA}'s to mask out values. -Window values are typically 0 or 1, or a value between 0 and 1 if you are using a rectangular area and/or the "sum" function. They can also be \code{NA}; these are ignored in the computation. That can be useful to compute, for example, the minimum or maximum value for a non-rectangular area. +Window values are typically 1 or \code{NA} to indicate whether a value is used or ignored in computations, respectively. \code{NA} values in \code{w} can be useful for creating non-rectangular (e.g. circular) windows. -The "mean" function is a special case, as zero weights are ignored automatically. +A weights matrix of numeric values can also be supplied to \code{w}. In the case of a weights matrix, cells with \code{NA} weights will be ignored, and the rest of the values in the focal window will be multiplied by the corresponding weight prior to `fun` being applied. Note, \code{na.rm} does not need to be \code{TRUE} if \code{w} contains \code{NA} values as these cells are ignored in computations. + +The "mean" function is a special case, where supplying weights to \code{w} will instead calculate a weighted mean. The "sum" function returns \code{NA} if all focal cells are \code{NA} and \code{na.rm=TRUE}. R would normally return a zero in these cases. See the difference between \code{focal(x, fun=sum, na.rm=TRUE)} and \code{focal(x, fun=\(i) sum(i, na.rm=TRUE))}