polars-df 0.10.0-x86_64-linux → 0.12.0-x86_64-linux

data/lib/polars/lazy_group_by.rb

@@ -6,11 +6,108 @@ module Polars
       @lgb = lgb
     end
 
-    # Describe the aggregation that need to be done on a group.
+    # Compute aggregations for each group of a group by operation.
+    #
+    # @param aggs [Array]
+    #   Aggregations to compute for each group of the group by operation,
+    #   specified as positional arguments.
+    #   Accepts expression input. Strings are parsed as column names.
+    # @param named_aggs [Hash]
+    #   Additional aggregations, specified as keyword arguments.
+    #   The resulting columns will be renamed to the keyword used.
     #
     # @return [LazyFrame]
-    def agg(aggs)
-      rbexprs = Utils.selection_to_rbexpr_list(aggs)
+    #
+    # @example Compute the aggregation of the columns for each group.
+    #   ldf = Polars::DataFrame.new(
+    #     {
+    #       "a" => ["a", "b", "a", "b", "c"],
+    #       "b" => [1, 2, 1, 3, 3],
+    #       "c" => [5, 4, 3, 2, 1]
+    #     }
+    #   ).lazy
+    #   ldf.group_by("a").agg(
+    #     [Polars.col("b"), Polars.col("c")]
+    #   ).collect
+    #   # =>
+    #   # shape: (3, 3)
+    #   # ┌─────┬───────────┬───────────┐
+    #   # │ a   ┆ b         ┆ c         │
+    #   # │ --- ┆ ---       ┆ ---       │
+    #   # │ str ┆ list[i64] ┆ list[i64] │
+    #   # ╞═════╪═══════════╪═══════════╡
+    #   # │ a   ┆ [1, 1]    ┆ [5, 3]    │
+    #   # │ b   ┆ [2, 3]    ┆ [4, 2]    │
+    #   # │ c   ┆ [3]       ┆ [1]       │
+    #   # └─────┴───────────┴───────────┘
+    #
+    # @example Compute the sum of a column for each group.
+    #   ldf.group_by("a").agg(
+    #     Polars.col("b").sum
+    #   ).collect
+    #   # =>
+    #   # shape: (3, 2)
+    #   # ┌─────┬─────┐
+    #   # │ a   ┆ b   │
+    #   # │ --- ┆ --- │
+    #   # │ str ┆ i64 │
+    #   # ╞═════╪═════╡
+    #   # │ a   ┆ 2   │
+    #   # │ b   ┆ 5   │
+    #   # │ c   ┆ 3   │
+    #   # └─────┴─────┘
+    #
+    # @example Compute multiple aggregates at once by passing a list of expressions.
+    #   ldf.group_by("a").agg(
+    #     [Polars.sum("b"), Polars.mean("c")]
+    #   ).collect
+    #   # =>
+    #   # shape: (3, 3)
+    #   # ┌─────┬─────┬─────┐
+    #   # │ a   ┆ b   ┆ c   │
+    #   # │ --- ┆ --- ┆ --- │
+    #   # │ str ┆ i64 ┆ f64 │
+    #   # ╞═════╪═════╪═════╡
+    #   # │ c   ┆ 3   ┆ 1.0 │
+    #   # │ a   ┆ 2   ┆ 4.0 │
+    #   # │ b   ┆ 5   ┆ 3.0 │
+    #   # └─────┴─────┴─────┘
+    #
+    # @example Or use positional arguments to compute multiple aggregations in the same way.
+    #   ldf.group_by("a").agg(
+    #     Polars.sum("b").name.suffix("_sum"),
+    #     (Polars.col("c") ** 2).mean.name.suffix("_mean_squared")
+    #   ).collect
+    #   # =>
+    #   # shape: (3, 3)
+    #   # ┌─────┬───────┬────────────────┐
+    #   # │ a   ┆ b_sum ┆ c_mean_squared │
+    #   # │ --- ┆ ---   ┆ ---            │
+    #   # │ str ┆ i64   ┆ f64            │
+    #   # ╞═════╪═══════╪════════════════╡
+    #   # │ a   ┆ 2     ┆ 17.0           │
+    #   # │ c   ┆ 3     ┆ 1.0            │
+    #   # │ b   ┆ 5     ┆ 10.0           │
+    #   # └─────┴───────┴────────────────┘
+    #
+    # @example Use keyword arguments to easily name your expression inputs.
+    #   ldf.group_by("a").agg(
+    #     b_sum: Polars.sum("b"),
+    #     c_mean_squared: (Polars.col("c") ** 2).mean
+    #   ).collect
+    #   # =>
+    #   # shape: (3, 3)
+    #   # ┌─────┬───────┬────────────────┐
+    #   # │ a   ┆ b_sum ┆ c_mean_squared │
+    #   # │ --- ┆ ---   ┆ ---            │
+    #   # │ str ┆ i64   ┆ f64            │
+    #   # ╞═════╪═══════╪════════════════╡
+    #   # │ a   ┆ 2     ┆ 17.0           │
+    #   # │ c   ┆ 3     ┆ 1.0            │
+    #   # │ b   ┆ 5     ┆ 10.0           │
+    #   # └─────┴───────┴────────────────┘
+    def agg(*aggs, **named_aggs)
+      rbexprs = Utils.parse_into_list_of_expressions(*aggs, **named_aggs)
       Utils.wrap_ldf(@lgb.agg(rbexprs))
     end
 

