polars-df 0.1.4 → 0.2.0

data/lib/polars/data_types.rb

@@ -0,0 +1,122 @@
+module Polars
+  # Base class for all Polars data types.
+  class DataType
+  end
+
+  # 8-bit signed integer type.
+  class Int8 < DataType
+  end
+
+  # 16-bit signed integer type.
+  class Int16 < DataType
+  end
+
+  # 32-bit signed integer type.
+  class Int32 < DataType
+  end
+
+  # 64-bit signed integer type.
+  class Int64 < DataType
+  end
+
+  # 8-bit unsigned integer type.
+  class UInt8 < DataType
+  end
+
+  # 16-bit unsigned integer type.
+  class UInt16 < DataType
+  end
+
+  # 32-bit unsigned integer type.
+  class UInt32 < DataType
+  end
+
+  # 64-bit unsigned integer type.
+  class UInt64 < DataType
+  end
+
+  # 32-bit floating point type.
+  class Float32 < DataType
+  end
+
+  # 64-bit floating point type.
+  class Float64 < DataType
+  end
+
+  # Boolean type.
+  class Boolean < DataType
+  end
+
+  # UTF-8 encoded string type.
+  class Utf8 < DataType
+  end
+
+  # Binary type.
+  class Binary < DataType
+  end
+
+  # Type representing Null / None values.
+  class Null < DataType
+  end
+
+  # Type representing Datatype values that could not be determined statically.
+  class Unknown < DataType
+  end
+
+  # Nested list/array type.
+  class List < DataType
+    def initialize(inner)
+      @inner = Utils.rb_type_to_dtype(inner)
+    end
+  end
+
+  # Calendar date type.
+  class Date < DataType
+  end
+
+  # Calendar date and time type.
+  class Datetime < DataType
+    def initialize(time_unit = "us", time_zone = nil)
+      @tu = time_unit || "us"
+      @time_zone = time_zone
+    end
+  end
+
+  # Time duration/delta type.
+  class Duration < DataType
+    def initialize(time_unit = "us")
+      @tu = time_unit
+    end
+  end
+
+  # Time of day type.
+  class Time < DataType
+  end
+
+  # Type for wrapping arbitrary Python objects.
+  class Object < DataType
+  end
+
+  # A categorical encoding of a set of strings.
+  class Categorical < DataType
+  end
+
+  # Definition of a single field within a `Struct` DataType.
+  class Field < DataType
+    def initialize(name, dtype)
+      @name = name
+      @dtype = Utils.rb_type_to_dtype(dtype)
+    end
+  end
+
+  # Struct composite type.
+  class Struct < DataType
+    def initialize(fields)
+      if fields.is_a?(Hash)
+        @fields = fields.map { |n, d| Field.new(n, d) }
+      else
+        @fields = fields
+      end
+    end
+  end
+end

data/lib/polars/date_time_expr.rb

@@ -465,7 +465,7 @@ module Polars
     #
     # Applies to Date and Datetime columns.
     #
-    # Returns the weekday number where monday = 0 and sunday = 6
+    # Returns the ISO weekday number where monday = 1 and sunday = 7
     #
     # @return [Expr]
     #
@@ -502,11 +502,11 @@ module Polars
     #   # │ ---     ┆ ---          ┆ ---         │
     #   # │ u32     ┆ u32          ┆ u32         │
     #   # ╞═════════╪══════════════╪═════════════╡
-    #   # │ 0       ┆ 1            ┆ 1           │
+    #   # │ 1       ┆ 1            ┆ 1           │
     #   # ├╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌┤
-    #   # │ 3       ┆ 4            ┆ 4           │
+    #   # │ 4       ┆ 4            ┆ 4           │
     #   # ├╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌┤
-    #   # │ 6       ┆ 7            ┆ 7           │
+    #   # │ 7       ┆ 7            ┆ 7           │
     #   # └─────────┴──────────────┴─────────────┘
     def weekday
       Utils.wrap_expr(_rbexpr.weekday)
@@ -554,11 +554,11 @@ module Polars
     #   # │ ---     ┆ ---          ┆ ---         │
     #   # │ u32     ┆ u32          ┆ u32         │
     #   # ╞═════════╪══════════════╪═════════════╡
