polars-df 0.23.0 → 0.24.0

data/lib/polars/expr.rb

@@ -1,9 +1,6 @@
 module Polars
   # Expressions that can be used in various contexts.
   class Expr
-    # @private
-    NO_DEFAULT = Object.new
-
     # @private
     attr_accessor :_rbexpr
 
@@ -182,21 +179,14 @@ module Polars
 
     # Cast to physical representation of the logical dtype.
     #
-    # - `:date` -> `:i32`
-    # - `:datetime` -> `:i64`
-    # - `:time` -> `:i64`
-    # - `:duration` -> `:i64`
-    # - `:cat` -> `:u32`
-    # - Other data types will be left unchanged.
-    #
     # @return [Expr]
     #
     # @example
     #   Polars::DataFrame.new({"vals" => ["a", "x", nil, "a"]}).with_columns(
     #     [
-    #       Polars.col("vals").cast(:cat),
+    #       Polars.col("vals").cast(Polars::Categorical),
     #       Polars.col("vals")
-    #         .cast(:cat)
+    #         .cast(Polars::Categorical)
     #         .to_physical
     #         .alias("vals_physical")
     #     ]
@@ -233,8 +223,8 @@ module Polars
     #   # ╞══════╪═══════╡
     #   # │ true ┆ false │
     #   # └──────┴───────┘
-    def any(drop_nulls: true)
-      wrap_expr(_rbexpr.any(drop_nulls))
+    def any(ignore_nulls: true)
+      wrap_expr(_rbexpr.any(ignore_nulls))
     end
 
     # Check if all boolean values in a Boolean column are `true`.
@@ -258,8 +248,8 @@ module Polars
     #   # ╞══════╪═══════╪═══════╡
     #   # │ true ┆ false ┆ false │
     #   # └──────┴───────┴───────┘
-    def all(drop_nulls: true)
-      wrap_expr(_rbexpr.all(drop_nulls))
+    def all(ignore_nulls: true)
+      wrap_expr(_rbexpr.all(ignore_nulls))
     end
 
     # Return indices where expression evaluates `true`.
@@ -449,114 +439,6 @@ module Polars
       meta.as_selector.exclude(columns, *more_columns).as_expr
     end
 
-    # Keep the original root name of the expression.
-    #
-    # @return [Expr]
-    #
-    # @example
-    #   df = Polars::DataFrame.new(
-    #     {
-    #       "a" => [1, 2],
-    #       "b" => [3, 4]
-    #     }
-    #   )
-    #   df.with_columns([(Polars.col("a") * 9).alias("c").keep_name])
-    #   # =>
-    #   # shape: (2, 2)
-    #   # ┌─────┬─────┐
-    #   # │ a   ┆ b   │
-    #   # │ --- ┆ --- │
-    #   # │ i64 ┆ i64 │
-    #   # ╞═════╪═════╡
-    #   # │ 9   ┆ 3   │
-    #   # │ 18  ┆ 4   │
-    #   # └─────┴─────┘
-    def keep_name
-      name.keep
-    end
-
-    # Add a prefix to the root column name of the expression.
-    #
-    # @return [Expr]
-    #
-    # @example
-    #   df = Polars::DataFrame.new(
-    #     {
-    #       "a" => [1, 2, 3],
-    #       "b" => ["x", "y", "z"]
-    #     }
-    #   )
-    #   df.with_columns(Polars.all.reverse.name.prefix("reverse_"))
-    #   # =>
-    #   # shape: (3, 4)
-    #   # ┌─────┬─────┬───────────┬───────────┐
-    #   # │ a   ┆ b   ┆ reverse_a ┆ reverse_b │
-    #   # │ --- ┆ --- ┆ ---       ┆ ---       │
-    #   # │ i64 ┆ str ┆ i64       ┆ str       │
-    #   # ╞═════╪═════╪═══════════╪═══════════╡
-    #   # │ 1   ┆ x   ┆ 3         ┆ z         │
-    #   # │ 2   ┆ y   ┆ 2         ┆ y         │
-    #   # │ 3   ┆ z   ┆ 1         ┆ x         │
-    #   # └─────┴─────┴───────────┴───────────┘
-    def prefix(prefix)
-      name.prefix(prefix)
-    end
-
-    # Add a suffix to the root column name of the expression.
-    #
-    # @return [Expr]
-    #
-    # @example
-    #   df = Polars::DataFrame.new(
-    #     {
-    #       "a" => [1, 2, 3],
-    #       "b" => ["x", "y", "z"]
-    #     }
-    #   )
-    #   df.with_columns(Polars.all.reverse.name.suffix("_reverse"))
-    #   # =>
-    #   # shape: (3, 4)
-    #   # ┌─────┬─────┬───────────┬───────────┐
-    #   # │ a   ┆ b   ┆ a_reverse ┆ b_reverse │
-    #   # │ --- ┆ --- ┆ ---       ┆ ---       │
-    #   # │ i64 ┆ str ┆ i64       ┆ str       │
-    #   # ╞═════╪═════╪═══════════╪═══════════╡
-    #   # │ 1   ┆ x   ┆ 3         ┆ z         │
-    #   # │ 2   ┆ y   ┆ 2         ┆ y         │
-    #   # │ 3   ┆ z   ┆ 1         ┆ x         │
-    #   # └─────┴─────┴───────────┴───────────┘
-    def suffix(suffix)
-      name.suffix(suffix)
-    end
-
-    # Rename the output of an expression by mapping a function over the root name.
-    #
-    # @return [Expr]
-    #
-    # @example
-    #   df = Polars::DataFrame.new(
-    #     {
-    #       "A" => [1, 2],
-    #       "B" => [3, 4]
-    #     }
-    #   )
-    #   df.select(
-    #     Polars.all.reverse.map_alias { |colName| colName + "_reverse" }
-    #   )
-    #   # =>
-    #   # shape: (2, 2)
-    #   # ┌───────────┬───────────┐
-    #   # │ A_reverse ┆ B_reverse │
-    #   # │ ---       ┆ ---       │
-    #   # │ i64       ┆ i64       │
-    #   # ╞═══════════╪═══════════╡
-    #   # │ 2         ┆ 4         │
-    #   # │ 1         ┆ 3         │
-    #   # └───────────┴───────────┘
-    def map_alias(&f)
-      name.map(&f)
-    end
-
     # Negate a boolean expression.
     #
     # @return [Expr]
@@ -609,7 +491,7 @@ module Polars
     #       "b" => [1.0, 2.0, Float::NAN, 1.0, 5.0]
     #     }
     #   )
-    #   df.with_column(Polars.all.is_null.suffix("_isnull"))
+    #   df.with_columns(Polars.all.is_null.name.suffix("_isnull"))
     #   # =>
     #   # shape: (5, 4)
     #   # ┌──────┬─────┬──────────┬──────────┐
@@ -638,7 +520,7 @@ module Polars
     #       "b" => [1.0, 2.0, Float::NAN, 1.0, 5.0]
     #     }
     #   )
-    #   df.with_column(Polars.all.is_not_null.suffix("_not_null"))
+    #   df.with_columns(Polars.all.is_not_null.name.suffix("_not_null"))
     #   # =>
     #   # shape: (5, 4)
     #   # ┌──────┬─────┬────────────┬────────────┐
@@ -723,7 +605,7 @@ module Polars
     #       "b" => [1.0, 2.0, Float::NAN, 1.0, 5.0]
     #     }
     #   )
-    #   df.with_column(Polars.col(Polars::Float64).is_nan.suffix("_isnan"))
+    #   df.with_columns(Polars.col(Polars::Float64).is_nan.name.suffix("_isnan"))
     #   # =>
     #   # shape: (5, 3)
     #   # ┌──────┬─────┬─────────┐
@@ -756,7 +638,7 @@ module Polars
     #       "b" => [1.0, 2.0, Float::NAN, 1.0, 5.0]
     #     }
     #   )
-    #   df.with_column(Polars.col(Polars::Float64).is_not_nan.suffix("_is_not_nan"))
+    #   df.with_columns(Polars.col(Polars::Float64).is_not_nan.name.suffix("_is_not_nan"))
     #   # =>
     #   # shape: (5, 3)
     #   # ┌──────┬─────┬──────────────┐
@@ -1009,8 +891,8 @@ module Polars
     # @return [Expr]
     #
     # @note
-    #   Dtypes in `:i8`, `:u8`, `:i16`, and `:u16` are cast to
-    #   `:i64` before summing to prevent overflow issues.
+    #   Dtypes in \\\\{Int8, UInt8, Int16, UInt16} are cast to
+    #   Int64 before summing to prevent overflow issues.
     #
     # @example
     #   df = Polars::DataFrame.new({"a" => [1, 2, 3, 4]})
@@ -1035,7 +917,6 @@ module Polars
     def cum_sum(reverse: false)
       wrap_expr(_rbexpr.cum_sum(reverse))
     end
-    alias_method :cumsum, :cum_sum
 
     # Get an array with the cumulative product computed at every element.
     #
@@ -1045,8 +926,8 @@ module Polars
     # @return [Expr]
     #
     # @note
-    #   Dtypes in `:i8`, `:u8`, `:i16`, and `:u16` are cast to
-    #   `:i64` before summing to prevent overflow issues.
+    #   Dtypes in \\\\{Int8, UInt8, Int16, UInt16} are cast to
+    #   Int64 before summing to prevent overflow issues.
     #
     # @example
     #   df = Polars::DataFrame.new({"a" => [1, 2, 3, 4]})
