polars-df 0.7.0-x86_64-linux → 0.9.0-x86_64-linux

data/lib/polars/series.rb

@@ -34,7 +34,7 @@ module Polars
     #   s3 = Polars::Series.new([1, 2, 3])
     def initialize(name = nil, values = nil, dtype: nil, strict: true, nan_to_null: false, dtype_if_empty: nil)
       # Handle case where values are passed as the first argument
-      if !name.nil? && !name.is_a?(String)
+      if !name.nil? && !name.is_a?(::String)
         if values.nil?
           values = name
           name = nil
@@ -46,7 +46,7 @@ module Polars
       name = "" if name.nil?
 
       # TODO improve
-      if values.is_a?(Range) && values.begin.is_a?(String)
+      if values.is_a?(Range) && values.begin.is_a?(::String)
         values = values.to_a
       end
 
@@ -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]
@@ -341,7 +461,7 @@ module Polars
     def []=(key, value)
       if value.is_a?(::Array)
         if is_numeric || is_datelike
-          set_at_idx(key, value)
+          scatter(key, value)
           return
         end
         raise ArgumentError, "cannot set Series of dtype: #{dtype} with list/tuple as value; use a scalar value"
@@ -351,9 +471,9 @@ module Polars
         if key.dtype == Boolean
           self._s = set(key, value)._s
         elsif key.dtype == UInt64
-          self._s = set_at_idx(key.cast(UInt32), value)._s
+          self._s = scatter(key.cast(UInt32), value)._s
         elsif key.dtype == UInt32
-          self._s = set_at_idx(key, value)._s
+          self._s = scatter(key, value)._s
         else
           raise Todo
         end
@@ -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?
@@ -735,6 +855,212 @@ module Polars
       Utils.wrap_df(_s.to_dummies(separator, drop_first))
     end
 
