polars-df 0.10.0 → 0.12.0

data/lib/polars/expr_dispatch.rb

@@ -14,7 +14,7 @@ module Polars
       namespace = self.class._accessor
 
       s = Utils.wrap_s(_s)
-      expr = Utils.col(s.name)
+      expr = F.col(s.name)
       expr = expr.send(namespace) if namespace
       s.to_frame.select(expr.send(method, ...)).to_series
     end

data/lib/polars/functions/aggregation/horizontal.rb

@@ -32,7 +32,7 @@ module Polars
     #   # │ null  ┆ null  ┆ z   ┆ null  │
     #   # └───────┴───────┴─────┴───────┘
     def all_horizontal(*exprs)
-      rbexprs = Utils.parse_as_list_of_expressions(*exprs)
+      rbexprs = Utils.parse_into_list_of_expressions(*exprs)
       Utils.wrap_expr(Plr.all_horizontal(rbexprs))
     end
 
@@ -68,7 +68,7 @@ module Polars
     #   # │ null  ┆ null  ┆ z   ┆ null  │
     #   # └───────┴───────┴─────┴───────┘
     def any_horizontal(*exprs)
-      rbexprs = Utils.parse_as_list_of_expressions(*exprs)
+      rbexprs = Utils.parse_into_list_of_expressions(*exprs)
       Utils.wrap_expr(Plr.any_horizontal(rbexprs))
     end
 
@@ -101,7 +101,7 @@ module Polars
     #   # │ 3   ┆ null ┆ z   ┆ 3   │
     #   # └─────┴──────┴─────┴─────┘
     def max_horizontal(*exprs)
-      rbexprs = Utils.parse_as_list_of_expressions(*exprs)
+      rbexprs = Utils.parse_into_list_of_expressions(*exprs)
       Utils.wrap_expr(Plr.max_horizontal(rbexprs))
     end
 
@@ -134,7 +134,7 @@ module Polars
     #   # │ 3   ┆ null ┆ z   ┆ 3   │
     #   # └─────┴──────┴─────┴─────┘
     def min_horizontal(*exprs)
-      rbexprs = Utils.parse_as_list_of_expressions(*exprs)
+      rbexprs = Utils.parse_into_list_of_expressions(*exprs)
       Utils.wrap_expr(Plr.min_horizontal(rbexprs))
     end
 
@@ -167,7 +167,7 @@ module Polars
     #   # │ 3   ┆ null ┆ z   ┆ 3   │
     #   # └─────┴──────┴─────┴─────┘
     def sum_horizontal(*exprs)
-      rbexprs = Utils.parse_as_list_of_expressions(*exprs)
+      rbexprs = Utils.parse_into_list_of_expressions(*exprs)
       Utils.wrap_expr(Plr.sum_horizontal(rbexprs))
     end
 
@@ -200,7 +200,7 @@ module Polars
     #   # │ 3   ┆ null ┆ z   ┆ 3.0  │
     #   # └─────┴──────┴─────┴──────┘
     def mean_horizontal(*exprs)
-      rbexprs = Utils.parse_as_list_of_expressions(*exprs)
+      rbexprs = Utils.parse_into_list_of_expressions(*exprs)
       Utils.wrap_expr(Plr.mean_horizontal(rbexprs))
     end
 
@@ -233,11 +233,11 @@ module Polars
     #   # │ 3   ┆ null ┆ z   ┆ {3,null}  │
     #   # └─────┴──────┴─────┴───────────┘
     def cum_sum_horizontal(*exprs)
-      rbexprs = Utils.parse_as_list_of_expressions(*exprs)
+      rbexprs = Utils.parse_into_list_of_expressions(*exprs)
       exprs_wrapped = rbexprs.map { |e| Utils.wrap_expr(e) }
 
       # (Expr): use u32 as that will not cast to float as eagerly
-      Polars.cum_fold(Polars.lit(0).cast(UInt32), -> (a, b) { a + b }, exprs_wrapped).alias(
+      Polars.cum_fold(Polars.lit(0).cast(UInt32), ->(a, b) { a + b }, exprs_wrapped).alias(
         "cum_sum"
       )
     end

data/lib/polars/functions/as_datatype.rb

@@ -44,28 +44,28 @@ module Polars
       time_unit: "us"
     )
       if !weeks.nil?