@@ -1071,7 +952,6 @@ module Polars
     def cum_prod(reverse: false)
       wrap_expr(_rbexpr.cum_prod(reverse))
     end
-    alias_method :cumprod, :cum_prod
 
     # Get an array with the cumulative min computed at every element.
     #
@@ -1103,7 +983,6 @@ module Polars
     def cum_min(reverse: false)
       wrap_expr(_rbexpr.cum_min(reverse))
     end
-    alias_method :cummin, :cum_min
 
     # Get an array with the cumulative max computed at every element.
     #
@@ -1135,7 +1014,6 @@ module Polars
     def cum_max(reverse: false)
       wrap_expr(_rbexpr.cum_max(reverse))
     end
-    alias_method :cummax, :cum_max
 
     # Get an array with the cumulative count computed at every element.
     #
@@ -1169,7 +1047,6 @@ module Polars
     def cum_count(reverse: false)
       wrap_expr(_rbexpr.cum_count(reverse))
     end
-    alias_method :cumcount, :cum_count
 
     # Rounds down to the nearest integer value.
     #
@@ -1338,11 +1215,14 @@ module Polars
 
     # Cast between data types.
     #
-    # @param dtype [Symbol]
+    # @param dtype [Object]
     #   DataType to cast to.
     # @param strict [Boolean]
     #   Throw an error if a cast could not be done.
     #   For instance, due to an overflow.
+    # @param wrap_numerical [Boolean]
+    #   If true numeric casts wrap overflowing values instead of
+    #   marking the cast as invalid.
     #
     # @return [Expr]
     #
@@ -1355,8 +1235,8 @@ module Polars
     #   )
     #   df.with_columns(
     #     [
-    #       Polars.col("a").cast(:f64),
-    #       Polars.col("b").cast(:i32)
+    #       Polars.col("a").cast(Polars::Float64),
+    #       Polars.col("b").cast(Polars::Int32)
     #     ]
     #   )
     #   # =>
@@ -1370,16 +1250,16 @@ module Polars
     #   # │ 2.0 ┆ 5   │
     #   # │ 3.0 ┆ 6   │
     #   # └─────┴─────┘
-    def cast(dtype, strict: true)
-      dtype = Utils.rb_type_to_dtype(dtype)
-      wrap_expr(_rbexpr.cast(dtype, strict))
+    def cast(dtype, strict: true, wrap_numerical: false)
+      dtype = Utils.parse_into_datatype_expr(dtype)
+      wrap_expr(_rbexpr.cast(dtype._rbdatatype_expr, strict, wrap_numerical))
     end
 
     # Sort this column. In projection/ selection context the whole column is sorted.
     #
     # If used in a group by context, the groups are sorted.
     #
-    # @param reverse [Boolean]
+    # @param descending [Boolean]
     #   false -> order from small to large.
     #   true -> order from large to small.
     # @param nulls_last [Boolean]
@@ -1446,8 +1326,8 @@ module Polars
     #   # │ two   ┆ [3, 4, 99] │
     #   # │ one   ┆ [1, 2, 98] │
     #   # └───────┴────────────┘
-    def sort(reverse: false, nulls_last: false)
-      wrap_expr(_rbexpr.sort_with(reverse, nulls_last))
+    def sort(descending: false, nulls_last: false)
+      wrap_expr(_rbexpr.sort_with(descending, nulls_last))
     end
 
     # Return the `k` largest elements.
@@ -1503,7 +1383,7 @@ module Polars
     #   Number of elements to return.
     # @param reverse [Object]
     #   Consider the `k` smallest elements of the `by` column(s) (instead of the `k`
-    #   largest). This can be specified per column by passing a sequence of
+    #   largest). This can be specified per column by passing an array of
     #   booleans.
     #
     # @return [Expr]
@@ -1648,7 +1528,7 @@ module Polars
     #   Number of elements to return.
     # @param reverse [Object]
     #   Consider the `k` largest elements of the `by` column(s) (instead of the `k`
-    #   smallest). This can be specified per column by passing a sequence of
+    #   smallest). This can be specified per column by passing an array of
     #   booleans.
     #
     # @return [Expr]
@@ -1742,7 +1622,7 @@ module Polars
 
     # Get the index values that would sort this column.
     #
-    # @param reverse [Boolean]
+    # @param descending [Boolean]
     #   Sort in reverse (descending) order.
     # @param nulls_last [Boolean]
     #   Place null values last instead of first.
@@ -1767,8 +1647,8 @@ module Polars
     #   # │ 0   │
     #   # │ 2   │
     #   # └─────┘
-    def arg_sort(reverse: false, nulls_last: false)
-      wrap_expr(_rbexpr.arg_sort(reverse, nulls_last))
+    def arg_sort(descending: false, nulls_last: false)
+      wrap_expr(_rbexpr.arg_sort(descending, nulls_last))
     end
 
     # Get the index of the maximal value.
@@ -1899,12 +1779,12 @@ module Polars
     #   The column(s) used for sorting.
     # @param more_by [Array]
     #   Additional columns to sort by, specified as positional arguments.
-    # @param reverse [Boolean]
+    # @param descending [Boolean]
     #   false -> order from small to large.
     #   true -> order from large to small.
     # @param nulls_last [Boolean]
     #   Place null values last; can specify a single boolean applying to all columns
-    #   or a sequence of booleans for per-column control.
+    #   or an array of booleans for per-column control.
     # @param multithreaded [Boolean]
     #   Sort using multiple threads.
     # @param maintain_order [Boolean]
@@ -1941,13 +1821,13 @@ module Polars
     #   # │ one   │
     #   # │ two   │
     #   # └───────┘
-    def sort_by(by, *more_by, reverse: false, nulls_last: false, multithreaded: true, maintain_order: false)
+    def sort_by(by, *more_by, descending: false, nulls_last: false, multithreaded: true, maintain_order: false)
       by = Utils.parse_into_list_of_expressions(by, *more_by)
-      reverse = Utils.extend_bool(reverse, by.length, "reverse", "by")
+      descending = Utils.extend_bool(descending, by.length, "descending", "by")
       nulls_last = Utils.extend_bool(nulls_last, by.length, "nulls_last", "by")
       wrap_expr(
         _rbexpr.sort_by(
-          by, reverse, nulls_last, multithreaded, maintain_order
+          by, descending, nulls_last, multithreaded, maintain_order
         )
       )
     end
@@ -1973,7 +1853,7 @@ module Polars
     #       "value" => [1, 98, 2, 3, 99, 4]
     #     }
     #   )
-    #   df.group_by("group", maintain_order: true).agg(Polars.col("value").take([2, 1]))
+    #   df.group_by("group", maintain_order: true).agg(Polars.col("value").gather([2, 1]))
     #   # =>
     #   # shape: (2, 2)
     #   # ┌───────┬───────────┐
@@ -1986,13 +1866,12 @@ module Polars
     #   # └───────┴───────────┘
     def gather(indices)
       if indices.is_a?(::Array)
-        indices_lit = Polars.lit(Series.new("", indices, dtype: :u32))._rbexpr
+        indices_lit_rbexpr = Polars.lit(Series.new("", indices, dtype: Int64))._rbexpr
       else
-        indices_lit = Utils.parse_into_expression(indices, str_as_lit: false)
+        indices_lit_rbexpr = Utils.parse_into_expression(indices)
       end
-      wrap_expr(_rbexpr.gather(indices_lit))
+      wrap_expr(_rbexpr.gather(indices_lit_rbexpr))
     end
-    alias_method :take, :gather
 
     # Return a single value by index.
     #
@@ -2063,34 +1942,6 @@ module Polars
       wrap_expr(_rbexpr.shift(n, fill_value))
     end
 
-    # Shift the values by a given period and fill the resulting null values.
-    #
-    # @param periods [Integer]
-    #   Number of places to shift (may be negative).
-    # @param fill_value [Object]
-    #   Fill nil values with the result of this expression.
-    #
-    # @return [Expr]
-    #
-    # @example
-    #   df = Polars::DataFrame.new({"foo" => [1, 2, 3, 4]})
-    #   df.select(Polars.col("foo").shift_and_fill(1, "a"))
-    #   # =>
-    #   # shape: (4, 1)
-    #   # ┌─────┐
-    #   # │ foo │
-    #   # │ --- │
-    #   # │ str │
-    #   # ╞═════╡
-    #   # │ a   │
-    #   # │ 1   │
-    #   # │ 2   │
-    #   # │ 3   │
-    #   # └─────┘
-    def shift_and_fill(periods, fill_value)
-      shift(periods, fill_value: fill_value)
-    end
-
     # Fill null values using the specified value or strategy.
     #
     # To interpolate over null values see interpolate.
@@ -2192,9 +2043,9 @@ module Polars
     #   # │ null ┆ zero │
     #   # │ zero ┆ 6.0  │
     #   # └──────┴──────┘
-    def fill_nan(fill_value)
-      fill_value = Utils.parse_into_expression(fill_value, str_as_lit: true)
-      wrap_expr(_rbexpr.fill_nan(fill_value))
+    def fill_nan(value)
+      fill_value_rbexpr = Utils.parse_into_expression(value, str_as_lit: true)
+      wrap_expr(_rbexpr.fill_nan(fill_value_rbexpr))
     end
 
     # Fill missing values with the latest seen values.
@@ -2424,8 +2275,8 @@ module Polars
     # @return [Expr]
     #
     # @note