data/lib/polars/list_expr.rb

@@ -146,7 +146,7 @@ module Polars
       end
 
       if !fraction.nil?
-        fraction = Utils.parse_as_expression(fraction)
+        fraction = Utils.parse_into_expression(fraction)
         return Utils.wrap_expr(
           _rbexpr.list_sample_fraction(
             fraction, with_replacement, shuffle, seed
@@ -155,7 +155,7 @@ module Polars
       end
 
       n = 1 if n.nil?
-      n = Utils.parse_as_expression(n)
+      n = Utils.parse_into_expression(n)
       Utils.wrap_expr(_rbexpr.list_sample_n(n, with_replacement, shuffle, seed))
     end
 
@@ -387,7 +387,7 @@ module Polars
     #   # │ 1    │
     #   # └──────┘
     def get(index, null_on_oob: true)
-      index = Utils.parse_as_expression(index)
+      index = Utils.parse_into_expression(index)
       Utils.wrap_expr(_rbexpr.list_get(index, null_on_oob))
     end
 
@@ -431,7 +431,7 @@ module Polars
       if index.is_a?(::Array)
         index = Series.new(index)
       end
-      index = Utils.expr_to_lit_or_expr(index, str_to_lit: false)._rbexpr
+      index = Utils.parse_into_expression(index, str_as_lit: false)
       Utils.wrap_expr(_rbexpr.list_gather(index, null_on_oob))
     end
     alias_method :take, :gather
@@ -502,7 +502,7 @@ module Polars
     #   # │ true  │
     #   # └───────┘
     def contains(item)
-      Utils.wrap_expr(_rbexpr.list_contains(Utils.expr_to_lit_or_expr(item)._rbexpr))
+      Utils.wrap_expr(_rbexpr.list_contains(Utils.parse_into_expression(item)))
     end
 
     # Join all string items in a sublist and place a separator between them.
@@ -530,7 +530,7 @@ module Polars
     #   # │ x y   │
     #   # └───────┘
     def join(separator, ignore_nulls: true)
-      separator = Utils.parse_as_expression(separator, str_as_lit: true)
+      separator = Utils.parse_into_expression(separator, str_as_lit: true)
       Utils.wrap_expr(_rbexpr.list_join(separator, ignore_nulls))
     end
 
@@ -625,7 +625,7 @@ module Polars
     #   #         [null, 10, 2]
     #   # ]
     def shift(n = 1)
-      n = Utils.parse_as_expression(n)
+      n = Utils.parse_into_expression(n)
       Utils.wrap_expr(_rbexpr.list_shift(n))
     end
 
@@ -650,8 +650,8 @@ module Polars
     #   #         [2, 1]
     #   # ]
     def slice(offset, length = nil)
-      offset = Utils.expr_to_lit_or_expr(offset, str_to_lit: false)._rbexpr
-      length = Utils.expr_to_lit_or_expr(length, str_to_lit: false)._rbexpr
+      offset = Utils.parse_into_expression(offset, str_as_lit: false)
+      length = Utils.parse_into_expression(length, str_as_lit: false)
       Utils.wrap_expr(_rbexpr.list_slice(offset, length))
     end
 
@@ -694,7 +694,7 @@ module Polars
     #   #         [2, 1]
     #   # ]
     def tail(n = 5)
-      n = Utils.parse_as_expression(n)
+      n = Utils.parse_into_expression(n)
       Utils.wrap_expr(_rbexpr.list_tail(n))
     end
 
@@ -722,7 +722,7 @@ module Polars
     #   # │ 0              │
     #   # └────────────────┘
     def count_matches(element)
-      Utils.wrap_expr(_rbexpr.list_count_matches(Utils.expr_to_lit_or_expr(element)._rbexpr))
+      Utils.wrap_expr(_rbexpr.list_count_matches(Utils.parse_into_expression(element)))
     end
     alias_method :count_match, :count_matches
 

data/lib/polars/list_name_space.rb

@@ -197,9 +197,13 @@ module Polars
     #
     # @param index [Integer]
     #   Index to return per sublist
+    # @param null_on_oob [Boolean]
+    #   Behavior if an index is out of bounds:
+    #   true -> set as null
+    #   false -> raise an error
     #
     # @return [Series]
-    def get(index)
+    def get(index, null_on_oob: false)
       super
     end
 

data/lib/polars/rolling_group_by.rb

@@ -10,27 +10,25 @@ module Polars
       period,
       offset,
       closed,
-      by,
-      check_sorted
+      group_by
     )
-      period = Utils._timedelta_to_pl_duration(period)
-      offset = Utils._timedelta_to_pl_duration(offset)
+      period = Utils.parse_as_duration_string(period)
+      offset = Utils.parse_as_duration_string(offset)
 
       @df = df
       @time_column = index_column
       @period = period
       @offset = offset
       @closed = closed
-      @by = by
-      @check_sorted = check_sorted
+      @group_by = group_by
     end
 
-    def agg(aggs)
+    def agg(*aggs, **named_aggs)
       @df.lazy
         .group_by_rolling(
-          index_column: @time_column, period: @period, offset: @offset, closed: @closed, by: @by, check_sorted: @check_sorted
+          index_column: @time_column, period: @period, offset: @offset, closed: @closed, by: @group_by
         )
-        .agg(aggs)
+        .agg(*aggs, **named_aggs)
         .collect(no_optimization: true, string_cache: false)
     end
   end