refine froll docs (#7383)

Author: jangorecki

man/froll.Rd

@@ -45,11 +45,11 @@
 }
 \arguments{
   \item{x}{ Integer, numeric or logical vector, coerced to numeric, on which sliding window calculates an aggregate function. It supports vectorized input, then it needs to be a \code{data.table}, \code{data.frame} or a \code{list}, in which case a rolling function is applied to each column/vector. }
-  \item{n}{ Integer, non-negative, rolling window size. This is the \emph{total} number of included values in aggregate function. In case of an adaptive rolling function window size has to be provided as a vector for each indivdual value of \code{x}. It supports vectorized input, then it needs to be a vector, or in case of an adaptive rolling a \code{list} of vectors. }
-  \item{fill}{ Numeric; value to pad by. Defaults to \code{NA}. }
-  \item{algo}{ Character, default \code{"fast"}. When set to \code{"exact"}, a slower (but more accurate) algorithm is used. It suffers less from floating point rounding errors by performing an extra pass, and carefully handles all non-finite values. It will use multiple cores where available. See Details for more information. }
+  \item{n}{ Integer, non-negative, non-NA, rolling window size. This is the \emph{total} number of included values in aggregate function. In case of an adaptive rolling function window size has to be provided as a vector for each indivdual value of \code{x}. It supports vectorized input, then it needs to be a vector, or in case of an adaptive rolling a \code{list} of vectors. }
+  \item{fill}{ Numeric; value to pad by for an incomplete window iterations. Defaults to \code{NA}. When partial=TRUE this argument is ignored. }
+  \item{algo}{ Character, default \code{"fast"}. When set to \code{"exact"}, a slower (in some cases more accurate) algorithm is used. It will use multiple cores where available. See Details for more information. }
   \item{align}{ Character, specifying the "alignment" of the rolling window, defaulting to \code{"right"}. \code{"right"} covers preceding rows (the window \emph{ends} on the current value); \code{"left"} covers following rows (the window \emph{starts} on the current value); \code{"center"} is halfway in between (the window is \emph{centered} on the current value, biased towards \code{"left"} when \code{n} is even). }
-  \item{na.rm}{ Logical, default \code{FALSE}. Should missing values be removed when calculating window? }
+  \item{na.rm}{ Logical, default \code{FALSE}. Should missing values be removed when calculating aggregate function on a window? }
   \item{has.nf}{ Logical. If it is known whether \code{x} contains non-finite values (\code{NA}, \code{NaN}, \code{Inf}, \code{-Inf}), then setting this to \code{TRUE} or \code{FALSE} may speed up computation. Defaults to \code{NA}. See \emph{has.nf argument} section below for details. }
   \item{adaptive}{ Logical, default \code{FALSE}. Should the rolling function be calculated adaptively? See \emph{Adaptive rolling functions} section below for details. }
   \item{partial}{ Logical, default \code{FALSE}. Should the rolling window size(s) provided in \code{n} be computed also for leading incomplete running window. See \emph{\code{partial} argument} section below for details. }
@@ -61,24 +61,9 @@
 
   Argument \code{n} allows multiple values to apply rolling function on multiple window sizes. If \code{adaptive=TRUE}, then \code{n} can be a list to specify multiple window sizes for adaptive rolling computation. See \emph{Adaptive rolling functions} section below for details.
 
-  When multiple columns and/or multiple window widths are provided, then computations run in parallel. The exception is for \code{algo="exact"}, which runs in parallel even for single column and single window width. By default, data.table uses only half of available CPUs, see \code{\link{setDTthreads}} for details on how to tune CPU usage.
+  When multiple columns or multiple windows width are provided, then they are run in parallel. The exception is for \code{algo="exact"} or \code{adaptive=TRUE}, which runs in parallel even for single column and single window width. By default, data.table uses only half of available CPUs, see \code{\link{setDTthreads}} for details on how to tune CPU usage.
 
-  Adaptive rolling functions are a special case where each
-  observation has its own corresponding rolling window width. Due to the logic
-  of adaptive rolling functions, the following restrictions apply:
-  \itemize{
-    \item \code{align} only \code{"right"}.
-    \item if list of vectors is passed to \code{x}, then all
-      vectors within it must have equal length.
-  }
-
-  When multiple columns or multiple windows width are provided, then they
-  are run in parallel. The exception is for \code{algo="exact"}, which runs in
-  parallel already.
-
-  Setting \code{options(datatable.verbose=TRUE)} will display various
-  information about how rolling function processed. It will not print
-  information in real-time but only at the end of the processing.
+  Setting \code{options(datatable.verbose=TRUE)} will display various information about how rolling function processed. It will not print information in real-time but only at the end of the processing.
 }
 \value{
   For a non \emph{vectorized} input (\code{x} is not a list, and \code{n} specify single rolling window) a \code{vector} is returned, for convenience. Thus, rolling functions can be used conveniently within \code{data.table} syntax. For a \emph{vectorized} input a list is returned.
@@ -96,8 +81,8 @@
       \item (\emph{mean, sum, prod, var, sd}) detect non-finite, re-run non-finite aware.
       \item (\emph{max, min, median}) does not detect non-finites and may silently produce an incorrect answer.
     }
