polars-df 0.8.0 → 0.10.0

data/lib/polars/data_types.rb

@@ -1,24 +1,122 @@
 module Polars
   # Base class for all Polars data types.
   class DataType
+    # Return this DataType's fundamental/root type class.
+    #
+    # @return [Class]
+    #
+    # @example
+    #   Polars::Datetime.new("ns").base_type
+    #   # => Polars::Datetime
+    # @example
+    #   Polars::List.new(Polars::Int32).base_type
+    #   # => Polars::List
+    # @example
+    #   Polars::Struct.new([Polars::Field.new("a", Polars::Int64), Polars::Field.new("b", Polars::Boolean)]).base_type
+    #   # => Polars::Struct
     def self.base_type
       self
     end
 
+    # Return this DataType's fundamental/root type class.
+    #
+    # @return [Class]
     def base_type
       is_a?(DataType) ? self.class : self
     end
 
+    # Check if this DataType is the same as another DataType.
+    #
+    # @return [Boolean]
+    def self.==(other)
+      eql?(other) || other.is_a?(self)
+    end
+
+    # Check if this DataType is the same as another DataType.
+    #
+    # @return [Boolean]
+    def ==(other)
+      if other.is_a?(Class)
+        is_a?(other)
+      else
+        other.instance_of?(self.class)
+      end
+    end
+
+    # Check whether the data type is a numeric type.
+    #
+    # @return [Boolean]
+    def self.numeric?
+      self < NumericType
+    end
+
+    # Check whether the data type is a decimal type.
+    #
+    # @return [Boolean]
+    def self.decimal?
+      self == Decimal
+    end
+
+    # Check whether the data type is an integer type.
+    #
+    # @return [Boolean]
+    def self.integer?
+      self < IntegerType
+    end
+
+    # Check whether the data type is a signed integer type.
+    #
+    # @return [Boolean]
+    def self.signed_integer?
+      self < SignedIntegerType
+    end
+
+    # Check whether the data type is an unsigned integer type.
+    #
+    # @return [Boolean]
+    def self.unsigned_integer?
+      self < UnsignedIntegerType
+    end
+
+    # Check whether the data type is a float type.
+    #
+    # @return [Boolean]
+    def self.float?
+      self < FloatType
+    end
+
+    # Check whether the data type is a temporal type.
+    #
+    # @return [Boolean]
+    def self.temporal?
+      self < TemporalType
+    end
+
+    # Check whether the data type is a nested type.
+    #
+    # @return [Boolean]
     def self.nested?
-      false
+      self < NestedType
     end
 
-    def nested?
-      self.class.nested?
+    [:numeric?, :decimal?, :integer?, :signed_integer?, :unsigned_integer?, :float?, :temporal?, :nested?].each do |v|
+      define_method(v) do
+        self.class.public_send(v)
+      end
     end
 
-    def self.==(other)
-      eql?(other) || other.is_a?(self)
+    # Returns a string representing the data type.
+    #
+    # @return [String]
+    def to_s
+      self.class.name
+    end
+
+    # Returns a string representing the data type.
+    #
+    # @return [String]
+    def inspect
+      to_s
     end
   end
 
@@ -27,15 +125,22 @@ module Polars
   end
 
   # Base class for integral data types.
-  class IntegralType < NumericType
+  class IntegerType < NumericType
   end
 
-  # Base class for fractional data types.
-  class FractionalType < NumericType
+  # @private
+  IntegralType = IntegerType
+
+  # Base class for signed integer data types.
+  class SignedIntegerType < IntegerType
+  end
+
+  # Base class for unsigned integer data types.
+  class UnsignedIntegerType < IntegerType
   end
 
   # Base class for float data types.
-  class FloatType < FractionalType
+  class FloatType < NumericType
   end
 
   # Base class for temporal data types.
@@ -44,41 +149,38 @@ module Polars
 
   # Base class for nested data types.
   class NestedType < DataType
-    def self.nested?
-      true
-    end
   end
 
   # 8-bit signed integer type.
-  class Int8 < IntegralType
+  class Int8 < SignedIntegerType
   end
 
   # 16-bit signed integer type.
-  class Int16 < IntegralType
+  class Int16 < SignedIntegerType
   end
 
   # 32-bit signed integer type.
-  class Int32 < IntegralType
+  class Int32 < SignedIntegerType
   end
 
   # 64-bit signed integer type.
-  class Int64 < IntegralType
+  class Int64 < SignedIntegerType
   end
 
   # 8-bit unsigned integer type.