-        weeks = Utils.expr_to_lit_or_expr(weeks, str_to_lit: false)._rbexpr
+        weeks = Utils.parse_into_expression(weeks, str_as_lit: false)
       end
       if !days.nil?
-        days = Utils.expr_to_lit_or_expr(days, str_to_lit: false)._rbexpr
+        days = Utils.parse_into_expression(days, str_as_lit: false)
       end
       if !hours.nil?
-        hours = Utils.expr_to_lit_or_expr(hours, str_to_lit: false)._rbexpr
+        hours = Utils.parse_into_expression(hours, str_as_lit: false)
       end
       if !minutes.nil?
-        minutes = Utils.expr_to_lit_or_expr(minutes, str_to_lit: false)._rbexpr
+        minutes = Utils.parse_into_expression(minutes, str_as_lit: false)
       end
       if !seconds.nil?
-        seconds = Utils.expr_to_lit_or_expr(seconds, str_to_lit: false)._rbexpr
+        seconds = Utils.parse_into_expression(seconds, str_as_lit: false)
       end
       if !milliseconds.nil?
-        milliseconds = Utils.expr_to_lit_or_expr(milliseconds, str_to_lit: false)._rbexpr
+        milliseconds = Utils.parse_into_expression(milliseconds, str_as_lit: false)
       end
       if !microseconds.nil?
-        microseconds = Utils.expr_to_lit_or_expr(microseconds, str_to_lit: false)._rbexpr
+        microseconds = Utils.parse_into_expression(microseconds, str_as_lit: false)
       end
       if !nanoseconds.nil?
