polars-df 0.8.0 → 0.9.0

data/lib/polars/series.rb

@@ -214,6 +214,126 @@ module Polars
       _comp(other, :lt_eq)
     end
 
+    # Method equivalent of operator expression `series <= other`.
+    #
+    # @return [Series]
+    def le(other)
+      self <= other
+    end
+
+    # Method equivalent of operator expression `series < other`.
+    #
+    # @return [Series]
+    def lt(other)
+      self < other
+    end
+
+    # Method equivalent of operator expression `series == other`.
+    #
+    # @return [Series]
+    def eq(other)
+      self == other
+    end
+
+    # Method equivalent of equality operator `series == other` where `nil == nil`.
+    #
+    # This differs from the standard `ne` where null values are propagated.
+    #
+    # @param other [Object]
+    #   A literal or expression value to compare with.
+    #
+    # @return [Object]
+    #
+    # @example
+    #   s1 = Polars::Series.new("a", [333, 200, nil])
+    #   s2 = Polars::Series.new("a", [100, 200, nil])
+    #   s1.eq(s2)
+    #   # =>
+    #   # shape: (3,)
+    #   # Series: 'a' [bool]
+    #   # [
+    #   #         false
+    #   #         true
+    #   #         null
+    #   # ]
+    #
+    # @example
+    #   s1.eq_missing(s2)
+    #   # =>
+    #   # shape: (3,)
+    #   # Series: 'a' [bool]
+    #   # [
+    #   #         false
+    #   #         true
+    #   #         true
+    #   # ]
+    def eq_missing(other)
+      if other.is_a?(Expr)
+        return Polars.lit(self).eq_missing(other)
+      end
+      to_frame.select(Polars.col(name).eq_missing(other)).to_series
+    end
+
+    # Method equivalent of operator expression `series != other`.
+    #
+    # @return [Series]
+    def ne(other)
+      self != other
+    end
+
+    # Method equivalent of equality operator `series != other` where `None == None`.
+    #
+    # This differs from the standard `ne` where null values are propagated.
+    #
+    # @param other [Object]
+    #   A literal or expression value to compare with.
+    #
+    # @return [Object]
+    #
+    # @example
+    #   s1 = Polars::Series.new("a", [333, 200, nil])
+    #   s2 = Polars::Series.new("a", [100, 200, nil])
+    #   s1.ne(s2)
+    #   # =>
+    #   # shape: (3,)
+    #   # Series: 'a' [bool]
+    #   # [
+    #   #         true
+    #   #         false
+    #   #         null
+    #   # ]
+    #
+    # @example
+    #   s1.ne_missing(s2)
+    #   # =>
+    #   # shape: (3,)
+    #   # Series: 'a' [bool]
+    #   # [
+    #   #         true
+    #   #         false
+    #   #         false
+    #   # ]
+    def ne_missing(other)
+      if other.is_a?(Expr)
+        return Polars.lit(self).ne_missing(other)
+      end
+      to_frame.select(Polars.col(name).ne_missing(other)).to_series
+    end
+
+    # Method equivalent of operator expression `series >= other`.
+    #
+    # @return [Series]
+    def ge(other)
+      self >= other
+    end
+
+    # Method equivalent of operator expression `series > other`.
+    #
+    # @return [Series]
+    def gt(other)
+      self > other
+    end
+
     # Performs addition.
     #
     # @return [Series]
@@ -411,11 +531,11 @@ module Polars
     # Check if any boolean value in the column is `true`.
     #
     # @return [Boolean]
-    def any?(&block)
+    def any?(ignore_nulls: true, &block)
       if block_given?
-        apply(&block).any?
+        apply(skip_nulls: ignore_nulls, &block).any?
       else
-        to_frame.select(Polars.col(name).any).to_series[0]
+        _s.any(ignore_nulls)
       end
     end
     alias_method :any, :any?
@@ -423,11 +543,11 @@ module Polars
     # Check if all boolean values in the column are `true`.
     #
     # @return [Boolean]
-    def all?(&block)
+    def all?(ignore_nulls: true, &block)
       if block_given?
-        apply(&block).all?
+        apply(skip_nulls: ignore_nulls, &block).all?
       else
-        to_frame.select(Polars.col(name).all).to_series[0]
+        _s.all(ignore_nulls)
       end
     end
     alias_method :all, :all?
@@ -923,7 +1043,7 @@ module Polars
     #
     # @example
     #   s = Polars::Series.new("s", [1, 1, 2, 1, nil, 1, 3, 3])
-    #   s.rle_id()
+    #   s.rle_id
     #   # =>
     #   # shape: (8,)
     #   # Series: 's' [u32]
