polars-df 0.25.0 → 0.26.0

data/lib/polars/expr.rb

@@ -252,6 +252,38 @@ module Polars
       wrap_expr(_rbexpr.all(ignore_nulls))
     end
 
+    # Return whether the column is empty.
+    #
+    # @note
+    #   This functionality is considered **unstable**. It may be changed
+    #   at any point without it being considered a breaking change.
+    #
+    # @param ignore_nulls [Boolean]
+    #   If true a column containing only nulls will also be considered empty.
+    #   The default is false.
+    #
+    # @return [Expr]
+    #
+    # @example
+    #   df = Polars::DataFrame.new({"x" => [nil, nil]})
+    #   df.select(
+    #     a: Polars.col("x").is_empty,
+    #     b: Polars.col("x").drop_nulls.is_empty,
+    #     c: Polars.col("x").is_empty(ignore_nulls: true)
+    #   )
+    #   # =>
+    #   # shape: (1, 3)
+    #   # ┌───────┬──────┬──────┐
+    #   # │ a     ┆ b    ┆ c    │
+    #   # │ ---   ┆ ---  ┆ ---  │
+    #   # │ bool  ┆ bool ┆ bool │
+    #   # ╞═══════╪══════╪══════╡
+    #   # │ false ┆ true ┆ true │
+    #   # └───────┴──────┴──────┘
+    def is_empty(ignore_nulls: false)
+      wrap_expr(_rbexpr.is_empty(ignore_nulls))
+    end
+
     # Return indices where expression evaluates `true`.
     #
     # @return [Expr]
@@ -1204,6 +1236,49 @@ module Polars
       wrap_expr(_rbexpr.round_sig_figs(digits))
     end
 
+    # Truncate numeric data toward zero to `decimals` number of decimal places.
+    #
+    # @param decimals [Integer]
+    #   Number of decimal places to truncate to.
+    #
+    # @return [Expr]
+    #
+    # @note
+    #   Truncation discards the fractional part beyond the given number of decimals.
+    #   For example, when rounding to 0 decimals 0.25, -0.25, 0.99, and -0.99 will
+    #   all round to 0. When rounding to 1 decimal 1.9999 rounds to 1.9 and -1.9999
+    #   rounds to -1.9. There is no tiebreak behaviour at midpoint values as there
+    #   is with :meth:`round` so 0.5 and -0.5 will also round to 0 when decimals=1.
+    #
+    # @note
+    #   This method performs numeric truncation. For truncating temporal
+    #   data (dates/datetimes), use :func:`Expr.dt.truncate` instead.
+    #
+    # @example
+    #   df = Polars::DataFrame.new({"n" => [-9.9999, 0.12345, 1.0251, 8.8765]})
+    #   df.with_columns(
+    #     t0: Polars.col("n").truncate(0),
+    #     t1: Polars.col("n").truncate(1),
+    #     t2: Polars.col("n").truncate(2),
+    #     t3: Polars.col("n").truncate(3),
+    #     t4: Polars.col("n").truncate(4)
+    #   )
+    #   # =>
+    #   # shape: (4, 6)
+    #   # ┌─────────┬──────┬──────┬───────┬────────┬─────────┐
+    #   # │ n       ┆ t0   ┆ t1   ┆ t2    ┆ t3     ┆ t4      │
+    #   # │ ---     ┆ ---  ┆ ---  ┆ ---   ┆ ---    ┆ ---     │
+    #   # │ f64     ┆ f64  ┆ f64  ┆ f64   ┆ f64    ┆ f64     │
+    #   # ╞═════════╪══════╪══════╪═══════╪════════╪═════════╡
+    #   # │ -9.9999 ┆ -9.0 ┆ -9.9 ┆ -9.99 ┆ -9.999 ┆ -9.9999 │
+    #   # │ 0.12345 ┆ 0.0  ┆ 0.1  ┆ 0.12  ┆ 0.123  ┆ 0.1234  │
+    #   # │ 1.0251  ┆ 1.0  ┆ 1.0  ┆ 1.02  ┆ 1.025  ┆ 1.025   │
+    #   # │ 8.8765  ┆ 8.0  ┆ 8.8  ┆ 8.87  ┆ 8.876  ┆ 8.8765  │
+    #   # └─────────┴──────┴──────┴───────┴────────┴─────────┘
+    def truncate(decimals = 0)
+      Utils.wrap_expr(_rbexpr.truncate(decimals))
+    end
+
     # Compute the dot/inner product between two Expressions.
     #
     # @param other [Expr]
