feat: Implement <dataframe>$remove() and <lazyframe>$remove() (#1632)

Author: etiennebacher

NEWS.md

@@ -5,6 +5,8 @@
 ### New features
 
 - `pl$collect_all()` to efficiently collect a list of LazyFrames (#1598).
+- `<lazyframe>$remove()` and `<dataframe>$remove()` as a complement to
+  `$filter()` (#1632).
 
 ## polars 1.5.0
 

R/000-wrappers.R

@@ -4018,6 +4018,13 @@ class(`PlRExpr`) <- c("PlRExpr__bundle", "savvy_polars__sealed")
   }
 }
 
+`PlRLazyFrame_remove` <- function(self) {
+  function(`predicate`) {
+    `predicate` <- .savvy_extract_ptr(`predicate`, "PlRExpr")
+    .savvy_wrap_PlRLazyFrame(.Call(savvy_PlRLazyFrame_remove__impl, `self`, `predicate`))
+  }
+}
+
 `PlRLazyFrame_rename` <- function(self) {
   function(`existing`, `new`, `strict`) {
     .savvy_wrap_PlRLazyFrame(.Call(savvy_PlRLazyFrame_rename__impl, `self`, `existing`, `new`, `strict`))
@@ -4228,6 +4235,7 @@ class(`PlRExpr`) <- c("PlRExpr__bundle", "savvy_polars__sealed")
   e$`optimization_toggle` <- `PlRLazyFrame_optimization_toggle`(ptr)
   e$`profile` <- `PlRLazyFrame_profile`(ptr)
   e$`quantile` <- `PlRLazyFrame_quantile`(ptr)
+  e$`remove` <- `PlRLazyFrame_remove`(ptr)
   e$`rename` <- `PlRLazyFrame_rename`(ptr)
   e$`reverse` <- `PlRLazyFrame_reverse`(ptr)
   e$`rolling` <- `PlRLazyFrame_rolling`(ptr)

R/dataframe-frame.R

@@ -623,6 +623,33 @@ dataframe__filter <- function(...) {
     wrap()
 }
 
+#' @inherit lazyframe__remove title description params
+#' @inherit as_polars_df return
+#' @examples
+#' df <- pl$DataFrame(
+#'   ccy = c("USD", "EUR", "USD", "JPY"),
+#'   year = c(2021, 2022, 2023, 2023),
+#'   total = c(3245, NA, -6680, 25000),
+#' )
+#'
+#' # Remove rows matching a condition. Note that the row where `total` is null
+#' # is kept:
+#' df$remove(pl$col("total") >= 0)
+#'
+#' # Note that this is *not* the same as simply inverting the condition in
+#' # `$filter()` because `$filter()` doesn't keep predicates that evaluate to
+#' # null:
+#' df$filter(pl$col("total") < 0)
+#'
+#' # We can use multiple conditions, combined with and/or operators:
+#' df$remove((pl$col("total") >= 0) & (pl$col("ccy") == "USD"))
+#'
+#' df$remove((pl$col("total") >= 0) | (pl$col("ccy") == "USD"))
+dataframe__remove <- function(...) {
+  self$lazy()$remove(...)$collect(`_eager` = TRUE) |>
+    wrap()
+}
+
 #' Sort a DataFrame by the given columns
 #'
 #' @inherit lazyframe__sort description params details

R/lazyframe-frame.R

@@ -629,6 +629,42 @@ lazyframe__filter <- function(...) {
     wrap()
 }
 
+#' Remove rows, dropping those that match the given predicate expression(s)
+#'
+#' The original order of the remaining rows is preserved. Rows where the filter
+#' does not evaluate to `TRUE` are retained (this includes rows where the
+#' predicate evaluates as `null`).
+#'
+#' @param ... <[`dynamic-dots`][rlang::dyn-dots]> Expression that evaluates to
+#' a boolean Series.
+#'
+#' @inherit as_polars_lf return
+#' @examples
+#' lf <- pl$LazyFrame(
+#'   ccy = c("USD", "EUR", "USD", "JPY"),
+#'   year = c(2021, 2022, 2023, 2023),
+#'   total = c(3245, NA, -6680, 25000),
+#' )
+#'
+#' # Remove rows matching a condition. Note that the row where `total` is null
+#' # is kept:
+#' lf$remove(pl$col("total") >= 0)$collect()
+#'
+#' # Note that this is *not* the same as simply inverting the condition in
+#' # `$filter()` because `$filter()` doesn't keep predicates that evaluate to
+#' # null:
+#' lf$filter(pl$col("total") < 0)$collect()
+#'
+#' # We can use multiple conditions, combined with and/or operators:
+#' lf$remove((pl$col("total") >= 0) & (pl$col("ccy") == "USD"))$collect()
+#'
+#' lf$remove((pl$col("total") >= 0) | (pl$col("ccy") == "USD"))$collect()
+lazyframe__remove <- function(...) {
+  parse_predicates_constraints_into_expression(...) |>
+    self$`_ldf`$remove() |>
+    wrap()
+}
+
 #' Sort the LazyFrame by the given columns
 #'
 #' @param ... <[`dynamic-dots`][rlang::dyn-dots]> Column(s) to sort by. Can be

altdoc/mkdocs.yml

@@ -108,6 +108,7 @@ nav:
             - partition_by: man/dataframe__partition_by.md
             - pivot: man/dataframe__pivot.md
             - rechunk: man/dataframe__rechunk.md
+            - remove: man/dataframe__remove.md
             - rename: man/dataframe__rename.md
             - reverse: man/dataframe__reverse.md
             - rolling: man/dataframe__rolling.md
@@ -185,6 +186,7 @@ nav:
             - join: man/lazyframe__join.md
             - last: man/lazyframe__last.md
             - merge_sorted: man/lazyframe__merge_sorted.md
+            - remove: man/lazyframe__remove.md
             - rename: man/lazyframe__rename.md
             - reverse: man/lazyframe__reverse.md
             - rolling: man/lazyframe__rolling.md

man/dataframe__remove.Rd

@@ -2754,6 +2754,11 @@ SEXP savvy_PlRLazyFrame_quantile__impl(SEXP self__, SEXP c_arg__quantile, SEXP c
     return handle_result(res);
 }
 
+SEXP savvy_PlRLazyFrame_remove__impl(SEXP self__, SEXP c_arg__predicate) {
+    SEXP res = savvy_PlRLazyFrame_remove__ffi(self__, c_arg__predicate);
+    return handle_result(res);
+}
+
 SEXP savvy_PlRLazyFrame_rename__impl(SEXP self__, SEXP c_arg__existing, SEXP c_arg__new, SEXP c_arg__strict) {
     SEXP res = savvy_PlRLazyFrame_rename__ffi(self__, c_arg__existing, c_arg__new, c_arg__strict);
     return handle_result(res);
@@ -3920,6 +3925,7 @@ static const R_CallMethodDef CallEntries[] = {
     {"savvy_PlRLazyFrame_optimization_toggle__impl", (DL_FUNC) &savvy_PlRLazyFrame_optimization_toggle__impl, 12},
     {"savvy_PlRLazyFrame_profile__impl", (DL_FUNC) &savvy_PlRLazyFrame_profile__impl, 1},
     {"savvy_PlRLazyFrame_quantile__impl", (DL_FUNC) &savvy_PlRLazyFrame_quantile__impl, 3},
+    {"savvy_PlRLazyFrame_remove__impl", (DL_FUNC) &savvy_PlRLazyFrame_remove__impl, 2},
     {"savvy_PlRLazyFrame_rename__impl", (DL_FUNC) &savvy_PlRLazyFrame_rename__impl, 4},
     {"savvy_PlRLazyFrame_reverse__impl", (DL_FUNC) &savvy_PlRLazyFrame_reverse__impl, 1},
     {"savvy_PlRLazyFrame_rolling__impl", (DL_FUNC) &savvy_PlRLazyFrame_rolling__impl, 6},

man/lazyframe__remove.Rd

@@ -558,6 +558,7 @@ SEXP savvy_PlRLazyFrame_null_count__ffi(SEXP self__);
 SEXP savvy_PlRLazyFrame_optimization_toggle__ffi(SEXP self__, SEXP c_arg__type_coercion, SEXP c_arg___type_check, SEXP c_arg__predicate_pushdown, SEXP c_arg__projection_pushdown, SEXP c_arg__simplify_expression, SEXP c_arg__slice_pushdown, SEXP c_arg__comm_subplan_elim, SEXP c_arg__comm_subexpr_elim, SEXP c_arg__cluster_with_columns, SEXP c_arg___eager, SEXP c_arg___check_order);
 SEXP savvy_PlRLazyFrame_profile__ffi(SEXP self__);
 SEXP savvy_PlRLazyFrame_quantile__ffi(SEXP self__, SEXP c_arg__quantile, SEXP c_arg__interpolation);
+SEXP savvy_PlRLazyFrame_remove__ffi(SEXP self__, SEXP c_arg__predicate);
 SEXP savvy_PlRLazyFrame_rename__ffi(SEXP self__, SEXP c_arg__existing, SEXP c_arg__new, SEXP c_arg__strict);
 SEXP savvy_PlRLazyFrame_reverse__ffi(SEXP self__);
 SEXP savvy_PlRLazyFrame_rolling__ffi(SEXP self__, SEXP c_arg__index_column, SEXP c_arg__period, SEXP c_arg__offset, SEXP c_arg__closed, SEXP c_arg__by);

src/init.c

@@ -111,6 +111,11 @@ impl PlRLazyFrame {
         Ok(ldf.filter(predicate.inner.clone()).into())
     }
 
+    fn remove(&self, predicate: &PlRExpr) -> Result<Self> {
+        let ldf = self.ldf.clone();
+        Ok(ldf.remove(predicate.inner.clone()).into())
+    }
+
     fn select(&mut self, exprs: ListSexp) -> Result<Self> {
         let ldf = self.ldf.clone();
         let exprs = <Wrap<Vec<Expr>>>::from(exprs).0;