-  class UInt8 < IntegralType
+  class UInt8 < UnsignedIntegerType
   end
 
   # 16-bit unsigned integer type.
-  class UInt16 < IntegralType
+  class UInt16 < UnsignedIntegerType
   end
 
   # 32-bit unsigned integer type.
-  class UInt32 < IntegralType
+  class UInt32 < UnsignedIntegerType
   end
 
   # 64-bit unsigned integer type.
-  class UInt64 < IntegralType
+  class UInt64 < UnsignedIntegerType
   end
 
   # 32-bit floating point type.
@@ -92,7 +194,7 @@ module Polars
   # Decimal 128-bit type with an optional precision and non-negative scale.
   #
   # NOTE: this is an experimental work-in-progress feature and may not work as expected.
-  class Decimal < FractionalType
+  class Decimal < NumericType
     attr_reader :precision, :scale
 
     def initialize(precision, scale)
@@ -123,6 +225,7 @@ module Polars
   class String < DataType
   end
 
+  # @private
   # Allow Utf8 as an alias for String
   Utf8 = String
 
@@ -189,6 +292,59 @@ module Polars
 
   # A categorical encoding of a set of strings.
   class Categorical < DataType
+    def initialize(ordering = "physical")
+      @ordering = ordering
+    end
+  end
+
+  # A fixed set categorical encoding of a set of strings.
+  #
+  # NOTE: this is an experimental work-in-progress feature and may not work as expected.
+  class Enum < DataType
+    attr_reader :categories
+
+    def initialize(categories)
+      if !categories.is_a?(Series)
+        categories = Series.new(categories)
+      end
+
+      if categories.empty?
+        self.categories = Series.new("category", [], dtype: String)
+        return
+      end
+
+      if categories.null_count > 0
+        msg = "Enum categories must not contain null values"
+        raise TypeError, msg
+      end
+
+      if (dtype = categories.dtype) != String
+        msg = "Enum categories must be strings; found data of type #{dtype}"
+        raise TypeError, msg
+      end
+
+      if categories.n_unique != categories.len
+        duplicate = categories.filter(categories.is_duplicated)[0]
+        msg = "Enum categories must be unique; found duplicate #{duplicate}"
+        raise ArgumentError, msg
+      end
+
+      @categories = categories.rechunk.alias("category")
+    end
+
+    def ==(other)
+      if other.eql?(Enum)
+        true
+      elsif other.is_a?(Enum)
+        categories == other.categories
+      else
+        false
+      end
+    end
+
+    def to_s
+      "#{self.class.name}(categories: #{categories.to_a.inspect})"
+    end
   end
 
   # Type for wrapping arbitrary Ruby objects.
@@ -228,27 +384,34 @@ module Polars
 
   # Nested list/array type.
   class Array < NestedType
-    attr_reader :width, :inner
+    attr_reader :inner, :width
 
-    def initialize(width, inner = nil)
-      @width = width
+    def initialize(inner, width)
+      if width.is_a?(DataType) || (width.is_a?(Class) && width < DataType)
+        inner, width = width, inner
+      end
       @inner = Utils.rb_type_to_dtype(inner) if inner
+      @width = width
     end
 
-    # TODO check width?
     def ==(other)
       if other.eql?(Array)
         true
       elsif other.is_a?(Array)
-        @inner.nil? || other.inner.nil? || @inner == other.inner
+        if @width != other.width
+          false
+        elsif @inner.nil? || other.inner.nil?
+          true
+        else
+          @inner == other.inner
+        end
       else
         false
       end
     end
 
-    # TODO add width?
     def to_s
-      "#{self.class.name}(#{inner})"
+      "#{self.class.name}(#{inner}, width: #{width.inspect})"
     end
   end
 

data/lib/polars/date_time_expr.rb

@@ -1027,14 +1027,20 @@ module Polars
     # Different from `convert_time_zone`, this will also modify
     # the underlying timestamp,
     #
-    # @param tz [String]
-    #   Time zone for the `Datetime` Series.
+    # @param time_zone [String]
+    #     Time zone for the `Datetime` Series. Pass `nil` to unset time zone.
+    # @param use_earliest [Boolean]
+    #     Determine how to deal with ambiguous datetimes.
+    # @param ambiguous [String]
+    #     Determine how to deal with ambiguous datetimes.
+    # @param non_existent [String]
+    #     Determine how to deal with non-existent datetimes.
     #
     # @return [Expr]
-    def replace_time_zone(tz, use_earliest: nil, ambiguous: "raise")
+    def replace_time_zone(time_zone, use_earliest: nil, ambiguous: "raise", non_existent: "raise")
       ambiguous = Utils.rename_use_earliest_to_ambiguous(use_earliest, ambiguous)
       ambiguous = Polars.lit(ambiguous) unless ambiguous.is_a?(Expr)
