polars-df 0.15.0 → 0.26.0

data/lib/polars/functions/lit.rb

@@ -3,7 +3,23 @@ module Polars
     # Return an expression representing a literal value.
     #
     # @return [Expr]
-    def lit(value, dtype: nil, allow_object: nil)
+    #
+    # @example Literal scalar values:
+    #   Polars.lit(1)
+    #   Polars.lit(5.5)
+    #   Polars.lit(nil)
+    #   Polars.lit("foo_bar")
+    #   Polars.lit(Date.new(2021, 1, 20))
+    #   Polars.lit(DateTime.new(2023, 3, 31, 10, 30, 45))
+    #
+    # @example Literal list/Series data (1D):
+    #   Polars.lit([1, 2, 3])
+    #   Polars.lit(Polars::Series.new("x", [1, 2, 3]))
+    #
+    # @example Literal list/Series data (2D):
+    #   Polars.lit([[1, 2], [3, 4]])
+    #   Polars.lit(Polars::Series.new("y", [[1, 2], [3, 4]]))
+    def lit(value, dtype: nil, allow_object: false)
       if value.is_a?(::Time) || value.is_a?(::DateTime)
         time_unit = dtype&.time_unit || "ns"
         time_zone = dtype.&time_zone
@@ -16,20 +32,15 @@ module Polars
       elsif value.is_a?(::Date)
         return lit(::Time.utc(value.year, value.month, value.day)).cast(Date)
       elsif value.is_a?(Polars::Series)
-        name = value.name
         value = value._s
-        e = Utils.wrap_expr(Plr.lit(value, allow_object))
-        if name == ""
-          return e
-        end
-        return e.alias(name)
+        return Utils.wrap_expr(Plr.lit(value, allow_object, false))
       elsif (defined?(Numo::NArray) && value.is_a?(Numo::NArray)) || value.is_a?(::Array)
-        return lit(Series.new("", value))
+        return Utils.wrap_expr(Plr.lit(Series.new("literal", [value.to_a], dtype: dtype)._s, allow_object, true))
       elsif dtype
-        return Utils.wrap_expr(Plr.lit(value, allow_object)).cast(dtype)
+        return Utils.wrap_expr(Plr.lit(value, allow_object, true)).cast(dtype)
       end
 
-      Utils.wrap_expr(Plr.lit(value, allow_object))
+      Utils.wrap_expr(Plr.lit(value, allow_object, true))
     end
   end
 end

data/lib/polars/functions/range/int_range.rb

@@ -12,7 +12,7 @@ module Polars
     # @param step [Integer]
     #   Step size of the range.
     # @param eager [Boolean]
-    #   If eager evaluation is `True`, a Series is returned instead of an Expr.
+    #   If eager evaluation is `true`, a Series is returned instead of an Expr.
     # @param dtype [Symbol]
     #   Apply an explicit integer dtype to the resulting expression (default is `Int64`).
     #
@@ -28,7 +28,7 @@ module Polars
     #   #         1
     #   #         2
     #   # ]
-    def int_range(start, stop = nil, step: 1, eager: false, dtype: nil)
+    def int_range(start = 0, stop = nil, step: 1, eager: false, dtype: Int64)
       if stop.nil?
         stop = start
         start = 0
@@ -47,5 +47,77 @@ module Polars
       result
     end
     alias_method :arange, :int_range