@@ -1887,6 +1962,11 @@ module Polars
     #
     # @param indices [Expr]
     #   An expression that leads to a `:u32` dtyped Series.
+    # @param null_on_oob [Boolean]
+    #   Behavior if an index is out of bounds:
+    #
+    #   - true  -> set the result to null
+    #   - false -> raise an error
     #
     # @return [Expr]
     #
@@ -1915,13 +1995,13 @@ module Polars
     #   # │ one   ┆ [2, 98]   │
     #   # │ two   ┆ [4, 99]   │
     #   # └───────┴───────────┘
-    def gather(indices)
+    def gather(indices, null_on_oob: false)
       if indices.is_a?(::Array)
         indices_lit_rbexpr = Polars.lit(Series.new("", indices, dtype: Int64))._rbexpr
       else
         indices_lit_rbexpr = Utils.parse_into_expression(indices)
       end
-      wrap_expr(_rbexpr.gather(indices_lit_rbexpr))
+      wrap_expr(_rbexpr.gather(indices_lit_rbexpr, null_on_oob))
     end
 
     # Return a single value by index.
@@ -2266,6 +2346,38 @@ module Polars
       wrap_expr(_rbexpr.max)
     end
 
+    # Get maximum value, ordered by another expression.
+    #
+    # If the by expression has multiple values equal to the maximum it is not
+    # defined which value will be chosen.
+    #
+    # @note
+    #   This functionality is considered **unstable**. It may be changed
+    #   at any point without it being considered a breaking change.
+    #
+    # @param by [Object]
+    #   Column used to determine the largest element.
+    #   Accepts expression input. Strings are parsed as column names.
+    #
+    # @return [Expr]
+    #
+    # @example
+    #   df = Polars::DataFrame.new({"a" => [-1.0, Float::NAN, 1.0], "b" => ["x", "y", "z"]})
+    #   df.select(Polars.col("b").max_by("a"))
+    #   # =>
+    #   # shape: (1, 1)
+    #   # ┌─────┐
+    #   # │ b   │
+    #   # │ --- │
+    #   # │ str │
+    #   # ╞═════╡
+    #   # │ z   │
+    #   # └─────┘
+    def max_by(by)
+      by_rbexpr = Utils.parse_into_expression(by)
+      wrap_expr(_rbexpr.max_by(by_rbexpr))
+    end
+
     # Get minimum value.
     #
     # @return [Expr]
@@ -2286,6 +2398,38 @@ module Polars
       wrap_expr(_rbexpr.min)
     end
 
+    # Get minimum value, ordered by another expression.
+    #
+    # If the by expression has multiple values equal to the minimum it is not
+    # defined which value will be chosen.
+    #
+    # @note
+    #   This functionality is considered **unstable**. It may be changed
+    #   at any point without it being considered a breaking change.
+    #
+    # @param by [Object]
+    #   Column used to determine the smallest element.
+    #   Accepts expression input. Strings are parsed as column names.
+    #
+    # @return [Expr]
+    #
+    # @example
+    #   df = Polars::DataFrame.new({"a" => [-1.0, Float::NAN, 1.0], "b" => ["x", "y", "z"]})
+    #   df.select(Polars.col("b").min_by("a"))
+    #   # =>
+    #   # shape: (1, 1)
+    #   # ┌─────┐
+    #   # │ b   │
+    #   # │ --- │
+    #   # │ str │
+    #   # ╞═════╡
+    #   # │ x   │
+    #   # └─────┘
+    def min_by(by)
+      by_rbexpr = Utils.parse_into_expression(by)
+      wrap_expr(_rbexpr.min_by(by_rbexpr))
+    end
+
     # Get maximum value, but propagate/poison encountered NaN values.
     #
     # @return [Expr]
@@ -3131,17 +3275,17 @@ module Polars
     #   )
     #   # =>
     #   # shape: (5, 2)