-    #   Dtypes in `:i8`, `:u8`, `:i16`, and `:u16` are cast to
-    #   `:i64` before summing to prevent overflow issues.
+    #   Dtypes in \\\\{Int8, UInt8, Int16, UInt16} are cast to
+    #   Int64 before summing to prevent overflow issues.
     #
     # @example
     #   df = Polars::DataFrame.new({"a" => [-1, 0, 1]})
@@ -2544,7 +2395,6 @@ module Polars
     def approx_n_unique
       wrap_expr(_rbexpr.approx_n_unique)
     end
-    alias_method :approx_unique, :approx_n_unique
 
     # Count null values.
     #
@@ -2705,13 +2555,82 @@ module Polars
       wrap_expr(_rbexpr.last)
     end
 
+    # Get the single value.
+    #
+    # This raises an error if there is not exactly one value.
+    #
+    # @param allow_empty [Boolean]
+    #   Allow having no values to return `null`.
+    #
+    # @return [Expr]
+    #
+    # @example
+    #   df = Polars::DataFrame.new({"a" => [1]})
+    #   df.select(Polars.col("a").item)
+    #   # =>
+    #   # shape: (1, 1)
+    #   # ┌─────┐
+    #   # │ a   │
+    #   # │ --- │
+    #   # │ i64 │
+    #   # ╞═════╡
+    #   # │ 1   │
+    #   # └─────┘
+    #
+    # @example
+    #   df.head(0).select(Polars.col("a").item(allow_empty: true))
+    #   # =>
+    #   # shape: (1, 1)
+    #   # ┌──────┐
+    #   # │ a    │
+    #   # │ ---  │
+    #   # │ i64  │
+    #   # ╞══════╡
+    #   # │ null │
+    #   # └──────┘
+    def item(allow_empty: false)
+      Utils.wrap_expr(_rbexpr.item(allow_empty))
+    end
+
     # Apply window function over a subgroup.
     #
     # This is similar to a group by + aggregation + self join.
     # Or similar to [window functions in Postgres](https://www.postgresql.org/docs/current/tutorial-window.html).
     #
-    # @param expr [Object]
-    #   Column(s) to group by.
+    # @param partition_by [Object]
+    #   Column(s) to group by. Accepts expression input. Strings are parsed as
+    #   column names.
+    # @param more_exprs [Array]
+    #   Additional columns to group by, specified as positional arguments.
+    # @param order_by [Object]
+    #   Order the window functions/aggregations with the partitioned groups by
+    #   the result of the expression passed to `order_by`.
+    # @param descending [Boolean]
+    #   In case 'order_by' is given, indicate whether to order in ascending or
+    #   descending order.
+    # @param nulls_last [Boolean]
+    #   In case 'order_by' is given, indicate whether to order
+    #   the nulls in last position.
+    # @param mapping_strategy ['group_to_rows', 'join', 'explode']
+    #   - group_to_rows
+    #       If the aggregation results in multiple values per group, map them back
+    #       to their row position in the DataFrame. This can only be done if each
+    #       group yields the same elements before aggregation as after. If the
+    #       aggregation results in one scalar value per group, this value will be
+    #       mapped to every row.
+    #   - join
+    #       If the aggregation may result in multiple values per group, join the
+    #       values as 'List<group_dtype>' to each row position. Warning: this can be
+    #       memory intensive. If the aggregation always results in one scalar value
+    #       per group, join this value as '<group_dtype>' to each row position.
+    #   - explode
+    #       If the aggregation may result in multiple values per group, map each
+    #       value to a new row, similar to the results of `group_by` + `agg` +
+    #       `explode`. If the aggregation always results in one scalar value per
+    #       group, map this value to one row position. Sorting of the given groups
+    #       is required if the groups are not part of the window operation for the
+    #       operation, otherwise the result would not make sense. This operation
+    #       changes the number of rows.
     #
     # @return [Expr]
     #
@@ -2722,7 +2641,7 @@ module Polars
     #       "values" => [1, 2, 3]
     #     }
     #   )
-    #   df.with_column(
+    #   df.with_columns(
     #     Polars.col("values").max.over("groups").alias("max_by_group")
     #   )
     #   # =>
@@ -2764,9 +2683,41 @@ module Polars
     #   # │ 6      │
     #   # │ 4      │
     #   # └────────┘
-    def over(expr)
-      rbexprs = Utils.parse_into_list_of_expressions(expr)
-      wrap_expr(_rbexpr.over(rbexprs))
+    #
+    # @example
+    #   df = Polars::DataFrame.new(
+    #     {
+    #       "store_id" => ["a", "a", "b", "b"],
+    #       "date" => [Date.new(2024, 9, 18), Date.new(2024, 9, 17), Date.new(2024, 9, 18), Date.new(2024, 9, 16)],
+    #       "sales" => [7, 9, 8, 10]
+    #     }
+    #   )
+    #   df.with_columns(
+    #     cumulative_sales: Polars.col("sales").cum_sum.over("store_id", order_by: "date")
+    #   )
+    #   # =>
+    #   # shape: (4, 4)
+    #   # ┌──────────┬────────────┬───────┬──────────────────┐
+    #   # │ store_id ┆ date       ┆ sales ┆ cumulative_sales │
+    #   # │ ---      ┆ ---        ┆ ---   ┆ ---              │
+    #   # │ str      ┆ date       ┆ i64   ┆ i64              │
+    #   # ╞══════════╪════════════╪═══════╪══════════════════╡
+    #   # │ a        ┆ 2024-09-18 ┆ 7     ┆ 16               │
+    #   # │ a        ┆ 2024-09-17 ┆ 9     ┆ 9                │
+    #   # │ b        ┆ 2024-09-18 ┆ 8     ┆ 18               │
+    #   # │ b        ┆ 2024-09-16 ┆ 10    ┆ 10               │
+    #   # └──────────┴────────────┴───────┴──────────────────┘
+    def over(partition_by = nil, *more_exprs, order_by: nil, descending: false, nulls_last: false, mapping_strategy: "group_to_rows")
+      partition_by_rbexprs =
+        if !partition_by.nil?
+          Utils.parse_into_list_of_expressions(partition_by, *more_exprs)
+        else
+          nil
+        end
+
+      order_by_rbexprs = !order_by.nil? ? Utils.parse_into_list_of_expressions(order_by) : nil
+
+      wrap_expr(_rbexpr.over(partition_by_rbexprs, order_by_rbexprs, descending, nulls_last, mapping_strategy))
     end
 
     # Create rolling groups based on a temporal or integer column.
@@ -2904,7 +2855,7 @@ module Polars
     #       "num" => [1, 2, 3, 1, 5]
     #     }
     #   )
-    #   df.with_column(Polars.col("num").is_first.alias("is_first"))
+    #   df.with_columns(Polars.col("num").is_first_distinct.alias("is_first"))
     #   # =>
     #   # shape: (5, 2)
     #   # ┌─────┬──────────┐
@@ -2921,7 +2872,6 @@ module Polars
     def is_first_distinct
       wrap_expr(_rbexpr.is_first_distinct)
     end
-    alias_method :is_first, :is_first_distinct
 
     # Return a boolean mask indicating the last occurrence of each distinct value.
     #
@@ -3296,8 +3246,12 @@ module Polars
     # Mostly useful in an aggregation context. If you want to filter on a DataFrame
     # level, use `LazyFrame#filter`.
     #
-    # @param predicate [Expr]
-    #   Boolean expression.
+    # @param predicates [Array]
+    #   Expression(s) that evaluates to a boolean Series.
+    # @param constraints [Hash]
+    #   Column filters; use `name = value` to filter columns by the supplied value.
+    #   Each constraint will behave the same as `Polars.col(name).eq(value)`, and
+    #   be implicitly joined with the other filter conditions using `&`.
     #
     # @return [Expr]
     #
@@ -3326,49 +3280,14 @@ module Polars
     #   # │ g1        ┆ 1   ┆ 2   │
     #   # │ g2        ┆ 0   ┆ 3   │
     #   # └───────────┴─────┴─────┘
-    def filter(predicate)
-      wrap_expr(_rbexpr.filter(predicate._rbexpr))
-    end
-
-    # Filter a single column.
-    #
-    # Alias for {#filter}.
-    #
-    # @param predicate [Expr]
-    #   Boolean expression.
-    #
-    # @return [Expr]
-    #
-    # @example
-    #   df = Polars::DataFrame.new(
-    #     {
-    #       "group_col" => ["g1", "g1", "g2"],
-    #       "b" => [1, 2, 3]
-    #     }
-    #   )
-    #   (
-    #     df.group_by("group_col").agg(
-    #       [
-    #         Polars.col("b").where(Polars.col("b") < 2).sum.alias("lt"),
-    #         Polars.col("b").where(Polars.col("b") >= 2).sum.alias("gte")
-    #       ]
-    #     )
-    #   ).sort("group_col")
-    #   # =>
-    #   # shape: (2, 3)
-    #   # ┌───────────┬─────┬─────┐
-    #   # │ group_col ┆ lt  ┆ gte │
-    #   # │ ---       ┆ --- ┆ --- │
-    #   # │ str       ┆ i64 ┆ i64 │
-    #   # ╞═══════════╪═════╪═════╡
-    #   # │ g1        ┆ 1   ┆ 2   │
-    #   # │ g2        ┆ 0   ┆ 3   │
-    #   # └───────────┴─────┴─────┘
-    def where(predicate)
-      filter(predicate)
+    def filter(*predicates, **constraints)
+      predicate = Utils.parse_predicates_constraints_into_expression(
+        *predicates, **constraints
+      )
+      wrap_expr(_rbexpr.filter(predicate))
     end
 