+
+    # Generate a range of integers for each row of the input columns.
+    #
+    # @param start [Integer, Expr, Series]
+    #   Start of the range (inclusive). Defaults to 0.
+    # @param stop [Integer, Expr, Series]
+    #   End of the range (exclusive). If set to `nil` (default),
+    #   the value of `start` is used and `start` is set to `0`.
+    # @param step [Integer]
+    #   Step size of the range.
+    # @param dtype [Object]
+    #   Integer data type of the ranges. Defaults to `Int64`.
+    # @param eager [Boolean]
+    #   Evaluate immediately and return a `Series`.
+    #   If set to `false` (default), return an expression instead.
+    #
+    # @return [Expr, Series]
+    #
+    # @example
+    #   df = Polars::DataFrame.new({"start" => [1, -1], "end" => [3, 2]})
+    #   df.with_columns(int_range: Polars.int_ranges("start", "end"))
+    #   # =>
+    #   # shape: (2, 3)
+    #   # ┌───────┬─────┬────────────┐
+    #   # │ start ┆ end ┆ int_range  │
+    #   # │ ---   ┆ --- ┆ ---        │
+    #   # │ i64   ┆ i64 ┆ list[i64]  │
+    #   # ╞═══════╪═════╪════════════╡
+    #   # │ 1     ┆ 3   ┆ [1, 2]     │
+    #   # │ -1    ┆ 2   ┆ [-1, 0, 1] │
+    #   # └───────┴─────┴────────────┘
+    #
+    # @example `end` can be omitted for a shorter syntax.
+    #   df.select("end", int_range: Polars.int_ranges("end"))
+    #   # =>
+    #   # shape: (2, 2)
+    #   # ┌─────┬───────────┐
+    #   # │ end ┆ int_range │
+    #   # │ --- ┆ ---       │
+    #   # │ i64 ┆ list[i64] │
+    #   # ╞═════╪═══════════╡
+    #   # │ 3   ┆ [0, 1, 2] │
+    #   # │ 2   ┆ [0, 1]    │
+    #   # └─────┴───────────┘
+    def int_ranges(
+      start = 0,
+      stop = nil,
+      step: 1,
+      dtype: Int64,
+      eager: false
+    )
+      if stop.nil?
+        stop = start
+        start = 0
+      end
+
+      dtype_expr = Utils.parse_into_datatype_expr(dtype)
+      start_rbexpr = Utils.parse_into_expression(start)
+      end_rbexpr = Utils.parse_into_expression(stop)
+      step_rbexpr = Utils.parse_into_expression(step)
+      result = Utils.wrap_expr(
+        Plr.int_ranges(
+          start_rbexpr, end_rbexpr, step_rbexpr, dtype_expr._rbdatatype_expr
+        )
+      )
+
+      if eager
+        return F.select(result).to_series
+      end
+
+      result
+    end
   end
 end

data/lib/polars/functions/range/linear_space.rb