-    #   # ┌─────┬─────┐
-    #   # │ foo ┆ cut │
-    #   # │ --- ┆ --- │
-    #   # │ i64 ┆ cat │
-    #   # ╞═════╪═════╡
-    #   # │ -2  ┆ a   │
-    #   # │ -1  ┆ a   │
-    #   # │ 0   ┆ b   │
-    #   # │ 1   ┆ b   │
-    #   # │ 2   ┆ c   │
-    #   # └─────┴─────┘
+    #   # ┌─────┬──────┐
+    #   # │ foo ┆ cut  │
+    #   # │ --- ┆ ---  │
+    #   # │ i64 ┆ enum │
+    #   # ╞═════╪══════╡
+    #   # │ -2  ┆ a    │
+    #   # │ -1  ┆ a    │
+    #   # │ 0   ┆ b    │
+    #   # │ 1   ┆ b    │
+    #   # │ 2   ┆ c    │
+    #   # └─────┴──────┘
     #
     # @example Add both the category and the breakpoint.
     #   df.with_columns(
@@ -3152,7 +3296,7 @@ module Polars
     #   # ┌─────┬────────────┬────────────┐
     #   # │ foo ┆ breakpoint ┆ category   │
     #   # │ --- ┆ ---        ┆ ---        │
-    #   # │ i64 ┆ f64        ┆ cat        │
+    #   # │ i64 ┆ f64        ┆ enum       │
     #   # ╞═════╪════════════╪════════════╡
     #   # │ -2  ┆ -1.0       ┆ (-inf, -1] │
     #   # │ -1  ┆ -1.0       ┆ (-inf, -1] │
@@ -4502,13 +4646,18 @@ module Polars
       wrap_expr(_rbexpr._hash(k0, k1, k2, k3))
     end
 
-    # Reinterpret the underlying bits as a signed/unsigned integer.
+    # Reinterpret the underlying bits as a signed/unsigned integer or float.
+    #
+    # This operation is only allowed for numeric types of the same size.
+    # For lower bits numbers, you can safely use the cast operation.
     #
-    # This operation is only allowed for 64bit integers. For lower bits integers,
-    # you can safely use that cast operation.
+    # Either `signed` or `dtype` can be specified.
     #
     # @param signed [Boolean]
-    #   If true, reinterpret as `Polars::Int64`. Otherwise, reinterpret as `Polars::UInt64`.
+    #   If true, reinterpret as signed integer. Otherwise, reinterpret
+    #   as unsigned integer.
+    # @param dtype [Object]
+    #   DataType to reinterpret to.
     #
     # @return [Expr]
     #
@@ -4517,7 +4666,7 @@ module Polars
     #   df = Polars::DataFrame.new([s])
     #   df.select(
     #     [
-    #       Polars.col("a").reinterpret(signed: true).alias("reinterpreted"),
+    #       Polars.col("a").reinterpret(dtype: Polars::Int64).alias("reinterpreted"),
     #       Polars.col("a").alias("original")
     #     ]
     #   )
@@ -4532,14 +4681,13 @@ module Polars
     #   # │ 1             ┆ 1        │
     #   # │ 2             ┆ 2        │
     #   # └───────────────┴──────────┘
-    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
+    def reinterpret(signed: nil, dtype: nil)
+      if signed.nil? == dtype.nil?
+        msg = "reinterpret requires exactly one of `signed` or `dtype` to be specified"
+        raise ArgumentError, msg
       end
 
-      wrap_expr(_rbexpr.reinterpret(signed))
+      wrap_expr(_rbexpr.reinterpret(signed, dtype))
     end
 
     # Print the value that this expression evaluates to and pass on the value.
@@ -5111,7 +5259,7 @@ module Polars
     def rolling_sum_by(
       by,
       window_size,
-      min_samples: 1,
+      min_samples: 0,
       closed: "right"
     )
       window_size = _prepare_rolling_by_window_args(window_size)
@@ -6486,6 +6634,67 @@ module Polars
       )
     end
 