@@ -1135,7 +1255,7 @@ module Polars
     #
     # @example
     #   s = Polars::Series.new("a", [1, 2, 3])
-    #   s.cumsum
+    #   s.cum_sum
     #   # =>
     #   # shape: (3,)
     #   # Series: 'a' [i64]
@@ -1144,9 +1264,10 @@ module Polars
     #   #         3
     #   #         6
     #   # ]
-    def cumsum(reverse: false)
+    def cum_sum(reverse: false)
       super
     end
+    alias_method :cumsum, :cum_sum
 
     # Get an array with the cumulative min computed at every element.
     #
@@ -1157,7 +1278,7 @@ module Polars
     #
     # @example
     #   s = Polars::Series.new("a", [3, 5, 1])
-    #   s.cummin
+    #   s.cum_min
     #   # =>
     #   # shape: (3,)
     #   # Series: 'a' [i64]
@@ -1166,9 +1287,10 @@ module Polars
     #   #         3
     #   #         1
     #   # ]
-    def cummin(reverse: false)
+    def cum_min(reverse: false)
       super
     end
+    alias_method :cummin, :cum_min
 
     # Get an array with the cumulative max computed at every element.
     #
@@ -1179,7 +1301,7 @@ module Polars
     #
     # @example
     #   s = Polars::Series.new("a", [3, 5, 1])
-    #   s.cummax
+    #   s.cum_max
     #   # =>
     #   # shape: (3,)
     #   # Series: 'a' [i64]
@@ -1188,9 +1310,10 @@ module Polars
     #   #         5
     #   #         5
     #   # ]
-    def cummax(reverse: false)
+    def cum_max(reverse: false)
       super
     end
+    alias_method :cummax, :cum_max
 
     # Get an array with the cumulative product computed at every element.
     #
@@ -1205,7 +1328,7 @@ module Polars
     #
     # @example
     #   s = Polars::Series.new("a", [1, 2, 3])
-    #   s.cumprod
+    #   s.cum_prod
     #   # =>
     #   # shape: (3,)
     #   # Series: 'a' [i64]
@@ -1214,9 +1337,10 @@ module Polars
     #   #         2
     #   #         6
     #   # ]
-    def cumprod(reverse: false)
+    def cum_prod(reverse: false)
       super
     end
+    alias_method :cumprod, :cum_prod
 
     # Get the first `n` rows.
     #
@@ -1443,12 +1567,12 @@ module Polars
     #   #         2
     #   #         1
     #   # ]
-    def sort(reverse: false, in_place: false)
+    def sort(reverse: false, nulls_last: false, in_place: false)
       if in_place
-        self._s = _s.sort(reverse)
+        self._s = _s.sort(reverse, nulls_last)
         self
       else
-        Utils.wrap_s(_s.sort(reverse))
+        Utils.wrap_s(_s.sort(reverse, nulls_last))
       end
     end
 
@@ -1957,11 +2081,9 @@ module Polars
     # @example
     #   s = Polars::Series.new("a", [1, 2, nil])
     #   s.count
-    #   # => 3
+    #   # => 2
     def count
-      warn "`Series#count` will exclude null values in 0.9.0. Use `Series#length` instead."
-      # len - null_count
-      len
+      len - null_count
     end
 
     # Return the number of elements in the Series.
@@ -2170,7 +2292,7 @@ module Polars
             Int64 => Numo::Int64,
             Float32 => Numo::SFloat,
             Float64 => Numo::DFloat
-          }.fetch(dtype).cast(to_a)
+          }.fetch(dtype.class).cast(to_a)
         elsif is_boolean
           Numo::Bit.cast(to_a)
         else
@@ -2209,7 +2331,7 @@ module Polars
     #   #         3
     #   # ]
     def set(filter, value)
-      Utils.wrap_s(_s.send("set_with_mask_#{DTYPE_TO_FFINAME.fetch(dtype)}", filter._s, value))
+      Utils.wrap_s(_s.send("set_with_mask_#{DTYPE_TO_FFINAME.fetch(dtype.class)}", filter._s, value))
     end
 
     # Set values at the index locations.
@@ -2735,7 +2857,7 @@ module Polars
     #
     # @example
     #   s = Polars::Series.new("a", [1, 2, 3])
-    #   s.apply { |x| x + 10 }
+    #   s.map_elements { |x| x + 10 }
     #   # =>
     #   # shape: (3,)
     #   # Series: 'a' [i64]
@@ -2744,7 +2866,7 @@ module Polars
     #   #         12
     #   #         13
     #   # ]
-    def apply(return_dtype: nil, skip_nulls: true, &func)
+    def map_elements(return_dtype: nil, skip_nulls: true, &func)
       if return_dtype.nil?
         pl_return_dtype = nil
       else
