polars-df 0.15.0 → 0.26.0

data/lib/polars/dynamic_group_by.rb

@@ -4,17 +4,19 @@ module Polars
   # This has an `.agg` method which allows you to run all polars expressions in a
   # group by context.
   class DynamicGroupBy
+    # @private
     def initialize(
       df,
       index_column,
       every,
       period,
       offset,
-      truncate,
       include_boundaries,
       closed,
-      by,
-      start_by
+      label,
+      group_by,
+      start_by,
+      predicates
     )
       period = Utils.parse_as_duration_string(period)
       offset = Utils.parse_as_duration_string(offset)
@@ -25,28 +27,118 @@ module Polars
       @every = every
       @period = period
       @offset = offset
-      @truncate = truncate
       @include_boundaries = include_boundaries
       @closed = closed
-      @by = by
+      @label = label
+      @group_by = group_by
       @start_by = start_by
+      @predicates = predicates
     end
 
+    # Filter groups with a list of predicates after aggregation.
+    #
+    # Using this method is equivalent to adding the predicates to the aggregation and
+    # filtering afterwards.
+    #
+    # This method can be chained and all conditions will be combined using `&`.
+    #
+    # @param predicates [Array]
+    #   Expressions that evaluate to a boolean value for each group. Typically, this
+    #   requires the use of an aggregation function. Multiple predicates are
+    #   combined using `&`.
+    #
+    # @return [DynamicGroupBy]
+    def having(*predicates)
+      DynamicGroupBy.new(
+        @df,
+        @time_column,
+        @every,
+        @period,
+        @offset,
+        @include_boundaries,
+        @closed,
+        @label,
+        @group_by,
+        @start_by,
+        Utils._chain_predicates(@predicates, predicates)
+      )
+    end
+
+    # 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 [DataFrame]
     def agg(*aggs, **named_aggs)
+      group_by =
+        @df.lazy.group_by_dynamic(
+          @time_column,
+          every: @every,
+          period: @period,
+          offset: @offset,
+          include_boundaries: @include_boundaries,
+          closed: @closed,
+          label: @label,
+          group_by: @group_by,
+          start_by: @start_by
+        )
+
+      if @predicates&.any?
+        group_by = group_by.having(@predicates)
+      end
+
+      group_by.agg(*aggs, **named_aggs).collect(
+        optimizations: QueryOptFlags.none
+      )
+    end
+
+    # Apply a custom/user-defined function (UDF) over the groups as a new DataFrame.
+    #
+    # Using this is considered an anti-pattern as it will be very slow because:
+    #
+    # - it forces the engine to materialize the whole `DataFrames` for the groups.
+    # - it is not parallelized.
+    # - it blocks optimizations as the passed python function is opaque to the
+    #   optimizer.
+    #
+    # The idiomatic way to apply custom functions over multiple columns is using:
+    #
+    # `Polars.struct([my_columns]).map_elements { |struct_series| ... }`
+    #
+    # @param schema [Object]
+    #   Schema of the output function. This has to be known statically. If the
+    #   given schema is incorrect, this is a bug in the caller's query and may
+    #   lead to errors. If set to None, polars assumes the schema is unchanged.
+    #
+    # @return [DataFrame]
+    def map_groups(
+      schema,
+      &function
+    )
+      if @predicates&.any?
+        msg = "cannot call `map_groups` when filtering groups with `having`"
+        raise TypeError, msg
+      end
+
       @df.lazy
         .group_by_dynamic(
-          @time_column,
+          index_column: @time_column,
           every: @every,
           period: @period,
           offset: @offset,
-          truncate: @truncate,
           include_boundaries: @include_boundaries,
           closed: @closed,
-          by: @by,
+          group_by: @group_by,
           start_by: @start_by
         )
-        .agg(*aggs, **named_aggs)
-        .collect(no_optimization: true, string_cache: false)
+        .map_groups(schema, &function)
+        .collect(optimizations: QueryOptFlags.none)
     end
   end
 end

data/lib/polars/exceptions.rb

@@ -3,13 +3,61 @@ module Polars
   # Base class for all Polars errors.
   class Error < StandardError; end
 
+  # @private
+  # Exception raised when a specified column is not found.
+  class ColumnNotFoundError < Error; end
+
+  # @private
+  # Exception raised when Polars could not perform an underlying computation.
+  class ComputeError < Error; end
+
+  # @private
+  # Exception raised when a column name is duplicated.
+  class DuplicateError < Error; end
+
   # @private
   # Exception raised when an operation is not allowed (or possible) against a given object or data structure.
   class InvalidOperationError < Error; end
 
   # @private
-  # Exception raised when an unsupported testing assert is made.
-  class InvalidAssert < Error; end
+  # Exception raised when an operation cannot be performed on an empty data structure.
+  class NoDataError < Error; end
+
+  # @private
+  # Exception raised when the given index is out of bounds.
+  class OutOfBoundsError < Error; end
+
+  # @private
+  # Exception raised when an unexpected state causes a panic in the underlying Rust library.
+  class PanicException < Error; end
+
+  # @private
+  # Exception raised when an unexpected schema mismatch causes an error.
+  class SchemaError < Error; end
+
+  # @private
+  # Exception raised when a specified schema field is not found.
+  class SchemaFieldNotFoundError < Error; end
+
+  # @private
+  # Exception raised when trying to perform operations on data structures with incompatible shapes.
+  class ShapeError < Error; end
+
+  # @private
+  # Exception raised when an error occurs in the SQL interface.
+  class SQLInterfaceError < Error; end
+
+  # @private
+  # Exception raised from the SQL interface when encountering invalid syntax.
+  class SQLSyntaxError < Error; end
+
+  # @private
+  # Exception raised when string caches come from different sources.
+  class StringCacheMismatchError < Error; end
+
+  # @private
+  # Exception raised when a specified Struct field is not found.
+  class StructFieldNotFoundError < Error; end
 
   # @private
   # Exception raised when the number of returned rows does not match expectation.
@@ -26,9 +74,6 @@ module Polars
   # @private
   class AssertionError < Error; end
 
-  # @private
-  class ComputeError < Error; end
-
   # @private
   class Todo < Error
     def message