+    # Bin continuous values into discrete categories.
+    #
+    # @param breaks [Array]
+    #   List of unique cut points.
+    # @param labels [Array]
+    #   Names of the categories. The number of labels must be equal to the number
+    #   of cut points plus one.
+    # @param left_closed [Boolean]
+    #   Set the intervals to be left-closed instead of right-closed.
+    # @param include_breaks [Boolean]
+    #   Include a column with the right endpoint of the bin each observation falls
+    #   in. This will change the data type of the output from a
+    #   `Categorical` to a `Struct`.
+    #
+    # @return [Series]
+    #
+    # @example Divide the column into three categories.
+    #   s = Polars::Series.new("foo", [-2, -1, 0, 1, 2])
+    #   s.cut([-1, 1], labels: ["a", "b", "c"])
+    #   # =>
+    #   # shape: (5,)
+    #   # Series: 'foo' [cat]
+    #   # [
+    #   #         "a"
+    #   #         "a"
+    #   #         "b"
+    #   #         "b"
+    #   #         "c"
+    #   # ]
+    #
+    # @example Create a DataFrame with the breakpoint and category for each value.
+    #   cut = s.cut([-1, 1], include_breaks: true).alias("cut")
+    #   s.to_frame.with_columns(cut).unnest("cut")
+    #   # =>
+    #   # shape: (5, 3)
+    #   # ┌─────┬─────────────┬────────────┐
+    #   # │ foo ┆ break_point ┆ category   │
+    #   # │ --- ┆ ---         ┆ ---        │
+    #   # │ i64 ┆ f64         ┆ cat        │
+    #   # ╞═════╪═════════════╪════════════╡
+    #   # │ -2  ┆ -1.0        ┆ (-inf, -1] │
+    #   # │ -1  ┆ -1.0        ┆ (-inf, -1] │
+    #   # │ 0   ┆ 1.0         ┆ (-1, 1]    │
+    #   # │ 1   ┆ 1.0         ┆ (-1, 1]    │
+    #   # │ 2   ┆ inf         ┆ (1, inf]   │
+    #   # └─────┴─────────────┴────────────┘
+    def cut(breaks, labels: nil, left_closed: false, include_breaks: false)
+      result = (
+        to_frame
+        .select(
+          Polars.col(name).cut(
+            breaks,
+            labels: labels,
+            left_closed: left_closed,
+            include_breaks: include_breaks
+          )
+        )
+        .to_series
+      )
+
+      if include_breaks
+        result = result.struct.rename_fields(["break_point", "category"])
+      end
+
+      result
+    end
+
+    # Bin continuous values into discrete categories based on their quantiles.
+    #
+    # @param quantiles [Array]
+    #   Either a list of quantile probabilities between 0 and 1 or a positive
+    #   integer determining the number of bins with uniform probability.
+    # @param labels [Array]
+    #   Names of the categories. The number of labels must be equal to the number
+    #   of cut points plus one.
+    # @param left_closed [Boolean]
+    #   Set the intervals to be left-closed instead of right-closed.
+    # @param allow_duplicates [Boolean]
+    #   If set to `true`, duplicates in the resulting quantiles are dropped,
+    #   rather than raising a `DuplicateError`. This can happen even with unique
+    #   probabilities, depending on the data.
+    # @param include_breaks [Boolean]
+    #   Include a column with the right endpoint of the bin each observation falls
+    #   in. This will change the data type of the output from a
+    #   `Categorical` to a `Struct`.
+    #
+    # @return [Series]
+    #
+    # @example Divide a column into three categories according to pre-defined quantile probabilities.
+    #   s = Polars::Series.new("foo", [-2, -1, 0, 1, 2])
+    #   s.qcut([0.25, 0.75], labels: ["a", "b", "c"])
+    #   # =>
+    #   # shape: (5,)
+    #   # Series: 'foo' [cat]
+    #   # [
+    #   #         "a"
+    #   #         "a"
+    #   #         "b"
+    #   #         "b"
+    #   #         "c"
+    #   # ]
+    #
+    # @example Divide a column into two categories using uniform quantile probabilities.
+    #   s.qcut(2, labels: ["low", "high"], left_closed: true)
+    #   # =>
+    #   # shape: (5,)
+    #   # Series: 'foo' [cat]
+    #   # [
+    #   #         "low"
+    #   #         "low"
+    #   #         "high"
+    #   #         "high"
+    #   #         "high"
+    #   # ]
+    #
+    # @example Create a DataFrame with the breakpoint and category for each value.
+    #   cut = s.qcut([0.25, 0.75], include_breaks: true).alias("cut")
+    #   s.to_frame.with_columns(cut).unnest("cut")
+    #   # =>
+    #   # shape: (5, 3)
+    #   # ┌─────┬─────────────┬────────────┐
+    #   # │ foo ┆ break_point ┆ category   │
+    #   # │ --- ┆ ---         ┆ ---        │
+    #   # │ i64 ┆ f64         ┆ cat        │
+    #   # ╞═════╪═════════════╪════════════╡
+    #   # │ -2  ┆ -1.0        ┆ (-inf, -1] │
+    #   # │ -1  ┆ -1.0        ┆ (-inf, -1] │
+    #   # │ 0   ┆ 1.0         ┆ (-1, 1]    │
+    #   # │ 1   ┆ 1.0         ┆ (-1, 1]    │
+    #   # │ 2   ┆ inf         ┆ (1, inf]   │
+    #   # └─────┴─────────────┴────────────┘
+    def qcut(quantiles, labels: nil, left_closed: false, allow_duplicates: false, include_breaks: false)
+      result = (
+        to_frame
+        .select(
+          Polars.col(name).qcut(
+            quantiles,
+            labels: labels,
+            left_closed: left_closed,
+            allow_duplicates: allow_duplicates,
+            include_breaks: include_breaks
+          )
+        )
+        .to_series
+      )
+
+      if include_breaks
+        result = result.struct.rename_fields(["break_point", "category"])
+      end
+
+      result
+    end
+
+    # Get the lengths of runs of identical values.
+    #
+    # @return [Series]
+    #
+    # @example
+    #   s = Polars::Series.new("s", [1, 1, 2, 1, nil, 1, 3, 3])
+    #   s.rle.struct.unnest
+    #   # =>
+    #   # shape: (6, 2)
+    #   # ┌─────────┬────────┐
+    #   # │ lengths ┆ values │
+    #   # │ ---     ┆ ---    │
+    #   # │ i32     ┆ i64    │
+    #   # ╞═════════╪════════╡
+    #   # │ 2       ┆ 1      │
+    #   # │ 1       ┆ 2      │
+    #   # │ 1       ┆ 1      │
+    #   # │ 1       ┆ null   │
+    #   # │ 1       ┆ 1      │
+    #   # │ 2       ┆ 3      │
+    #   # └─────────┴────────┘
+    def rle
+      super
+    end
+
+    # Map values to run IDs.
+    #
+    # Similar to RLE, but it maps each value to an ID corresponding to the run into
+    # which it falls. This is especially useful when you want to define groups by
+    # runs of identical values rather than the values themselves.
+    #
+    # @return [Series]
+    #
+    # @example
+    #   s = Polars::Series.new("s", [1, 1, 2, 1, nil, 1, 3, 3])
+    #   s.rle_id
+    #   # =>
+    #   # shape: (8,)
+    #   # Series: 's' [u32]
+    #   # [
+    #   #         0
+    #   #         0
+    #   #         1
+    #   #         2
+    #   #         3
+    #   #         4
+    #   #         5
+    #   #         5
+    #   # ]
+    def rle_id
+      super
+    end
+
     # Count the unique values in a Series.
     #
     # @param sort [Boolean]
