polars-df 0.6.0-x86_64-linux → 0.8.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
 
@@ -341,7 +341,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 +351,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
@@ -432,6 +432,18 @@ module Polars
     end
     alias_method :all, :all?
 
+    # Check if all boolean values in the column are `false`.
+    #
+    # @return [Boolean]
+    def none?(&block)
+      if block_given?
+        apply(&block).none?
+      else
+        to_frame.select(Polars.col(name).is_not.all).to_series[0]
+      end
+    end
+    alias_method :none, :none?
+
     # Compute the logarithm to a given base.
     #
     # @param base [Float]
@@ -723,6 +735,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]
@@ -799,7 +1017,7 @@ module Polars
     #   Number of valid values there should be in the window before the expression
     #   is evaluated. valid values = `length - null_count`
     # @param parallel [Boolean]
-    #   Run in parallel. Don't do this in a groupby or another operation that
+    #   Run in parallel. Don't do this in a group by or another operation that
     #   already has much parallelization.
     #
     # @return [Series]
@@ -1236,15 +1454,45 @@ module Polars
 
     # 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
 
@@ -1693,26 +1941,40 @@ 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
+    #   # => 3
+    def count
+      warn "`Series#count` will exclude null values in 0.9.0. Use `Series#length` instead."
+      # len - null_count
+      len
+    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
 
@@ -1874,7 +2136,7 @@ module Polars
     #   s.is_utf8
     #   # => true
     def is_utf8
-      dtype == Utf8
+      dtype == String
     end
     alias_method :utf8?, :is_utf8
 
@@ -1970,7 +2232,7 @@ module Polars
     #   #         10
     #   #         3
     #   # ]
-    def set_at_idx(idx, value)
+    def scatter(idx, value)
       if idx.is_a?(Integer)
         idx = [idx]
       end
@@ -1979,7 +2241,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
@@ -1989,9 +2251,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.
     #
@@ -2818,7 +3081,8 @@ module Polars
       weights: nil,
       min_periods: nil,
       center: false,
-      ddof: 1
+      ddof: 1,
+      warn_if_unsorted: true
     )
       to_frame
         .select(
@@ -2827,7 +3091,8 @@ module Polars
             weights: weights,
             min_periods: min_periods,
             center: center,
-            ddof: ddof
+            ddof: ddof,
+            warn_if_unsorted: warn_if_unsorted
           )
         )
         .to_series
@@ -2871,7 +3136,8 @@ module Polars
       weights: nil,
       min_periods: nil,
       center: false,
-      ddof: 1
+      ddof: 1,
+      warn_if_unsorted: true
     )
       to_frame
         .select(
@@ -2880,7 +3146,8 @@ module Polars
             weights: weights,
             min_periods: min_periods,
             center: center,
-            ddof: ddof
+            ddof: ddof,
+            warn_if_unsorted: warn_if_unsorted
           )
         )
         .to_series
@@ -2922,7 +3189,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
@@ -2934,7 +3202,8 @@ module Polars
             window_size,
             weights: weights,
             min_periods: min_periods,
-            center: center
+            center: center,
+            warn_if_unsorted: warn_if_unsorted
           )
         )
         .to_series
@@ -2993,7 +3262,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
@@ -3007,7 +3277,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
@@ -3097,7 +3368,7 @@ module Polars
     #   s.peak_max
     #   # =>
     #   # shape: (5,)
-    #   # Series: '' [bool]
+    #   # Series: 'a' [bool]
     #   # [
     #   #         false
     #   #         false
@@ -3106,7 +3377,7 @@ module Polars
     #   #         true
     #   # ]
     def peak_max
-      Utils.wrap_s(_s.peak_max)
+      super
     end
 
     # Get a boolean mask of the local minimum peaks.
@@ -3118,7 +3389,7 @@ module Polars
     #   s.peak_min
     #   # =>
     #   # shape: (5,)
-    #   # Series: '' [bool]
+    #   # Series: 'a' [bool]
     #   # [
     #   #         false
     #   #         true
@@ -3127,7 +3398,7 @@ module Polars
     #   #         false
     #   # ]
     def peak_min
-      Utils.wrap_s(_s.peak_min)
+      super
     end
 
     # Count the number of unique values in this Series.
@@ -3211,13 +3482,13 @@ module Polars
     #   s.interpolate
     #   # =>
     #   # shape: (5,)
-    #   # Series: 'a' [i64]
+    #   # Series: 'a' [f64]
     #   # [
-    #   #         1
-    #   #         2
-    #   #         3
-    #   #         4
-    #   #         5
+    #   #         1.0
+    #   #         2.0
+    #   #         3.0
+    #   #         4.0
+    #   #         5.0
     #   # ]
     def interpolate(method: "linear")
       super
@@ -3260,7 +3531,7 @@ module Polars
     #   s.rank
     #   # =>
     #   # shape: (5,)
-    #   # Series: 'a' [f32]
+    #   # Series: 'a' [f64]
     #   # [
     #   #         3.0
     #   #         4.5
@@ -3749,7 +4020,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
@@ -3915,7 +4186,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
@@ -3998,7 +4269,8 @@ module Polars
       Integer => RbSeries.method(:new_opt_i64),
       TrueClass => RbSeries.method(:new_opt_bool),
       FalseClass => RbSeries.method(:new_opt_bool),
-      BigDecimal => RbSeries.method(:new_decimal)
+      BigDecimal => RbSeries.method(:new_decimal),
+      NilClass => RbSeries.method(:new_null)
     }
 
     def rb_type_to_constructor(dtype)