polars-df 0.7.0 → 0.8.0

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
@@ -735,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]
@@ -1248,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
 
@@ -1705,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
 
@@ -1886,7 +2136,7 @@ module Polars
     #   s.is_utf8
     #   # => true
     def is_utf8
-      dtype == Utf8
+      dtype == String
     end
     alias_method :utf8?, :is_utf8
 
@@ -1982,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
@@ -1991,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
@@ -2001,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.
     #
@@ -2830,7 +3081,8 @@ module Polars
       weights: nil,
       min_periods: nil,
       center: false,
-      ddof: 1
+      ddof: 1,
+      warn_if_unsorted: true
     )
       to_frame
         .select(
@@ -2839,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
@@ -2883,7 +3136,8 @@ module Polars
       weights: nil,
       min_periods: nil,
       center: false,
-      ddof: 1
+      ddof: 1,
+      warn_if_unsorted: true
     )
       to_frame
         .select(
@@ -2892,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
@@ -2934,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
@@ -2946,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
@@ -3005,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
@@ -3019,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
@@ -3761,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
@@ -3927,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

data/lib/polars/sql_context.rb

@@ -157,7 +157,7 @@ module Polars
     #   ctx.unregister(["test1", "test3"]).tables
     #   # => ["test2"]
     def unregister(names)
-      if names.is_a?(String)
+      if names.is_a?(::String)
         names = [names]
       end
       names.each do |nm|

data/lib/polars/struct_expr.rb

@@ -13,7 +13,7 @@ module Polars
     #
     # @return [Expr]
     def [](item)
-      if item.is_a?(String)
+      if item.is_a?(::String)
         field(item)
       elsif item.is_a?(Integer)
         Utils.wrap_expr(_rbexpr.struct_field_by_index(item))

data/lib/polars/struct_name_space.rb

@@ -16,7 +16,7 @@ module Polars
     def [](item)
       if item.is_a?(Integer)
         field(fields[item])
-      elsif item.is_a?(String)
+      elsif item.is_a?(::String)
         field(item)
       else
         raise ArgumentError, "expected type Integer or String, got #{item.class.name}"

data/lib/polars/utils.rb

@@ -27,7 +27,7 @@ module Polars
       if obj.is_a?(Range)
         # size only works for numeric ranges
         obj.to_a.length
-      elsif obj.is_a?(String)
+      elsif obj.is_a?(::String)
         nil
       else
         obj.length
@@ -116,7 +116,7 @@ module Polars
     end
 
     def self.selection_to_rbexpr_list(exprs)
-      if exprs.is_a?(String) || exprs.is_a?(Symbol) || exprs.is_a?(Expr) || exprs.is_a?(Series)
+      if exprs.is_a?(::String) || exprs.is_a?(Symbol) || exprs.is_a?(Expr) || exprs.is_a?(Series)
         exprs = [exprs]
       end
 
@@ -124,9 +124,9 @@ module Polars
     end
 
     def self.expr_to_lit_or_expr(expr, str_to_lit: true)
-      if (expr.is_a?(String) || expr.is_a?(Symbol)) && !str_to_lit
+      if (expr.is_a?(::String) || expr.is_a?(Symbol)) && !str_to_lit
         col(expr)
-      elsif expr.is_a?(Integer) || expr.is_a?(Float) || expr.is_a?(String) || expr.is_a?(Symbol) || expr.is_a?(Series) || expr.nil?
+      elsif expr.is_a?(Integer) || expr.is_a?(Float) || expr.is_a?(::String) || expr.is_a?(Symbol) || expr.is_a?(Series) || expr.nil?
         lit(expr)
       elsif expr.is_a?(Expr)
         expr
@@ -152,7 +152,7 @@ module Polars
       if data_type == Unknown
         return include_unknown
       end
-      data_type.is_a?(Symbol) || data_type.is_a?(String) || data_type.is_a?(DataType) || (data_type.is_a?(Class) && data_type < DataType)
+      data_type.is_a?(Symbol) || data_type.is_a?(::String) || data_type.is_a?(DataType) || (data_type.is_a?(Class) && data_type < DataType)
     end
 
     def self.map_rb_type_to_dtype(ruby_dtype)
@@ -160,7 +160,7 @@ module Polars
         Float64
       elsif ruby_dtype == Integer
         Int64
-      elsif ruby_dtype == String
+      elsif ruby_dtype == ::String
         Utf8
       elsif ruby_dtype == TrueClass || ruby_dtype == FalseClass
         Boolean
@@ -211,7 +211,7 @@ module Polars
       projection = nil
       if columns
         raise Todo
-        # if columns.is_a?(String) || columns.is_a?(Symbol)
+        # if columns.is_a?(::String) || columns.is_a?(Symbol)
         #   columns = [columns]
         # elsif is_int_sequence(columns)
         #   projection = columns.to_a
@@ -243,11 +243,11 @@ module Polars
     end
 
     def self.strlike?(value)
-      value.is_a?(String) || value.is_a?(Symbol)
+      value.is_a?(::String) || value.is_a?(Symbol)
     end
 
     def self.pathlike?(value)
-      value.is_a?(String) || (defined?(Pathname) && value.is_a?(Pathname))
+      value.is_a?(::String) || (defined?(Pathname) && value.is_a?(Pathname))
     end
 
     def self._is_iterable_of(val, eltype)
@@ -275,10 +275,10 @@ module Polars
     end
 
     def self.is_str_sequence(val, allow_str: false)
-      if allow_str == false && val.is_a?(String)
+      if allow_str == false && val.is_a?(::String)
         false
       else
-        val.is_a?(::Array) && _is_iterable_of(val, String)
+        val.is_a?(::Array) && _is_iterable_of(val, ::String)
       end
     end
 
@@ -289,10 +289,10 @@ module Polars
     def self.parse_as_expression(input, str_as_lit: false, structify: false)
       if input.is_a?(Expr)
         expr = input
-      elsif input.is_a?(String) && !str_as_lit
+      elsif input.is_a?(::String) && !str_as_lit
         expr = Polars.col(input)
         structify = false
-      elsif [Integer, Float, String, Series, ::Date, ::Time, ::DateTime].any? { |cls| input.is_a?(cls) } || input.nil?
+      elsif [Integer, Float, ::String, Series, ::Date, ::Time, ::DateTime].any? { |cls| input.is_a?(cls) } || input.nil?
         expr = Polars.lit(input)
         structify = false
       elsif input.is_a?(Array)

data/lib/polars/version.rb

@@ -1,4 +1,4 @@
 module Polars
   # @private
-  VERSION = "0.7.0"
+  VERSION = "0.8.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: polars-df
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.8.0
 platform: ruby
 authors:
 - Andrew Kane
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-11-18 00:00:00.000000000 Z
+date: 2024-01-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rb_sys
@@ -75,15 +75,16 @@ files:
 - ext/polars/src/map/mod.rs
 - ext/polars/src/map/series.rs
 - ext/polars/src/object.rs
+- ext/polars/src/on_startup.rs
 - ext/polars/src/prelude.rs
 - ext/polars/src/rb_modules.rs
-- ext/polars/src/series.rs
 - ext/polars/src/series/aggregation.rs
 - ext/polars/src/series/arithmetic.rs
 - ext/polars/src/series/comparison.rs
 - ext/polars/src/series/construction.rs
 - ext/polars/src/series/export.rs
-- ext/polars/src/series/set_at_idx.rs
+- ext/polars/src/series/mod.rs
+- ext/polars/src/series/scatter.rs
 - ext/polars/src/sql.rs
 - ext/polars/src/utils.rs
 - lib/polars-df.rb
@@ -140,14 +141,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.0'
+      version: '3.1'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.10
+rubygems_version: 3.5.3
 signing_key:
 specification_version: 4
 summary: Blazingly fast DataFrames for Ruby