-    # Apply a custom Ruby function to a Series or sequence of Series.
+    # Apply a custom Ruby function to a Series or array of Series.
     #
     # The output of this custom function must be a Series.
     # If you want to apply a custom function elementwise over single values, see
@@ -3406,11 +3325,11 @@ module Polars
     #   # └──────┴────────┘
     # def map_batches(return_dtype: nil, agg_list: false, is_elementwise: false, returns_scalar: false, &f)
     #   if !return_dtype.nil?
-    #     return_dtype = Utils.rb_type_to_dtype(return_dtype)
+    #     return_dtype = Utils.parse_into_dtype(return_dtype)
     #   end
     #   wrap_expr(
     #     _rbexpr.map_batches(
-    #       # TODO _map_batches_wrapper
+    #       _map_batches_wrapper,
     #       f,
     #       return_dtype,
     #       agg_list,
@@ -3460,7 +3379,7 @@ module Polars
     #   )
     #
     # @example In a selection context, the function is applied by row.
-    #   df.with_column(
+    #   df.with_columns(
     #     Polars.col("a").map_elements { |x| x * 2 }.alias("a_times_2")
     #   )
     #   # =>
@@ -3591,7 +3510,6 @@ module Polars
     def gather_every(n, offset = 0)
       wrap_expr(_rbexpr.gather_every(n, offset))
     end
-    alias_method :take_every, :gather_every
 
     # Get the first `n` rows.
     #
@@ -4304,7 +4222,7 @@ module Polars
     # Check if elements of this expression are present in the other Series.
     #
     # @param other [Object]
-    #   Series or sequence of primitive type.
+    #   Series or array of primitive type.
     # @param nulls_equal [Boolean]
     #   If true, treat null as a distinct value. Null values will not propagate.
     #
@@ -4472,7 +4390,7 @@ module Polars
     def is_close(
       other,
       abs_tol: 0.0,
-      rel_tol: 1e-09,
+      rel_tol: 1.0e-09,
       nans_equal: false
     )
       other = Utils.parse_into_expression(other)
@@ -4481,7 +4399,7 @@ module Polars
 
     # Hash the elements in the selection.
     #
-    # The hash value is of type `:u64`.
+    # The hash value is of type `UInt64`.
     #
     # @param seed [Integer]
     #   Random seed parameter. Defaults to 0.
@@ -4501,7 +4419,7 @@ module Polars
     #       "b" => ["x", nil, "z"]
     #     }
     #   )
-    #   df.with_column(Polars.all._hash(10, 20, 30, 40))
+    #   df.with_columns(Polars.all.hash_(10, 20, 30, 40))
     #   # =>
     #   # shape: (3, 2)
     #   # ┌──────────────────────┬──────────────────────┐
@@ -4513,7 +4431,7 @@ module Polars
     #   # │ 16386608652769605760 ┆ 11638928888656214026 │
     #   # │ 11638928888656214026 ┆ 11040941213715918520 │
     #   # └──────────────────────┴──────────────────────┘
-    def _hash(seed = 0, seed_1 = nil, seed_2 = nil, seed_3 = nil)
+    def hash_(seed = 0, seed_1 = nil, seed_2 = nil, seed_3 = nil)
       k0 = seed
       k1 = seed_1.nil? ? seed : seed_1
       k2 = seed_2.nil? ? seed : seed_2
@@ -4527,12 +4445,12 @@ module Polars
     # you can safely use that cast operation.
     #
     # @param signed [Boolean]
-    #   If true, reinterpret as `:i64`. Otherwise, reinterpret as `:u64`.
+    #   If true, reinterpret as `Polars::Int64`. Otherwise, reinterpret as `Polars::UInt64`.
     #
     # @return [Expr]
     #
     # @example
-    #   s = Polars::Series.new("a", [1, 1, 2], dtype: :u64)
+    #   s = Polars::Series.new("a", [1, 1, 2], dtype: Polars::UInt64)
     #   df = Polars::DataFrame.new([s])
     #   df.select(
     #     [
@@ -4551,7 +4469,13 @@ module Polars
     #   # │ 1             ┆ 1        │
     #   # │ 2             ┆ 2        │
     #   # └───────────────┴──────────┘
-    def reinterpret(signed: false)
+    def reinterpret(signed: nil)
+      # TODO update
+      if signed.nil?
+        warn "The default `signed` for `reinterpret` method will change from `false` to `true` in a future version"
+        signed = false
+      end
+
       wrap_expr(_rbexpr.reinterpret(signed))
     end
 
@@ -4561,7 +4485,7 @@ module Polars
     #
     # @example
     #   df = Polars::DataFrame.new({"foo" => [1, 1, 2]})
-    #   df.select(Polars.col("foo").cumsum._inspect("value is: %s").alias("bar"))
+    #   df.select(Polars.col("foo").cumsum.inspect_("value is: %s").alias("bar"))
     #   # =>
     #   # value is: shape: (3,)
     #   # Series: 'foo' [i64]
@@ -4580,7 +4504,7 @@ module Polars
     #   # │ 2   │
     #   # │ 4   │
     #   # └─────┘
-    # def _inspect(fmt = "%s")
+    # def inspect_(fmt = "%s")
     #   inspect = lambda do |s|
     #     puts(fmt % [s])
     #     s
@@ -4673,14 +4597,12 @@ module Polars
     #   (which may not be 24 hours, due to daylight savings). Similarly for
     #   "calendar week", "calendar month", "calendar quarter", and
     #   "calendar year".
-    # @param min_periods [Integer]
+    # @param min_samples [Integer]
     #   The number of values in the window that should be non-null before computing
     #   a result.
     # @param closed ['left', 'right', 'both', 'none']
     #   Define which sides of the temporal interval are closed (inclusive),
     #   defaults to `'right'`.
-    # @param warn_if_unsorted [Boolean]
-    #   Warn if data is not known to be sorted by `by` column.
     #
     # @return [Expr]
     #
@@ -4741,14 +4663,13 @@ module Polars
     def rolling_min_by(
       by,
       window_size,
-      min_periods: 1,
-      closed: "right",
-      warn_if_unsorted: nil
+      min_samples: 1,
+      closed: "right"
     )
       window_size = _prepare_rolling_by_window_args(window_size)
       by = Utils.parse_into_expression(by)
       wrap_expr(
-        _rbexpr.rolling_min_by(by, window_size, min_periods, closed)
+        _rbexpr.rolling_min_by(by, window_size, min_samples, closed)
       )
     end
 
@@ -4776,14 +4697,12 @@ module Polars
     #   (which may not be 24 hours, due to daylight savings). Similarly for
     #   "calendar week", "calendar month", "calendar quarter", and
     #   "calendar year".
-    # @param min_periods [Integer]
+    # @param min_samples [Integer]
     #   The number of values in the window that should be non-null before computing
     #   a result.
     # @param closed ['left', 'right', 'both', 'none']
     #   Define which sides of the temporal interval are closed (inclusive),
     #   defaults to `'right'`.
-    # @param warn_if_unsorted [Boolean]
-    #   Warn if data is not known to be sorted by `by` column.
     #
     # @return [Expr]
     #
@@ -4870,14 +4789,13 @@ module Polars
     def rolling_max_by(
       by,
       window_size,
-      min_periods: 1,
-      closed: "right",
-      warn_if_unsorted: nil
+      min_samples: 1,
+      closed: "right"
     )
       window_size = _prepare_rolling_by_window_args(window_size)
       by = Utils.parse_into_expression(by)
       wrap_expr(
-        _rbexpr.rolling_max_by(by, window_size, min_periods, closed)
+        _rbexpr.rolling_max_by(by, window_size, min_samples, closed)
       )
     end
 
@@ -4905,14 +4823,12 @@ module Polars
     #   (which may not be 24 hours, due to daylight savings). Similarly for
     #   "calendar week", "calendar month", "calendar quarter", and
     #   "calendar year".
-    # @param min_periods [Integer]
+    # @param min_samples [Integer]
     #   The number of values in the window that should be non-null before computing
     #   a result.
     # @param closed ['left', 'right', 'both', 'none']
     #   Define which sides of the temporal interval are closed (inclusive),
     #   defaults to `'right'`.
-    # @param warn_if_unsorted [Boolean]
-    #   Warn if data is not known to be sorted by `by` column.
     #
     # @return [Expr]
     #
@@ -5001,9 +4917,8 @@ module Polars
     def rolling_mean_by(
       by,
       window_size,
-      min_periods: 1,
-      closed: "right",
-      warn_if_unsorted: nil
+      min_samples: 1,
+      closed: "right"
     )
       window_size = _prepare_rolling_by_window_args(window_size)
       by = Utils.parse_into_expression(by)
@@ -5011,7 +4926,7 @@ module Polars
         _rbexpr.rolling_mean_by(
           by,
           window_size,
-          min_periods,
+          min_samples,
           closed
         )
       )
@@ -5041,14 +4956,12 @@ module Polars
     #   (which may not be 24 hours, due to daylight savings). Similarly for
     #   "calendar week", "calendar month", "calendar quarter", and
     #   "calendar year".