@@ -929,7 +1255,7 @@ module Polars
     #
     # @example
     #   s = Polars::Series.new("a", [1, 2, 3])
-    #   s.cumsum
+    #   s.cum_sum
     #   # =>
     #   # shape: (3,)
     #   # Series: 'a' [i64]
@@ -938,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.
     #
@@ -951,7 +1278,7 @@ module Polars
     #
     # @example
     #   s = Polars::Series.new("a", [3, 5, 1])
-    #   s.cummin
+    #   s.cum_min
     #   # =>
     #   # shape: (3,)
     #   # Series: 'a' [i64]
@@ -960,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.
     #
@@ -973,7 +1301,7 @@ module Polars
     #
     # @example
     #   s = Polars::Series.new("a", [3, 5, 1])
-    #   s.cummax
+    #   s.cum_max
     #   # =>
     #   # shape: (3,)
     #   # Series: 'a' [i64]
@@ -982,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.
     #
@@ -999,7 +1328,7 @@ module Polars
     #
     # @example
     #   s = Polars::Series.new("a", [1, 2, 3])
-    #   s.cumprod
+    #   s.cum_prod
     #   # =>
     #   # shape: (3,)
     #   # Series: 'a' [i64]
@@ -1008,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.
     #
@@ -1237,26 +1567,56 @@ 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
 
     # Return the `k` largest elements.
     #
-    # If `reverse: true`, the smallest elements will be given.
+    # @param k [Integer]
+    #   Number of elements to return.
+    #
+    # @return [Boolean]
+    #
+    # @example
+    #   s = Polars::Series.new("a", [2, 5, 1, 4, 3])
+    #   s.top_k(k: 3)
+    #   # =>
+    #   # shape: (3,)
+    #   # Series: 'a' [i64]
+    #   # [
+    #   #         5
+    #   #         4
+    #   #         3
+    #   # ]
+    def top_k(k: 5)
+      super
+    end
+
+    # Return the `k` smallest elements.
     #
     # @param k [Integer]
     #   Number of elements to return.
-    # @param reverse [Boolean]
-    #   Return the smallest elements.
     #
     # @return [Boolean]
-    def top_k(k: 5, reverse: false)
+    #
+    # @example
+    #   s = Polars::Series.new("a", [2, 5, 1, 4, 3])
+    #   s.bottom_k(k: 3)
+    #   # =>
+    #   # shape: (3,)
+    #   # Series: 'a' [i64]
+    #   # [
+    #   #         1
+    #   #         2
+    #   #         3
+    #   # ]
+    def bottom_k(k: 5)
       super
     end
 
@@ -1705,26 +2065,38 @@ module Polars
     # @example
     #   s = Polars::Series.new("a", [1, 2, 3])
     #   s2 = Polars::Series.new("b", [4, 5, 6])
-    #   s.series_equal(s)
+    #   s.equals(s)
     #   # => true
-    #   s.series_equal(s2)
+    #   s.equals(s2)
     #   # => false
-    def series_equal(other, null_equal: false, strict: false)
-      _s.series_equal(other._s, null_equal, strict)
+    def equals(other, null_equal: false, strict: false)
+      _s.equals(other._s, null_equal, strict)
     end
+    alias_method :series_equal, :equals
 
-    # Length of this Series.
+    # Return the number of elements in the Series.
     #
     # @return [Integer]
     #
     # @example
-    #   s = Polars::Series.new("a", [1, 2, 3])
+    #   s = Polars::Series.new("a", [1, 2, nil])
+    #   s.count
+    #   # => 2
+    def count
+      len - null_count
+    end
+
+    # Return the number of elements in the Series.
+    #
+    # @return [Integer]
+    #
+    # @example
+    #   s = Polars::Series.new("a", [1, 2, nil])
     #   s.len
     #   # => 3
     def len
       _s.len
     end
-    alias_method :count, :len
     alias_method :length, :len
     alias_method :size, :len
 
@@ -1886,7 +2258,7 @@ module Polars
     #   s.is_utf8
     #   # => true
     def is_utf8