-    #   # │ 0       ┆ 1            ┆ 1           │
+    #   # │ 1       ┆ 1            ┆ 1           │
     #   # ├╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌┤
-    #   # │ 3       ┆ 4            ┆ 4           │
+    #   # │ 4       ┆ 4            ┆ 4           │
     #   # ├╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌┤
-    #   # │ 6       ┆ 7            ┆ 7           │
+    #   # │ 7       ┆ 7            ┆ 7           │
     #   # └─────────┴──────────────┴─────────────┘
     def day
       Utils.wrap_expr(_rbexpr.day)
@@ -606,11 +606,11 @@ module Polars
     #   # │ ---     ┆ ---          ┆ ---         │
     #   # │ u32     ┆ u32          ┆ u32         │
     #   # ╞═════════╪══════════════╪═════════════╡
-    #   # │ 0       ┆ 1            ┆ 1           │
+    #   # │ 1       ┆ 1            ┆ 1           │
     #   # ├╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌┤
-    #   # │ 3       ┆ 4            ┆ 4           │
+    #   # │ 4       ┆ 4            ┆ 4           │
     #   # ├╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌┤
-    #   # │ 6       ┆ 7            ┆ 7           │
+    #   # │ 7       ┆ 7            ┆ 7           │
     #   # └─────────┴──────────────┴─────────────┘
     def ordinal_day
       Utils.wrap_expr(_rbexpr.ordinal_day)

data/lib/polars/date_time_name_space.rb

@@ -317,7 +317,7 @@ module Polars
     #
     # Applies to Date and Datetime columns.
     #
-    # Returns the weekday number where monday = 0 and sunday = 6
+    # Returns the ISO weekday number where monday = 1 and sunday = 7
     #
     # @return [Series]
     #
@@ -344,13 +344,13 @@ module Polars
     #   # shape: (7,)
     #   # Series: '' [u32]
     #   # [
-    #   #         0
     #   #         1
     #   #         2
     #   #         3
     #   #         4
     #   #         5
     #   #         6
+    #   #         7
     #   # ]
     def weekday
       super
@@ -973,9 +973,9 @@ module Polars
     #   # shape: (3,)
     #   # Series: 'NYC' [datetime[μs, America/New_York]]
     #   # [
-    #   #         2020-02-29 14:00:00 EST
-    #   #         2020-03-31 15:00:00 EDT
-    #   #         2020-04-30 15:00:00 EDT
+    #   #         2020-03-01 00:00:00 EST
+    #   #         2020-04-01 01:00:00 EDT
+    #   #         2020-05-01 01:00:00 EDT
     #   # ]
     #
     # @example Timestamps have changed after cast_time_zone
@@ -984,9 +984,9 @@ module Polars
     #   # shape: (3,)
     #   # Series: 'NYC' [i64]
     #   # [
-    #   #         1583002800
-    #   #         1585681200
-    #   #         1588273200
+    #   #         1583038800
+    #   #         1585717200
+    #   #         1588309200
     #   # ]
     def cast_time_zone(tz)
       super

data/lib/polars/dynamic_group_by.rb

@@ -0,0 +1,52 @@
+module Polars
+  # A dynamic grouper.
+  #
+  # This has an `.agg` method which allows you to run all polars expressions in a
+  # groupby context.
+  class DynamicGroupBy
+    def initialize(
+      df,
+      index_column,
+      every,
+      period,
+      offset,
+      truncate,
+      include_boundaries,
+      closed,
+      by,
+      start_by
+    )
+      period = Utils._timedelta_to_pl_duration(period)
+      offset = Utils._timedelta_to_pl_duration(offset)
+      every = Utils._timedelta_to_pl_duration(every)
+
+      @df = df
+      @time_column = index_column
+      @every = every
+      @period = period
+      @offset = offset
+      @truncate = truncate
+      @include_boundaries = include_boundaries
+      @closed = closed
+      @by = by
+      @start_by = start_by
+    end
+
+    def agg(aggs)
+      @df.lazy
+        .groupby_dynamic(
+          @time_column,
+          every: @every,
+          period: @period,
+          offset: @offset,
+          truncate: @truncate,
+          include_boundaries: @include_boundaries,
+          closed: @closed,
+          by: @by,
+          start_by: @start_by
+        )
+        .agg(aggs)
+        .collect(no_optimization: true, string_cache: false)
+    end
+  end
+end