-    In general \code{has.nf=FALSE && any(!is.finite(x))} should be considered as undefined behavior. Therefore \code{has.nf=FALSE} should be used with care.
   }
+  In general \code{has.nf=FALSE && any(!is.finite(x))} should be considered as undefined behavior. Therefore \code{has.nf=FALSE} should be used with care.
 }
 \section{Implementation}{
   Most of the rolling functions have 4 different implementations. First factor that decides which implementation is used is the \code{adaptive} argument (either \code{TRUE} or \code{FALSE}), see section below for details. Then for each of those two algorithms there are usually two implementations depending on the \code{algo} argument.
@@ -117,7 +102,7 @@
   }
 }
 \section{Adaptive rolling functions}{
-  Adaptive rolling functions are a special case where each observation has its own corresponding rolling window width. Therefore, values passed to \code{n} argument must be series corresponding to observations in \code{x}. If multiple windows are meant to be computed, then a list of integer vectors is expected; each list element must be an integer vector of window size corresponding to observations in \code{x}; see Examples. Due to the logic or implementation of adaptive rolling functions, the following restrictions apply
+  Adaptive rolling functions are a special case where each observation has its own corresponding rolling window width. Therefore, values passed to \code{n} argument must be series corresponding to observations in \code{x}. If multiple windows are meant to be computed, then a list of integer vectors is expected; each list element must be an integer vector of window size corresponding to observations in \code{x}; see Examples. Due to the logic or implementation of adaptive rolling functions, the following restrictions apply:
   \itemize{
     \item \code{align} does not support \code{"center"}.
     \item if list of vectors is passed to \code{x}, then all vectors within it must have equal length due to the fact that length of adaptive window widths must match the length of vectors in \code{x}.
@@ -131,19 +116,14 @@
 \section{\code{zoo} package users notice}{
   Users coming from most popular package for rolling functions \code{zoo} might expect following differences in \code{data.table} implementation
   \itemize{
-    \item rolling function will always return result of the same length
-      as input.
+    \item rolling function will always return result of the same length as input.
     \item \code{fill} defaults to \code{NA}.
-    \item \code{fill} accepts only constant values. It does not support
-      for \emph{na.locf} or other functions.
+    \item \code{fill} accepts only constant values. It does not support for \emph{na.locf} or other functions.
     \item \code{align} defaults to \code{"right"}.
-    \item \code{na.rm} is respected, and other functions are not needed
-      when input contains \code{NA}.
+    \item \code{na.rm} is respected, and other functions are not needed when input contains \code{NA}.
     \item integers and logical are always coerced to numeric.
-    \item when \code{adaptive=FALSE} (default), then \code{n} must be a
-      numeric vector. List is not accepted.
-    \item when \code{adaptive=TRUE}, then \code{n} must be vector of
-      length equal to \code{nrow(x)}, or list of such vectors.
+    \item when \code{adaptive=FALSE} (default), then \code{n} must be a numeric vector. List is not accepted.
+    \item when \code{adaptive=TRUE}, then \code{n} must be vector of length equal to \code{nrow(x)}, or list of such vectors.
   }
 }
 \examples{