-    # @param min_periods [Integer]
+    # @param min_samples [Integer]
     #   The number of values in the window that should be non-null before computing
     #   a result.
     # @param closed ['left', 'right', 'both', 'none']
     #   Define which sides of the temporal interval are closed (inclusive),
     #   defaults to `'right'`.
-    # @param warn_if_unsorted [Boolean]
-    #   Warn if data is not known to be sorted by `by` column.
     #
     # @return [Expr]
     #
@@ -5135,14 +5048,13 @@ module Polars
     def rolling_sum_by(
       by,
       window_size,
-      min_periods: 1,
-      closed: "right",
-      warn_if_unsorted: nil
+      min_samples: 1,
+      closed: "right"
     )
       window_size = _prepare_rolling_by_window_args(window_size)
       by = Utils.parse_into_expression(by)
       wrap_expr(
-        _rbexpr.rolling_sum_by(by, window_size, min_periods, closed)
+        _rbexpr.rolling_sum_by(by, window_size, min_samples, closed)
       )
     end
 
@@ -5170,7 +5082,7 @@ module Polars
     #   (which may not be 24 hours, due to daylight savings). Similarly for
     #   "calendar week", "calendar month", "calendar quarter", and
     #   "calendar year".
-    # @param min_periods [Integer]
+    # @param min_samples [Integer]
     #   The number of values in the window that should be non-null before computing
     #   a result.
     # @param closed ['left', 'right', 'both', 'none']
@@ -5178,8 +5090,6 @@ module Polars
     #   defaults to `'right'`.
     # @param ddof [Integer]
     #   "Delta Degrees of Freedom": The divisor for a length N window is N - ddof
-    # @param warn_if_unsorted [Boolean]
-    #   Warn if data is not known to be sorted by `by` column.
     #
     # @return [Expr]
     #
@@ -5266,10 +5176,9 @@ module Polars
     def rolling_std_by(
       by,
       window_size,
-      min_periods: 1,
+      min_samples: 1,
       closed: "right",
-      ddof: 1,
-      warn_if_unsorted: nil
+      ddof: 1
     )
       window_size = _prepare_rolling_by_window_args(window_size)
       by = Utils.parse_into_expression(by)
@@ -5277,7 +5186,7 @@ module Polars
         _rbexpr.rolling_std_by(
           by,
           window_size,
-          min_periods,
+          min_samples,
           closed,
           ddof
         )
@@ -5308,7 +5217,7 @@ module Polars
     #   (which may not be 24 hours, due to daylight savings). Similarly for
     #   "calendar week", "calendar month", "calendar quarter", and
     #   "calendar year".
-    # @param min_periods [Integer]
+    # @param min_samples [Integer]
     #   The number of values in the window that should be non-null before computing
     #   a result.
     # @param closed ['left', 'right', 'both', 'none']
@@ -5316,8 +5225,6 @@ module Polars
     #   defaults to `'right'`.
     # @param ddof [Integer]
     #   "Delta Degrees of Freedom": The divisor for a length N window is N - ddof
-    # @param warn_if_unsorted [Boolean]
-    #   Warn if data is not known to be sorted by `by` column.
     #
     # @return [Expr]
     #
@@ -5404,10 +5311,9 @@ module Polars
     def rolling_var_by(
       by,
       window_size,
-      min_periods: 1,
+      min_samples: 1,
       closed: "right",
-      ddof: 1,
-      warn_if_unsorted: nil
+      ddof: 1
     )
       window_size = _prepare_rolling_by_window_args(window_size)
       by = Utils.parse_into_expression(by)
@@ -5415,7 +5321,7 @@ module Polars
         _rbexpr.rolling_var_by(
           by,
           window_size,
-          min_periods,
+          min_samples,
           closed,
           ddof
         )
@@ -5446,14 +5352,12 @@ module Polars
     #   (which may not be 24 hours, due to daylight savings). Similarly for
     #   "calendar week", "calendar month", "calendar quarter", and
     #   "calendar year".
-    # @param min_periods [Integer]
+    # @param min_samples [Integer]
     #   The number of values in the window that should be non-null before computing
     #   a result.
     # @param closed ['left', 'right', 'both', 'none']
     #   Define which sides of the temporal interval are closed (inclusive),
     #   defaults to `'right'`.
-    # @param warn_if_unsorted [Boolean]
-    #   Warn if data is not known to be sorted by `by` column.
     #
     # @return [Expr]
     #
@@ -5516,14 +5420,13 @@ module Polars
     def rolling_median_by(
       by,
       window_size,
-      min_periods: 1,
-      closed: "right",
-      warn_if_unsorted: nil
+      min_samples: 1,
+      closed: "right"
     )
       window_size = _prepare_rolling_by_window_args(window_size)
       by = Utils.parse_into_expression(by)
       wrap_expr(
-        _rbexpr.rolling_median_by(by, window_size, min_periods, closed)
+        _rbexpr.rolling_median_by(by, window_size, min_samples, closed)
       )
     end
 
@@ -5555,14 +5458,12 @@ module Polars
     #   Quantile between 0.0 and 1.0.
     # @param interpolation ['nearest', 'higher', 'lower', 'midpoint', 'linear']
     #   Interpolation method.
-    # @param min_periods [Integer]
+    # @param min_samples [Integer]
     #   The number of values in the window that should be non-null before computing
     #   a result.
     # @param closed ['left', 'right', 'both', 'none']
     #   Define which sides of the temporal interval are closed (inclusive),
     #   defaults to `'right'`.
-    # @param warn_if_unsorted [Boolean]
-    #   Warn if data is not known to be sorted by `by` column.
     #
     # @return [Expr]
     #
@@ -5627,9 +5528,8 @@ module Polars
       window_size,
       quantile:,
       interpolation: "nearest",
-      min_periods: 1,
-      closed: "right",
-      warn_if_unsorted: nil
+      min_samples: 1,
+      closed: "right"
     )
       window_size = _prepare_rolling_by_window_args(window_size)
       by = Utils.parse_into_expression(by)
@@ -5639,12 +5539,99 @@ module Polars
           quantile,
           interpolation,
           window_size,
-          min_periods,
+          min_samples,
           closed,
         )
       )
     end
 
+    # Compute a rolling rank based on another column.
+    #
+    # @note
+    #   This functionality is considered **unstable**. It may be changed
+    #   at any point without it being considered a breaking change.
+    #
+    # Given a `by` column `<t_0, t_1, ..., t_n>`, then `closed: "right"`
+    # (the default) means the windows will be:
+    #
+    #   - (t_0 - window_size, t_0]
+    #   - (t_1 - window_size, t_1]
+    #   - ...
+    #   - (t_n - window_size, t_n]
+    #
+    # @param by [Expr]
+    #   Should be `DateTime`, `Date`, `UInt64`, `UInt32`, `Int64`,
+    #   or `Int32` data type (note that the integral ones require using `'i'`
+    #   in `window size`).
+    # @param window_size [String]
+    #   The length of the window. Can be a dynamic
+    #   temporal size indicated by a timedelta or the following string language:
+    #
+    #   - 1ns   (1 nanosecond)
+    #   - 1us   (1 microsecond)
+    #   - 1ms   (1 millisecond)
+    #   - 1s    (1 second)
+    #   - 1m    (1 minute)
+    #   - 1h    (1 hour)
+    #   - 1d    (1 calendar day)
+    #   - 1w    (1 calendar week)
+    #   - 1mo   (1 calendar month)
+    #   - 1q    (1 calendar quarter)
+    #   - 1y    (1 calendar year)
+    #   - 1i    (1 index count)
+    #
+    #   By "calendar day", we mean the corresponding time on the next day
+    #   (which may not be 24 hours, due to daylight savings). Similarly for
+    #   "calendar week", "calendar month", "calendar quarter", and
+    #   "calendar year".
+    # @param method ['average', 'min', 'max', 'dense', 'random']
+    #   The method used to assign ranks to tied elements.
+    #   The following methods are available (default is 'average'):
+    #
+    #   - 'average' : The average of the ranks that would have been assigned to
+    #     all the tied values is assigned to each value.
+    #   - 'min' : The minimum of the ranks that would have been assigned to all
+    #     the tied values is assigned to each value. (This is also referred to
+    #     as "competition" ranking.)
+    #   - 'max' : The maximum of the ranks that would have been assigned to all
+    #     the tied values is assigned to each value.
+    #   - 'dense' : Like 'min', but the rank of the next highest element is
+    #     assigned the rank immediately after those assigned to the tied
+    #     elements.
+    #   - 'random' : Choose a random rank for each value in a tie.
+    # @param seed [Integer]
+    #   Random seed used when `method: 'random'`. If set to nil (default), a
+    #   random seed is generated for each rolling rank operation.
+    # @param min_samples [Integer]
+    #   The number of values in the window that should be non-null before computing
+    #   a result.
+    # @param closed ['left', 'right', 'both', 'none']
+    #   Define which sides of the temporal interval are closed (inclusive),
+    #   defaults to `'right'`.
+    #
+    # @return [Expr]
+    def rolling_rank_by(
+      by,
+      window_size,
+      method: "average",
+      seed: nil,
+      min_samples: 1,
+      closed: "right"
+    )
+      window_size = _prepare_rolling_by_window_args(window_size)
+      by_rbexpr = Utils.parse_into_expression(by)
+      Utils.wrap_expr(
+        _rbexpr.rolling_rank_by(
+          by_rbexpr,
+          window_size,
+          method,
+          seed,
+          min_samples,
+          closed
+        )
+      )
+    end
+
     # Apply a rolling min (moving min) over the values in this array.
     #
     # A window of length `window_size` will traverse the array. The values that fill