-        nanoseconds = Utils.expr_to_lit_or_expr(nanoseconds, str_to_lit: false)._rbexpr
+        nanoseconds = Utils.parse_into_expression(nanoseconds, str_as_lit: false)
       end
 
       Utils.wrap_expr(
@@ -87,28 +87,38 @@ module Polars
     #
     # @return [Expr]
     def concat_list(exprs)
-      exprs = Utils.selection_to_rbexpr_list(exprs)
+      exprs = Utils.parse_into_list_of_expressions(exprs)
       Utils.wrap_expr(Plr.concat_list(exprs))
     end
 
     # Collect several columns into a Series of dtype Struct.
     #
-    # @param exprs [Object]
-    #   Columns/Expressions to collect into a Struct
+    # @param exprs [Array]
+    #   Column(s) to collect into a struct column, specified as positional arguments.
+    #   Accepts expression input. Strings are parsed as column names,
+    #   other non-expression inputs are parsed as literals.
+    # @param schema [Hash]
+    #   Optional schema that explicitly defines the struct field dtypes. If no columns
+    #   or expressions are provided, schema keys are used to define columns.
     # @param eager [Boolean]
-    #   Evaluate immediately
+    #   Evaluate immediately and return a `Series`. If set to `false` (default),
+    #   return an expression instead.
+    # @param named_exprs [Hash]
+    #   Additional columns to collect into the struct column, specified as keyword
+    #   arguments. The columns will be renamed to the keyword used.
     #
     # @return [Object]
     #
     # @example
-    #   Polars::DataFrame.new(
+    #   df = Polars::DataFrame.new(
     #     {
     #       "int" => [1, 2],
     #       "str" => ["a", "b"],
     #       "bool" => [true, nil],
     #       "list" => [[1, 2], [3]],
     #     }
-    #   ).select([Polars.struct(Polars.all).alias("my_struct")])
+    #   )
+    #   df.select([Polars.struct(Polars.all).alias("my_struct")])
     #   # =>
     #   # shape: (2, 1)
     #   # ┌─────────────────────┐
@@ -120,29 +130,42 @@ module Polars
     #   # │ {2,"b",null,[3]}    │
     #   # └─────────────────────┘
     #
-    # @example Only collect specific columns as a struct:
-    #   df = Polars::DataFrame.new(
-    #     {"a" => [1, 2, 3, 4], "b" => ["one", "two", "three", "four"], "c" => [9, 8, 7, 6]}
-    #   )
-    #   df.with_column(Polars.struct(Polars.col(["a", "b"])).alias("a_and_b"))
+    # @example Collect selected columns into a struct by either passing a list of columns, or by specifying each column as a positional argument.
+    #   df.select(Polars.struct("int", false).alias("my_struct"))
     #   # =>
-    #   # shape: (4, 4)
-    #   # ┌─────┬───────┬─────┬─────────────┐
-    #   # │ a   ┆ b     ┆ c   ┆ a_and_b     │
-    #   # │ --- ┆ ---   ┆ --- ┆ ---         │
-    #   # │ i64 ┆ str   ┆ i64 ┆ struct[2]   │
-    #   # ╞═════╪═══════╪═════╪═════════════╡
-    #   # │ 1   ┆ one   ┆ 9   ┆ {1,"one"}   │
-    #   # │ 2   ┆ two   ┆ 8   ┆ {2,"two"}   │
-    #   # │ 3   ┆ three ┆ 7   ┆ {3,"three"} │
-    #   # │ 4   ┆ four  ┆ 6   ┆ {4,"four"}  │
-    #   # └─────┴───────┴─────┴─────────────┘
-    def struct(exprs, eager: false)
+    #   # shape: (2, 1)
+    #   # ┌───────────┐
+    #   # │ my_struct │
+    #   # │ ---       │
+    #   # │ struct[2] │
+    #   # ╞═══════════╡
+    #   # │ {1,false} │
+    #   # │ {2,false} │
+    #   # └───────────┘
+    #
+    # @example Use keyword arguments to easily name each struct field.
+    #   df.select(Polars.struct(p: "int", q: "bool").alias("my_struct")).schema
+    #   # => {"my_struct"=>Polars::Struct({"p"=>Polars::Int64, "q"=>Polars::Boolean})}
+    def struct(*exprs, schema: nil, eager: false, **named_exprs)
+      rbexprs = Utils.parse_into_list_of_expressions(*exprs, **named_exprs)
+      expr = Utils.wrap_expr(Plr.as_struct(rbexprs))
+
+      if !schema.nil? && !schema.empty?
+        if !exprs.any?
+          # no columns or expressions provided; create one from schema keys
+          expr =
+            Utils.wrap_expr(
+              Plr.as_struct(Utils.parse_into_list_of_expressions(schema.keys))
+            )
+          expr = expr.cast(Struct.new(schema), strict: false)
+        end
+      end
+
       if eager
-        Polars.select(struct(exprs, eager: false)).to_series
+        Polars.select(expr).to_series
+      else
+        expr
       end
-      exprs = Utils.selection_to_rbexpr_list(exprs)
-      Utils.wrap_expr(Plr.as_struct(exprs))
     end
 
     # Horizontally concat Utf8 Series in linear time. Non-Utf8 columns are cast to Utf8.
@@ -188,13 +211,13 @@ module Polars
     #   # │ 3   ┆ null ┆ walk ┆ null          │
     #   # └─────┴──────┴──────┴───────────────┘
     def concat_str(exprs, sep: "", ignore_nulls: false)
-      exprs = Utils.selection_to_rbexpr_list(exprs)
+      exprs = Utils.parse_into_list_of_expressions(exprs)
       Utils.wrap_expr(Plr.concat_str(exprs, sep, ignore_nulls))
     end
 
     # Format expressions as a string.
     #
-    # @param fstring [String]
+    # @param f_string [String]
     #   A string that with placeholders.
     #   For example: "hello_{}" or "{}_world
     # @param args [Object]
@@ -225,17 +248,17 @@ module Polars
     #   # │ foo_b_bar_2 │
     #   # │ foo_c_bar_3 │
     #   # └─────────────┘
-    def format(fstring, *args)
-      if fstring.scan("{}").length != args.length
+    def format(f_string, *args)
+      if f_string.scan("{}").length != args.length
         raise ArgumentError, "number of placeholders should equal the number of arguments"
       end
 
       exprs = []
 
       arguments = args.each
-      fstring.split(/(\{\})/).each do |s|
+      f_string.split(/(\{\})/).each do |s|
         if s == "{}"
-          e = Utils.expr_to_lit_or_expr(arguments.next, str_to_lit: false)
+          e = Utils.wrap_expr(Utils.parse_into_expression(arguments.next))
           exprs << e
         elsif s.length > 0
           exprs << lit(s)

data/lib/polars/functions/lazy.rb

@@ -524,6 +524,55 @@ module Polars
       col(*columns).last
     end
 
+    # Get the nth column(s) of the context.
+    #
+    # @param indices [Array]
+    #   One or more indices representing the columns to retrieve.
+    #
+    # @return [Expr]
+    #
+    # @example
+    #   df = Polars::DataFrame.new(
+    #     {
+    #       "a" => [1, 8, 3],
+    #       "b" => [4, 5, 2],
+    #       "c" => ["foo", "bar", "baz"]
+    #     }
+    #   )
+    #   df.select(Polars.nth(1))
+    #   # =>
+    #   # shape: (3, 1)
+    #   # ┌─────┐
+    #   # │ b   │
+    #   # │ --- │
+    #   # │ i64 │
+    #   # ╞═════╡
+    #   # │ 4   │
+    #   # │ 5   │
+    #   # │ 2   │
+    #   # └─────┘
+    #
+    # @example
+    #   df.select(Polars.nth(2, 0))
+    #   # =>
+    #   # shape: (3, 2)
+    #   # ┌─────┬─────┐
+    #   # │ c   ┆ a   │
+    #   # │ --- ┆ --- │
+    #   # │ str ┆ i64 │
+    #   # ╞═════╪═════╡
+    #   # │ foo ┆ 1   │
+    #   # │ bar ┆ 8   │
+    #   # │ baz ┆ 3   │
+    #   # └─────┴─────┘
+    def nth(*indices)
+      if indices.length == 1 && indices[0].is_a?(Array)
+        indices = indices[0]
+      end
+
+      Utils.wrap_expr(Plr.index_cols(indices))
+    end
+
     # Get the first `n` rows.
     #
     # This function is syntactic sugar for `col(column).head(n)`.
@@ -683,8 +732,8 @@ module Polars
       ddof: 1,
       propagate_nans: false
     )
