feat!: remove $shift_and_fill(), add fill_value to $shift() (#1201

)

NEWS.md

@@ -25,6 +25,10 @@
 - In `$dt$epoch()`, the argument `tu` is renamed to `time_unit` (#1196).
 - In `$fill_nan()` for `DataFrame`, `LazyFrame` and `Expr`, the argument is
   renamed `value` (#1198).
+- `$shift_and_fill()` is removed and replaced by a new argument `fill_value` in
+  `$shift()`. `$shift_and_fill(fill_value, periods)` can be replaced by
+  `$shift(n, fill_value)` (#1201).
+- In `$shift()` for various `Expr`, the argument `periods` is renamed `n` (#1201).
 
 ### New features
 

R/dataframe__frame.R

@@ -781,37 +781,22 @@ DataFrame_equals = function(other) {
 #' rows will be discarded. Vice-versa if the period is negative. In the end,
 #' the total number of rows of the DataFrame doesn't change.
 #'
-#' @keywords DataFrame
-#' @param periods Number of periods to shift (can be negative).
-#' @return DataFrame
-#' @examples
-#' pl$DataFrame(mtcars)$shift(2)
-#'
-#' pl$DataFrame(mtcars)$shift(-2)
-DataFrame_shift = function(periods = 1) {
-  self$lazy()$shift(periods)$collect()
-}
-
-#' @title Shift and fill
+#' @param n Number of indices to shift forward. If a negative value is
+#' passed, values are shifted in the opposite direction instead.
+#' @param fill_value Fill the resulting null values with this value. Accepts
+#' expression input. Non-expression inputs are parsed as literals.
 #'
-#' @description Shift the values by a given period and fill the resulting null
-#' values. See the docs of `$shift()` for more details on shifting.
-#' @keywords DataFrame
-#'
-#' @param fill_value Fill new `NULL` values with this value. Must of length 1.
-#' A logical value will be converted to numeric.
-#' @param periods Number of periods to shift (can be negative).
 #' @return DataFrame
 #' @examples
-#' df = pl$DataFrame(mtcars)
+#' df = pl$DataFrame(a = 1:4, b = 5:8)
+#'
+#' df$shift(2)
 #'
-#' # insert two rows filled with 0 at the top of the DataFrame
-#' df$shift_and_fill(0, 2)
+#' df$shift(-2)
 #'
-#' # automatic conversion of logical value to numeric
-#' df$shift_and_fill(TRUE, 2)
-DataFrame_shift_and_fill = function(fill_value, periods = 1) {
-  self$lazy()$shift_and_fill(fill_value, periods)$collect()
+#' df$shift(-2, fill_value = 100)
+DataFrame_shift = function(n = 1, fill_value = NULL) {
+  self$lazy()$shift(n, fill_value)$collect()
 }
 
 #' Modify/append column(s)

R/expr__array.R

@@ -233,7 +233,7 @@ ExprArr_any = function() .pr$Expr$arr_any(self)
 
 #' Shift array values by `n` indices
 #'
-#' @inheritParams ExprList_shift
+#' @inheritParams DataFrame_shift
 #'
 #' @return Expr
 #' @examples
@@ -246,8 +246,8 @@ ExprArr_any = function() .pr$Expr$arr_any(self)
 #'   shift_by_expr = pl$col("values")$arr$shift(pl$col("idx")),
 #'   shift_by_lit = pl$col("values")$arr$shift(2)
 #' )
-ExprArr_shift = function(periods = 1) {
-  .pr$Expr$arr_shift(self, periods) |>
+ExprArr_shift = function(n = 1) {
+  .pr$Expr$arr_shift(self, n) |>
     unwrap("in $arr$shift():")
 }
 

R/expr__expr.R

@@ -1555,39 +1555,22 @@ Expr_gather = function(indices) {
     unwrap("in $gather():")
 }
 
-#' Shift values
+#' Shift values by the given number of indices
+#'
+#' @inheritParams DataFrame_shift
 #'
-#' @param periods Number of periods to shift, may be negative.
 #' @return Expr
 #' @examples
 #' pl$DataFrame(a = c(1, 2, 4, 5, 8))$
 #'   with_columns(
 #'   pl$col("a")$shift(-2)$alias("shift-2"),
 #'   pl$col("a")$shift(2)$alias("shift+2")
 #' )
-Expr_shift = function(periods = 1) {
-  .pr$Expr$shift(self, periods) |>
+Expr_shift = function(n = 1, fill_value = NULL) {
+  .pr$Expr$shift(self, n, fill_value) |>
     unwrap("in $shift():")
 }
 
-#' Shift and fill values
-#'
-#' Shift the values by a given period and fill the resulting null values.
-#'
-#' @inheritParams Expr_shift
-#' @param fill_value Fill null values with the result of this expression.
-#' @return Expr
-#' @examples
-#' pl$DataFrame(a = c(1, 2, 4, 5, 8))$
-#'   with_columns(
-#'   pl$col("a")$shift_and_fill(-2, fill_value = 42)$alias("shift-2"),
-#'   pl$col("a")$shift_and_fill(2, fill_value = pl$col("a") / 2)$alias("shift+2")
-#' )
-Expr_shift_and_fill = function(periods, fill_value) {
-  .pr$Expr$shift_and_fill(self, periods, pl$lit(fill_value)) |>
-    unwrap("in $shift_and_fill():")
-}
-
 #' Fill null values with a value or strategy
 #'
 #' @param value Expr or something coercible in an Expr

R/expr__list.R

@@ -311,8 +311,7 @@ ExprList_diff = function(n = 1, null_behavior = c("ignore", "drop")) {
 
 #' Shift list values by `n` indices
 #'
-#' @param periods Number of places to shift (may be negative). Can be an Expr.
-#' Strings are *not* parsed as columns.
+#' @inheritParams DataFrame_shift
 #'
 #' @return Expr
 #'
@@ -325,7 +324,10 @@ ExprList_diff = function(n = 1, null_behavior = c("ignore", "drop")) {
 #'   shift_by_expr = pl$col("s")$list$shift(pl$col("idx")),
 #'   shift_by_lit = pl$col("s")$list$shift(2)
 #' )
-ExprList_shift = function(periods = 1) unwrap(.pr$Expr$list_shift(self, periods))
+ExprList_shift = function(n = 1) {
+  .pr$Expr$list_shift(self, n) |>
+    unwrap("in $list$shift():")
+}
 
 #' Slice list
 #'

R/extendr-wrappers.R

@@ -548,9 +548,7 @@ RPolarsExpr$backward_fill <- function(limit) .Call(wrap__RPolarsExpr__backward_f
 
 RPolarsExpr$forward_fill <- function(limit) .Call(wrap__RPolarsExpr__forward_fill, self, limit)
 
-RPolarsExpr$shift <- function(periods) .Call(wrap__RPolarsExpr__shift, self, periods)
-
-RPolarsExpr$shift_and_fill <- function(periods, fill_value) .Call(wrap__RPolarsExpr__shift_and_fill, self, periods, fill_value)
+RPolarsExpr$shift <- function(n, fill_value) .Call(wrap__RPolarsExpr__shift, self, n, fill_value)
 
 RPolarsExpr$fill_null <- function(expr) .Call(wrap__RPolarsExpr__fill_null, self, expr)
 
@@ -1220,9 +1218,7 @@ RPolarsLazyFrame$var <- function(ddof) .Call(wrap__RPolarsLazyFrame__var, self,
 
 RPolarsLazyFrame$quantile <- function(quantile, interpolation) .Call(wrap__RPolarsLazyFrame__quantile, self, quantile, interpolation)
 
-RPolarsLazyFrame$shift <- function(periods) .Call(wrap__RPolarsLazyFrame__shift, self, periods)
-
-RPolarsLazyFrame$shift_and_fill <- function(fill_value, periods) .Call(wrap__RPolarsLazyFrame__shift_and_fill, self, fill_value, periods)
+RPolarsLazyFrame$shift <- function(n, fill_value) .Call(wrap__RPolarsLazyFrame__shift, self, n, fill_value)
 
 RPolarsLazyFrame$reverse <- function() .Call(wrap__RPolarsLazyFrame__reverse, self)
 

R/group_by.R

@@ -272,25 +272,15 @@ GroupBy_quantile = function(quantile, interpolation = "nearest") {
   self$agg(pl$all()$quantile(quantile, interpolation))
 }
 
-#' @title Shift
-#' @description Shift the values by a given period.
-#' @keywords GroupBy
-#' @param periods integer Number of periods to shift (may be negative).
-#' @return GroupBy
-#' @examples pl$DataFrame(mtcars)$group_by("cyl")$shift(2)
-GroupBy_shift = function(periods = 1) {
-  self$agg(pl$all()$shift(periods))
-}
-
-#' @title Shift and fill
-#' @description Shift and fill the values by a given period.
-#' @keywords GroupBy
-#' @param fill_value fill None values with the result of this expression.
-#' @param periods integer Number of periods to shift (may be negative).
+#' Shift the values by a given period
+#'
+#' @inheritParams DataFrame_shift
+#'
 #' @return GroupBy
-#' @examples pl$DataFrame(mtcars)$group_by("cyl")$shift_and_fill(99, 1)
-GroupBy_shift_and_fill = function(fill_value, periods = 1) {
-  self$agg(pl$all()$shift_and_fill(periods, fill_value))
+#' @examples
+#' pl$DataFrame(mtcars)$group_by("cyl")$shift(2)
+GroupBy_shift = function(n = 1, fill_value = NULL) {
+  self$agg(pl$all()$shift(n, fill_value))
 }
 
 #' @title GroupBy null count

R/lazyframe__lazy.R

@@ -1104,27 +1104,22 @@ LazyFrame_fill_null = function(fill_value) {
   unwrap(.pr$LazyFrame$fill_null(self, wrap_e_result(fill_value)), "in $fill_null():")
 }
 
-#' @title Shift
-#' @description Shift the values by a given period.
-#' @keywords LazyFrame
-#' @param periods integer Number of periods to shift (may be negative).
-#' @return LazyFrame
-#' @examples pl$LazyFrame(mtcars)$shift(2)$collect()
-LazyFrame_shift = function(periods = 1) {
-  unwrap(.pr$LazyFrame$shift(self, periods), "in $shift():")
-}
-
 #' Shift a LazyFrame
 #'
-#' @description Shift the values by a given period. If the period (`n`) is positive,
-#' then `n` rows will be inserted at the top of the LazyFrame and the last `n`
-#' rows will be discarded. Vice-versa if the period is negative. In the end,
-#' the total number of rows of the LazyFrame doesn't change.
-#' @inheritParams DataFrame_shift_and_fill
+#' @inherit DataFrame_shift description params
+#'
 #' @return LazyFrame
-#' @examples pl$LazyFrame(mtcars)$shift_and_fill(0., 2.)$collect()$to_data_frame()
-LazyFrame_shift_and_fill = function(fill_value, periods = 1) {
-  unwrap(.pr$LazyFrame$shift_and_fill(self, wrap_e(fill_value), periods), "in $shift_and_fill():")
+#' @examples
+#' lf = pl$LazyFrame(a = 1:4, b = 5:8)
+#'
+#' lf$shift(2)$collect()
+#'
+#' lf$shift(-2)$collect()
+#'
+#' lf$shift(-2, fill_value = 100)$collect()
+LazyFrame_shift = function(n = 1, fill_value = NULL) {
+  .pr$LazyFrame$shift(self, n, fill_value) |>
+    unwrap("in $shift():")
 }
 
 #' Drop columns of a LazyFrame