-      dtype == Utf8
+      dtype == String
     end
     alias_method :utf8?, :is_utf8
 
@@ -1920,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
@@ -1959,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.
@@ -1982,7 +2354,7 @@ module Polars
     #   #         10
     #   #         3
     #   # ]
-    def set_at_idx(idx, value)
+    def scatter(idx, value)
       if idx.is_a?(Integer)
         idx = [idx]
       end
@@ -1991,7 +2363,7 @@ module Polars
       end
 
       idx = Series.new("", idx)
-      if value.is_a?(Integer) || value.is_a?(Float) || Utils.bool?(value) || value.is_a?(String) || value.nil?
+      if value.is_a?(Integer) || value.is_a?(Float) || Utils.bool?(value) || value.is_a?(::String) || value.nil?
         value = Series.new("", [value])
 
         # if we need to set more than a single value, we extend it
@@ -2001,9 +2373,10 @@ module Polars
       elsif !value.is_a?(Series)
         value = Series.new("", value)
       end
-      _s.set_at_idx(idx._s, value._s)
+      _s.scatter(idx._s, value._s)
       self
     end
+    alias_method :set_at_idx, :scatter
 
     # Create an empty copy of the current Series.
     #
@@ -2484,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]
@@ -2493,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
@@ -2501,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.
     #
@@ -2830,7 +3204,8 @@ module Polars
       weights: nil,
       min_periods: nil,
       center: false,
-      ddof: 1
+      ddof: 1,
+      warn_if_unsorted: true
     )
       to_frame
         .select(
@@ -2839,7 +3214,8 @@ module Polars
             weights: weights,
             min_periods: min_periods,
             center: center,
-            ddof: ddof
+            ddof: ddof,
+            warn_if_unsorted: warn_if_unsorted
           )
         )
         .to_series
@@ -2883,7 +3259,8 @@ module Polars
       weights: nil,
       min_periods: nil,
       center: false,
-      ddof: 1
+      ddof: 1,
+      warn_if_unsorted: true
     )
       to_frame
         .select(
@@ -2892,7 +3269,8 @@ module Polars
             weights: weights,
             min_periods: min_periods,
             center: center,
-            ddof: ddof
+            ddof: ddof,
+            warn_if_unsorted: warn_if_unsorted
           )
         )
         .to_series
@@ -2934,7 +3312,8 @@ module Polars
       window_size,
       weights: nil,
       min_periods: nil,
-      center: false
+      center: false,
+      warn_if_unsorted: true
     )
       if min_periods.nil?
         min_periods = window_size
@@ -2946,7 +3325,8 @@ module Polars
             window_size,
             weights: weights,
             min_periods: min_periods,
-            center: center
+            center: center,
+            warn_if_unsorted: warn_if_unsorted
           )
         )
         .to_series
@@ -3005,7 +3385,8 @@ module Polars
       window_size: 2,
       weights: nil,
       min_periods: nil,
-      center: false
+      center: false,
+      warn_if_unsorted: true
     )
       if min_periods.nil?
         min_periods = window_size
@@ -3019,7 +3400,8 @@ module Polars
             window_size: window_size,
             weights: weights,
             min_periods: min_periods,
-            center: center
+            center: center,
+            warn_if_unsorted: warn_if_unsorted
           )
         )
         .to_series
@@ -3076,8 +3458,8 @@ module Polars
     #   # shape: (2,)
     #   # Series: 'a' [i64]
     #   # [
-    #   #     1
-    #   #     5
+    #   #         5
+    #   #         3
     #   # ]
     def sample(
       n: nil,
@@ -3456,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]
@@ -3665,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
@@ -3750,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)
@@ -3761,7 +4250,7 @@ module Polars
         return Utils.wrap_s(_s.send(op, other._s))
       end
 
-      if (other.is_a?(Float) || other.is_a?(::Date) || other.is_a?(::DateTime) || other.is_a?(::Time) || other.is_a?(String)) && !is_float
+      if (other.is_a?(Float) || other.is_a?(::Date) || other.is_a?(::DateTime) || other.is_a?(::Time) || other.is_a?(::String)) && !is_float
         _s2 = sequence_to_rbseries(name, [other])
         return Utils.wrap_s(_s.send(op, _s2))
       end
@@ -3865,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?
@@ -3927,7 +4424,7 @@ module Polars
           return RbSeries.new_series_list(name, values, strict)
         else
           constructor =
-            if value.is_a?(String)
+            if value.is_a?(::String)
               if value.encoding == Encoding::UTF_8
                 RbSeries.method(:new_str)
               else
@@ -3970,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)
     }