-      a = Utils.parse_as_expression(a)
-      b = Utils.parse_as_expression(b)
+      a = Utils.parse_into_expression(a)
+      b = Utils.parse_into_expression(b)
 
       if method == "pearson"
         Utils.wrap_expr(Plr.pearson_corr(a, b, ddof))
@@ -728,8 +777,8 @@ module Polars
     #   # │ 3.0 │
     #   # └─────┘
     def cov(a, b, ddof: 1)
-      a = Utils.parse_as_expression(a)
-      b = Utils.parse_as_expression(b)
+      a = Utils.parse_into_expression(a)
+      b = Utils.parse_into_expression(b)
       Utils.wrap_expr(Plr.cov(a, b, ddof))
     end
 
@@ -743,13 +792,13 @@ module Polars
     #
     # @return [Expr]
     def fold(acc, f, exprs)
-      acc = Utils.expr_to_lit_or_expr(acc, str_to_lit: true)
+      acc = Utils.parse_into_expression(acc, str_as_lit: true)
       if exprs.is_a?(Expr)
         exprs = [exprs]
       end
 
-      exprs = Utils.selection_to_rbexpr_list(exprs)
-      Utils.wrap_expr(Plr.fold(acc._rbexpr, f, exprs))
+      exprs = Utils.parse_into_list_of_expressions(exprs)
+      Utils.wrap_expr(Plr.fold(acc, f, exprs))
     end
 
     # def reduce
@@ -776,13 +825,13 @@ module Polars
     #   If you simply want the first encountered expression as accumulator,
     #   consider using `cumreduce`.
     def cum_fold(acc, f, exprs, include_init: false)
-      acc = Utils.expr_to_lit_or_expr(acc, str_to_lit: true)
+      acc = Utils.parse_into_expression(acc, str_as_lit: true)
       if exprs.is_a?(Expr)
         exprs = [exprs]
       end
 