-      Utils.wrap_expr(_rbexpr.dt_replace_time_zone(tz, ambiguous._rbexpr))
+      Utils.wrap_expr(_rbexpr.dt_replace_time_zone(time_zone, ambiguous._rbexpr, non_existent))
     end
 
     # Extract the days from a Duration type.
@@ -1066,9 +1072,10 @@ module Polars
     #   # │ 2020-04-01 00:00:00 ┆ 31        │
     #   # │ 2020-05-01 00:00:00 ┆ 30        │
     #   # └─────────────────────┴───────────┘
-    def days
-      Utils.wrap_expr(_rbexpr.duration_days)
+    def total_days
+      Utils.wrap_expr(_rbexpr.dt_total_days)
     end
+    alias_method :days, :total_days
 
     # Extract the hours from a Duration type.
     #
@@ -1100,9 +1107,10 @@ module Polars
     #   # │ 2020-01-03 00:00:00 ┆ 24         │
     #   # │ 2020-01-04 00:00:00 ┆ 24         │
     #   # └─────────────────────┴────────────┘
-    def hours
-      Utils.wrap_expr(_rbexpr.duration_hours)
+    def total_hours
+      Utils.wrap_expr(_rbexpr.dt_total_hours)
     end
+    alias_method :hours, :total_hours
 
     # Extract the minutes from a Duration type.
     #
@@ -1134,9 +1142,10 @@ module Polars
     #   # │ 2020-01-03 00:00:00 ┆ 1440         │
     #   # │ 2020-01-04 00:00:00 ┆ 1440         │
     #   # └─────────────────────┴──────────────┘
-    def minutes
-      Utils.wrap_expr(_rbexpr.duration_minutes)
+    def total_minutes
+      Utils.wrap_expr(_rbexpr.dt_total_minutes)
     end
+    alias_method :minutes, :total_minutes
 
     # Extract the seconds from a Duration type.
     #
@@ -1169,9 +1178,10 @@ module Polars
     #   # │ 2020-01-01 00:03:00 ┆ 60           │
     #   # │ 2020-01-01 00:04:00 ┆ 60           │
     #   # └─────────────────────┴──────────────┘
-    def seconds
-      Utils.wrap_expr(_rbexpr.duration_seconds)
+    def total_seconds
+      Utils.wrap_expr(_rbexpr.dt_total_seconds)
     end
+    alias_method :seconds, :total_seconds
 
     # Extract the milliseconds from a Duration type.
     #
@@ -1202,15 +1212,18 @@ module Polars
     #   # │ 2020-01-01 00:00:00.001 ┆ 1                 │
     #   # │ 2020-01-01 00:00:00.002 ┆ 1                 │
     #   # │ 2020-01-01 00:00:00.003 ┆ 1                 │
+    #   # │ 2020-01-01 00:00:00.004 ┆ 1                 │
     #   # │ …                       ┆ …                 │
+    #   # │ 2020-01-01 00:00:00.996 ┆ 1                 │
     #   # │ 2020-01-01 00:00:00.997 ┆ 1                 │
     #   # │ 2020-01-01 00:00:00.998 ┆ 1                 │
     #   # │ 2020-01-01 00:00:00.999 ┆ 1                 │
     #   # │ 2020-01-01 00:00:01     ┆ 1                 │
     #   # └─────────────────────────┴───────────────────┘
-    def milliseconds
-      Utils.wrap_expr(_rbexpr.duration_milliseconds)
+    def total_milliseconds
+      Utils.wrap_expr(_rbexpr.dt_total_milliseconds)
     end
+    alias_method :milliseconds, :total_milliseconds
 
     # Extract the microseconds from a Duration type.
     #
@@ -1241,15 +1254,18 @@ module Polars
     #   # │ 2020-01-01 00:00:00.001 ┆ 1000              │
     #   # │ 2020-01-01 00:00:00.002 ┆ 1000              │
     #   # │ 2020-01-01 00:00:00.003 ┆ 1000              │
+    #   # │ 2020-01-01 00:00:00.004 ┆ 1000              │
     #   # │ …                       ┆ …                 │
+    #   # │ 2020-01-01 00:00:00.996 ┆ 1000              │
     #   # │ 2020-01-01 00:00:00.997 ┆ 1000              │
     #   # │ 2020-01-01 00:00:00.998 ┆ 1000              │
     #   # │ 2020-01-01 00:00:00.999 ┆ 1000              │
     #   # │ 2020-01-01 00:00:01     ┆ 1000              │
     #   # └─────────────────────────┴───────────────────┘
