polars-df 0.13.0 → 0.15.0

data/lib/polars/series.rb

@@ -88,6 +88,11 @@ module Polars
     # Get the data type of this Series.
     #
     # @return [Symbol]
+    #
+    # @example
+    #   s = Polars::Series.new("a", [1, 2, 3])
+    #   s.dtype
+    #   # => Polars::Int64
     def dtype
       _s.dtype
     end
@@ -95,6 +100,11 @@ module Polars
     # Get flags that are set on the Series.
     #
     # @return [Hash]
+    #
+    # @example
+    #   s = Polars::Series.new("a", [1, 2, 3])
+    #   s.flags
+    #   # => {"SORTED_ASC"=>false, "SORTED_DESC"=>false}
     def flags
       out = {
         "SORTED_ASC" => _s.is_sorted_flag,
@@ -106,16 +116,14 @@ module Polars
       out
     end
 
-    # Get the inner dtype in of a List typed Series.
-    #
-    # @return [Symbol]
-    def inner_dtype
-      _s.inner_dtype
-    end
-
     # Get the name of this Series.
     #
     # @return [String]
+    #
+    # @example
+    #   s = Polars::Series.new("a", [1, 2, 3])
+    #   s.name
+    #   # => "a"
     def name
       _s.name
     end
@@ -123,17 +131,15 @@ module Polars
     # Shape of this Series.
     #
     # @return [Array]
+    #
+    # @example
+    #   s = Polars::Series.new("a", [1, 2, 3])
+    #   s.shape
+    #   # => [3]
     def shape
       [_s.len]
     end
 
-    # Get the time unit of underlying Datetime Series as `"ns"`, `"us"`, or `"ms"`.
-    #
-    # @return [String]
-    def time_unit
-      _s.time_unit
-    end
-
     # Returns a string representing the Series.
     #
     # @return [String]
@@ -524,6 +530,18 @@ module Polars
     # Compute the square root of the elements.
     #
     # @return [Series]
+    #
+    # @example
+    #   s = Polars::Series.new([1, 2, 3])
+    #   s.sqrt
+    #   # =>
+    #   # shape: (3,)
+    #   # Series: '' [f64]
+    #   # [
+    #   #         1.0
+    #   #         1.414214
+    #   #         1.732051
+    #   # ]
     def sqrt
       self**0.5
     end
@@ -531,6 +549,18 @@ module Polars
     # Check if any boolean value in the column is `true`.
     #
     # @return [Boolean]
+    #
+    # @example
+    #   Polars::Series.new([true, false]).any?
+    #   # => true
+    #
+    # @example
+    #   Polars::Series.new([false, false]).any?
+    #   # => false
+    #
+    # @example
+    #   Polars::Series.new([nil, false]).any?
+    #   # => false
     def any?(ignore_nulls: true, &block)
       if block_given?
         apply(skip_nulls: ignore_nulls, &block).any?
@@ -543,6 +573,18 @@ module Polars
     # Check if all boolean values in the column are `true`.
     #
     # @return [Boolean]
+    #
+    # @example
+    #   Polars::Series.new([true, true]).all?
+    #   # => true
+    #
+    # @example
+    #   Polars::Series.new([false, true]).all?
+    #   # => false
+    #
+    # @example
+    #   Polars::Series.new([nil, true]).all?
+    #   # => true
     def all?(ignore_nulls: true, &block)
       if block_given?
         apply(skip_nulls: ignore_nulls, &block).all?
@@ -555,6 +597,18 @@ module Polars
     # Check if all boolean values in the column are `false`.
     #
     # @return [Boolean]
+    #
+    # @example
+    #   Polars::Series.new([true, false]).none?
+    #   # => false
+    #
+    # @example
+    #   Polars::Series.new([false, false]).none?
+    #   # => true
+    #
+    # @example
+    #   Polars::Series.new([nil, false]).none?
+    #   # => true
     def none?(&block)
       if block_given?
         apply(&block).none?
@@ -570,6 +624,18 @@ module Polars
     #   Given base, defaults to `Math::E`.
     #
     # @return [Series]
+    #
+    # @example
+    #   s = Polars::Series.new([1, 2, 3])
+    #   s.log
+    #   # =>
+    #   # shape: (3,)
+    #   # Series: '' [f64]
+    #   # [
+    #   #         0.0
+    #   #         0.693147
+    #   #         1.098612
+    #   # ]
     def log(base = Math::E)
       super
     end
@@ -577,6 +643,18 @@ module Polars
     # Compute the base 10 logarithm of the input array, element-wise.
     #
     # @return [Series]
+    #
+    # @example
+    #   s = Polars::Series.new([10, 100, 1000])
+    #   s.log10
+    #   # =>
+    #   # shape: (3,)
+    #   # Series: '' [f64]
+    #   # [
+    #   #         1.0
+    #   #         2.0
+    #   #         3.0
+    #   # ]
     def log10
       super
     end
@@ -584,6 +662,18 @@ module Polars
     # Compute the exponential, element-wise.
     #
     # @return [Series]
+    #
+    # @example
+    #   s = Polars::Series.new([1, 2, 3])
+    #   s.exp
+    #   # =>
+    #   # shape: (3,)
+    #   # Series: '' [f64]
+    #   # [
+    #   #         2.718282
+    #   #         7.389056
+    #   #         20.085537
+    #   # ]
     def exp
       super
     end
@@ -591,6 +681,18 @@ module Polars
     # Create a new Series that copies data from this Series without null values.
     #
     # @return [Series]
+    #
+    # @example
+    #   s = Polars::Series.new([1.0, nil, 3.0, Float::NAN])
+    #   s.drop_nulls
+    #   # =>
+    #   # shape: (3,)
+    #   # Series: '' [f64]
+    #   # [
+    #   #         1.0
+    #   #         3.0
+    #   #         NaN
+    #   # ]
     def drop_nulls
       super
     end
@@ -598,6 +700,18 @@ module Polars
     # Drop NaN values.
     #
     # @return [Series]
+    #
+    # @example
+    #   s = Polars::Series.new([1.0, nil, 3.0, Float::NAN])
+    #   s.drop_nans
+    #   # =>
+    #   # shape: (3,)
+    #   # Series: '' [f64]
+    #   # [
+    #   #         1.0
+    #   #         null
+    #   #         3.0
+    #   # ]
     def drop_nans
       super
     end
@@ -605,7 +719,37 @@ module Polars
     # Cast this Series to a DataFrame.
     #
     # @return [DataFrame]
-    def to_frame
+    #
+    # @example
+    #   s = Polars::Series.new("a", [123, 456])
+    #   s.to_frame
+    #   # =>
+    #   # shape: (2, 1)
+    #   # ┌─────┐
+    #   # │ a   │
+    #   # │ --- │
+    #   # │ i64 │
+    #   # ╞═════╡
+    #   # │ 123 │
+    #   # │ 456 │
+    #   # └─────┘
+    #
+    # @example
+    #   s.to_frame("xyz")
+    #   # =>
+    #   # shape: (2, 1)
+    #   # ┌─────┐
+    #   # │ xyz │
+    #   # │ --- │
+    #   # │ i64 │
+    #   # ╞═════╡
+    #   # │ 123 │
+    #   # │ 456 │
+    #   # └─────┘
+    def to_frame(name = nil)
+      if name
+        return Utils.wrap_df(RbDataFrame.new([rename(name)._s]))
+      end
       Utils.wrap_df(RbDataFrame.new([_s]))
     end
 
@@ -722,6 +866,11 @@ module Polars
     # Reduce this Series to the product value.
     #
     # @return [Numeric]
+    #
+    # @example
+    #   s = Polars::Series.new("a", [1, 2, 3])
+    #   s.product
+    #   # => 6
     def product
       to_frame.select(Polars.col(name).product).to_series[0]
     end
@@ -753,15 +902,35 @@ module Polars
     # Get maximum value, but propagate/poison encountered NaN values.
     #
     # @return [Object]
+    #
+    # @example
+    #   s = Polars::Series.new("a", [1, 3, 4])
+    #   s.nan_max
+    #   # => 4
+    #
+    # @example
+    #   s = Polars::Series.new("a", [1.0, Float::NAN, 4.0])
+    #   s.nan_max
+    #   # => NaN
     def nan_max
-      to_frame.select(Polars.col(name).nan_max)[0, 0]
+      to_frame.select(F.col(name).nan_max)[0, 0]
     end
 
     # Get minimum value, but propagate/poison encountered NaN values.
     #
     # @return [Object]
+    #
+    # @example
+    #   s = Polars::Series.new("a", [1, 3, 4])
+    #   s.nan_min
+    #   # => 1
+    #
+    # @example
+    #   s = Polars::Series.new("a", [1.0, Float::NAN, 4.0])
+    #   s.nan_min
+    #   # => NaN
     def nan_min
-      to_frame.select(Polars.col(name).nan_min)[0, 0]
+      to_frame.select(F.col(name).nan_min)[0, 0]
     end
 
     # Get the standard deviation of this Series.
@@ -1661,20 +1830,7 @@ module Polars
     def arg_sort(reverse: false, nulls_last: false)
       super
     end
-
-    # Get the index values that would sort this Series.
-    #
-    # Alias for {#arg_sort}.
-    #
-    # @param reverse [Boolean]
-    #   Sort in reverse (descending) order.
-    # @param nulls_last [Boolean]
-    #   Place null values last instead of first.
-    #
-    # @return [Series]
-    def argsort(reverse: false, nulls_last: false)
-      super
-    end
+    alias_method :argsort, :arg_sort
 
     # Get unique index as Series.
     #
@@ -1725,6 +1881,52 @@ module Polars
     #   Expression or scalar value.
     #
     # @return [Integer]
+    #
+    # @example
+    #   s = Polars::Series.new("set", [1, 2, 3, 4, 4, 5, 6, 7])
+    #   s.search_sorted(4)
+    #   # => 3
+    #
+    # @example
+    #   s.search_sorted(4, side: "left")
+    #   # => 3
+    #
+    # @example
+    #   s.search_sorted(4, side: "right")
+    #   # => 5
+    #
+    # @example
+    #   s.search_sorted([1, 4, 5])
+    #   # =>
+    #   # shape: (3,)
+    #   # Series: 'set' [u32]
+    #   # [
+    #   #         0
+    #   #         3
+    #   #         5
+    #   # ]
+    #
+    # @example
+    #   s.search_sorted([1, 4, 5], side: "left")
+    #   # =>
+    #   # shape: (3,)
+    #   # Series: 'set' [u32]
+    #   # [
+    #   #         0
+    #   #         3
+    #   #         5
+    #   # ]
+    #
+    # @example
+    #   s.search_sorted([1, 4, 5], side: "right")
+    #   # =>
+    #   # shape: (3,)
+    #   # Series: 'set' [u32]
+    #   # [
+    #   #         1
+    #   #         5
+    #   #         6
+    #   # ]
     def search_sorted(element, side: "any")
       if element.is_a?(Integer) || element.is_a?(Float)
         return Polars.select(Polars.lit(self).search_sorted(element, side: side)).item
@@ -1780,6 +1982,11 @@ module Polars
     # Count the null values in this Series.
     #
     # @return [Integer]
+    #
+    # @example
+    #   s = Polars::Series.new([1, nil, nil])
+    #   s.null_count
+    #   # => 2
     def null_count
       _s.null_count
     end
@@ -1790,6 +1997,15 @@ module Polars
     # Use this to swiftly assert a Series does not have null values.
     #
     # @return [Boolean]
+    #
+    # @example
+    #   s = Polars::Series.new([1, 2, nil])
+    #   s.has_nulls
+    #   # => true
+    #
+    # @example
+    #   s[...2].has_nulls
+    #   # => false
     def has_nulls
       _s.has_nulls
     end
@@ -2019,9 +2235,24 @@ module Polars
     # Get a mask of the first unique value.
     #
     # @return [Series]
-    def is_first
+    #
+    # @example
+    #   s = Polars::Series.new([1, 1, 2, 3, 2])
+    #   s.is_first_distinct
+    #   # =>
+    #   # shape: (5,)
+    #   # Series: '' [bool]
+    #   # [
+    #   #         true
+    #   #         false
+    #   #         true
+    #   #         true
+    #   #         false
+    #   # ]
+    def is_first_distinct
       super
     end
+    alias_method :is_first, :is_first_distinct
 
     # Get mask of all duplicated values.
     #
@@ -2187,6 +2418,35 @@ module Polars
     #   In place or not.
     #
     # @return [Series]
+    #
+    # @example
+    #   s1 = Polars::Series.new("a", [1, 2, 3])
+    #   s1.n_chunks
+    #   # => 1
+    #
+    # @example
+    #   s2 = Polars::Series.new("a", [4, 5, 6])
+    #   s = Polars.concat([s1, s2], rechunk: false)
+    #   s.n_chunks
+    #   # => 2
+    #
+    # @example
+    #   s.rechunk(in_place: true)
+    #   # =>
+    #   # shape: (6,)
+    #   # Series: 'a' [i64]
+    #   # [
+    #   #         1
+    #   #         2
+    #   #         3
+    #   #         4
+    #   #         5
+    #   #         6
+    #   # ]
+    #
+    # @example
+    #   s.n_chunks
+    #   # => 1
     def rechunk(in_place: false)
       opt_s = _s.rechunk(in_place)
       in_place ? self : Utils.wrap_s(opt_s)
@@ -2606,12 +2866,12 @@ module Polars
     #   s.sign
     #   # =>
     #   # shape: (5,)
-    #   # Series: 'a' [i64]
+    #   # Series: 'a' [f64]
     #   # [
-    #   #         -1
-    #   #         0
-    #   #         0
-    #   #         1
+    #   #         -1.0
+    #   #         -0.0
+    #   #         0.0
+    #   #         1.0
     #   #         null
     #   # ]
     def sign
@@ -3518,6 +3778,18 @@ module Polars
     #   If true, reinterpret as `:i64`. Otherwise, reinterpret as `:u64`.
     #
     # @return [Series]
+    #
+    # @example
+    #   s = Polars::Series.new("a", [-(2**60), -2, 3])
+    #   s.reinterpret(signed: false)
+    #   # =>
+    #   # shape: (3,)
+    #   # Series: 'a' [u64]
+    #   # [
+    #   #         17293822569102704640
+    #   #         18446744073709551614
+    #   #         3
+    #   # ]
     def reinterpret(signed: true)
       super
     end
@@ -3546,6 +3818,18 @@ module Polars
     # Compute absolute values.
     #
     # @return [Series]
+    #
+    # @example
+    #   s = Polars::Series.new([1, -2, -3])
+    #   s.abs
+    #   # =>
+    #   # shape: (3,)
+    #   # Series: '' [i64]
+    #   # [
+    #   #         1
+    #   #         2
+    #   #         3
+    #   # ]
     def abs
       super
     end
@@ -3616,6 +3900,44 @@ module Polars
     #   How to handle null values.
     #
     # @return [Series]
+    #
+    # @example
+    #   s = Polars::Series.new("s", [20, 10, 30, 25, 35], dtype: Polars::Int8)
+    #   s.diff
+    #   # =>
+    #   # shape: (5,)
+    #   # Series: 's' [i8]
+    #   # [
+    #   #         null
+    #   #         -10
+    #   #         20
+    #   #         -5
+    #   #         10
+    #   # ]
+    #
+    # @example
+    #   s.diff(n: 2)
+    #   # =>
+    #   # shape: (5,)
+    #   # Series: 's' [i8]
+    #   # [
+    #   #         null
+    #   #         null
+    #   #         10
+    #   #         15
+    #   #         5
+    #   # ]
+    #
+    # @example
+    #   s.diff(n: 2, null_behavior: "drop")
+    #   # =>
+    #   # shape: (3,)
+    #   # Series: 's' [i8]
+    #   # [
+    #   #         10
+    #   #         15
+    #   #         5
+    #   # ]
     def diff(n: 1, null_behavior: "ignore")
       super
     end
@@ -3683,6 +4005,11 @@ module Polars
     #   If `false`, the calculations are corrected for statistical bias.
     #
     # @return [Float, nil]
+    #
+    # @example
+    #   s = Polars::Series.new([1, 2, 2, 4, 5])
+    #   s.skew
+    #   # => 0.34776706224699483
     def skew(bias: true)
       _s.skew(bias)
     end
@@ -3702,6 +4029,19 @@ module Polars
     #   If `false`, the calculations are corrected for statistical bias.
     #
     # @return [Float, nil]
+    #
+    # @example
+    #   s = Polars::Series.new("grades", [66, 79, 54, 97, 96, 70, 69, 85, 93, 75])
+    #   s.kurtosis
+    #   # => -1.0522623626787952
+    #
+    # @example
+    #   s.kurtosis(fisher: false)
+    #   # => 1.9477376373212048
+    #
+    # @example
+    #   s.kurtosis(fisher: false, bias: false)
+    #   # => 2.1040361802642726
     def kurtosis(fisher: true, bias: true)
       _s.kurtosis(fisher, bias)
     end
@@ -3845,6 +4185,35 @@ module Polars
     #   dimension is inferred.
     #
     # @return [Series]
+    #
+    # @example
+    #   s = Polars::Series.new("foo", [1, 2, 3, 4, 5, 6, 7, 8, 9])
+    #   square = s.reshape([3, 3])
+    #   # =>
+    #   # shape: (3,)
+    #   # Series: 'foo' [array[i64, 3]]
+    #   # [
+    #   #         [1, 2, 3]
+    #   #         [4, 5, 6]
+    #   #         [7, 8, 9]
+    #   # ]
+    #
+    # @example
+    #   square.reshape([9])
+    #   # =>
+    #   # shape: (9,)
+    #   # Series: 'foo' [i64]
+    #   # [
+    #   #         1
+    #   #         2
+    #   #         3
+    #   #         4
+    #   #         5
+    #   #         6
+    #   #         7
+    #   #         8
+    #   #         9
+    #   # ]
     def reshape(dims)
       super
     end
@@ -3874,6 +4243,18 @@ module Polars
     # Exponentially-weighted moving average.
     #
     # @return [Series]
+    #
+    # @example
+    #   s = Polars::Series.new([1, 2, 3])
+    #   s.ewm_mean(com: 1, ignore_nulls: false)
+    #   # =>
+    #   # shape: (3,)
+    #   # Series: '' [f64]
+    #   # [
+    #   #         1.0
+    #   #         1.666667
+    #   #         2.428571
+    #   # ]
     def ewm_mean(
       com: nil,
       span: nil,
@@ -3889,6 +4270,18 @@ module Polars
     # Exponentially-weighted moving standard deviation.
     #
     # @return [Series]
+    #
+    # @example
+    #   s = Polars::Series.new("a", [1, 2, 3])
+    #   s.ewm_std(com: 1, ignore_nulls: false)
+    #   # =>
+    #   # shape: (3,)
+    #   # Series: 'a' [f64]
+    #   # [
+    #   #         0.0
+    #   #         0.707107
+    #   #         0.963624
+    #   # ]
     def ewm_std(
       com: nil,
       span: nil,
@@ -3905,6 +4298,18 @@ module Polars
     # Exponentially-weighted moving variance.
     #
     # @return [Series]
+    #
+    # @example
+    #   s = Polars::Series.new("a", [1, 2, 3])
+    #   s.ewm_var(com: 1, ignore_nulls: false)
+    #   # =>
+    #   # shape: (3,)
+    #   # Series: 'a' [f64]
+    #   # [
+    #   #         0.0
+    #   #         0.5
+    #   #         0.928571
+    #   # ]
     def ewm_var(
       com: nil,
       span: nil,
@@ -3969,6 +4374,18 @@ module Polars
     # Create a new Series filled with values from the given index.
     #
     # @return [Series]
+    #
+    # @example
+    #   s = Polars::Series.new("a", [1, 2, 3, 4, 5])
+    #   s.new_from_index(1, 3)
+    #   # =>
+    #   # shape: (3,)
+    #   # Series: 'a' [i64]
+    #   # [
+    #   #         2
+    #   #         2
+    #   #         2
+    #   # ]
     def new_from_index(index, length)
       Utils.wrap_s(_s.new_from_index(index, length))
     end
@@ -3979,6 +4396,21 @@ module Polars
     # This can be used to reduce memory pressure.
     #
     # @return [Series]
+    #
+    # @example
+    #   s = Polars::Series.new("a", [1, 2, 3, 4, 5, 6])
+    #   s.shrink_dtype
+    #   # =>
+    #   # shape: (6,)
+    #   # Series: 'a' [i8]
+    #   # [
+    #   #         1
+    #   #         2
+    #   #         3
+    #   #         4
+    #   #         5
+    #   #         6
+    #   # ]
     def shrink_dtype
       super
     end
@@ -4264,12 +4696,10 @@ module Polars
         end
 
         constructor = polars_type_to_constructor(dtype)
-        # TODO remove
-        strict = false if dtype == Decimal
         rbseries = constructor.call(name, values, strict)
 
         base_type = dtype.is_a?(DataType) ? dtype.class : dtype
-        if [Date, Datetime, Duration, Time, Categorical, Boolean, Enum].include?(base_type)
+        if [Date, Datetime, Duration, Time, Categorical, Boolean, Enum, Decimal].include?(base_type)
           if rbseries.dtype != dtype
             rbseries = rbseries.cast(dtype, true)
           end