+    # Compute a custom rolling window function.
+    #
+    # @note
+    #   This functionality is considered **unstable**. It may be changed
+    #   at any point without it being considered a breaking change.
+    #
+    # @param window_size [Integer]
+    #   The length of the window in number of elements.
+    # @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_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" => [11.0, 2.0, 9.0, Float::NAN, 8.0]})
+    #   df.select(Polars.col("a").rolling_map(3) { |v| v.drop_nans.sum })
+    #   # =>
+    #   # shape: (5, 1)
+    #   # ┌──────┐
+    #   # │ a    │
+    #   # │ ---  │
+    #   # │ f64  │
+    #   # ╞══════╡
+    #   # │ null │
+    #   # │ null │
+    #   # │ 22.0 │
+    #   # │ 11.0 │
+    #   # │ 17.0 │
+    #   # └──────┘
+    def rolling_map(
+      window_size,
+      weights: nil,
+      min_samples: nil,
+      center: false,
+      &function
+    )
+      if min_samples.nil?
+        min_samples = window_size
+      end
+
+      _wrap = lambda do |rbs|
+        s = Utils.wrap_s(rbs)
+        rv = function.(s)
+        if rv.is_a?(Series)
+          rv._s
+        else
+          Series.new([rv])._s
+        end
+      end
+
+      wrap_expr(
+        _rbexpr.rolling_map(_wrap, window_size, weights, min_samples, center)
+      )
+    end
+
     # Compute absolute values.
     #
     # @return [Expr]
@@ -7237,17 +7446,11 @@ module Polars
     #   # └─────┘
     def sample(
       fraction: nil,
-      with_replacement: nil,
+      with_replacement: false,
       shuffle: false,
       seed: nil,
       n: nil
     )
-      # 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? && !fraction.nil?
         raise ArgumentError, "cannot specify both `n` and `fraction`"
       end
@@ -7636,13 +7839,7 @@ module Polars
     #   # ╞═══════════╡
     #   # │ -6.754888 │
     #   # └───────────┘
-    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
-
+    def entropy(base: Math::E, normalize: true)
       wrap_expr(_rbexpr.entropy(base, normalize))
     end
 
@@ -7698,6 +7895,8 @@ module Polars
     #
     # @param descending [Boolean]
     #   Whether the `Series` order is descending.
+    # @param nulls_last [Boolean]
+    #   Whether the nulls are at the end.
     #
     # @return [Expr]
     #
@@ -7717,12 +7916,16 @@ module Polars
     #   # ╞════════╡
     #   # │ 3      │
     #   # └────────┘
-    def set_sorted(descending: false)
-      wrap_expr(_rbexpr.set_sorted_flag(descending))
+    def set_sorted(descending: false, nulls_last: false)
+      wrap_expr(_rbexpr.set_sorted_flag(descending, nulls_last))
     end
 
     # Aggregate to list.
     #
+    # @param maintain_order [Boolean]
+    #   Whether to preserve the order of elements in the list. Setting this
+    #   to `false` can improve performance, especially within `group_by`.
+    #
     # @return [Expr]
     #
     # @example
@@ -7742,8 +7945,8 @@ module Polars
     #   # ╞═══════════╪═══════════╡
     #   # │ [1, 2, 3] ┆ [4, 5, 6] │
     #   # └───────────┴───────────┘
-    def implode
-      wrap_expr(_rbexpr.implode)
+    def implode(maintain_order: true)
+      wrap_expr(_rbexpr.implode(maintain_order))
     end
 
     # Bin values into buckets and count their occurrences.

data/lib/polars/functions/business.rb

@@ -81,13 +81,13 @@ module Polars
     )
       start_rbexpr = Utils.parse_into_expression(start)
       end_rbexpr = Utils.parse_into_expression(stop)
-      unix_epoch = ::Date.new(1970, 1, 1)
+      holidays_rbexpr = Utils._holidays_to_expr(holidays)
       Utils.wrap_expr(
         Plr.business_day_count(
           start_rbexpr,
           end_rbexpr,
           week_mask,
-          holidays.map { |holiday| holiday - unix_epoch }
+          holidays_rbexpr
         )
       )
     end

data/lib/polars/functions/datatype.rb

@@ -28,5 +28,35 @@ module Polars
     def self_dtype
       DataTypeExpr._from_rbdatatype_expr(RbDataTypeExpr.self_dtype)
     end
+
+    # Create a new datatype expression that represents a Struct datatype.
+    #
+    # @note
+    #   This functionality is considered **unstable**. It may be changed
+    #   at any point without it being considered a breaking change.
+    #
+    # @return [DataTypeExpr]
+    def struct_with_fields(
+      mapping
+    )
+      preprocess = lambda do |dtype_expr|
+        if dtype_expr.is_a?(DataType)
+          dtype_expr.to_dtype_expr._rbdatatype_expr
+        elsif dtype_expr < DataType
+          dtype_expr.to_dtype_expr._rbdatatype_expr
+        elsif dtype_expr.is_a?(DataTypeExpr)
+          dtype_expr._rbdatatype_expr
+        else
+          msg = "mapping item must be a datatype or datatype expression; found #{dtype_expr.inspect}"
+          raise TypeError, msg
+        end
+      end
+
+      fields = mapping.map { |name, dtype_expr| [name.to_s, preprocess.(dtype_expr)]  }
+
+      DataTypeExpr._from_rbdatatype_expr(
+        RbDataTypeExpr.struct_with_fields(fields)
+      )
+    end
   end
 end