data/lib/polars/expr.rb

@@ -432,8 +432,34 @@ module Polars
       wrap_expr(_rbexpr.suffix(suffix))
     end
 
-    # def map_alias
-    # end
+    # Rename the output of an expression by mapping a function over the root name.
+    #
+    # @return [Expr]
+    #
+    # @example
+    #   df = Polars::DataFrame.new(
+    #     {
+    #       "A" => [1, 2],
+    #       "B" => [3, 4]
+    #     }
+    #   )
+    #   df.select(
+    #     Polars.all.reverse.map_alias { |colName| colName + "_reverse" }
+    #   )
+    #   # =>
+    #   # shape: (2, 2)
+    #   # ┌───────────┬───────────┐
+    #   # │ A_reverse ┆ B_reverse │
+    #   # │ ---       ┆ ---       │
+    #   # │ i64       ┆ i64       │
+    #   # ╞═══════════╪═══════════╡
+    #   # │ 2         ┆ 4         │
+    #   # ├╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌┤
+    #   # │ 1         ┆ 3         │
+    #   # └───────────┴───────────┘
+    def map_alias(&f)
+      Utils.wrap_expr(_rbexpr.map_alias(f))
+    end
 
     # Negate a boolean expression.
     #
@@ -2460,7 +2486,8 @@ module Polars
     #   # │ 1.5 │
     #   # └─────┘
     def quantile(quantile, interpolation: "nearest")
-      wrap_expr(_rbexpr.quantile(quantile, interpolation))
+      quantile = Utils.expr_to_lit_or_expr(quantile, str_to_lit: false)
+      wrap_expr(_rbexpr.quantile(quantile._rbexpr, interpolation))
     end
 
     # Filter a single column.
@@ -2575,14 +2602,98 @@ module Polars
     #   # ╞══════╪════════╡
     #   # │ 1    ┆ 0      │
     #   # └──────┴────────┘
-    # def map(return_dtype: nil, agg_list: false, &block)
+    # def map(return_dtype: nil, agg_list: false, &f)
     #   if !return_dtype.nil?
     #     return_dtype = Utils.rb_type_to_dtype(return_dtype)
     #   end
-    #   wrap_expr(_rbexpr.map(return_dtype, agg_list, &block))
+    #   wrap_expr(_rbexpr.map(f, return_dtype, agg_list))
     # end
 