@@ -2752,7 +2874,8 @@ module Polars
       end
       Utils.wrap_s(_s.apply_lambda(func, pl_return_dtype, skip_nulls))
     end
-    alias_method :map, :apply
+    alias_method :map, :map_elements
+    alias_method :apply, :map_elements
 
     # Shift the values by a given period.
     #
@@ -3335,8 +3458,8 @@ module Polars
     #   # shape: (2,)
     #   # Series: 'a' [i64]
     #   # [
-    #   #     1
-    #   #     5
+    #   #         5
+    #   #         3
     #   # ]
     def sample(
       n: nil,
@@ -3715,6 +3838,113 @@ module Polars
       super
     end
 
+    # Replace values by different values.
+    #
+    # @param old [Object]
+    #   Value or sequence of values to replace.
+    #   Also accepts a mapping of values to their replacement.
+    # @param new [Object]
+    #   Value or sequence of values to replace by.
+    #   Length must match the length of `old` or have length 1.
+    # @param default [Object]
+    #   Set values that were not replaced to this value.
+    #   Defaults to keeping the original value.
+    #   Accepts expression input. Non-expression inputs are parsed as literals.
+    # @param return_dtype [Object]
+    #   The data type of the resulting Series. If set to `nil` (default),
+    #   the data type is determined automatically based on the other inputs.
+    #
+    # @return [Series]
+    #
+    # @example Replace a single value by another value. Values that were not replaced remain unchanged.
+    #   s = Polars::Series.new([1, 2, 2, 3])
+    #   s.replace(2, 100)
+    #   # =>
+    #   # shape: (4,)
+    #   # Series: '' [i64]
+    #   # [
+    #   #         1
+    #   #         100
+    #   #         100
+    #   #         3
+    #   # ]
+    #
+    # @example Replace multiple values by passing sequences to the `old` and `new` parameters.
+    #   s.replace([2, 3], [100, 200])
+    #   # =>
+    #   # shape: (4,)
+    #   # Series: '' [i64]
+    #   # [
+    #   #         1
+    #   #         100
+    #   #         100
+    #   #         200
+    #   # ]
+    #
+    # @example Passing a mapping with replacements is also supported as syntactic sugar. Specify a default to set all values that were not matched.
+    #   mapping = {2 => 100, 3 => 200}
+    #   s.replace(mapping, default: -1)
+    #   # =>
+    #   # shape: (4,)
+    #   # Series: '' [i64]
+    #   # [
+    #   #         -1
+    #   #         100
+    #   #         100
+    #   #         200
+    #   # ]
+    #
+    # @example The default can be another Series.
+    #   default = Polars::Series.new([2.5, 5.0, 7.5, 10.0])
+    #   s.replace(2, 100, default: default)
+    #   # =>
+    #   # shape: (4,)
+    #   # Series: '' [f64]
+    #   # [
+    #   #         2.5
+    #   #         100.0
+    #   #         100.0
+    #   #         10.0
+    #   # ]
+    #
+    # @example Replacing by values of a different data type sets the return type based on a combination of the `new` data type and either the original data type or the default data type if it was set.
+    #   s = Polars::Series.new(["x", "y", "z"])
+    #   mapping = {"x" => 1, "y" => 2, "z" => 3}
+    #   s.replace(mapping)
+    #   # =>
+    #   # shape: (3,)
+    #   # Series: '' [str]
+    #   # [
+    #   #         "1"
+    #   #         "2"
+    #   #         "3"
+    #   # ]
+    #
+    # @example
+    #   s.replace(mapping, default: nil)
+    #   # =>
+    #   # shape: (3,)
+    #   # Series: '' [i64]
+    #   # [
+    #   #         1
+    #   #         2
+    #   #         3
+    #   # ]
+    #
+    # @example Set the `return_dtype` parameter to control the resulting data type directly.
+    #   s.replace(mapping, return_dtype: Polars::UInt8)
+    #   # =>
+    #   # shape: (3,)
+    #   # Series: '' [u8]
+    #   # [
+    #   #         1
+    #   #         2
+    #   #         3
+    #   # ]
+    def replace(old, new = Expr::NO_DEFAULT, default: Expr::NO_DEFAULT, return_dtype: nil)
+      super
+    end
+
     # Reshape this Series to a flat Series or a Series of Lists.
     #
     # @param dims [Array]
@@ -3924,7 +4154,7 @@ module Polars
     end
 
     def _pos_idxs(idxs)
-      idx_type = Polars._get_idx_type
+      idx_type = Plr.get_index_type
 
       if idxs.is_a?(Series)
         if idxs.dtype == idx_type
@@ -4009,7 +4239,7 @@ module Polars
     end
 
     def ffi_func(name, dtype, _s)
-      _s.method(name.sub("<>", DTYPE_TO_FFINAME.fetch(dtype))) if DTYPE_TO_FFINAME.key?(dtype)
+      _s.method(name.sub("<>", DTYPE_TO_FFINAME.fetch(dtype.class))) if DTYPE_TO_FFINAME.key?(dtype.class)
     end
 
     def _arithmetic(other, op)
@@ -4124,21 +4354,29 @@ module Polars
         end
       end
 
-      if !dtype.nil? && ![List, Unknown].include?(dtype) && Utils.is_polars_dtype(dtype) && ruby_dtype.nil?
+      if !dtype.nil? && ![List, Struct, Unknown].include?(dtype) && Utils.is_polars_dtype(dtype) && ruby_dtype.nil?
         if dtype == Array && !dtype.is_a?(Array) && value.is_a?(::Array)
-          dtype = Array.new(value.size)
+          dtype = Array.new(nil, value.size)
         end
 
         constructor = polars_type_to_constructor(dtype)
         rbseries = constructor.call(name, values, strict)
 
         base_type = dtype.is_a?(DataType) ? dtype.class : dtype
-        if [Date, Datetime, Duration, Time, Categorical, Boolean].include?(base_type)
+        if [Date, Datetime, Duration, Time, Categorical, Boolean, Enum].include?(base_type)
           if rbseries.dtype != dtype
             rbseries = rbseries.cast(dtype, true)
           end
         end
         return rbseries
+      elsif dtype == Struct
+        struct_schema = dtype.is_a?(Struct) ? dtype.to_schema : nil
+        empty = {}
+        return DataFrame.sequence_to_rbdf(
+          values.map { |v| v.nil? ? empty : v },
+          schema: struct_schema,
+          orient: "row",
+        ).to_struct(name)
       else
         if ruby_dtype.nil?
           if value.nil?
@@ -4229,6 +4467,7 @@ module Polars
       Utf8 => RbSeries.method(:new_str),
       Object => RbSeries.method(:new_object),
       Categorical => RbSeries.method(:new_str),
+      Enum => RbSeries.method(:new_str),
       Binary => RbSeries.method(:new_binary),
       Null => RbSeries.method(:new_null)
     }