@@ -5672,7 +5659,7 @@ module Polars
     # @param weights [Array]
     #   An optional slice with the same length as the window that will be multiplied
     #   elementwise with the values in the window.
-    # @param min_periods [Integer]
+    # @param min_samples [Integer]
     #   The number of values in the window that should be non-null before computing
     #   a result. If nil, it will be set equal to window size.
     # @param center [Boolean]
@@ -5684,7 +5671,7 @@ module Polars
     #
     # @note
     #   If you want to compute multiple aggregation statistics over the same dynamic
-    #   window, consider using `group_by_rolling` this method can cache the window size
+    #   window, consider using `rolling` this method can cache the window size
     #   computation.
     #
     # @return [Expr]
@@ -5713,12 +5700,12 @@ module Polars
     def rolling_min(
       window_size,
       weights: nil,
-      min_periods: nil,
+      min_samples: nil,
       center: false
     )
       wrap_expr(
         _rbexpr.rolling_min(
-          window_size, weights, min_periods, center
+          window_size, weights, min_samples, center
         )
       )
     end
@@ -5750,7 +5737,7 @@ module Polars
     # @param weights [Array]
     #   An optional slice with the same length as the window that will be multiplied
     #   elementwise with the values in the window.
-    # @param min_periods [Integer]
+    # @param min_samples [Integer]
     #   The number of values in the window that should be non-null before computing
     #   a result. If nil, it will be set equal to window size.
     # @param center [Boolean]
@@ -5762,7 +5749,7 @@ module Polars
     #
     # @note
     #   If you want to compute multiple aggregation statistics over the same dynamic
-    #   window, consider using `group_by_rolling` this method can cache the window size
+    #   window, consider using `rolling` this method can cache the window size
     #   computation.
     #
     # @return [Expr]
@@ -5791,12 +5778,12 @@ module Polars
     def rolling_max(
       window_size,
       weights: nil,
-      min_periods: nil,
+      min_samples: nil,
       center: false
     )
       wrap_expr(
         _rbexpr.rolling_max(
-          window_size, weights, min_periods, center
+          window_size, weights, min_samples, center
         )
       )
     end
@@ -5828,7 +5815,7 @@ module Polars
     # @param weights [Array]
     #   An optional slice with the same length as the window that will be multiplied
     #   elementwise with the values in the window.
-    # @param min_periods [Integer]
+    # @param min_samples [Integer]
     #   The number of values in the window that should be non-null before computing
     #   a result. If nil, it will be set equal to window size.
     # @param center [Boolean]
@@ -5840,7 +5827,7 @@ module Polars
     #
     # @note
     #   If you want to compute multiple aggregation statistics over the same dynamic
-    #   window, consider using `group_by_rolling` this method can cache the window size
+    #   window, consider using `rolling` this method can cache the window size
     #   computation.
     #
     # @return [Expr]
@@ -5869,12 +5856,12 @@ module Polars
     def rolling_mean(
       window_size,
       weights: nil,
-      min_periods: nil,
+      min_samples: nil,
       center: false
     )
       wrap_expr(
         _rbexpr.rolling_mean(
-          window_size, weights, min_periods, center
+          window_size, weights, min_samples, center
         )
       )
     end
@@ -5906,7 +5893,7 @@ module Polars
     # @param weights [Array]
     #   An optional slice with the same length as the window that will be multiplied
     #   elementwise with the values in the window.
-    # @param min_periods [Integer]
+    # @param min_samples [Integer]
     #   The number of values in the window that should be non-null before computing
     #   a result. If nil, it will be set equal to window size.
     # @param center [Boolean]
@@ -5918,7 +5905,7 @@ module Polars
     #
     # @note
     #   If you want to compute multiple aggregation statistics over the same dynamic
-    #   window, consider using `group_by_rolling` this method can cache the window size
+    #   window, consider using `rolling` this method can cache the window size
     #   computation.
     #
     # @return [Expr]
@@ -5947,12 +5934,12 @@ module Polars
     def rolling_sum(
       window_size,
       weights: nil,
-      min_periods: nil,
+      min_samples: nil,
       center: false
     )
       wrap_expr(
         _rbexpr.rolling_sum(
-          window_size, weights, min_periods, center
+          window_size, weights, min_samples, center
         )
       )
     end
@@ -5984,7 +5971,7 @@ module Polars
     # @param weights [Array]
     #   An optional slice with the same length as the window that will be multiplied
     #   elementwise with the values in the window.
-    # @param min_periods [Integer]
+    # @param min_samples [Integer]
     #   The number of values in the window that should be non-null before computing
     #   a result. If nil, it will be set equal to window size.
     # @param center [Boolean]
@@ -5998,7 +5985,7 @@ module Polars
     #
     # @note
     #   If you want to compute multiple aggregation statistics over the same dynamic
-    #   window, consider using `group_by_rolling` this method can cache the window size
+    #   window, consider using `rolling` this method can cache the window size
     #   computation.
     #
     # @return [Expr]
@@ -6027,13 +6014,13 @@ module Polars
     def rolling_std(
       window_size,
       weights: nil,
-      min_periods: nil,
+      min_samples: nil,
       center: false,
       ddof: 1
     )
       wrap_expr(
         _rbexpr.rolling_std(
-          window_size, weights, min_periods, center, ddof
+          window_size, weights, min_samples, center, ddof
         )
       )
     end
@@ -6065,7 +6052,7 @@ module Polars
     # @param weights [Array]
     #   An optional slice with the same length as the window that will be multiplied
     #   elementwise with the values in the window.
-    # @param min_periods [Integer]
+    # @param min_samples [Integer]
     #   The number of values in the window that should be non-null before computing
     #   a result. If nil, it will be set equal to window size.
     # @param center [Boolean]
@@ -6079,7 +6066,7 @@ module Polars
     #
     # @note
     #   If you want to compute multiple aggregation statistics over the same dynamic
-    #   window, consider using `group_by_rolling` this method can cache the window size
+    #   window, consider using `rolling` this method can cache the window size
     #   computation.
     #
     # @return [Expr]
@@ -6108,13 +6095,13 @@ module Polars
     def rolling_var(
       window_size,
       weights: nil,
-      min_periods: nil,
+      min_samples: nil,
       center: false,
       ddof: 1
     )
       wrap_expr(
         _rbexpr.rolling_var(
-          window_size, weights, min_periods, center, ddof
+          window_size, weights, min_samples, center, ddof
         )
       )
     end
@@ -6142,7 +6129,7 @@ module Polars
     # @param weights [Array]
     #   An optional slice with the same length as the window that will be multiplied
     #   elementwise with the values in the window.
-    # @param min_periods [Integer]
+    # @param min_samples [Integer]
     #   The number of values in the window that should be non-null before computing
     #   a result. If nil, it will be set equal to window size.
     # @param center [Boolean]
@@ -6154,7 +6141,7 @@ module Polars
     #
     # @note
     #   If you want to compute multiple aggregation statistics over the same dynamic
-    #   window, consider using `group_by_rolling` this method can cache the window size
+    #   window, consider using `rolling` this method can cache the window size
     #   computation.
     #
     # @return [Expr]
@@ -6183,12 +6170,12 @@ module Polars
     def rolling_median(
       window_size,
       weights: nil,
-      min_periods: nil,
+      min_samples: nil,
       center: false
     )
       wrap_expr(
         _rbexpr.rolling_median(
-          window_size, weights, min_periods, center
+          window_size, weights, min_samples, center
         )
       )
     end
@@ -6220,7 +6207,7 @@ module Polars
     # @param weights [Array]
     #   An optional slice with the same length as the window that will be multiplied
     #   elementwise with the values in the window.
-    # @param min_periods [Integer]
+    # @param min_samples [Integer]
     #   The number of values in the window that should be non-null before computing
     #   a result. If nil, it will be set equal to window size.
     # @param center [Boolean]
@@ -6232,7 +6219,7 @@ module Polars
     #
     # @note
     #   If you want to compute multiple aggregation statistics over the same dynamic
-    #   window, consider using `group_by_rolling` this method can cache the window size
+    #   window, consider using `rolling` this method can cache the window size
     #   computation.
     #
     # @return [Expr]
@@ -6263,12 +6250,85 @@ module Polars
       interpolation: "nearest",
       window_size: 2,
       weights: nil,
