Improve Documentation for shift Function Regarding List Columns (#6201)

* improving documentation of shift * Update man/shift.Rd Co-authored-by: Benjamin Schwendinger <[email protected]> * updated doc * add spaces for formatting --------- Co-authored-by: nitish jha <[email protected]> Co-authored-by: Benjamin Schwendinger <[email protected]> Co-authored-by: Benjamin Schwendinger <[email protected]>
Rdatatable · Jul 2, 2024 · 6df30c3 · 6df30c3
1 parent da30260
commit 6df30c3
Showing 1 changed file with 2 additions and 0 deletions.
diff --git a/man/shift.Rd b/man/shift.Rd
@@ -25,6 +25,8 @@ shift(x, n=1L, fill, type=c("lag", "lead", "shift", "cyclic"), give.names=FALSE)
   Argument \code{n} allows multiple values. For example, \code{DT[, (cols) := shift(.SD, 1:2), by=id]} would lag every column of \code{.SD} by \code{1} and \code{2} for each group. If \code{.SD} contained four columns, the first two elements of the list would correspond to \code{lag=1} and \code{lag=2} for the first column of \code{.SD}, the next two for second column of \code{.SD} and so on. Please see examples for more.
 
   \code{shift} is designed mainly for use in data.tables along with \code{:=} or \code{set}. Therefore, it returns an unnamed list by default as assigning names for each group over and over can be quite time consuming with many groups. It may be useful to set names automatically in other cases, which can be done by setting \code{give.names} to \code{TRUE}.
+
+  Note that when using \code{shift} with a list, it should be a list of lists rather than a flattened list. The function was not designed to handle flattened lists directly. This also applies to the use of list columns in a data.table. For example, \code{DT = data.table(x=as.list(1:4))} is a data.table with four rows. Applying \code{DT[, shift(x)]} now lags every entry individually, rather than shifting the full columns like \code{DT[, shift(as.integer(x))]} does. Using \code{DT = data.table(x=list(1:4))} creates a data.table with one row. Now \code{DT[, shift(x)]} returns a data.table with four rows where x is lagged. To get a shifted data.table with the same number of rows, wrap the \code{shift} function in \code{list} or \code{dot}, e.g., \code{DT[, .(shift(x))]}.
 }
 \value{
   A list containing the lead/lag of input \code{x}.