data/lib/polars/functions/eager.rb

@@ -399,6 +399,85 @@ module Polars
       out
     end
 
+    # Merge multiple sorted DataFrames or LazyFrames by the sorted key.
+    #
+    # The output of this operation will also be sorted.
+    # It is the callers responsibility that the frames
+    # are sorted in ascending order by that key otherwise
+    # the output will not make sense.
+    #
+    # @note
+    #   This functionality is considered **unstable**. It may be changed
+    #   at any point without it being considered a breaking change.
+    #
+    # @param items [Array]
+    #   DataFrames or LazyFrames to merge.
+    # @param key [String]
+    #   Key that is sorted.
+    # @param maintain_order [Boolean]
+    #   If `true`, the output is guaranteed to have left-biased ordering
+    #   for equal keys: rows from the left frame appear before rows from
+    #   the right frame when their keys are equal.
+    #
+    # @return [Object]
+    #
+    # @example
+    #   df0 = Polars::DataFrame.new(
+    #     {"name" => ["steve", "elise", "bob"], "age" => [42, 44, 18]}
+    #   ).sort("age")
+    #   df1 = Polars::DataFrame.new(
+    #     {"name" => ["anna", "megan", "steve", "thomas"], "age" => [21, 33, 17, 20]}
+    #   ).sort("age")
+    #   df2 = Polars::DataFrame.new({"name" => ["ida", "maya"], "age" => [37, 27]}).sort("age")
+    #   Polars.merge_sorted([df0, df1, df2], "age")
+    #   # =>
+    #   # shape: (9, 2)
+    #   # ┌────────┬─────┐
+    #   # │ name   ┆ age │
+    #   # │ ---    ┆ --- │
+    #   # │ str    ┆ i64 │
+    #   # ╞════════╪═════╡
+    #   # │ steve  ┆ 17  │
+    #   # │ bob    ┆ 18  │
+    #   # │ thomas ┆ 20  │
+    #   # │ anna   ┆ 21  │
+    #   # │ maya   ┆ 27  │
+    #   # │ megan  ┆ 33  │
+    #   # │ ida    ┆ 37  │
+    #   # │ steve  ┆ 42  │
+    #   # │ elise  ┆ 44  │
+    #   # └────────┴─────┘
+    def merge_sorted(
+      items,
+      key,
+      maintain_order: false
+    )
+      elems = items.to_a
+
+      if elems.empty?
+        msg = "cannot merge_sort empty list"
+        raise ArgumentError, msg
+      end
+      if elems.length == 1 && (elems[0].is_a?(DataFrame) || elems[0].is_a?(LazyFrame))
+        return elems[0]
+      end
+
+      if !Utils.is_non_empty_sequence_of(elems, DataFrame) && !Utils.is_non_empty_sequence_of(elems, LazyFrame)
+        msg = "merge_sorted is not supported for #{elems[0].inspect}"
+        raise TypeError, msg
+      end
+
+      frames = elems.map { |df| df.lazy }
+
+      reduce_fn = lambda do |x, y|
+        x.merge_sorted(y, key, maintain_order: maintain_order)
+      end
+
+      lf = Utils.reduce_balanced(reduce_fn, frames)
+      eager = elems[0].is_a?(DataFrame)
+      eager ? lf.collect : lf
+    end
+
     # Align an array of frames using the unique values from one or more columns as a key.
     #
     # Frames that do not contain the given key values have rows injected (with nulls
@@ -464,16 +543,10 @@ module Polars
     def align_frames(
       *frames,
       on:,
-      how: nil,
+      how: "full",
       select: nil,
       descending: false
     )
-      # TODO update
-      if how.nil?
-        warn "The default `how` for `align_frames` method will change from `left` to `full` in a future version"
-        how = "left"
-      end
-
       if frames.empty?
         return []
       elsif frames.map(&:class).uniq.length != 1