-      min_periods: nil,
+      min_samples: nil,
       center: false
     )
       wrap_expr(
         _rbexpr.rolling_quantile(
-          quantile, interpolation, window_size, weights, min_periods, center
+          quantile, interpolation, window_size, weights, min_samples, center
+        )
+      )
+    end
+
+    # Compute a rolling rank.
+    #
+    # @note
+    #   This functionality is considered **unstable**. It may be changed
+    #   at any point without it being considered a breaking change.
+    #
+    # A window of length `window_size` will traverse the array. The values
+    # that fill this window will be ranked according to the `method`
+    # parameter. The resulting values will be the rank of the value that is
+    # at the end of the sliding window.
+    #
+    # @param window_size [Integer]
+    #   Integer size of the rolling window.
+    # @param method ['average', 'min', 'max', 'dense', 'random']
+    #   The method used to assign ranks to tied elements.
+    #   The following methods are available (default is 'average'):
+    #
+    #   - 'average' : The average of the ranks that would have been assigned to
+    #     all the tied values is assigned to each value.
+    #   - 'min' : The minimum of the ranks that would have been assigned to all
+    #     the tied values is assigned to each value. (This is also referred to
+    #     as "competition" ranking.)
+    #   - 'max' : The maximum of the ranks that would have been assigned to all
+    #     the tied values is assigned to each value.
+    #   - 'dense' : Like 'min', but the rank of the next highest element is
+    #     assigned the rank immediately after those assigned to the tied
+    #     elements.
+    #   - 'random' : Choose a random rank for each value in a tie.
+    # @param seed [Integer]
+    #   Random seed used when `method: 'random'`. If set to nil (default), a
+    #   random seed is generated for each rolling rank operation.
+    # @param min_samples [Integer]
+    #   The number of values in the window that should be non-null before computing
+    #   a result. If set to `nil` (default), it will be set equal to `window_size`.
+    # @param center [Boolean]
+    #   Set the labels at the center of the window.
+    #
+    # @return [Expr]
+    #
+    # @example
+    #   df = Polars::DataFrame.new({"a" => [1, 4, 4, 1, 9]})
+    #   df.select(Polars.col("a").rolling_rank(3, method: "average"))
+    #   # =>
+    #   # shape: (5, 1)
+    #   # ┌──────┐
+    #   # │ a    │
+    #   # │ ---  │
+    #   # │ f64  │
+    #   # ╞══════╡
+    #   # │ null │
+    #   # │ null │
+    #   # │ 2.5  │
+    #   # │ 1.0  │
+    #   # │ 3.0  │
+    #   # └──────┘
+    def rolling_rank(
+      window_size,
+      method: "average",
+      seed: nil,
+      min_samples: nil,
+      center: false
+    )
+      Utils.wrap_expr(
+        _rbexpr.rolling_rank(
+          window_size,
+          method,
+          seed,
+          min_samples,
+          center
         )
       )
     end
@@ -6288,7 +6348,7 @@ module Polars
     # @param weights [Object]
     #   An optional slice with the same length as the window that will be multiplied
     #   elementwise with the values in the window.
-    # @param min_periods [Integer]
+    # @param min_samples [Integer]
     #   The number of values in the window that should be non-null before computing
     #   a result. If nil, it will be set equal to window size.
     # @param center [Boolean]
@@ -6323,16 +6383,16 @@ module Polars
     # def rolling_apply(
     #   window_size:,
     #   weights: nil,
-    #   min_periods: nil,
+    #   min_samples: nil,
     #   center: false,
     #   &function
     # )
-    #   if min_periods.nil?
-    #     min_periods = window_size
+    #   if min_samples.nil?
+    #     min_samples = window_size
     #   end
     #   wrap_expr(
     #     _rbexpr.rolling_apply(
-    #       function, window_size, weights, min_periods, center
+    #       function, window_size, weights, min_samples, center
     #     )
     #   )
     # end
@@ -6454,39 +6514,6 @@ module Polars
       wrap_expr(_rbexpr.abs)
     end
 
-    # Get the index values that would sort this column.
-    #
-    # Alias for {#arg_sort}.
-    #
-    # @param reverse [Boolean]
-    #   Sort in reverse (descending) order.
-    # @param nulls_last [Boolean]
-    #   Place null values last instead of first.
-    #
-    # @return [expr]
-    #
-    # @example
-    #   df = Polars::DataFrame.new(
-    #     {
-    #       "a" => [20, 10, 30]
-    #     }
-    #   )
-    #   df.select(Polars.col("a").argsort)
-    #   # =>
-    #   # shape: (3, 1)
-    #   # ┌─────┐
-    #   # │ a   │
-    #   # │ --- │
-    #   # │ u32 │
-    #   # ╞═════╡
-    #   # │ 1   │
-    #   # │ 0   │
-    #   # │ 2   │
-    #   # └─────┘
-    def argsort(reverse: false, nulls_last: false)
-      arg_sort(reverse: reverse, nulls_last: nulls_last)
-    end
-
     # Assign ranks to data, dealing with ties appropriately.
     #
     # @param method ["average", "min", "max", "dense", "ordinal", "random"]
@@ -6507,7 +6534,7 @@ module Polars
     #     the order that the values occur in the Series.
     #   - 'random' : Like 'ordinal', but the rank for ties is not dependent
     #     on the order that the values occur in the Series.
-    # @param reverse [Boolean]
+    # @param descending [Boolean]
     #   Reverse the operation.
     # @param seed [Integer]
     #   If `method: "random"`, use this as seed.
@@ -6547,8 +6574,8 @@ module Polars
     #   # │ 2   │
     #   # │ 5   │
     #   # └─────┘
-    def rank(method: "average", reverse: false, seed: nil)
-      wrap_expr(_rbexpr.rank(method, reverse, seed))
+    def rank(method: "average", descending: false, seed: nil)
+      wrap_expr(_rbexpr.rank(method, descending, seed))
     end
 
     # Calculate the n-th discrete difference.
@@ -6601,7 +6628,7 @@ module Polars
     #       "a" => [10, 11, 12, nil, 12]
     #     }
     #   )
-    #   df.with_column(Polars.col("a").pct_change.alias("pct_change"))
+    #   df.with_columns(Polars.col("a").pct_change.alias("pct_change"))
     #   # =>
     #   # shape: (5, 2)
     #   # ┌──────┬────────────┐
@@ -6654,7 +6681,7 @@ module Polars
     # Kurtosis is the fourth central moment divided by the square of the
     # variance. If Fisher's definition is used, then 3.0 is subtracted from
     # the result to give 0.0 for a normal distribution.
-    # If bias is False then the kurtosis is calculated using k statistics to
+    # If bias is false then the kurtosis is calculated using k statistics to
     # eliminate bias coming from biased moment estimators
     #
     # @param fisher [Boolean]
@@ -6695,7 +6722,7 @@ module Polars
     #
     # @example
     #   df = Polars::DataFrame.new({"foo" => [-50, 5, nil, 50]})
-    #   df.with_column(Polars.col("foo").clip(1, 10).alias("foo_clipped"))
+    #   df.with_columns(Polars.col("foo").clip(1, 10).alias("foo_clipped"))
     #   # =>
     #   # shape: (4, 2)
     #   # ┌──────┬─────────────┐
@@ -6718,68 +6745,6 @@ module Polars
       wrap_expr(_rbexpr.clip(lower_bound, upper_bound))
     end
 
-    # Clip (limit) the values in an array to a `min` boundary.
-    #
-    # Only works for numerical types.
-    #
-    # If you want to clip other dtypes, consider writing a "when, then, otherwise"
-    # expression. See `when` for more information.
-    #
-    # @param lower_bound [Numeric]
-    #   Minimum value.
-    #
-    # @return [Expr]
-    #
-    # @example
-    #   df = Polars::DataFrame.new({"foo" => [-50, 5, nil, 50]})
-    #   df.with_column(Polars.col("foo").clip_min(0).alias("foo_clipped"))
-    #   # =>
-    #   # shape: (4, 2)
-    #   # ┌──────┬─────────────┐
-    #   # │ foo  ┆ foo_clipped │
-    #   # │ ---  ┆ ---         │
-    #   # │ i64  ┆ i64         │
-    #   # ╞══════╪═════════════╡
-    #   # │ -50  ┆ 0           │
-    #   # │ 5    ┆ 5           │
-    #   # │ null ┆ null        │
-    #   # │ 50   ┆ 50          │
-    #   # └──────┴─────────────┘
-    def clip_min(lower_bound)
-      clip(lower_bound, nil)
-    end
-
-    # Clip (limit) the values in an array to a `max` boundary.
-    #
-    # Only works for numerical types.
-    #
-    # If you want to clip other dtypes, consider writing a "when, then, otherwise"
-    # expression. See `when` for more information.
-    #
-    # @param upper_bound [Numeric]
-    #   Maximum value.
-    #
-    # @return [Expr]
-    #
-    # @example
-    #   df = Polars::DataFrame.new({"foo" => [-50, 5, nil, 50]})
-    #   df.with_column(Polars.col("foo").clip_max(0).alias("foo_clipped"))
-    #   # =>
-    #   # shape: (4, 2)
-    #   # ┌──────┬─────────────┐
-    #   # │ foo  ┆ foo_clipped │
-    #   # │ ---  ┆ ---         │
-    #   # │ i64  ┆ i64         │
-    #   # ╞══════╪═════════════╡
-    #   # │ -50  ┆ -50         │
-    #   # │ 5    ┆ 0           │
-    #   # │ null ┆ null        │
-    #   # │ 50   ┆ 0           │
-    #   # └──────┴─────────────┘
-    def clip_max(upper_bound)
-      clip(nil, upper_bound)
-    end
-
     # Calculate the lower bound.
     #
     # Returns a unit Series with the lowest value possible for the dtype of this
@@ -7168,7 +7133,7 @@ module Polars
 
     # Reshape this Expr to a flat Series or a Series of Lists.
     #
-    # @param dims [Array]
+    # @param dimensions [Array]
     #   Tuple of the dimension sizes. If a -1 is used in any of the dimensions, that
     #   dimension is inferred.
     #
@@ -7208,8 +7173,8 @@ module Polars
     #   # │ 8   │
     #   # │ 9   │
     #   # └─────┘
-    def reshape(dims)
-      wrap_expr(_rbexpr.reshape(dims))
+    def reshape(dimensions)
+      wrap_expr(_rbexpr.reshape(dimensions))
     end
 
     # Shuffle the contents of this expr.