@@ -0,0 +1,195 @@
+module Polars
+  module Functions
+    # Create sequence of evenly-spaced points.
+    #
+    # @param start [Object]
+    #   Lower bound of the range.
+    # @param stop [Object]
+    #   Upper bound of the range.
+    # @param num_samples [Object]
+    #   Number of samples in the output sequence.
+    # @param closed ['both', 'left', 'right', 'none']
+    #   Define which sides of the interval are closed (inclusive).
+    # @param eager [Boolean]
+    #   Evaluate immediately and return a `Series`.
+    #   If set to `false` (default), return an expression instead.
+    #
+    # @return [Object]
+    #
+    # @note
+    #   This functionality is experimental. It may be changed at any point without it
+    #   being considered a breaking change.
+    #
+    # @example
+    #   Polars.linear_space(0, 1, 3, eager: true)
+    #   # =>
+    #   # shape: (3,)
+    #   # Series: 'literal' [f64]
+    #   # [
+    #   #         0.0
+    #   #         0.5
+    #   #         1.0
+    #   # ]
+    #
+    # @example
+    #   Polars.linear_space(0, 1, 3, closed: "left", eager: true)
+    #   # =>
+    #   # shape: (3,)
+    #   # Series: 'literal' [f64]
+    #   # [
+    #   #         0.0
+    #   #         0.333333
+    #   #         0.666667
+    #   # ]
+    #
+    # @example
+    #   Polars.linear_space(0, 1, 3, closed: "right", eager: true)
+    #   # =>
+    #   # shape: (3,)
+    #   # Series: 'literal' [f64]
+    #   # [
+    #   #         0.333333
+    #   #         0.666667
+    #   #         1.0
+    #   # ]
+    #
+    # @example
+    #   Polars.linear_space(0, 1, 3, closed: "none", eager: true)
+    #   # =>
+    #   # shape: (3,)
+    #   # Series: 'literal' [f64]
+    #   # [
+    #   #         0.25
+    #   #         0.5
+    #   #         0.75
+    #   # ]
+    #
+    # @example `Date` endpoints generate a sequence of `Datetime` values:
+    #   Polars.linear_space(
+    #     Date.new(2025, 1, 1),
+    #     Date.new(2025, 2, 1),
+    #     3,
+    #     closed: "right",
+    #     eager: true
+    #   )
+    #   # =>
+    #   # shape: (3,)
+    #   # Series: 'literal' [datetime[μs]]
+    #   # [
+    #   #         2025-01-11 08:00:00
+    #   #         2025-01-21 16:00:00
+    #   #         2025-02-01 00:00:00
+    #   # ]
+    #
+    # @example When `eager: false` (default), an expression is produced. You can generate a sequence using the length of the dataframe:
+    #   df = Polars::DataFrame.new({"a" => [1, 2, 3, 4, 5]})
+    #   df.with_columns(Polars.linear_space(0, 1, Polars.len).alias("ls"))
+    #   # =>
+    #   # shape: (5, 2)
+    #   # ┌─────┬──────┐
+    #   # │ a   ┆ ls   │
+    #   # │ --- ┆ ---  │
+    #   # │ i64 ┆ f64  │
+    #   # ╞═════╪══════╡
+    #   # │ 1   ┆ 0.0  │
+    #   # │ 2   ┆ 0.25 │
+    #   # │ 3   ┆ 0.5  │
+    #   # │ 4   ┆ 0.75 │
+    #   # │ 5   ┆ 1.0  │
+    #   # └─────┴──────┘
+    def linear_space(
+      start,
+      stop,
+      num_samples,
+      closed: "both",
+      eager: false
+    )
+      start_rbexpr = Utils.parse_into_expression(start)
+      end_rbexpr = Utils.parse_into_expression(stop)
+      num_samples_rbexpr = Utils.parse_into_expression(num_samples)
+      result = Utils.wrap_expr(
+        Plr.linear_space(start_rbexpr, end_rbexpr, num_samples_rbexpr, closed)
+      )
+
+      if eager
+        return F.select(result).to_series
+      end
+
+      result
+    end
+
+    # Generate a sequence of evenly-spaced values for each row between `start` and `end`.
+    #
+    # The number of values in each sequence is determined by `num_samples`.
+    #
+    # @param start [Object]
+    #   Lower bound of the range.
+    # @param stop [Object]
+    #   Upper bound of the range.
+    # @param num_samples [Integer]
+    #   Number of samples in the output sequence.
+    # @param closed ['both', 'left', 'right', 'none']
+    #   Define which sides of the interval are closed (inclusive).
+    # @param as_array [Boolean]
+    #   Return result as a fixed-length `Array`. `num_samples` must be a constant.
+    # @param eager [Boolean]
+    #   Evaluate immediately and return a `Series`.
+    #   If set to `false` (default), return an expression instead.
+    #
+    # @return [Expr, Series]
+    #
+    # @note
+    #   This functionality is experimental. It may be changed at any point without it
+    #   being considered a breaking change.
+    #
+    # @example
+    #   df = Polars::DataFrame.new({"start" => [1, -1], "end" => [3, 2], "num_samples" => [4, 5]})
+    #   df.with_columns(ls: Polars.linear_spaces("start", "end", "num_samples"))
+    #   # =>
+    #   # shape: (2, 4)
+    #   # ┌───────┬─────┬─────────────┬────────────────────────┐
+    #   # │ start ┆ end ┆ num_samples ┆ ls                     │
+    #   # │ ---   ┆ --- ┆ ---         ┆ ---                    │
+    #   # │ i64   ┆ i64 ┆ i64         ┆ list[f64]              │
+    #   # ╞═══════╪═════╪═════════════╪════════════════════════╡
+    #   # │ 1     ┆ 3   ┆ 4           ┆ [1.0, 1.666667, … 3.0] │
+    #   # │ -1    ┆ 2   ┆ 5           ┆ [-1.0, -0.25, … 2.0]   │
+    #   # └───────┴─────┴─────────────┴────────────────────────┘
+    #
+    # @example
+    #   df.with_columns(ls: Polars.linear_spaces("start", "end", 3, as_array: true))
+    #   # =>
+    #   # shape: (2, 4)
+    #   # ┌───────┬─────┬─────────────┬──────────────────┐
+    #   # │ start ┆ end ┆ num_samples ┆ ls               │
+    #   # │ ---   ┆ --- ┆ ---         ┆ ---              │
+    #   # │ i64   ┆ i64 ┆ i64         ┆ array[f64, 3]    │
+    #   # ╞═══════╪═════╪═════════════╪══════════════════╡
+    #   # │ 1     ┆ 3   ┆ 4           ┆ [1.0, 2.0, 3.0]  │
+    #   # │ -1    ┆ 2   ┆ 5           ┆ [-1.0, 0.5, 2.0] │
+    #   # └───────┴─────┴─────────────┴──────────────────┘
+    def linear_spaces(
+      start,
+      stop,
+      num_samples,
+      closed: "both",
+      as_array: false,
+      eager: false
+    )
+      start_rbexpr = Utils.parse_into_expression(start)
+      end_rbexpr = Utils.parse_into_expression(stop)
+      num_samples_rbexpr = Utils.parse_into_expression(num_samples)
+      result = Utils.wrap_expr(
+        Plr.linear_spaces(
+          start_rbexpr, end_rbexpr, num_samples_rbexpr, closed, as_array
+        )
+      )
+
+      if eager
+        return F.select(result).to_series
+      end
+
+      result
+    end
+  end
+end