-      exprs = Utils.selection_to_rbexpr_list(exprs)
-      Utils.wrap_expr(Plr.cum_fold(acc._rbexpr, f, exprs, include_init))
+      exprs = Utils.parse_into_list_of_expressions(exprs)
+      Utils.wrap_expr(Plr.cum_fold(acc, f, exprs, include_init))
     end
     alias_method :cumfold, :cum_fold
 
@@ -982,7 +1031,7 @@ module Polars
       if reverse == true || reverse == false
         reverse = [reverse] * exprs.length
       end
-      exprs = Utils.selection_to_rbexpr_list(exprs)
+      exprs = Utils.parse_into_list_of_expressions(exprs)
       Utils.wrap_expr(Plr.arg_sort_by(exprs, reverse))
     end
     alias_method :argsort_by, :arg_sort_by
@@ -1119,8 +1168,8 @@ module Polars
         end
         condition.to_frame.select(arg_where(Polars.col(condition.name))).to_series
       else
-        condition = Utils.expr_to_lit_or_expr(condition, str_to_lit: true)
-        Utils.wrap_expr(Plr.arg_where(condition._rbexpr))
+        condition = Utils.parse_into_expression(condition, str_as_lit: true)
+        Utils.wrap_expr(Plr.arg_where(condition))
       end
     end
 
@@ -1171,7 +1220,7 @@ module Polars
     #   # │ null ┆ null ┆ null ┆ 10.0 │
     #   # └──────┴──────┴──────┴──────┘
     def coalesce(exprs, *more_exprs)
-      exprs = Utils.parse_as_list_of_expressions(exprs, *more_exprs)
+      exprs = Utils.parse_into_list_of_expressions(exprs, *more_exprs)
       Utils.wrap_expr(Plr.coalesce(exprs))
     end
 

data/lib/polars/functions/lit.rb

@@ -7,7 +7,7 @@ module Polars
       if value.is_a?(::Time) || value.is_a?(::DateTime)
         time_unit = dtype&.time_unit || "ns"
         time_zone = dtype.&time_zone
-        e = lit(Utils._datetime_to_pl_timestamp(value, time_unit)).cast(Datetime.new(time_unit))
+        e = lit(Utils.datetime_to_int(value, time_unit)).cast(Datetime.new(time_unit))
         if time_zone
           return e.dt.replace_time_zone(time_zone.to_s)
         else

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

@@ -9,16 +9,11 @@ module Polars
     # @param interval [Object]
     #   Interval periods. It can be a polars duration string, such as `3d12h4m25s`
     #   representing 3 days, 12 hours, 4 minutes, and 25 seconds.
-    # @param lazy [Boolean]
-    #   Return an expression.
     # @param closed ["both", "left", "right", "none"]
     #   Define whether the temporal window interval is closed or not.
-    # @param name [String]
-    #   Name of the output Series.
-    # @param time_unit [nil, "ns", "us", "ms"]
-    #   Set the time unit.
-    # @param time_zone [String]
-    #   Optional timezone
+    # @param eager [Boolean]
+    #   Evaluate immediately and return a `Series`.
+    #   If set to `false` (default), return an expression instead.
     #
     # @return [Object]
     #
@@ -28,73 +23,111 @@ module Polars
     #   type date. All other permutations return a datetime Series.
     #
     # @example Using polars duration string to specify the interval
-    #   Polars.date_range(Date.new(2022, 1, 1), Date.new(2022, 3, 1), "1mo", name: "drange")
+    #   Polars.date_range(Date.new(2022, 1, 1), Date.new(2022, 3, 1), "1mo", eager: true).alias(
+    #     "date"
+    #   )
     #   # =>
     #   # shape: (3,)
-    #   # Series: 'drange' [date]
+    #   # Series: 'date' [date]
     #   # [
     #   #         2022-01-01
     #   #         2022-02-01
     #   #         2022-03-01
     #   # ]