data/lib/polars/string_cache.rb

@@ -0,0 +1,75 @@
+module Polars
+  # Context manager for enabling and disabling the global string cache.
+  class StringCache
+    def initialize(&block)
+      RbStringCacheHolder.hold(&block)
+    end
+  end
+
+  module Functions
+    # Enable the global string cache.
+    #
+    # `Categorical` columns created under the same global string cache have
+    # the same underlying physical value when string values are equal. This allows the
+    # columns to be concatenated or used in a join operation, for example.
+    #
+    # @return [nil]
+    #
+    # @example Construct two Series using the same global string cache.
+    #   Polars.enable_string_cache
+    #   s1 = Polars::Series.new("color", ["red", "green", "red"], dtype: Polars::Categorical)
+    #   s2 = Polars::Series.new("color", ["blue", "red", "green"], dtype: Polars::Categorical)
+    #   Polars.disable_string_cache
+    #
+    # @example As both Series are constructed under the same global string cache, they can be concatenated.
+    #   Polars.concat([s1, s2])
+    #   # =>
+    #   # shape: (6,)
+    #   # Series: 'color' [cat]
+    #   # [
+    #   #         "red"
+    #   #         "green"
+    #   #         "red"
+    #   #         "blue"
+    #   #         "red"
+    #   #         "green"
+    #   # ]
+    def enable_string_cache
+      Plr.enable_string_cache
+    end
+
+    # Disable and clear the global string cache.
+    #
+    # @return [nil]
+    #
+    # @example Construct two Series using the same global string cache.
+    #   Polars.enable_string_cache
+    #   s1 = Polars::Series.new("color", ["red", "green", "red"], dtype: Polars::Categorical)
+    #   s2 = Polars::Series.new("color", ["blue", "red", "green"], dtype: Polars::Categorical)
+    #   Polars.disable_string_cache
+    #
+    # @example As both Series are constructed under the same global string cache, they can be concatenated.
+    #   Polars.concat([s1, s2])
+    #   # =>
+    #   # shape: (6,)
+    #   # Series: 'color' [cat]
+    #   # [
+    #   #         "red"
+    #   #         "green"
+    #   #         "red"
+    #   #         "blue"
+    #   #         "red"
+    #   #         "green"
+    #   # ]
+    def disable_string_cache
+      Plr.disable_string_cache
+    end
+
+    # Check whether the global string cache is enabled.
+    #
+    # @return [Boolean]
+    def using_string_cache
+      Plr.using_string_cache
+    end
+  end
+end