-    # def apply
+    # Apply a custom/user-defined function (UDF) in a GroupBy or Projection context.
+    #
+    # Depending on the context it has the following behavior:
+    #
+    # * Selection
+    #     Expects `f` to be of type Callable[[Any], Any].
+    #     Applies a Ruby function over each individual value in the column.
+    # * GroupBy
+    #     Expects `f` to be of type Callable[[Series], Series].
+    #     Applies a Ruby function over each group.
+    #
+    # Implementing logic using a Ruby function is almost always _significantly_
+    # slower and more memory intensive than implementing the same logic using
+    # the native expression API because:
+    #
+    # - The native expression engine runs in Rust; UDFs run in Ruby.
+    # - Use of Ruby UDFs forces the DataFrame to be materialized in memory.
+    # - Polars-native expressions can be parallelised (UDFs cannot).
+    # - Polars-native expressions can be logically optimised (UDFs cannot).
+    #
+    # Wherever possible you should strongly prefer the native expression API
+    # to achieve the best performance.
+    #
+    # @param return_dtype [Symbol]
+    #   Dtype of the output Series.
+    #   If not set, polars will assume that
+    #   the dtype remains unchanged.
+    #
+    # @return [Expr]
+    #
+    # @example
+    #   df = Polars::DataFrame.new(
+    #     {
+    #       "a" => [1, 2, 3, 1],
+    #       "b" => ["a", "b", "c", "c"]
+    #     }
+    #   )
+    #
+    # @example In a selection context, the function is applied by row.
+    #   df.with_column(
+    #     Polars.col("a").apply { |x| x * 2 }.alias("a_times_2")
+    #   )
+    #   # =>
+    #   # shape: (4, 3)
+    #   # ┌─────┬─────┬───────────┐
+    #   # │ a   ┆ b   ┆ a_times_2 │
+    #   # │ --- ┆ --- ┆ ---       │
+    #   # │ i64 ┆ str ┆ i64       │
+    #   # ╞═════╪═════╪═══════════╡
+    #   # │ 1   ┆ a   ┆ 2         │
+    #   # ├╌╌╌╌╌┼╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌┤
+    #   # │ 2   ┆ b   ┆ 4         │
+    #   # ├╌╌╌╌╌┼╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌┤
+    #   # │ 3   ┆ c   ┆ 6         │
+    #   # ├╌╌╌╌╌┼╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌┤
+    #   # │ 1   ┆ c   ┆ 2         │
+    #   # └─────┴─────┴───────────┘
+    #
+    # @example In a GroupBy context the function is applied by group:
+    #   df.lazy
+    #     .groupby("b", maintain_order: true)
+    #     .agg(
+    #       [
+    #         Polars.col("a").apply { |x| x.sum }
+    #       ]
+    #     )
+    #     .collect
+    #   # =>
+    #   # shape: (3, 2)
+    #   # ┌─────┬─────┐
+    #   # │ b   ┆ a   │
+    #   # │ --- ┆ --- │
+    #   # │ str ┆ i64 │
+    #   # ╞═════╪═════╡
+    #   # │ a   ┆ 1   │
+    #   # ├╌╌╌╌╌┼╌╌╌╌╌┤
+    #   # │ b   ┆ 2   │
+    #   # ├╌╌╌╌╌┼╌╌╌╌╌┤
+    #   # │ c   ┆ 4   │
+    #   # └─────┴─────┘
+    # def apply(return_dtype: nil, &f)
+    #   wrap_f = lambda do |x|
+    #     x.apply(return_dtype: return_dtype, &f)
+    #   end
+    #   map(agg_list: true, return_dtype: return_dtype, &wrap_f)
     # end
 
     # Explode a list or utf8 Series. This means that every item is expanded to a new
@@ -2898,8 +3009,49 @@ module Polars
       end
     end
 
-    # def _hash
-    # end
+    # Hash the elements in the selection.
+    #
+    # The hash value is of type `:u64`.
+    #
+    # @param seed [Integer]
+    #   Random seed parameter. Defaults to 0.
+    # @param seed_1 [Integer]
+    #   Random seed parameter. Defaults to `seed` if not set.
+    # @param seed_2 [Integer]
+    #   Random seed parameter. Defaults to `seed` if not set.
+    # @param seed_3 [Integer]
+    #   Random seed parameter. Defaults to `seed` if not set.
+    #
+    # @return [Expr]
+    #
+    # @example
+    #   df = Polars::DataFrame.new(
+    #     {
+    #       "a" => [1, 2, nil],
+    #       "b" => ["x", nil, "z"]
+    #     }
+    #   )
+    #   df.with_column(Polars.all._hash(10, 20, 30, 40))
+    #   # =>
+    #   # shape: (3, 2)
+    #   # ┌──────────────────────┬──────────────────────┐
+    #   # │ a                    ┆ b                    │
+    #   # │ ---                  ┆ ---                  │
+    #   # │ u64                  ┆ u64                  │
+    #   # ╞══════════════════════╪══════════════════════╡
+    #   # │ 4629889412789719550  ┆ 6959506404929392568  │
+    #   # ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
+    #   # │ 16386608652769605760 ┆ 11638928888656214026 │
+    #   # ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
+    #   # │ 11638928888656214026 ┆ 11040941213715918520 │
+    #   # └──────────────────────┴──────────────────────┘
+    def _hash(seed = 0, seed_1 = nil, seed_2 = nil, seed_3 = nil)
+      k0 = seed
+      k1 = seed_1.nil? ? seed : seed_1
+      k2 = seed_2.nil? ? seed : seed_2
+      k3 = seed_3.nil? ? seed : seed_3
+      wrap_expr(_rbexpr._hash(k0, k1, k2, k3))
+    end
 
     # Reinterpret the underlying bits as a signed/unsigned integer.
     #