-    def microseconds
-      Utils.wrap_expr(_rbexpr.duration_microseconds)
+    def total_microseconds
+      Utils.wrap_expr(_rbexpr.dt_total_microseconds)
     end
+    alias_method :microseconds, :total_microseconds
 
     # Extract the nanoseconds from a Duration type.
     #
@@ -1280,15 +1296,18 @@ module Polars
     #   # │ 2020-01-01 00:00:00.001 ┆ 1000000          │
     #   # │ 2020-01-01 00:00:00.002 ┆ 1000000          │
     #   # │ 2020-01-01 00:00:00.003 ┆ 1000000          │
+    #   # │ 2020-01-01 00:00:00.004 ┆ 1000000          │
     #   # │ …                       ┆ …                │
+    #   # │ 2020-01-01 00:00:00.996 ┆ 1000000          │
     #   # │ 2020-01-01 00:00:00.997 ┆ 1000000          │
     #   # │ 2020-01-01 00:00:00.998 ┆ 1000000          │
     #   # │ 2020-01-01 00:00:00.999 ┆ 1000000          │
     #   # │ 2020-01-01 00:00:01     ┆ 1000000          │
     #   # └─────────────────────────┴──────────────────┘
-    def nanoseconds
-      Utils.wrap_expr(_rbexpr.duration_nanoseconds)
+    def total_nanoseconds
+      Utils.wrap_expr(_rbexpr.dt_total_nanoseconds)
     end
+    alias_method :nanoseconds, :total_nanoseconds
 
     # Offset this date by a relative time offset.
     #
@@ -1372,7 +1391,9 @@ module Polars
     #   # │ 2000-02-01 02:00:00 │
     #   # │ 2000-03-01 02:00:00 │
     #   # │ 2000-04-01 02:00:00 │
+    #   # │ 2000-05-01 02:00:00 │
     #   # │ …                   │
+    #   # │ 2000-08-01 02:00:00 │
     #   # │ 2000-09-01 02:00:00 │
     #   # │ 2000-10-01 02:00:00 │
     #   # │ 2000-11-01 02:00:00 │
@@ -1408,7 +1429,9 @@ module Polars
     #   # │ 2000-02-29 02:00:00 │
     #   # │ 2000-03-31 02:00:00 │
     #   # │ 2000-04-30 02:00:00 │
+    #   # │ 2000-05-31 02:00:00 │
     #   # │ …                   │
+    #   # │ 2000-08-31 02:00:00 │
     #   # │ 2000-09-30 02:00:00 │
     #   # │ 2000-10-31 02:00:00 │
     #   # │ 2000-11-30 02:00:00 │

data/lib/polars/date_time_name_space.rb

@@ -910,8 +910,14 @@ module Polars
     # Different from `with_time_zone`, this will also modify
     # the underlying timestamp.
     #
-    # @param tz [String]
-    #   Time zone for the `Datetime` Series.
+    # @param time_zone [String]
+    #     Time zone for the `Datetime` Series. Pass `nil` to unset time zone.
+    # @param use_earliest [Boolean]
+    #     Determine how to deal with ambiguous datetimes.
+    # @param ambiguous [String]
+    #     Determine how to deal with ambiguous datetimes.
+    # @param non_existent [String]
+    #     Determine how to deal with non-existent datetimes.
     #
     # @return [Series]
     #
@@ -982,7 +988,7 @@ module Polars
     #   #         1585717200
     #   #         1588309200
     #   # ]
-    def replace_time_zone(tz)
+    def replace_time_zone(time_zone, use_earliest: nil, ambiguous: "raise", non_existent: "raise")
       super
     end
 

data/lib/polars/exceptions.rb

@@ -1,15 +1,26 @@
 module Polars
   # @private
+  # Base class for all Polars errors.
   class Error < StandardError; end
 
   # @private
+  # Exception raised when an unsupported testing assert is made.
+  class InvalidAssert < Error; end
+
+  # @private
+  # Exception raised when the number of returned rows does not match expectation.
   class RowsException < Error; end
 
   # @private
+  # Exception raised when no rows are returned, but at least one row is expected.
+  class NoRowsReturned < RowsException; end
+
+  # @private
+  # Exception raised when more rows than expected are returned.
   class TooManyRowsReturned < RowsException; end
 
   # @private
-  class NoRowsReturned < RowsException; end
+  class AssertionError < Error; end
 
   # @private
   class Todo < Error