@@ -7243,7 +7208,7 @@ module Polars
 
     # Sample from this expression.
     #
-    # @param frac [Float]
+    # @param fraction [Float]
     #   Fraction of items to return. Cannot be used with `n`.
     # @param with_replacement [Boolean]
     #   Allow values to be sampled more than once.
@@ -7253,13 +7218,13 @@ module Polars
     #   Seed for the random number generator. If set to nil (default), a random
     #   seed is used.
     # @param n [Integer]
-    #   Number of items to return. Cannot be used with `frac`.
+    #   Number of items to return. Cannot be used with `fraction`.
     #
     # @return [Expr]
     #
     # @example
     #   df = Polars::DataFrame.new({"a" => [1, 2, 3]})
-    #   df.select(Polars.col("a").sample(frac: 1.0, with_replacement: true, seed: 1))
+    #   df.select(Polars.col("a").sample(fraction: 1.0, with_replacement: true, seed: 1))
     #   # =>
     #   # shape: (3, 1)
     #   # ┌─────┐
@@ -7272,27 +7237,33 @@ module Polars
     #   # │ 1   │
     #   # └─────┘
     def sample(
-      frac: nil,
-      with_replacement: true,
+      fraction: nil,
+      with_replacement: nil,
       shuffle: false,
       seed: nil,
       n: nil
     )
-      if !n.nil? && !frac.nil?
-        raise ArgumentError, "cannot specify both `n` and `frac`"
+      # TODO update
+      if with_replacement.nil?
+        warn "The default `with_replacement` for `sample` method will change from `true` to `false` in a future version"
+        with_replacement = true
       end
 
-      if !n.nil? && frac.nil?
+      if !n.nil? && !fraction.nil?
+        raise ArgumentError, "cannot specify both `n` and `fraction`"
+      end
+
+      if !n.nil? && fraction.nil?
         n = Utils.parse_into_expression(n)
         return wrap_expr(_rbexpr.sample_n(n, with_replacement, shuffle, seed))
       end
 
-      if frac.nil?
-        frac = 1.0
+      if fraction.nil?
+        fraction = 1.0
       end
-      frac = Utils.parse_into_expression(frac)
+      fraction = Utils.parse_into_expression(fraction)
       wrap_expr(
-        _rbexpr.sample_frac(frac, with_replacement, shuffle, seed)
+        _rbexpr.sample_frac(fraction, with_replacement, shuffle, seed)
       )
     end
 
@@ -7320,11 +7291,11 @@ module Polars
       half_life: nil,
       alpha: nil,
       adjust: true,
-      min_periods: 1,
-      ignore_nulls: true
+      min_samples: 1,
+      ignore_nulls: false
     )
       alpha = _prepare_alpha(com, span, half_life, alpha)
-      wrap_expr(_rbexpr.ewm_mean(alpha, adjust, min_periods, ignore_nulls))
+      wrap_expr(_rbexpr.ewm_mean(alpha, adjust, min_samples, ignore_nulls))
     end
 
     # Compute time-based exponentially weighted moving average.
@@ -7421,11 +7392,11 @@ module Polars
       alpha: nil,
       adjust: true,
       bias: false,
-      min_periods: 1,
-      ignore_nulls: true
+      min_samples: 1,
+      ignore_nulls: false
     )
       alpha = _prepare_alpha(com, span, half_life, alpha)
-      wrap_expr(_rbexpr.ewm_std(alpha, adjust, bias, min_periods, ignore_nulls))
+      wrap_expr(_rbexpr.ewm_std(alpha, adjust, bias, min_samples, ignore_nulls))
     end
 
     # Exponentially-weighted moving variance.
@@ -7453,11 +7424,11 @@ module Polars
       alpha: nil,
       adjust: true,
       bias: false,
-      min_periods: 1,
-      ignore_nulls: true
+      min_samples: 1,
+      ignore_nulls: false
     )
       alpha = _prepare_alpha(com, span, half_life, alpha)
-      wrap_expr(_rbexpr.ewm_var(alpha, adjust, bias, min_periods, ignore_nulls))
+      wrap_expr(_rbexpr.ewm_var(alpha, adjust, bias, min_samples, ignore_nulls))
     end
 
     # Extend the Series with given number of values.
@@ -7636,7 +7607,7 @@ module Polars
     # Uses the formula `-sum(pk * log(pk)` where `pk` are discrete probabilities.
     #
     # @param base [Float]
-    #   Given base, defaults to `e`.
+    #   Given base, defaults to `2`.
     # @param normalize [Boolean]
     #   Normalize pk if it doesn't sum to 1.
     #
@@ -7666,7 +7637,13 @@ module Polars
     #   # ╞═══════════╡
     #   # │ -6.754888 │
     #   # └───────────┘
-    def entropy(base: 2, normalize: true)
+    def entropy(base: nil, normalize: true)
+      # TODO update (including param docs)
+      if base.nil?
+        warn "The default `base` for `entropy` method will change from `2` to `Math::E` in a future version"
+        base = 2
+      end
+
       wrap_expr(_rbexpr.entropy(base, normalize))
     end
 
@@ -7674,7 +7651,7 @@ module Polars
     #
     # @param expr [Expr]
     #   Expression to evaluate
-    # @param min_periods [Integer]
+    # @param min_samples [Integer]
     #   Number of valid values there should be in the window before the expression
     #   is evaluated. valid values = `length - null_count`
     #
@@ -7710,9 +7687,9 @@ module Polars
     #   # │ -15    │
     #   # │ -24    │
     #   # └────────┘
-    def cumulative_eval(expr, min_periods: 1)
+    def cumulative_eval(expr, min_samples: 1)
       wrap_expr(
-        _rbexpr.cumulative_eval(expr._rbexpr, min_periods)
+        _rbexpr.cumulative_eval(expr._rbexpr, min_samples)
       )
     end
 
@@ -7770,17 +7747,6 @@ module Polars
       wrap_expr(_rbexpr.implode)
     end
 
-    # Shrink numeric columns to the minimal required datatype.
-    #
-    # Shrink to the dtype needed to fit the extrema of this `Series`.
-    # This can be used to reduce memory pressure.
-    #
-    # @return [Expr]
-    def shrink_dtype
-      warn "`Expr.shrink_dtype` is deprecated and is a no-op; use `Series.shrink_dtype` instead."
-      self
-    end
-
     # Bin values into buckets and count their occurrences.
     #
     # @note
@@ -7849,13 +7815,13 @@ module Polars
     # Replace values by different values.
     #
     # @param old [Object]
-    #   Value or sequence of values to replace.
-    #   Accepts expression input. Sequences are parsed as Series,
+    #   Value or array of values to replace.
+    #   Accepts expression input. Arrays are parsed as Series,
     #   other non-expression inputs are parsed as literals.
     #   Also accepts a mapping of values to their replacement.
     # @param new [Object]
-    #   Value or sequence of values to replace by.
-    #   Accepts expression input. Sequences are parsed as Series,
+    #   Value or array of values to replace by.
+    #   Accepts expression input. Arrays are parsed as Series,
     #   other non-expression inputs are parsed as literals.
     #   Length must match the length of `old` or have length 1.
     # @param default [Object]
@@ -7884,7 +7850,7 @@ module Polars
     #   # │ 3   ┆ 3        │
     #   # └─────┴──────────┘
     #
-    # @example Replace multiple values by passing sequences to the `old` and `new` parameters.
+    # @example Replace multiple values by passing arrays to the `old` and `new` parameters.
     #   df.with_columns(replaced: Polars.col("a").replace([2, 3], [100, 200]))
     #   # =>
     #   # shape: (4, 2)
@@ -8014,14 +7980,14 @@ module Polars
     # Replace all values by different values.
     #
     # @param old [Object]
-    #   Value or sequence of values to replace.
-    #   Accepts expression input. Sequences are parsed as Series,
+    #   Value or array of values to replace.
+    #   Accepts expression input. Arrays are parsed as Series,
     #   other non-expression inputs are parsed as literals.
     #   Also accepts a mapping of values to their replacement as syntactic sugar for
     #   `replace_all(old: Series.new(mapping.keys), new: Series.new(mapping.values))`.
     # @param new [Object]
-    #   Value or sequence of values to replace by.
-    #   Accepts expression input. Sequences are parsed as Series,
+    #   Value or array of values to replace by.
+    #   Accepts expression input. Arrays are parsed as Series,
     #   other non-expression inputs are parsed as literals.
     #   Length must match the length of `old` or have length 1.
     # @param default [Object]
@@ -8037,7 +8003,7 @@ module Polars
     # @note
     #   The global string cache must be enabled when replacing categorical values.
     #
-    # @example Replace values by passing sequences to the `old` and `new` parameters.
+    # @example Replace values by passing arrays to the `old` and `new` parameters.
     #   df = Polars::DataFrame.new({"a" => [1, 2, 2, 3]})
     #   df.with_columns(
     #     replaced: Polars.col("a").replace_strict([1, 2, 3], [100, 200, 300])
@@ -8419,19 +8385,6 @@ module Polars
       alpha
     end
 
-    def _prepare_rolling_window_args(window_size, min_periods)
-      if window_size.is_a?(Integer)
-        if min_periods.nil?
-          min_periods = window_size
-        end
-        window_size = "#{window_size}i"
-      end
-      if min_periods.nil?
-        min_periods = 1
-      end
-      [window_size, min_periods]
-    end
-
     def _prepare_rolling_by_window_args(window_size)
       window_size
     end