@@ -2937,7 +3089,40 @@ module Polars
       wrap_expr(_rbexpr.reinterpret(signed))
     end
 
-    # def _inspect
+    # Print the value that this expression evaluates to and pass on the value.
+    #
+    # @return [Expr]
+    #
+    # @example
+    #   df = Polars::DataFrame.new({"foo" => [1, 1, 2]})
+    #   df.select(Polars.col("foo").cumsum._inspect("value is: %s").alias("bar"))
+    #   # =>
+    #   # value is: shape: (3,)
+    #   # Series: 'foo' [i64]
+    #   # [
+    #   #     1
+    #   #     2
+    #   #     4
+    #   # ]
+    #   # shape: (3, 1)
+    #   # ┌─────┐
+    #   # │ bar │
+    #   # │ --- │
+    #   # │ i64 │
+    #   # ╞═════╡
+    #   # │ 1   │
+    #   # ├╌╌╌╌╌┤
+    #   # │ 2   │
+    #   # ├╌╌╌╌╌┤
+    #   # │ 4   │
+    #   # └─────┘
+    # def _inspect(fmt = "%s")
+    #   inspect = lambda do |s|
+    #     puts(fmt % [s])
+    #     s
+    #   end
+
+    #   map(return_dtype: nil, agg_list: true, &inspect)
     # end
 
     # Fill nulls with linear interpolation over missing values.
@@ -2967,8 +3152,8 @@ module Polars
     #   # ├╌╌╌╌╌┼╌╌╌╌╌┤
     #   # │ 3   ┆ 3.0 │
     #   # └─────┴─────┘
-    def interpolate
-      wrap_expr(_rbexpr.interpolate)
+    def interpolate(method: "linear")
+      wrap_expr(_rbexpr.interpolate(method))
     end
 
     # Apply a rolling min (moving min) over the values in this array.
@@ -3721,7 +3906,72 @@ module Polars
       )
     end
 
-    # def rolling_apply
+    # Apply a custom rolling window function.
+    #
+    # Prefer the specific rolling window functions over this one, as they are faster.
+    #
+    # Prefer:
+    # * rolling_min
+    # * rolling_max
+    # * rolling_mean
+    # * rolling_sum
+    #
+    # @param window_size [Integer]
+    #   The length of the window.
+    # @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_periods [Integer]
+    #   The number of values in the window that should be non-null before computing
+    #   a result. If nil, 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" => [1.0, 2.0, 9.0, 2.0, 13.0]
+    #     }
+    #   )
+    #   df.select(
+    #     [
+    #       Polars.col("A").rolling_apply(window_size: 3) { |s| s.std }
+    #     ]
+    #   )
+    #   # =>
+    #   # shape: (5, 1)
+    #   # ┌──────────┐
+    #   # │ A        │
+    #   # │ ---      │
+    #   # │ f64      │
+    #   # ╞══════════╡
+    #   # │ null     │
+    #   # ├╌╌╌╌╌╌╌╌╌╌┤
+    #   # │ null     │
+    #   # ├╌╌╌╌╌╌╌╌╌╌┤
+    #   # │ 4.358899 │
+    #   # ├╌╌╌╌╌╌╌╌╌╌┤
+    #   # │ 4.041452 │
+    #   # ├╌╌╌╌╌╌╌╌╌╌┤
+    #   # │ 5.567764 │
+    #   # └──────────┘
+    # def rolling_apply(
+    #   window_size:,
+    #   weights: nil,
+    #   min_periods: nil,
+    #   center: false,
+    #   &function
+    # )
+    #   if min_periods.nil?
+    #     min_periods = window_size
+    #   end
+    #   wrap_expr(
+    #     _rbexpr.rolling_apply(
+    #       function, window_size, weights, min_periods, center
+    #     )
+    #   )
     # end
 
     # Compute a rolling skew.