-    #
-    # @example Using `timedelta` object to specify the interval:
-    #   Polars.date_range(
-    #       DateTime.new(1985, 1, 1),
-    #       DateTime.new(1985, 1, 10),
-    #       "1d12h",
-    #       time_unit: "ms"
-    #   )
-    #   # =>
-    #   # shape: (7,)
-    #   # Series: '' [datetime[ms]]
-    #   # [
-    #   #         1985-01-01 00:00:00
-    #   #         1985-01-02 12:00:00
-    #   #         1985-01-04 00:00:00
-    #   #         1985-01-05 12:00:00
-    #   #         1985-01-07 00:00:00
-    #   #         1985-01-08 12:00:00
-    #   #         1985-01-10 00:00:00
-    #   # ]
     def date_range(
       start,
       stop,
-      interval,
-      lazy: false,
+      interval = "1d",
       closed: "both",
-      name: nil,
-      time_unit: nil,
-      time_zone: nil
+      eager: false
     )
-      if defined?(ActiveSupport::Duration) && interval.is_a?(ActiveSupport::Duration)
-        raise Todo
-      else
-        interval = interval.to_s
-        if interval.include?(" ")
-          interval = interval.gsub(" ", "")
-        end
-      end
-
-      if time_unit.nil?
-        if interval.include?("ns")
-          time_unit = "ns"
-        else
-          time_unit = "us"
-        end
-      end
+      interval = Utils.parse_interval_argument(interval)
 
-      start_rbexpr = Utils.parse_as_expression(start)
-      stop_rbexpr = Utils.parse_as_expression(stop)
+      start_rbexpr = Utils.parse_into_expression(start)
+      end_rbexpr = Utils.parse_into_expression(stop)
 
       result = Utils.wrap_expr(
-        Plr.date_range(start_rbexpr, stop_rbexpr, interval, closed, time_unit, time_zone)
+        Plr.date_range(start_rbexpr, end_rbexpr, interval, closed)
       )
 
-      result = result.alias(name.to_s)
+      if eager
+        return F.select(result).to_series
+      end
+
+      result
+    end
+
+    # Create a column of date ranges.
+    #
+    # @param start [Object]
+    #   Lower bound of the date range.
+    # @param stop [Object]
+    #   Upper bound of the date range.
+    # @param interval [Object]
+    #   Interval of the range periods, specified using the Polars duration string language (see "Notes" section below).
+    # @param closed ["both", "left", "right", "none"]
+    #   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.
+    #
+    # @return [Object]
+    #
+    # @note
+    #   `interval` is created according to 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)
+    #
+    #   Or combine them:
+    #   "3d12h4m25s" # 3 days, 12 hours, 4 minutes, and 25 seconds
+    #
+    #   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".
+    #
+    # @example
+    #   df = Polars::DataFrame.new(
+    #     {
+    #       "start" => [Date.new(2022, 1, 1), Date.new(2022, 1, 2)],
+    #       "end" => Date.new(2022, 1, 3)
+    #     }
+    #   )
+    #   df.with_columns(date_range: Polars.date_ranges("start", "end"))
+    #   # =>
+    #   # shape: (2, 3)
+    #   # ┌────────────┬────────────┬─────────────────────────────────┐
+    #   # │ start      ┆ end        ┆ date_range                      │
+    #   # │ ---        ┆ ---        ┆ ---                             │
+    #   # │ date       ┆ date       ┆ list[date]                      │
+    #   # ╞════════════╪════════════╪═════════════════════════════════╡
+    #   # │ 2022-01-01 ┆ 2022-01-03 ┆ [2022-01-01, 2022-01-02, 2022-… │
+    #   # │ 2022-01-02 ┆ 2022-01-03 ┆ [2022-01-02, 2022-01-03]        │
+    #   # └────────────┴────────────┴─────────────────────────────────┘
+    def date_ranges(
+      start,
+      stop,
+      interval = "1d",
+      closed: "both",
+      eager: false
+    )
+      interval = Utils.parse_interval_argument(interval)
+      start_rbexpr = Utils.parse_into_expression(start)
+      end_rbexpr = Utils.parse_into_expression(stop)
+
+      result = Utils.wrap_expr(Plr.date_ranges(start_rbexpr, end_rbexpr, interval, closed))
 
-      if !lazy
-        return select(result).to_series
+      if eager
+        return F.select(result).to_series
       end
 
       result