data/lib/polars/functions/range/time_range.rb

@@ -12,7 +12,7 @@ module Polars
     #   Define which sides of the range are closed (inclusive).
     # @param eager [Boolean]
     #   Evaluate immediately and return a `Series`.
-    #   If set to `False` (default), return an expression instead.
+    #   If set to `false` (default), return an expression instead.
     #
     # @return [Object]
     #

data/lib/polars/functions/repeat.rb

@@ -6,10 +6,12 @@ module Polars
     #   Value to repeat.
     # @param n [Integer]
     #   Repeat `n` times.
+    # @param dtype [Object]
+    #   Data type of the resulting column. If set to `nil` (default), data type is
+    #   inferred from the given value. Defaults to Int32 for integer values, unless
+    #   Int64 is required to fit the given value. Defaults to Float64 for float values.
     # @param eager [Boolean]
     #   Run eagerly and collect into a `Series`.
-    # @param name [String]
-    #   Only used in `eager` mode. As expression, use `alias`.
     #
     # @return [Object]
     #
@@ -34,20 +36,13 @@ module Polars
     #   #         3
     #   #         3
     #   # ]
-    def repeat(value, n, dtype: nil, eager: false, name: nil)
-      if !name.nil?
-        warn "the `name` argument is deprecated. Use the `alias` method instead."
-      end
-
+    def repeat(value, n, dtype: nil, eager: false)
       if n.is_a?(Integer)
         n = lit(n)
       end
 
       value = Utils.parse_into_expression(value, str_as_lit: true)
       expr = Utils.wrap_expr(Plr.repeat(value, n._rbexpr, dtype))
-      if !name.nil?
-        expr = expr.alias(name)
-      end
       if eager
         return select(expr).to_series
       end
@@ -78,7 +73,7 @@ module Polars
     #   #         1
     #   #         1
     #   # ]
-    def ones(n, dtype: nil, eager: true)
+    def ones(n, dtype: Float64, eager: false)
       if (zero = _one_or_zero_by_dtype(1, dtype)).nil?
         msg = "invalid dtype for `ones`; found #{dtype}"
         raise TypeError, msg
@@ -111,7 +106,7 @@ module Polars
     #   #         0
     #   #         0
     #   # ]
-    def zeros(n, dtype: nil, eager: true)
+    def zeros(n, dtype: Float64, eager: false)
       if (zero = _one_or_zero_by_dtype(0, dtype)).nil?
         msg = "invalid dtype for `zeros`; found #{dtype}"
         raise TypeError, msg

data/lib/polars/functions/whenthen.rb

@@ -6,7 +6,7 @@ module Polars
     #
     # @example Below we add a column with the value 1, where column "foo" > 2 and the value -1 where it isn't.
     #   df = Polars::DataFrame.new({"foo" => [1, 3, 4], "bar" => [3, 4, 0]})
-    #   df.with_column(Polars.when(Polars.col("foo") > 2).then(Polars.lit(1)).otherwise(Polars.lit(-1)))
+    #   df.with_columns(Polars.when(Polars.col("foo") > 2).then(Polars.lit(1)).otherwise(Polars.lit(-1)))
     #   # =>
     #   # shape: (3, 3)
     #   # ┌─────┬─────┬─────────┐
@@ -40,7 +40,7 @@ module Polars
     #   # │ 4   ┆ 0   ┆ 1   │
     #   # └─────┴─────┴─────┘
     #
-    # @example The `otherwise` at the end is optional. If left out, any rows where none of the `when` expressions evaluate to True, are set to `null`:
+    # @example The `otherwise` at the end is optional. If left out, any rows where none of the `when` expressions evaluate to true, are set to `null`:
     #   df.with_columns(Polars.when(Polars.col("foo") > 2).then(1).alias("val"))
     #   # =>
     #   # shape: (3, 3)