Class: Polars::Series

Inherits:
Object
  • Object
show all
Defined in:
lib/polars/series.rb

Overview

A Series represents a single column in a polars DataFrame.

Instance Method Summary collapse

Constructor Details

#initialize(name = nil, values = nil, dtype: nil, strict: true, nan_to_null: false, dtype_if_empty: nil) ⇒ Series

Create a new Series.

Examples:

Constructing a Series by specifying name and values positionally:

s = Polars::Series.new("a", [1, 2, 3])

Notice that the dtype is automatically inferred as a polars Int64:

s.dtype
# => Polars::Int64

Constructing a Series with a specific dtype:

s2 = Polars::Series.new("a", [1, 2, 3], dtype: :f32)

It is possible to construct a Series with values as the first positional argument. This syntax considered an anti-pattern, but it can be useful in certain scenarios. You must specify any other arguments through keywords.

s3 = Polars::Series.new([1, 2, 3])

Parameters:

  • name (String, Array, nil) (defaults to: nil) —

    Name of the series. Will be used as a column name when used in a DataFrame. When not specified, name is set to an empty string.

  • values (Array, nil) (defaults to: nil) —

    One-dimensional data in various forms. Supported are: Array and Series.

  • dtype (Symbol, nil) (defaults to: nil) —

    Polars dtype of the Series data. If not specified, the dtype is inferred.

  • strict (Boolean) (defaults to: true) —

    Throw error on numeric overflow.

  • nan_to_null (Boolean) (defaults to: false) —

    Not used.

  • dtype_if_empty (Symbol, nil) (defaults to: nil) —

    If no dtype is specified and values contains nil or an empty array, set the Polars dtype of the Series data. If not specified, Float32 is used.



35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
 
# File 'lib/polars/series.rb', line 35

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 values.nil?
      values = name
      name = nil
    else
      raise ArgumentError, "Series name must be a string."
    end
  end

  name = "" if name.nil?

  # TODO improve
  if values.is_a?(Range) && values.begin.is_a?(::String)
    values = values.to_a
  end

  if values.nil?
    self._s = sequence_to_rbseries(name, [], dtype: dtype, dtype_if_empty: dtype_if_empty)
  elsif values.is_a?(Series)
    self._s = series_to_rbseries(name, values)
  elsif values.is_a?(Range)
    self._s =
      Polars.arange(
        values.first,
        values.last + (values.exclude_end? ? 0 : 1),
        step: 1,
        eager: true,
        dtype: dtype
      )
      .rename(name, in_place: true)
      ._s
  elsif values.is_a?(::Array)
    self._s = sequence_to_rbseries(name, values, dtype: dtype, strict: strict, dtype_if_empty: dtype_if_empty)
  elsif defined?(Numo::NArray) && values.is_a?(Numo::NArray)
    self._s = numo_to_rbseries(name, values, strict: strict, nan_to_null: nan_to_null)

    if !dtype.nil?
      self._s = self.cast(dtype, strict: true)._s
    end
  else
    raise ArgumentError, "Series constructor called with unsupported type; got #{values.class.name}"
  end
end

Dynamic Method Handling

This class handles dynamic methods through the method_missing method in the class Polars::ExprDispatch

Instance Method Details

#! ⇒ Series

Performs boolean not.

Returns:

Raises:

  • (NotImplementedError) 


408
409
410
411
412
413
 
# File 'lib/polars/series.rb', line 408

def !
  if dtype == Boolean
    return Utils.wrap_s(_s.not_)
  end
  raise NotImplementedError
end

#!=(other) ⇒ Series

Not equal.

Returns:



191
192
193
 
# File 'lib/polars/series.rb', line 191

def !=(other)
  _comp(other, :neq)
end

#%(other) ⇒ Series

Returns the modulo.

Returns:



388
389
390
391
392
393
 
# File 'lib/polars/series.rb', line 388

def %(other)
  if is_datelike
    raise ArgumentError, "first cast to integer before applying modulo on datelike dtypes"
  end
  _arithmetic(other, :rem)
end

#&(other) ⇒ Series

Bitwise AND.

Returns:



154
155
156
157
158
159
 
# File 'lib/polars/series.rb', line 154

def &(other)
  if !other.is_a?(Series)
    other = Series.new([other])
  end
  Utils.wrap_s(_s.bitand(other._s))
end

#*(other) ⇒ Series

Performs multiplication.

Returns:



360
361
362
363
364
365
366
367
368
 
# File 'lib/polars/series.rb', line 360

def *(other)
  if is_temporal
    raise ArgumentError, "first cast to integer before multiplying datelike dtypes"
  elsif other.is_a?(DataFrame)
    other * self
  else
    _arithmetic(other, :mul)
  end
end

#**(power) ⇒ Series

Raises to the power of exponent.

Returns:



398
399
400
401
402
403
 
# File 'lib/polars/series.rb', line 398

def **(power)
  if is_datelike
    raise ArgumentError, "first cast to integer before raising datelike dtypes to a power"
  end
  to_frame.select(Polars.col(name).pow(power)).to_series
end

#+(other) ⇒ Series

Performs addition.

Returns:



346
347
348
 
# File 'lib/polars/series.rb', line 346

def +(other)
  _arithmetic(other, :add)
end

#-(other) ⇒ Series

Performs subtraction.

Returns:



353
354
355
 
# File 'lib/polars/series.rb', line 353

def -(other)
  _arithmetic(other, :sub)
end

#-@ ⇒ Series

Performs negation.

Returns:



418
419
420
 
# File 'lib/polars/series.rb', line 418

def -@
  0 - self
end

#/(other) ⇒ Series

Performs division.

Returns:



373
374
375
376
377
378
379
380
381
382
383
 
# File 'lib/polars/series.rb', line 373

def /(other)
  if is_temporal
    raise ArgumentError, "first cast to integer before dividing datelike dtypes"
  end

  if is_float
    return _arithmetic(other, :div)
  end

  cast(Float64) / other
end

#<(other) ⇒ Series

Less than.

Returns:



205
206
207
 
# File 'lib/polars/series.rb', line 205

def <(other)
  _comp(other, :lt)
end

#<=(other) ⇒ Series

Less than or equal.

Returns:



219
220
221
 
# File 'lib/polars/series.rb', line 219

def <=(other)
  _comp(other, :lt_eq)
end

#==(other) ⇒ Series

Equal.

Returns:



184
185
186
 
# File 'lib/polars/series.rb', line 184

def ==(other)
  _comp(other, :eq)
end

#>(other) ⇒ Series

Greater than.

Returns:



198
199
200
 
# File 'lib/polars/series.rb', line 198

def >(other)
  _comp(other, :gt)
end

#>=(other) ⇒ Series

Greater than or equal.

Returns:



212
213
214
 
# File 'lib/polars/series.rb', line 212

def >=(other)
  _comp(other, :gt_eq)
end

#[](item) ⇒ Object

Returns elements of the Series.

Returns:

Raises:

  • (ArgumentError) 


436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
 
# File 'lib/polars/series.rb', line 436

def [](item)
  if item.is_a?(Series) && [UInt8, UInt16, UInt32, UInt64, Int8, Int16, Int32, Int64].include?(item.dtype)
    return Utils.wrap_s(_s.take_with_series(_pos_idxs(item)._s))
  end

  if item.is_a?(Series) && item.bool?
    return filter(item)
  end

  if item.is_a?(Integer)
    if item < 0
      item = len + item
    end

    return _s.get_index(item)
  end

  if item.is_a?(Range)
    return Slice.new(self).apply(item)
  end

  if Utils.is_int_sequence(item)
    return Utils.wrap_s(_s.take_with_series(_pos_idxs(Series.new("", item))._s))
  end

  raise ArgumentError, "Cannot get item of type: #{item.class.name}"
end

#[]=(key, value) ⇒ Object

Sets an element of the Series.

Returns:



467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
 
# File 'lib/polars/series.rb', line 467

def []=(key, value)
  if value.is_a?(::Array)
    if is_numeric || is_datelike
      scatter(key, value)
      return
    end
    raise ArgumentError, "cannot set Series of dtype: #{dtype} with list/tuple as value; use a scalar value"
  end

  if key.is_a?(Series)
    if key.dtype == Boolean
      self._s = set(key, value)._s
    elsif key.dtype == UInt64
      self._s = scatter(key.cast(UInt32), value)._s
    elsif key.dtype == UInt32
      self._s = scatter(key, value)._s
    else
      raise Todo
    end
  elsif key.is_a?(::Array)
    s = Utils.wrap_s(sequence_to_rbseries("", key, dtype: UInt32))
    self[s] = value
  elsif key.is_a?(Range)
    s = Series.new("", key, dtype: UInt32)
    self[s] = value
  elsif key.is_a?(Integer)
    self[[key]] = value
  else
    raise ArgumentError, "cannot use #{key} for indexing"
  end
end

#^(other) ⇒ Series

Bitwise XOR.

Returns:



174
175
176
177
178
179
 
# File 'lib/polars/series.rb', line 174

def ^(other)
  if !other.is_a?(Series)
    other = Series.new([other])
  end
  Utils.wrap_s(_s.bitxor(other._s))
end

#_hash(seed = 0, seed_1 = nil, seed_2 = nil, seed_3 = nil) ⇒ Series

Hash the Series.

The hash value is of type :u64.

Examples:

s = Polars::Series.new("a", [1, 2, 3])
s._hash(42)
# =>
# shape: (3,)
# Series: 'a' [u64]
# [
#         2374023516666777365
#         10386026231460783898
#         17796317186427479491
# ]

Parameters:

  • seed (Integer) (defaults to: 0) —

    Random seed parameter. Defaults to 0.

  • seed_1 (Integer) (defaults to: nil) —

    Random seed parameter. Defaults to seed if not set.

  • seed_2 (Integer) (defaults to: nil) —

    Random seed parameter. Defaults to seed if not set.

  • seed_3 (Integer) (defaults to: nil) —

    Random seed parameter. Defaults to seed if not set.

Returns:



4409
4410
4411
 
# File 'lib/polars/series.rb', line 4409

def _hash(seed = 0, seed_1 = nil, seed_2 = nil, seed_3 = nil)
  super
end

#abs ⇒ Series

Compute absolute values.

Examples:

s = Polars::Series.new([1, -2, -3])
s.abs
# =>
# shape: (3,)
# Series: '' [i64]
# [
#         1
#         2
#         3
# ]

Returns:



4498
4499
4500
 
# File 'lib/polars/series.rb', line 4498

def abs
  super
end

#alias(name) ⇒ Series

Return a copy of the Series with a new alias/name.

Examples:

s = Polars::Series.new("x", [1, 2, 3])
s.alias("y")

Parameters:

Returns:



1542
1543
1544
1545
1546
 
# File 'lib/polars/series.rb', line 1542

def alias(name)
  s = dup
  s._s.rename(name)
  s
end

#all?(ignore_nulls: true, &block) ⇒ Boolean Also known as: all

Check if all boolean values in the column are true.

Examples:

Polars::Series.new([true, true]).all?
# => true

Polars::Series.new([false, true]).all?
# => false

Polars::Series.new([nil, true]).all?
# => true

Returns:



638
639
640
641
642
643
644
 
# File 'lib/polars/series.rb', line 638

def all?(ignore_nulls: true, &block)
  if block_given?
    apply(return_dtype: Boolean, skip_nulls: ignore_nulls, &block).all?
  else
    _s.all(ignore_nulls)
  end
end

#any?(ignore_nulls: true, &block) ⇒ Boolean Also known as: any

Check if any boolean value in the column is true.

Examples:

Polars::Series.new([true, false]).any?
# => true

Polars::Series.new([false, false]).any?
# => false

Polars::Series.new([nil, false]).any?
# => false

Returns:



614
615
616
617
618
619
620
 
# File 'lib/polars/series.rb', line 614

def any?(ignore_nulls: true, &block)
  if block_given?
    apply(return_dtype: Boolean, skip_nulls: ignore_nulls, &block).any?
  else
    _s.any(ignore_nulls)
  end
end

#append(other, append_chunks: true) ⇒ Series

Append a Series to this one.

Examples:

s = Polars::Series.new("a", [1, 2, 3])
s2 = Polars::Series.new("b", [4, 5, 6])
s.append(s2)
# =>
# shape: (6,)
# Series: 'a' [i64]
# [
#         1
#         2
#         3
#         4
#         5
#         6
# ]

Parameters:

  • other (Series) —

    Series to append.

  • append_chunks (Boolean) (defaults to: true) —

    If set to true the append operation will add the chunks from other to self. This is super cheap.

    If set to false the append operation will do the same as DataFrame#extend which extends the memory backed by this Series with the values from other.

    Different from append_chunks, extend appends the data from other to the underlying memory locations and thus may cause a reallocation (which is expensive).

    If this does not cause a reallocation, the resulting data structure will not have any extra chunks and thus will yield faster queries.

    Prefer extend over append_chunks when you want to do a query after a single append. For instance during online operations where you add n rows and rerun a query.

    Prefer append_chunks over extend when you want to append many times before doing a query. For instance, when you read in multiple files and when to store them in a single Series. In the latter case, finish the sequence of append_chunks operations with a rechunk.

Returns:



1799
1800
1801
1802
1803
1804
1805
1806
1807
1808
1809
1810
1811
1812
1813
1814
 
# File 'lib/polars/series.rb', line 1799

def append(other, append_chunks: true)
  begin
    if append_chunks
      _s.append(other._s)
    else
      _s.extend(other._s)
    end
  rescue => e
    if e.message == "Already mutably borrowed"
      append(other.clone, append_chunks)
    else
      raise e
    end
  end
  self
end

#approx_n_unique ⇒ Object

Approximate count of unique values.

This is done using the HyperLogLog++ algorithm for cardinality estimation.

Returns:



5443
5444
5445
 
# File 'lib/polars/series.rb', line 5443

def approx_n_unique
  _s.approx_n_unique
end

#arccos ⇒ Series Also known as: acos

Compute the element-wise value for the inverse cosine.

Examples:

s = Polars::Series.new("a", [1.0, 0.0, -1.0])
s.arccos
# =>
# shape: (3,)
# Series: 'a' [f64]
# [
#         0.0
#         1.570796
#         3.141593
# ]

Returns:



3563
3564
3565
 
# File 'lib/polars/series.rb', line 3563

def arccos
  super
end

#arccosh ⇒ Series Also known as: acosh

Compute the element-wise value for the inverse hyperbolic cosine.

Examples:

s = Polars::Series.new("a", [5.0, 1.0, 0.0, -1.0])
s.arccosh
# =>
# shape: (4,)
# Series: 'a' [f64]
# [
#         2.292432
#         0.0
#         NaN
#         NaN
# ]

Returns:



3624
3625
3626
 
# File 'lib/polars/series.rb', line 3624

def arccosh
  super
end

#arcsin ⇒ Series Also known as: asin

Compute the element-wise value for the inverse sine.

Examples:

s = Polars::Series.new("a", [1.0, 0.0, -1.0])
s.arcsin
# =>
# shape: (3,)
# Series: 'a' [f64]
# [
#         1.570796
#         0.0
#         -1.570796
# ]

Returns:



3543
3544
3545
 
# File 'lib/polars/series.rb', line 3543

def arcsin
  super
end

#arcsinh ⇒ Series Also known as: asinh

Compute the element-wise value for the inverse hyperbolic sine.

Examples:

s = Polars::Series.new("a", [1.0, 0.0, -1.0])
s.arcsinh
# =>
# shape: (3,)
# Series: 'a' [f64]
# [
#         0.881374
#         0.0
#         -0.881374
# ]

Returns:



3603
3604
3605
 
# File 'lib/polars/series.rb', line 3603

def arcsinh
  super
end

#arctan ⇒ Series Also known as: atan

Compute the element-wise value for the inverse tangent.

Examples:

s = Polars::Series.new("a", [1.0, 0.0, -1.0])
s.arctan
# =>
# shape: (3,)
# Series: 'a' [f64]
# [
#         0.785398
#         0.0
#         -0.785398
# ]

Returns:



3583
3584
3585
 
# File 'lib/polars/series.rb', line 3583

def arctan
  super
end

#arctanh ⇒ Series Also known as: atanh

Compute the element-wise value for the inverse hyperbolic tangent.

Examples:

s = Polars::Series.new("a", [2.0, 1.0, 0.5, 0.0, -0.5, -1.0, -1.1])
s.arctanh
# =>
# shape: (7,)
# Series: 'a' [f64]
# [
#         NaN
#         inf
#         0.549306
#         0.0
#         -0.549306
#         -inf
#         NaN
# ]

Returns:



3648
3649
3650
 
# File 'lib/polars/series.rb', line 3648

def arctanh
  super
end

#arg_max ⇒ Integer?

Get the index of the maximal value.

Examples:

s = Polars::Series.new("a", [3, 2, 1])
s.arg_max
# => 0

Returns:

  • (Integer, nil) 


2170
2171
2172
 
# File 'lib/polars/series.rb', line 2170

def arg_max
  _s.arg_max
end

#arg_min ⇒ Integer?

Get the index of the minimal value.

Examples:

s = Polars::Series.new("a", [3, 2, 1])
s.arg_min
# => 2

Returns:

  • (Integer, nil) 


2158
2159
2160
 
# File 'lib/polars/series.rb', line 2158

def arg_min
  _s.arg_min
end

#arg_sort(reverse: false, nulls_last: false) ⇒ Series Also known as: argsort

Get the index values that would sort this Series.

Examples:

s = Polars::Series.new("a", [5, 3, 4, 1, 2])
s.arg_sort
# =>
# shape: (5,)
# Series: 'a' [u32]
# [
#         3
#         4
#         1
#         2
#         0
# ]

Parameters:

  • reverse (Boolean) (defaults to: false) —

    Sort in reverse (descending) order.

  • nulls_last (Boolean) (defaults to: false) —

    Place null values last instead of first.

Returns:



2126
2127
2128
 
# File 'lib/polars/series.rb', line 2126

def arg_sort(reverse: false, nulls_last: false)
  super
end

#arg_true ⇒ Series

Get index values where Boolean Series evaluate true.

Examples:

s = Polars::Series.new("a", [1, 2, 3])
(s == 2).arg_true
# =>
# shape: (1,)
# Series: 'a' [u32]
# [
#         1
# ]

Returns:



2572
2573
2574
 
# File 'lib/polars/series.rb', line 2572

def arg_true
  Polars.arg_where(self, eager: true)
end

#arg_unique ⇒ Series

Get unique index as Series.

Examples:

s = Polars::Series.new("a", [1, 2, 2, 3])
s.arg_unique
# =>
# shape: (3,)
# Series: 'a' [u32]
# [
#         0
#         1
#         3
# ]

Returns:



2146
2147
2148
 
# File 'lib/polars/series.rb', line 2146

def arg_unique
  super
end

#arr ⇒ ArrayNameSpace

Create an object namespace of all array related methods.

Returns:



5457
5458
5459
 
# File 'lib/polars/series.rb', line 5457

def arr
  ArrayNameSpace.new(self)
end

#backward_fill(limit: nil) ⇒ Series

Fill missing values with the next non-null value.

This is an alias of .fill_null(strategy: "backward").

Parameters:

  • limit (Integer) (defaults to: nil) —

    The number of consecutive null values to backward fill.

Returns:



3287
3288
3289
 
# File 'lib/polars/series.rb', line 3287

def backward_fill(limit: nil)
  fill_null(strategy: "backward", limit: limit)
end

#bin ⇒ BinaryNameSpace

Create an object namespace of all binary related methods.

Returns:



5464
5465
5466
 
# File 'lib/polars/series.rb', line 5464

def bin
  BinaryNameSpace.new(self)
end

#bitwise_and ⇒ Object

Perform an aggregation of bitwise ANDs.

Returns:



5402
5403
5404
 
# File 'lib/polars/series.rb', line 5402

def bitwise_and
  _s.bitwise_and
end

#bitwise_count_ones ⇒ Series

Evaluate the number of set bits.

Returns:



5360
5361
5362
 
# File 'lib/polars/series.rb', line 5360

def bitwise_count_ones
  super
end

#bitwise_count_zeros ⇒ Series

Evaluate the number of unset bits.

Returns:



5367
5368
5369
 
# File 'lib/polars/series.rb', line 5367

def bitwise_count_zeros
  super
end

#bitwise_leading_ones ⇒ Series

Evaluate the number most-significant set bits before seeing an unset bit.

Returns:



5374
5375
5376
 
# File 'lib/polars/series.rb', line 5374

def bitwise_leading_ones
  super
end

#bitwise_leading_zeros ⇒ Series

Evaluate the number most-significant unset bits before seeing a set bit.

Returns:



5381
5382
5383
 
# File 'lib/polars/series.rb', line 5381

def bitwise_leading_zeros
  super
end

#bitwise_or ⇒ Object

Perform an aggregation of bitwise ORs.

Returns:



5409
5410
5411
 
# File 'lib/polars/series.rb', line 5409

def bitwise_or
  _s.bitwise_or
end

#bitwise_trailing_ones ⇒ Series

Evaluate the number least-significant set bits before seeing an unset bit.

Returns:



5388
5389
5390
 
# File 'lib/polars/series.rb', line 5388

def bitwise_trailing_ones
  super
end

#bitwise_trailing_zeros ⇒ Series

Evaluate the number least-significant unset bits before seeing a set bit.

Returns:



5395
5396
5397
 
# File 'lib/polars/series.rb', line 5395

def bitwise_trailing_zeros
  super
end

#bitwise_xor ⇒ Object

Perform an aggregation of bitwise XORs.

Returns:



5416
5417
5418
 
# File 'lib/polars/series.rb', line 5416

def bitwise_xor
  _s.bitwise_xor
end

#bottom_k(k: 5) ⇒ Boolean

Return the k smallest elements.

Examples:

s = Polars::Series.new("a", [2, 5, 1, 4, 3])
s.bottom_k(k: 3)
# =>
# shape: (3,)
# Series: 'a' [i64]
# [
#         1
#         2
#         3
# ]

Parameters:

  • k (Integer) (defaults to: 5) —

    Number of elements to return.

Returns:



2062
2063
2064
 
# File 'lib/polars/series.rb', line 2062

def bottom_k(k: 5)
  super
end

#bottom_k_by(by, k: 5, reverse: false) ⇒ Series

Return the k smallest elements of the by column.

Non-null elements are always preferred over null elements, regardless of the value of reverse. The output is not guaranteed to be in any particular order, call sort after this function if you wish the output to be sorted.

Examples:

s = Polars::Series.new("a", [2, 5, 1, 4, 3])
s.bottom_k_by("a", k: 3)
# =>
# shape: (3,)
# Series: 'a' [i64]
# [
#         1
#         2
#         3
# ]

Parameters:

  • by (Object) —

    Column used to determine the smallest elements. Accepts expression input. Strings are parsed as column names.

  • k (Integer) (defaults to: 5) —

    Number of elements to return.

  • reverse (Object) (defaults to: false) —

    Consider the k largest elements of the by column( (instead of the k smallest). This can be specified per column by passing a sequence of booleans.

Returns:



2096
2097
2098
2099
2100
2101
2102
 
# File 'lib/polars/series.rb', line 2096

def bottom_k_by(
  by,
  k: 5,
  reverse: false
)
  super
end

#cast(dtype, strict: true) ⇒ Series

Cast between data types.

Examples:

s = Polars::Series.new("a", [true, false, true])
s.cast(:u32)
# =>
# shape: (3,)
# Series: 'a' [u32]
# [
#         1
#         0
#         1
# ]

Parameters:

  • dtype (Symbol) —

    DataType to cast to

  • strict (Boolean) (defaults to: true) —

    Throw an error if a cast could not be done for instance due to an overflow

Returns:



2755
2756
2757
 
# File 'lib/polars/series.rb', line 2755

def cast(dtype, strict: true)
  super
end

#cat ⇒ CatNameSpace

Create an object namespace of all categorical related methods.

Returns:



5471
5472
5473
 
# File 'lib/polars/series.rb', line 5471

def cat
  CatNameSpace.new(self)
end

#cbrt ⇒ Series

Compute the cube root of the elements.

Examples:

s = Polars::Series.new([1, 2, 3])
s.cbrt
# =>
# shape: (3,)
# Series: '' [f64]
# [
#         1.0
#         1.259921
#         1.44225
# ]

Returns:



595
596
597
 
# File 'lib/polars/series.rb', line 595

def cbrt
  super
end

#ceil ⇒ Series

Rounds up to the nearest integer value.

Only works on floating point Series.

Examples:

s = Polars::Series.new("a", [1.12345, 2.56789, 3.901234])
s.ceil
# =>
# shape: (3,)
# Series: 'a' [f64]
# [
#         2.0
#         3.0
#         4.0
# ]

Returns:



3341
3342
3343
 
# File 'lib/polars/series.rb', line 3341

def ceil
  super
end

#chunk_lengths ⇒ Array

Get the length of each individual chunk.

Examples:

s = Polars::Series.new("a", [1, 2, 3])
s2 = Polars::Series.new("b", [4, 5, 6])

Concatenate Series with rechunk: true

Polars.concat([s, s2]).chunk_lengths
# => [6]

Concatenate Series with rechunk: false

Polars.concat([s, s2], rechunk: false).chunk_lengths
# => [3, 3]

Returns:



1584
1585
1586
 
# File 'lib/polars/series.rb', line 1584

def chunk_lengths
  _s.chunk_lengths
end

#clear(n: 0) ⇒ Series Also known as: cleared

Create an empty copy of the current Series.

The copy has identical name/dtype but no data.

Examples:

s = Polars::Series.new("a", [nil, true, false])
s.clear
# =>
# shape: (0,)
# Series: 'a' [bool]
# [
# ]

s.clear(n: 2)
# =>
# shape: (2,)
# Series: 'a' [bool]
# [
#         null
#         null
# ]

Parameters:

  • n (Integer) (defaults to: 0) —

    Number of (empty) elements to return in the cleared frame.

Returns:



3188
3189
3190
3191
3192
3193
3194
3195
3196
3197
3198
3199
 
# File 'lib/polars/series.rb', line 3188

def clear(n: 0)
  if n < 0
    msg = "`n` should be greater than or equal to 0, got #{n}"
    raise ArgumentError, msg
  end
  # faster path
  if n == 0
    return self.class._from_rbseries(_s.clear)
  end
  s = len > 0 ? self.class.new(name, [], dtype: dtype) : clone
  n > 0 ? s.extend_constant(nil, n) : s
end

#clip(min_val = nil, max_val = nil) ⇒ Series

Clip (limit) the values in an array to a min and max boundary.

Only works for numerical types.

If you want to clip other dtypes, consider writing a "when, then, otherwise" expression. See Functions#when for more information.

Examples:

s = Polars::Series.new("foo", [-50, 5, nil, 50])
s.clip(1, 10)
# =>
# shape: (4,)
# Series: 'foo' [i64]
# [
#         1
#         5
#         null
#         10
# ]

Parameters:

  • min_val (Numeric) (defaults to: nil) —

    Minimum value.

  • max_val (Numeric) (defaults to: nil) —

    Maximum value.

Returns:



4740
4741
4742
 
# File 'lib/polars/series.rb', line 4740

def clip(min_val = nil, max_val = nil)
  super
end

#clip_max(max_val) ⇒ Series

Clip (limit) the values in an array to a max boundary.

Only works for numerical types.

If you want to clip other dtypes, consider writing a "when, then, otherwise" expression. See Functions#when for more information.

Parameters:

  • max_val (Numeric) —

    Maximum value.

Returns:



4770
4771
4772
 
# File 'lib/polars/series.rb', line 4770

def clip_max(max_val)
  super
end

#clip_min(min_val) ⇒ Series

Clip (limit) the values in an array to a min boundary.

Only works for numerical types.

If you want to clip other dtypes, consider writing a "when, then, otherwise" expression. See Functions#when for more information.

Parameters:

  • min_val (Numeric) —

    Minimum value.

Returns:



4755
4756
4757
 
# File 'lib/polars/series.rb', line 4755

def clip_min(min_val)
  super
end

#cos ⇒ Series

Compute the element-wise value for the cosine.

Examples:

s = Polars::Series.new("a", [0.0, Math::PI / 2.0, Math::PI])
s.cos
# =>
# shape: (3,)
# Series: 'a' [f64]
# [
#         1.0
#         6.1232e-17
#         -1.0
# ]

Returns:



3486
3487
3488
 
# File 'lib/polars/series.rb', line 3486

def cos
  super
end

#cosh ⇒ Series

Compute the element-wise value for the hyperbolic cosine.

Examples:

s = Polars::Series.new("a", [1.0, 0.0, -1.0])
s.cosh
# =>
# shape: (3,)
# Series: 'a' [f64]
# [
#         1.543081
#         1.0
#         1.543081
# ]

Returns:



3687
3688
3689
 
# File 'lib/polars/series.rb', line 3687

def cosh
  super
end

#cot ⇒ Series

Compute the element-wise value for the cotangent.

Examples:

s = Polars::Series.new("a", [0.0, Math::PI / 2.0, Math::PI])
s.cot
# =>
# shape: (3,)
# Series: 'a' [f64]
# [
#         inf
#         6.1232e-17
#         -8.1656e15
# ]

Returns:



3524
3525
3526
 
# File 'lib/polars/series.rb', line 3524

def cot
  super
end

#count ⇒ Integer

Return the number of elements in the Series.

Examples:

s = Polars::Series.new("a", [1, 2, nil])
s.count
# => 2

Returns:

  • (Integer) 


2717
2718
2719
 
# File 'lib/polars/series.rb', line 2717

def count
  len - null_count
end

#cum_count(reverse: false) ⇒ Series

Return the cumulative count of the non-null values in the column.

Examples:

s = Polars::Series.new(["x", "k", nil, "d"])
s.cum_count
# =>
# shape: (4,)
# Series: '' [u32]
# [
#         1
#         2
#         2
#         3
# ]

Parameters:

  • reverse (Boolean) (defaults to: false) —

    Reverse the operation.

Returns:



1653
1654
1655
 
# File 'lib/polars/series.rb', line 1653

def cum_count(reverse: false)
  super
end

#cum_max(reverse: false) ⇒ Series Also known as: cummax

Get an array with the cumulative max computed at every element.

Examples:

s = Polars::Series.new("a", [3, 5, 1])
s.cum_max
# =>
# shape: (3,)
# Series: 'a' [i64]
# [
#         3
#         5
#         5
# ]

Parameters:

  • reverse (Boolean) (defaults to: false) —

    reverse the operation.

Returns:



1698
1699
1700
 
# File 'lib/polars/series.rb', line 1698

def cum_max(reverse: false)
  super
end

#cum_min(reverse: false) ⇒ Series Also known as: cummin

Get an array with the cumulative min computed at every element.

Examples:

s = Polars::Series.new("a", [3, 5, 1])
s.cum_min
# =>
# shape: (3,)
# Series: 'a' [i64]
# [
#         3
#         3
#         1
# ]

Parameters:

  • reverse (Boolean) (defaults to: false) —

    reverse the operation.

Returns:



1675
1676
1677
 
# File 'lib/polars/series.rb', line 1675

def cum_min(reverse: false)
  super
end

#cum_prod(reverse: false) ⇒ Series Also known as: cumprod

Note:

Dtypes :i8, :u8, :i16, and :u16 are cast to :i64 before multiplying to prevent overflow issues.

Get an array with the cumulative product computed at every element.

Examples:

s = Polars::Series.new("a", [1, 2, 3])
s.cum_prod
# =>
# shape: (3,)
# Series: 'a' [i64]
# [
#         1
#         2
#         6
# ]

Parameters:

  • reverse (Boolean) (defaults to: false) —

    reverse the operation.

Returns:



1725
1726
1727
 
# File 'lib/polars/series.rb', line 1725

def cum_prod(reverse: false)
  super
end

#cum_sum(reverse: false) ⇒ Series Also known as: cumsum

Note:

Dtypes :i8, :u8, :i16, and :u16 are cast to :i64 before summing to prevent overflow issues.

Get an array with the cumulative sum computed at every element.

Examples:

s = Polars::Series.new("a", [1, 2, 3])
s.cum_sum
# =>
# shape: (3,)
# Series: 'a' [i64]
# [
#         1
#         3
#         6
# ]

Parameters:

  • reverse (Boolean) (defaults to: false) —

    reverse the operation.

Returns:



1629
1630
1631
 
# File 'lib/polars/series.rb', line 1629

def cum_sum(reverse: false)
  super
end

#cumulative_eval(expr, min_periods: 1) ⇒ Series

Note:

This functionality is experimental and may change without it being considered a breaking change.

Note:

This can be really slow as it can have O(n^2) complexity. Don't use this for operations that visit all elements.

Run an expression over a sliding window that increases 1 slot every iteration.

Examples:

s = Polars::Series.new("values", [1, 2, 3, 4, 5])
s.cumulative_eval(Polars.element.first - Polars.element.last ** 2)
# =>
# shape: (5,)
# Series: 'values' [i64]
# [
#         0
#         -3
#         -8
#         -15
#         -24
# ]

Parameters:

  • expr (Expr) —

    Expression to evaluate

  • min_periods (Integer) (defaults to: 1) —

    Number of valid values there should be in the window before the expression is evaluated. valid values = length - null_count

Returns:



1528
1529
1530
 
# File 'lib/polars/series.rb', line 1528

def cumulative_eval(expr, min_periods: 1)
  super
end

#cut(breaks, labels: nil, left_closed: false, include_breaks: false) ⇒ Series

Bin continuous values into discrete categories.

Examples:

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"
# ]

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]   │
# └─────┴─────────────┴────────────┘

Parameters:

  • breaks (Array) —

    List of unique cut points.

  • labels (Array) (defaults to: nil) —

    Names of the categories. The number of labels must be equal to the number of cut points plus one.

  • left_closed (Boolean) (defaults to: false) —

    Set the intervals to be left-closed instead of right-closed.

  • include_breaks (Boolean) (defaults to: false) —

    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.

Returns:



1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
 
# File 'lib/polars/series.rb', line 1187

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

#describe ⇒ DataFrame

Quick summary statistics of a series.

Series with mixed datatypes will return summary statistics for the datatype of the first value.

Examples:

series_num = Polars::Series.new([1, 2, 3, 4, 5])
series_num.describe
# =>
# shape: (6, 2)
# ┌────────────┬──────────┐
# │ statistic  ┆ value    │
# │ ---        ┆ ---      │
# │ str        ┆ f64      │
# ╞════════════╪══════════╡
# │ min        ┆ 1.0      │
# │ max        ┆ 5.0      │
# │ null_count ┆ 0.0      │
# │ mean       ┆ 3.0      │
# │ std        ┆ 1.581139 │
# │ count      ┆ 5.0      │
# └────────────┴──────────┘

series_str = Polars::Series.new(["a", "a", nil, "b", "c"])
series_str.describe
# =>
# shape: (3, 2)
# ┌────────────┬───────┐
# │ statistic  ┆ value │
# │ ---        ┆ ---   │
# │ str        ┆ i64   │
# ╞════════════╪═══════╡
# │ unique     ┆ 4     │
# │ null_count ┆ 1     │
# │ count      ┆ 5     │
# └────────────┴───────┘

Returns:



864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
 
# File 'lib/polars/series.rb', line 864

def describe
  if len == 0
    raise ArgumentError, "Series must contain at least one value"
  elsif is_numeric
    s = cast(:f64)
    stats = {
      "min" => s.min,
      "max" => s.max,
      "null_count" => s.null_count,
      "mean" => s.mean,
      "std" => s.std,
      "count" => s.len
    }
  elsif is_boolean
    stats = {
      "sum" => sum,
      "null_count" => null_count,
      "count" => len
    }
  elsif is_utf8
    stats = {
      "unique" => unique.length,
      "null_count" => null_count,
      "count" => len
    }
  elsif is_datelike
    # we coerce all to string, because a polars column
    # only has a single dtype and dates: datetime and count: int don't match
    stats = {
      "min" => dt.min.to_s,
      "max" => dt.max.to_s,
      "null_count" => null_count.to_s,
      "count" => len.to_s
    }
  else
    raise TypeError, "This type is not supported"
  end

  Polars::DataFrame.new(
    {"statistic" => stats.keys, "value" => stats.values}
  )
end

#diff(n: 1, null_behavior: "ignore") ⇒ Series

Calculate the n-th discrete difference.

Examples:

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
# ]

s.diff(n: 2)
# =>
# shape: (5,)
# Series: 's' [i8]
# [
#         null
#         null
#         10
#         15
#         5
# ]

s.diff(n: 2, null_behavior: "drop")
# =>
# shape: (3,)
# Series: 's' [i8]
# [
#         10
#         15
#         5
# ]

Parameters:

  • n (Integer) (defaults to: 1) —

    Number of slots to shift.

  • null_behavior ("ignore", "drop") (defaults to: "ignore") —

    How to handle null values.

Returns:



4606
4607
4608
 
# File 'lib/polars/series.rb', line 4606

def diff(n: 1, null_behavior: "ignore")
  super
end

#dot(other) ⇒ Numeric

Compute the dot/inner product between two Series.

Examples:

s = Polars::Series.new("a", [1, 2, 3])
s2 = Polars::Series.new("b", [4.0, 5.0, 6.0])
s.dot(s2)
# => 32.0

Parameters:

  • other (Object) —

    Series (or array) to compute dot product with.

Returns:

  • (Numeric) 


3401
3402
3403
3404
3405
3406
3407
3408
3409
3410
 
# File 'lib/polars/series.rb', line 3401

def dot(other)
  if !other.is_a?(Series)
    other = Series.new(other)
  end
  if len != other.len
    n, m = len, other.len
    raise ArgumentError, "Series length mismatch: expected #{n}, found #{m}"
  end
  _s.dot(other._s)
end

#drop_nans ⇒ Series

Drop NaN values.

Examples:

s = Polars::Series.new([1.0, nil, 3.0, Float::NAN])
s.drop_nans
# =>
# shape: (3,)
# Series: '' [f64]
# [
#         1.0
#         null
#         3.0
# ]

Returns:



784
785
786
 
# File 'lib/polars/series.rb', line 784

def drop_nans
  super
end

#drop_nulls ⇒ Series

Create a new Series that copies data from this Series without null values.

Examples:

s = Polars::Series.new([1.0, nil, 3.0, Float::NAN])
s.drop_nulls
# =>
# shape: (3,)
# Series: '' [f64]
# [
#         1.0
#         3.0
#         NaN
# ]

Returns:



765
766
767
 
# File 'lib/polars/series.rb', line 765

def drop_nulls
  super
end

#dt ⇒ DateTimeNameSpace

Create an object namespace of all datetime related methods.

Returns:



5478
5479
5480
 
# File 'lib/polars/series.rb', line 5478

def dt
  DateTimeNameSpace.new(self)
end

#dtype ⇒ Symbol

Get the data type of this Series.

Examples:

s = Polars::Series.new("a", [1, 2, 3])
s.dtype
# => Polars::Int64

Returns:

  • (Symbol) 


96
97
98
 
# File 'lib/polars/series.rb', line 96

def dtype
  _s.dtype
end

#each ⇒ Object

Returns an enumerator.

Returns:



425
426
427
428
429
430
431
 
# File 'lib/polars/series.rb', line 425

def each
  return to_enum(:each) unless block_given?

  length.times do |i|
    yield self[i]
  end
end

#entropy(base: Math::E, normalize: false) ⇒ Float?

Computes the entropy.

Uses the formula -sum(pk * log(pk) where pk are discrete probabilities.

Examples:

a = Polars::Series.new([0.99, 0.005, 0.005])
a.entropy(normalize: true)
# => 0.06293300616044681

b = Polars::Series.new([0.65, 0.10, 0.25])
b.entropy(normalize: true)
# => 0.8568409950394724

Parameters:

  • base (Float) (defaults to: Math::E) —

    Given base, defaults to e

  • normalize (Boolean) (defaults to: false) —

    Normalize pk if it doesn't sum to 1.

Returns:

  • (Float, nil) 


1493
1494
1495
 
# File 'lib/polars/series.rb', line 1493

def entropy(base: Math::E, normalize: false)
  Polars.select(Polars.lit(self).entropy(base: base, normalize: normalize)).to_series[0]
end

#eq(other) ⇒ Series

Method equivalent of operator expression series == other.

Returns:



240
241
242
 
# File 'lib/polars/series.rb', line 240

def eq(other)
  self == other
end

#eq_missing(other) ⇒ Object

Method equivalent of equality operator series == other where nil == nil.

This differs from the standard ne where null values are propagated.

Examples:

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
# ]

s1.eq_missing(s2)
# =>
# shape: (3,)
# Series: 'a' [bool]
# [
#         false
#         true
#         true
# ]

Parameters:

  • other (Object) —

    A literal or expression value to compare with.

Returns:



276
277
278
279
280
281
 
# File 'lib/polars/series.rb', line 276

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

#equals(other, strict: false, check_names: false, null_equal: false) ⇒ Boolean Also known as: series_equal

Check if series is equal with another Series.

Examples:

s = Polars::Series.new("a", [1, 2, 3])
s2 = Polars::Series.new("b", [4, 5, 6])
s.equals(s)
# => true
s.equals(s2)
# => false

Parameters:

  • other (Series) —

    Series to compare with.

  • strict (Boolean) (defaults to: false) —

    Require data types to match.

  • check_names (Boolean) (defaults to: false) —

    Require names to match.

  • null_equal (Boolean) (defaults to: false) —

    Consider null values as equal.

Returns:



2704
2705
2706
 
# File 'lib/polars/series.rb', line 2704

def equals(other, strict: false, check_names: false, null_equal: false)
  _s.equals(other._s, strict, check_names, null_equal)
end

#estimated_size(unit = "b") ⇒ Numeric

Return an estimation of the total (heap) allocated size of the Series.

Estimated size is given in the specified unit (bytes by default).

This estimation is the sum of the size of its buffers, validity, including nested arrays. Multiple arrays may share buffers and bitmaps. Therefore, the size of 2 arrays is not the sum of the sizes computed from this function. In particular, StructArray's size is an upper bound.

When an array is sliced, its allocated size remains constant because the buffer unchanged. However, this function will yield a smaller number. This is because this function returns the visible size of the buffer, not its total capacity.

FFI buffers are included in this estimation.

Examples:

s = Polars::Series.new("values", 1..1_000_000, dtype: :u32)
s.estimated_size
# => 4000000
s.estimated_size("mb")
# => 3.814697265625

Parameters:

  • unit ("b", "kb", "mb", "gb", "tb") (defaults to: "b") —

    Scale the returned size to the given unit.

Returns:

  • (Numeric) 


556
557
558
559
 
# File 'lib/polars/series.rb', line 556

def estimated_size(unit = "b")
  sz = _s.estimated_size
  Utils.scale_bytes(sz, to: unit)
end

#ewm_mean(com: nil, span: nil, half_life: nil, alpha: nil, adjust: true, min_periods: 1, ignore_nulls: true) ⇒ Series

Exponentially-weighted moving average.

Examples:

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
# ]

Returns:



5091
5092
5093
5094
5095
5096
5097
5098
5099
5100
5101
 
# File 'lib/polars/series.rb', line 5091

def ewm_mean(
  com: nil,
  span: nil,
  half_life: nil,
  alpha: nil,
  adjust: true,
  min_periods: 1,
  ignore_nulls: true
)
  super
end

#ewm_mean_by(by, half_life:) ⇒ Series

Compute time-based exponentially weighted moving average.

Examples:

df = Polars::DataFrame.new(
  {
    "values" => [0, 1, 2, nil, 4],
    "times" => [
      Date.new(2020, 1, 1),
      Date.new(2020, 1, 3),
      Date.new(2020, 1, 10),
      Date.new(2020, 1, 15),
      Date.new(2020, 1, 17)
    ]
  }
).sort("times")
df["values"].ewm_mean_by(df["times"], half_life: "4d")
# =>
# shape: (5,)
# Series: 'values' [f64]
# [
#         0.0
#         0.292893
#         1.492474
#         null
#         3.254508
# ]

Parameters:

  • by (Object) —

    Times to calculate average by. Should be DateTime, Date, UInt64, UInt32, Int64, or Int32 data type.

  • half_life (String) —

    Unit over which observation decays to half its value.

    Can be created either from a timedelta, or by using the following string language:

    • 1ns (1 nanosecond)
    • 1us (1 microsecond)
    • 1ms (1 millisecond)
    • 1s (1 second)
    • 1m (1 minute)
    • 1h (1 hour)
    • 1d (1 day)
    • 1w (1 week)
    • 1i (1 index count)

    Or combine them: "3d12h4m25s" # 3 days, 12 hours, 4 minutes, and 25 seconds

    Note that half_life is treated as a constant duration - calendar durations such as months (or even days in the time-zone-aware case) are not supported, please express your duration in an approximately equivalent number of hours (e.g. '370h' instead of '1mo').

Returns:



5158
5159
5160
5161
5162
5163
 
# File 'lib/polars/series.rb', line 5158

def ewm_mean_by(
  by,
  half_life:
)
  super
end

#ewm_std(com: nil, span: nil, half_life: nil, alpha: nil, adjust: true, bias: false, min_periods: 1, ignore_nulls: true) ⇒ Series

Exponentially-weighted moving standard deviation.

Examples:

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
# ]

Returns:



5180
5181
5182
5183
5184
5185
5186
5187
5188
5189
5190
5191
 
# File 'lib/polars/series.rb', line 5180

def ewm_std(
  com: nil,
  span: nil,
  half_life: nil,
  alpha: nil,
  adjust: true,
  bias: false,
  min_periods: 1,
  ignore_nulls: true
)
  super
end

#ewm_var(com: nil, span: nil, half_life: nil, alpha: nil, adjust: true, bias: false, min_periods: 1, ignore_nulls: true) ⇒ Series

Exponentially-weighted moving variance.

Examples:

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
# ]

Returns:



5208
5209
5210
5211
5212
5213
5214
5215
5216
5217
5218
5219
 
# File 'lib/polars/series.rb', line 5208

def ewm_var(
  com: nil,
  span: nil,
  half_life: nil,
  alpha: nil,
  adjust: true,
  bias: false,
  min_periods: 1,
  ignore_nulls: true
)
  super
end

#exp ⇒ Series

Compute the exponential, element-wise.

Examples:

s = Polars::Series.new([1, 2, 3])
s.exp
# =>
# shape: (3,)
# Series: '' [f64]
# [
#         2.718282
#         7.389056
#         20.085537
# ]

Returns:



746
747
748
 
# File 'lib/polars/series.rb', line 746

def exp
  super
end

#explode ⇒ Series

Explode a list or utf8 Series.

This means that every item is expanded to a new row.

Examples:

s = Polars::Series.new("a", [[1, 2], [3, 4], [9, 10]])
s.explode
# =>
# shape: (6,)
# Series: 'a' [i64]
# [
#         1
#         2
#         3
#         4
#         9
#         10
# ]

Returns:



2680
2681
2682
 
# File 'lib/polars/series.rb', line 2680

def explode
  super
end

#extend_constant(value, n) ⇒ Series

Extend the Series with given number of values.

Examples:

s = Polars::Series.new("a", [1, 2, 3])
s.extend_constant(99, 2)
# =>
# shape: (5,)
# Series: 'a' [i64]
# [
#         1
#         2
#         3
#         99
#         99
# ]

Parameters:

  • value (Object) —

    The value to extend the Series with. This value may be nil to fill with nulls.

  • n (Integer) —

    The number of values to extend.

Returns:



5244
5245
5246
 
# File 'lib/polars/series.rb', line 5244

def extend_constant(value, n)
  super
end

#fill_nan(fill_value) ⇒ Series

Fill floating point NaN value with a fill value.

Examples:

s = Polars::Series.new("a", [1.0, 2.0, 3.0, Float::NAN])
s.fill_nan(0)
# =>
# shape: (4,)
# Series: 'a' [f64]
# [
#         1.0
#         2.0
#         3.0
#         0.0
# ]

Parameters:

  • fill_value (Object) —

    Value used to fill nan values.

Returns:



3223
3224
3225
 
# File 'lib/polars/series.rb', line 3223

def fill_nan(fill_value)
  super
end

#fill_null(value = nil, strategy: nil, limit: nil) ⇒ Series

Fill null values using the specified value or strategy.

Examples:

s = Polars::Series.new("a", [1, 2, 3, nil])
s.fill_null(strategy: "forward")
# =>
# shape: (4,)
# Series: 'a' [i64]
# [
#         1
#         2
#         3
#         3
# ]

s.fill_null(strategy: "min")
# =>
# shape: (4,)
# Series: 'a' [i64]
# [
#         1
#         2
#         3
#         1
# ]

s = Polars::Series.new("b", ["x", nil, "z"])
s.fill_null(Polars.lit(""))
# =>
# shape: (3,)
# Series: 'b' [str]
# [
#         "x"
#         ""
#         "z"
# ]

Parameters:

  • value (Object) (defaults to: nil) —

    Value used to fill null values.

  • strategy (nil, "forward", "backward", "min", "max", "mean", "zero", "one") (defaults to: nil) —

    Strategy used to fill null values.

  • limit (defaults to: nil) —

    Number of consecutive null values to fill when using the "forward" or "backward" strategy.

Returns:



3275
3276
3277
 
# File 'lib/polars/series.rb', line 3275

def fill_null(value = nil, strategy: nil, limit: nil)
  super
end

#filter(predicate) ⇒ Series

Filter elements by a boolean mask.

Examples:

s = Polars::Series.new("a", [1, 2, 3])
mask = Polars::Series.new("", [true, false, true])
s.filter(mask)
# =>
# shape: (2,)
# Series: 'a' [i64]
# [
#         1
#         3
# ]

Parameters:

Returns:



1834
1835
1836
1837
1838
1839
 
# File 'lib/polars/series.rb', line 1834

def filter(predicate)
  if predicate.is_a?(::Array)
    predicate = Series.new("", predicate)
  end
  Utils.wrap_s(_s.filter(predicate._s))
end

#first ⇒ Object

Get the first element of the Series.

Returns nil if the Series is empty.

Returns:



5425
5426
5427
 
# File 'lib/polars/series.rb', line 5425

def first
  _s.first
end

#flags ⇒ Hash

Get flags that are set on the Series.

Examples:

s = Polars::Series.new("a", [1, 2, 3])
s.flags
# => {"SORTED_ASC"=>false, "SORTED_DESC"=>false}

Returns:

  • (Hash) 


108
109
110
111
112
113
114
115
116
117
 
# File 'lib/polars/series.rb', line 108

def flags
  out = {
    "SORTED_ASC" => _s.is_sorted_flag,
    "SORTED_DESC" => _s.is_sorted_reverse_flag
  }
  if dtype.is_a?(List)
    out["FAST_EXPLODE"] = _s.can_fast_explode_flag
  end
  out
end

#floor ⇒ Series

Rounds down to the nearest integer value.

Only works on floating point Series.

Examples:

s = Polars::Series.new("a", [1.12345, 2.56789, 3.901234])
s.floor
# =>
# shape: (3,)
# Series: 'a' [f64]
# [
#         1.0
#         2.0
#         3.0
# ]

Returns:



3320
3321
3322
 
# File 'lib/polars/series.rb', line 3320

def floor
  Utils.wrap_s(_s.floor)
end

#forward_fill(limit: nil) ⇒ Series

Fill missing values with the next non-null value.

This is an alias of .fill_null(strategy: "forward").

Parameters:

  • limit (Integer) (defaults to: nil) —

    The number of consecutive null values to forward fill.

Returns:



3299
3300
3301
 
# File 'lib/polars/series.rb', line 3299

def forward_fill(limit: nil)
  fill_null(strategy: "forward", limit: limit)
end

#gather(indices) ⇒ Series Also known as: take

Take values by index.

Examples:

s = Polars::Series.new("a", [1, 2, 3, 4])
s.gather([1, 3])
# =>
# shape: (2,)
# Series: 'a' [i64]
# [
#         2
#         4
# ]

Parameters:

  • indices (Array) —

    Index location used for selection.

Returns:



2281
2282
2283
 
# File 'lib/polars/series.rb', line 2281

def gather(indices)
  super
end

#gather_every(n, offset = 0) ⇒ Series Also known as: take_every

Take every nth value in the Series and return as new Series.

Examples:

s = Polars::Series.new("a", [1, 2, 3, 4])
s.gather_every(2)
# =>
# shape: (2,)
# Series: 'a' [i64]
# [
#         1
#         3
# ]

s.gather_every(2, 1)
# =>
# shape: (2,)
# Series: 'a' [i64]
# [
#         2
#         4
# ]

Parameters:

  • n (Integer) —

    Gather every n-th row.

  • offset (Integer) (defaults to: 0) —

    Start the row index at this offset.

Returns:



1935
1936
1937
 
# File 'lib/polars/series.rb', line 1935

def gather_every(n, offset = 0)
  super
end

#ge(other) ⇒ Series

Method equivalent of operator expression series >= other.

Returns:



332
333
334
 
# File 'lib/polars/series.rb', line 332

def ge(other)
  self >= other
end

#get_chunks ⇒ Array

Get the chunks of this Series as a list of Series.

Examples:

s1 = Polars::Series.new("a", [1, 2, 3])
s2 = Polars::Series.new("a", [4, 5, 6])
s = Polars.concat([s1, s2], rechunk: false)
s.get_chunks
# =>
# [shape: (3,)
# Series: 'a' [i64]
# [
#         1
#         2
#         3
# ], shape: (3,)
# Series: 'a' [i64]
# [
#         4
#         5
#         6
# ]]

Returns:



5336
5337
5338
 
# File 'lib/polars/series.rb', line 5336

def get_chunks
  _s.get_chunks
end

#gt(other) ⇒ Series

Method equivalent of operator expression series > other.

Returns:



339
340
341
 
# File 'lib/polars/series.rb', line 339

def gt(other)
  self > other
end

#has_nulls ⇒ Boolean Also known as: has_validity

Return true if the Series has a validity bitmask.

If there is none, it means that there are no null values. Use this to swiftly assert a Series does not have null values.

Examples:

s = Polars::Series.new([1, 2, nil])
s.has_nulls
# => true

s[...2].has_nulls
# => false

Returns:



2313
2314
2315
 
# File 'lib/polars/series.rb', line 2313

def has_nulls
  _s.has_nulls
end

#head(n = 10) ⇒ Series

Get the first n rows.

Examples:

s = Polars::Series.new("a", [1, 2, 3])
s.head(2)
# =>
# shape: (2,)
# Series: 'a' [i64]
# [
#         1
#         2
# ]

Parameters:

  • n (Integer) (defaults to: 10) —

    Number of rows to return.

Returns:



1858
1859
1860
 
# File 'lib/polars/series.rb', line 1858

def head(n = 10)
  to_frame.select(F.col(name).head(n)).to_series
end

#hist(bins: nil, bin_count: nil, include_category: true, include_breakpoint: true) ⇒ DataFrame

Note:

This functionality is considered unstable. It may be changed at any point without it being considered a breaking change.

Bin values into buckets and count their occurrences.

Examples:

a = Polars::Series.new("a", [1, 3, 8, 8, 2, 1, 3])
a.hist(bin_count: 4)
# =>
# shape: (4, 3)
# ┌────────────┬─────────────┬───────┐
# │ breakpoint ┆ category    ┆ count │
# │ ---        ┆ ---         ┆ ---   │
# │ f64        ┆ cat         ┆ u32   │
# ╞════════════╪═════════════╪═══════╡
# │ 2.75       ┆ [1.0, 2.75] ┆ 3     │
# │ 4.5        ┆ (2.75, 4.5] ┆ 2     │
# │ 6.25       ┆ (4.5, 6.25] ┆ 0     │
# │ 8.0        ┆ (6.25, 8.0] ┆ 2     │
# └────────────┴─────────────┴───────┘

Parameters:

  • bins (Object) (defaults to: nil) —

    Bin edges. If nil given, we determine the edges based on the data.

  • bin_count (Integer) (defaults to: nil) —

    If bins is not provided, bin_count uniform bins are created that fully encompass the data.

  • include_category (Boolean) (defaults to: true) —

    Include a column that shows the intervals as categories.

  • include_breakpoint (Boolean) (defaults to: true) —

    Include a column that indicates the upper breakpoint.

Returns:



1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
 
# File 'lib/polars/series.rb', line 1380

def hist(
  bins: nil,
  bin_count: nil,
  include_category: true,
  include_breakpoint: true
)
  out = (
    to_frame
    .select_seq(
      F.col(name).hist(
        bins: bins,
        bin_count: bin_count,
        include_category: include_category,
        include_breakpoint: include_breakpoint
      )
    )
    .to_series
  )
  if !include_breakpoint && !include_category
    out.to_frame
  else
    out.struct.unnest
  end
end

#implode ⇒ Series

Aggregate values into a list.

Examples:

s = Polars::Series.new("a", [1, 2, 3])
s.implode
# =>
# shape: (1,)
# Series: 'a' [list[i64]]
# [
#         [1, 2, 3]
# ]

Returns:



5353
5354
5355
 
# File 'lib/polars/series.rb', line 5353

def implode
  super
end

#index_of(element) ⇒ Object

Get the index of the first occurrence of a value, or nil if it's not found.

Examples:

s = Polars::Series.new("a", [1, nil, 17])
s.index_of(17)
# => 2

s.index_of(nil) # search for a null
# => 1

s.index_of(55).nil?
# => true

Parameters:

  • element (Object) —

    Value to find.

Returns:



3157
3158
3159
 
# File 'lib/polars/series.rb', line 3157

def index_of(element)
  F.select(F.lit(self).index_of(element)).item
end

#interpolate(method: "linear") ⇒ Series

Interpolate intermediate values. The interpolation method is linear.

Examples:

s = Polars::Series.new("a", [1, 2, nil, nil, 5])
s.interpolate
# =>
# shape: (5,)
# Series: 'a' [f64]
# [
#         1.0
#         2.0
#         3.0
#         4.0
#         5.0
# ]

Returns:



4455
4456
4457
 
# File 'lib/polars/series.rb', line 4455

def interpolate(method: "linear")
  super
end

#interpolate_by(by) ⇒ Series

Fill null values using interpolation based on another column.

Examples:

Fill null values using linear interpolation.

s = Polars::Series.new("a", [1, nil, nil, 3])
by = Polars::Series.new("b", [1, 2, 7, 8])
s.interpolate_by(by)
# =>
# shape: (4,)
# Series: 'a' [f64]
# [
#         1.0
#         1.285714
#         2.714286
#         3.0
# ]

Parameters:

  • by (Expr) —

    Column to interpolate values based on.

Returns:



4479
4480
4481
 
# File 'lib/polars/series.rb', line 4479

def interpolate_by(by)
  super
end

#is_between(lower_bound, upper_bound, closed: "both") ⇒ Series

Note:

If the value of the lower_bound is greater than that of the upper_bound then the result will be False, as no value can satisfy the condition.

Get a boolean mask of the values that are between the given lower/upper bounds.

Examples:

s = Polars::Series.new("num", [1, 2, 3, 4, 5])
s.is_between(2, 4)
# =>
# shape: (5,)
# Series: 'num' [bool]
# [
#         false
#         true
#         true
#         true
#         false
# ]

Use the closed argument to include or exclude the values at the bounds:

s.is_between(2, 4, closed: "left")
# =>
# shape: (5,)
# Series: 'num' [bool]
# [
#         false
#         true
#         true
#         false
#         false
# ]

You can also use strings as well as numeric/temporal values:

s = Polars::Series.new("s", ["a", "b", "c", "d", "e"])
s.is_between("b", "d", closed: "both")
# =>
# shape: (5,)
# Series: 's' [bool]
# [
#         false
#         true
#         true
#         true
#         false
# ]

Parameters:

  • lower_bound (Object) —

    Lower bound value. Accepts expression input. Non-expression inputs (including strings) are parsed as literals.

  • upper_bound (Object) —

    Upper bound value. Accepts expression input. Non-expression inputs (including strings) are parsed as literals.

  • closed ('both', 'left', 'right', 'none') (defaults to: "both") —

    Define which sides of the interval are closed (inclusive).

Returns:



2914
2915
2916
2917
2918
2919
2920
2921
2922
2923
2924
2925
2926
2927
2928
2929
2930
2931
2932
2933
2934
 
# File 'lib/polars/series.rb', line 2914

def is_between(
  lower_bound,
  upper_bound,
  closed: "both"
)
  if closed == "none"
    out = (self > lower_bound) & (self < upper_bound)
  elsif closed == "both"
    out = (self >= lower_bound) & (self <= upper_bound)
  elsif closed == "right"
    out = (self > lower_bound) & (self <= upper_bound)
  elsif closed == "left"
    out = (self >= lower_bound) & (self < upper_bound)
  end

  if out.is_a?(Expr)
    out = F.select(out).to_series
  end

  out
end

#is_boolean ⇒ Boolean Also known as: boolean?, is_bool, bool?

Check if this Series is a Boolean.

Examples:

s = Polars::Series.new("a", [true, false, true])
s.is_boolean
# => true

Returns:



3024
3025
3026
 
# File 'lib/polars/series.rb', line 3024

def is_boolean
  dtype == Boolean
end

#is_close(other, abs_tol: 0.0, rel_tol: 1e-09, nans_equal: false) ⇒ Series

Get a boolean mask of the values being close to the other values.

Examples:

s = Polars::Series.new("s", [1.0, 1.2, 1.4, 1.45, 1.6])
s.is_close(1.4, abs_tol: 0.1)
# =>
# shape: (5,)
# Series: 's' [bool]
# [
#         false
#         false
#         true
#         true
#         false
# ]

Parameters:

  • abs_tol (Float) (defaults to: 0.0) —

    Absolute tolerance. This is the maximum allowed absolute difference between two values. Must be non-negative.

  • rel_tol (Float) (defaults to: 1e-09) —

    Relative tolerance. This is the maximum allowed difference between two values, relative to the larger absolute value. Must be in the range [0, 1).

  • nans_equal (Boolean) (defaults to: false) —

    Whether NaN values should be considered equal.

Returns:



2962
2963
2964
2965
2966
2967
2968
2969
2970
2971
2972
2973
 
# File 'lib/polars/series.rb', line 2962

def is_close(
  other,
  abs_tol: 0.0,
  rel_tol: 1e-09,
  nans_equal: false
)
  F.select(
    F.lit(self).is_close(
      other, abs_tol: abs_tol, rel_tol: rel_tol, nans_equal: nans_equal
    )
  ).to_series
end

#is_datelike ⇒ Boolean Also known as: datelike?, is_temporal, temporal?

Check if this Series datatype is datelike.

Examples:

s = Polars::Series.new([Date.new(2021, 1, 1), Date.new(2021, 1, 2), Date.new(2021, 1, 3)])
s.is_datelike
# => true

Returns:



2996
2997
2998
 
# File 'lib/polars/series.rb', line 2996

def is_datelike
  [Date, Time].include?(dtype) || dtype.is_a?(Datetime) || dtype.is_a?(Duration)
end

#is_duplicated ⇒ Series

Get mask of all duplicated values.

Examples:

s = Polars::Series.new("a", [1, 2, 2, 3])
s.is_duplicated
# =>
# shape: (4,)
# Series: 'a' [bool]
# [
#         false
#         true
#         true
#         false
# ]

Returns:



2656
2657
2658
 
# File 'lib/polars/series.rb', line 2656

def is_duplicated
  super
end

#is_empty ⇒ Boolean Also known as: empty?

Check if the Series is empty.

Examples:

s = Polars::Series.new("a", [])
s.is_empty
# => true

Returns:



2326
2327
2328
 
# File 'lib/polars/series.rb', line 2326

def is_empty
  len == 0
end

#is_finite ⇒ Series

Returns a boolean Series indicating which values are finite.

Examples:

s = Polars::Series.new("a", [1.0, 2.0, Float::INFINITY])
s.is_finite
# =>
# shape: (3,)
# Series: 'a' [bool]
# [
#         true
#         true
#         false
# ]

Returns:



2428
2429
2430
 
# File 'lib/polars/series.rb', line 2428

def is_finite
  super
end

#is_first_distinct ⇒ Series Also known as: is_first

Get a mask of the first unique value.

Examples:

s = Polars::Series.new([1, 1, 2, 3, 2])
s.is_first_distinct
# =>
# shape: (5,)
# Series: '' [bool]
# [
#         true
#         false
#         true
#         true
#         false
# ]

Returns:



2613
2614
2615
 
# File 'lib/polars/series.rb', line 2613

def is_first_distinct
  super
end

#is_float ⇒ Boolean Also known as: float?

Check if this Series has floating point numbers.

Examples:

s = Polars::Series.new("a", [1.0, 2.0, 3.0])
s.is_float
# => true

Returns:



3011
3012
3013
 
# File 'lib/polars/series.rb', line 3011

def is_float
  [Float32, Float64].include?(dtype)
end

#is_in(other, nulls_equal: false) ⇒ Series Also known as: in?

Check if elements of this Series are in the other Series.

Examples:

s = Polars::Series.new("a", [[1, 2, 3]])
s2 = Polars::Series.new("b", [2, 4, nil])
s2.is_in(s)
# =>
# shape: (3,)
# Series: 'b' [bool]
# [
#         true
#         false
#         null
# ]

s2.is_in(s, nulls_equal: true)
# =>
# shape: (3,)
# Series: 'b' [bool]
# [
#         true
#         false
#         false
# ]

sets = Polars::Series.new("sets", [[1, 2, 3], [1, 2], [9, 10]])
# =>
# shape: (3,)
# Series: 'sets' [list[i64]]
# [
#         [1, 2, 3]
#         [1, 2]
#         [9, 10]
# ]

optional_members = Polars::Series.new("optional_members", [1, 2, 3])
# =>
# shape: (3,)
# Series: 'optional_members' [i64]
# [
#         1
#         2
#         3
# ]

optional_members.is_in(sets)
# =>
# shape: (3,)
# Series: 'optional_members' [bool]
# [
#         true
#         true
#         false
# ]

Parameters:

  • nulls_equal (Boolean) (defaults to: false) —

    If true, treat null as a distinct value. Null values will not propagate.

Returns:



2554
2555
2556
 
# File 'lib/polars/series.rb', line 2554

def is_in(other, nulls_equal: false)
  super
end

#is_infinite ⇒ Series

Returns a boolean Series indicating which values are infinite.

Examples:

s = Polars::Series.new("a", [1.0, 2.0, Float::INFINITY])
s.is_infinite
# =>
# shape: (3,)
# Series: 'a' [bool]
# [
#         false
#         false
#         true
# ]

Returns:



2447
2448
2449
 
# File 'lib/polars/series.rb', line 2447

def is_infinite
  super
end

#is_last_distinct ⇒ Series

Return a boolean mask indicating the last occurrence of each distinct value.

Examples:

s = Polars::Series.new([1, 1, 2, 3, 2])
s.is_last_distinct
# =>
# shape: (5,)
# Series: '' [bool]
# [
#         false
#         true
#         false
#         true
#         true
# ]

Returns:



2636
2637
2638
 
# File 'lib/polars/series.rb', line 2636

def is_last_distinct
  super
end

#is_nan ⇒ Series

Returns a boolean Series indicating which values are NaN.

Examples:

s = Polars::Series.new("a", [1.0, 2.0, 3.0, Float::NAN])
s.is_nan
# =>
# shape: (4,)
# Series: 'a' [bool]
# [
#         false
#         false
#         false
#         true
# ]

Returns:



2467
2468
2469
 
# File 'lib/polars/series.rb', line 2467

def is_nan
  super
end

#is_not_nan ⇒ Series

Returns a boolean Series indicating which values are not NaN.

Examples:

s = Polars::Series.new("a", [1.0, 2.0, 3.0, Float::NAN])
s.is_not_nan
# =>
# shape: (4,)
# Series: 'a' [bool]
# [
#         true
#         true
#         true
#         false
# ]

Returns:



2487
2488
2489
 
# File 'lib/polars/series.rb', line 2487

def is_not_nan
  super
end

#is_not_null ⇒ Series

Returns a boolean Series indicating which values are not null.

Examples:

s = Polars::Series.new("a", [1.0, 2.0, 3.0, nil])
s.is_not_null
# =>
# shape: (4,)
# Series: 'a' [bool]
# [
#         true
#         true
#         true
#         false
# ]

Returns:



2409
2410
2411
 
# File 'lib/polars/series.rb', line 2409

def is_not_null
  super
end

#is_null ⇒ Series

Returns a boolean Series indicating which values are null.

Examples:

s = Polars::Series.new("a", [1.0, 2.0, 3.0, nil])
s.is_null
# =>
# shape: (4,)
# Series: 'a' [bool]
# [
#         false
#         false
#         false
#         true
# ]

Returns:



2389
2390
2391
 
# File 'lib/polars/series.rb', line 2389

def is_null
  super
end

#is_numeric ⇒ Boolean Also known as: numeric?

Check if this Series datatype is numeric.

Examples:

s = Polars::Series.new("a", [1, 2, 3])
s.is_numeric
# => true

Returns:



2983
2984
2985
 
# File 'lib/polars/series.rb', line 2983

def is_numeric
  [Int8, Int16, Int32, Int64, UInt8, UInt16, UInt32, UInt64, Float32, Float64].include?(dtype)
end

#is_sorted(descending: false, nulls_last: false) ⇒ Boolean Also known as: sorted?

Check if the Series is sorted.

Examples:

s = Polars::Series.new([1, 3, 2])
s.is_sorted
# => false

s = Polars::Series.new([3, 2, 1])
s.is_sorted(descending: true)
# => true

Parameters:

  • descending (Boolean) (defaults to: false) —

    Check if the Series is sorted in descending order

  • nulls_last (Boolean) (defaults to: false) —

    Set nulls at the end of the Series in sorted check.

Returns:



2349
2350
2351
 
# File 'lib/polars/series.rb', line 2349

def is_sorted(descending: false, nulls_last: false)
  _s.is_sorted(descending, nulls_last)
end

#is_unique ⇒ Series

Get mask of all unique values.

Examples:

s = Polars::Series.new("a", [1, 2, 2, 3])
s.is_unique
# =>
# shape: (4,)
# Series: 'a' [bool]
# [
#         true
#         false
#         false
#         true
# ]

Returns:



2592
2593
2594
 
# File 'lib/polars/series.rb', line 2592

def is_unique
  super
end

#is_utf8 ⇒ Boolean Also known as: utf8?

Check if this Series datatype is a Utf8.

Examples:

s = Polars::Series.new("x", ["a", "b", "c"])
s.is_utf8
# => true

Returns:



3039
3040
3041
 
# File 'lib/polars/series.rb', line 3039

def is_utf8
  dtype == String
end

#item(index = nil) ⇒ Object

Return the Series as a scalar, or return the element at the given index.

If no index is provided, this is equivalent to s[0], with a check that the shape is (1,). With an index, this is equivalent to s[index].

Examples:

s1 = Polars::Series.new("a", [1])
s1.item
# => 1

s2 = Polars::Series.new("a", [9, 8, 7])
s2.cum_sum.item(-1)
# => 24

Returns:



515
516
517
518
519
520
521
522
523
524
525
526
527
528
 
# File 'lib/polars/series.rb', line 515

def item(index = nil)
  if index.nil?
    if len != 1
      msg = (
        "can only call '.item' if the Series is of length 1," +
        " or an explicit index is provided (Series is of length #{len})"
      )
      raise ArgumentError, msg
    end
    return _s.get_index(0)
  end

  _s.get_index_signed(index)
end

#kurtosis(fisher: true, bias: true) ⇒ Float?

Compute the kurtosis (Fisher or Pearson) of a dataset.

Kurtosis is the fourth central moment divided by the square of the variance. If Fisher's definition is used, then 3.0 is subtracted from the result to give 0.0 for a normal distribution. If bias is false, then the kurtosis is calculated using k statistics to eliminate bias coming from biased moment estimators

Examples:

s = Polars::Series.new("grades", [66, 79, 54, 97, 96, 70, 69, 85, 93, 75])
s.kurtosis
# => -1.0522623626787952

s.kurtosis(fisher: false)
# => 1.9477376373212048

s.kurtosis(fisher: false, bias: false)
# => 2.1040361802642717

Parameters:

  • fisher (Boolean) (defaults to: true) —

    If true, Fisher's definition is used (normal ==> 0.0). If false, Pearson's definition is used (normal ==> 3.0).

  • bias (Boolean) (defaults to: true) —

    If false, the calculations are corrected for statistical bias.

Returns:

  • (Float, nil) 


4710
4711
4712
 
# File 'lib/polars/series.rb', line 4710

def kurtosis(fisher: true, bias: true)
  _s.kurtosis(fisher, bias)
end

#last ⇒ Object

Get the last element of the Series.

Returns nil if the Series is empty.

Returns:



5434
5435
5436
 
# File 'lib/polars/series.rb', line 5434

def last
  _s.last
end

#le(other) ⇒ Series

Method equivalent of operator expression series <= other.

Returns:



226
227
228
 
# File 'lib/polars/series.rb', line 226

def le(other)
  self <= other
end

#len ⇒ Integer Also known as: length, size

Return the number of elements in the Series.

Examples:

s = Polars::Series.new("a", [1, 2, nil])
s.len
# => 3

Returns:

  • (Integer) 


2729
2730
2731
 
# File 'lib/polars/series.rb', line 2729

def len
  _s.len
end

#limit(n = 10) ⇒ Series

Get the first n rows.

Alias for #head.

Examples:

s = Polars::Series.new("a", [1, 2, 3])
s.limit(2)
# =>
# shape: (2,)
# Series: 'a' [i64]
# [
#         1
#         2
# ]

Parameters:

  • n (Integer) (defaults to: 10) —

    Number of rows to return.

Returns:



1902
1903
1904
 
# File 'lib/polars/series.rb', line 1902

def limit(n = 10)
  to_frame.select(F.col(name).limit(n)).to_series
end

#list ⇒ ListNameSpace

Create an object namespace of all list related methods.

Returns:



5450
5451
5452
 
# File 'lib/polars/series.rb', line 5450

def list
  ListNameSpace.new(self)
end

#log(base = Math::E) ⇒ Series

Compute the logarithm to a given base.

Examples:

s = Polars::Series.new([1, 2, 3])
s.log
# =>
# shape: (3,)
# Series: '' [f64]
# [
#         0.0
#         0.693147
#         1.098612
# ]

Parameters:

  • base (Float) (defaults to: Math::E) —

    Given base, defaults to Math::E.

Returns:



689
690
691
 
# File 'lib/polars/series.rb', line 689

def log(base = Math::E)
  super
end

#log10 ⇒ Series

Compute the base 10 logarithm of the input array, element-wise.

Examples:

s = Polars::Series.new([10, 100, 1000])
s.log10
# =>
# shape: (3,)
# Series: '' [f64]
# [
#         1.0
#         2.0
#         3.0
# ]

Returns:



727
728
729
 
# File 'lib/polars/series.rb', line 727

def log10
  super
end

#log1p ⇒ Series

Compute the natural logarithm of the input array plus one, element-wise.

Examples:

s = Polars::Series.new([1, 2, 3])
s.log1p
# =>
# shape: (3,)
# Series: '' [f64]
# [
#         0.693147
#         1.098612
#         1.386294
# ]

Returns:



708
709
710
 
# File 'lib/polars/series.rb', line 708

def log1p
  super
end

#lower_bound ⇒ Series

Return the lower bound of this Series' dtype as a unit Series.

Examples:

s = Polars::Series.new("s", [-1, 0, 1], dtype: Polars::Int32)
s.lower_bound
# =>
# shape: (1,)
# Series: 's' [i32]
# [
#         -2147483648
# ]

s = Polars::Series.new("s", [1.0, 2.5, 3.0], dtype: Polars::Float32)
s.lower_bound
# =>
# shape: (1,)
# Series: 's' [f32]
# [
#         -inf
# ]

Returns:



4797
4798
4799
 
# File 'lib/polars/series.rb', line 4797

def lower_bound
  super
end

#lt(other) ⇒ Series

Method equivalent of operator expression series < other.

Returns:



233
234
235
 
# File 'lib/polars/series.rb', line 233

def lt(other)
  self < other
end

#map_elements(return_dtype: nil, skip_nulls: true, &func) ⇒ Series Also known as: map, apply

Apply a custom/user-defined function (UDF) over elements in this Series and return a new Series.

If the function returns another datatype, the return_dtype arg should be set, otherwise the method will fail.

Examples:

s = Polars::Series.new("a", [1, 2, 3])
s.map_elements(return_dtype: Polars::Int64) { |x| x + 10 }
# =>
# shape: (3,)
# Series: 'a' [i64]
# [
#         11
#         12
#         13
# ]

Parameters:

  • return_dtype (Symbol) (defaults to: nil) —

    Output datatype. If none is given, the same datatype as this Series will be used.

  • skip_nulls (Boolean) (defaults to: true) —

    Nulls will be skipped and not passed to the Ruby function. This is faster because Ruby can be skipped and because we call more specialized functions.

Returns:



3737
3738
3739
3740
3741
3742
3743
3744
 
# File 'lib/polars/series.rb', line 3737

def map_elements(return_dtype: nil, skip_nulls: true, &func)
  if return_dtype.nil?
    pl_return_dtype = nil
  else
    pl_return_dtype = Utils.rb_type_to_dtype(return_dtype)
  end
  Utils.wrap_s(_s.map_elements(func, pl_return_dtype, skip_nulls))
end

#max ⇒ Object

Get the maximum value in this Series.

Examples:

s = Polars::Series.new("a", [1, 2, 3])
s.max
# => 3

Returns:



1005
1006
1007
 
# File 'lib/polars/series.rb', line 1005

def max
  _s.max
end

#mean ⇒ Float?

Reduce this Series to the mean value.

Examples:

s = Polars::Series.new("a", [1, 2, 3])
s.mean
# => 2.0

Returns:

  • (Float, nil) 


931
932
933
 
# File 'lib/polars/series.rb', line 931

def mean
  _s.mean
end

#median ⇒ Float?

Get the median of this Series.

Examples:

s = Polars::Series.new("a", [1, 2, 3])
s.median
# => 2.0

Returns:

  • (Float, nil) 


1091
1092
1093
 
# File 'lib/polars/series.rb', line 1091

def median
  _s.median
end

#min ⇒ Object

Get the minimal value in this Series.

Examples:

s = Polars::Series.new("a", [1, 2, 3])
s.min
# => 1

Returns:



993
994
995
 
# File 'lib/polars/series.rb', line 993

def min
  _s.min
end

#mode ⇒ Series

Compute the most occurring value(s).

Can return multiple Values.

Examples:

s = Polars::Series.new("a", [1, 2, 2, 3])
s.mode
# =>
# shape: (1,)
# Series: 'a' [i64]
# [
#         2
# ]

Returns:



3427
3428
3429
 
# File 'lib/polars/series.rb', line 3427

def mode
  super
end

#n_chunks ⇒ Integer

Get the number of chunks that this Series contains.

Examples:

s = Polars::Series.new("a", [1, 2, 3])
s2 = Polars::Series.new("b", [4, 5, 6])

Concatenate Series with rechunk: true

Polars.concat([s, s2]).n_chunks
# => 1

Concatenate Series with rechunk: false

Polars.concat([s, s2], rechunk: false).n_chunks
# => 2

Returns:

  • (Integer) 


1603
1604
1605
 
# File 'lib/polars/series.rb', line 1603

def n_chunks
  _s.n_chunks
end

#n_unique ⇒ Integer

Count the number of unique values in this Series.

Examples:

s = Polars::Series.new("a", [1, 2, 2, 3])
s.n_unique
# => 3

Returns:

  • (Integer) 


4362
4363
4364
 
# File 'lib/polars/series.rb', line 4362

def n_unique
  _s.n_unique
end

#name ⇒ String

Get the name of this Series.

Examples:

s = Polars::Series.new("a", [1, 2, 3])
s.name
# => "a"

Returns:



127
128
129
 
# File 'lib/polars/series.rb', line 127

def name
  _s.name
end

#nan_max ⇒ Object

Get maximum value, but propagate/poison encountered NaN values.

Examples:

s = Polars::Series.new("a", [1, 3, 4])
s.nan_max
# => 4

s = Polars::Series.new("a", [1.0, Float::NAN, 4.0])
s.nan_max
# => NaN

Returns:



1022
1023
1024
 
# File 'lib/polars/series.rb', line 1022

def nan_max
  to_frame.select(F.col(name).nan_max)[0, 0]
end

#nan_min ⇒ Object

Get minimum value, but propagate/poison encountered NaN values.

Examples:

s = Polars::Series.new("a", [1, 3, 4])
s.nan_min
# => 1

s = Polars::Series.new("a", [1.0, Float::NAN, 4.0])
s.nan_min
# => NaN

Returns:



1039
1040
1041
 
# File 'lib/polars/series.rb', line 1039

def nan_min
  to_frame.select(F.col(name).nan_min)[0, 0]
end

#ne(other) ⇒ Series

Method equivalent of operator expression series != other.

Returns:



286
287
288
 
# File 'lib/polars/series.rb', line 286

def ne(other)
  self != other
end

#ne_missing(other) ⇒ Object

Method equivalent of equality operator series != other where nil == nil.

This differs from the standard ne where null values are propagated.

Examples:

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
# ]

s1.ne_missing(s2)
# =>
# shape: (3,)
# Series: 'a' [bool]
# [
#         true
#         false
#         false
# ]

Parameters:

  • other (Object) —

    A literal or expression value to compare with.

Returns:



322
323
324
325
326
327
 
# File 'lib/polars/series.rb', line 322

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

#new_from_index(index, length) ⇒ Series

Create a new Series filled with values from the given index.

Examples:

s = Polars::Series.new("a", [1, 2, 3, 4, 5])
s.new_from_index(1, 3)
# =>
# shape: (3,)
# Series: 'a' [i64]
# [
#         2
#         2
#         2
# ]

Returns:



5284
5285
5286
 
# File 'lib/polars/series.rb', line 5284

def new_from_index(index, length)
  Utils.wrap_s(_s.new_from_index(index, length))
end

#none?(&block) ⇒ Boolean Also known as: none

Check if all boolean values in the column are false.

Examples:

Polars::Series.new([true, false]).none?
# => false

Polars::Series.new([false, false]).none?
# => true

Polars::Series.new([nil, false]).none?
# => true

Returns:



662
663
664
665
666
667
668
 
# File 'lib/polars/series.rb', line 662

def none?(&block)
  if block_given?
    apply(return_dtype: Boolean, &block).none?
  else
    to_frame.select(Polars.col(name).is_not.all).to_series[0]
  end
end

#not_ ⇒ Series

Negate a boolean Series.

Examples:

s = Polars::Series.new("a", [true, false, false])
s.not_
# =>
# shape: (3,)
# Series: 'a' [bool]
# [
#         false
#         true
#         true
# ]

Returns:



2369
2370
2371
 
# File 'lib/polars/series.rb', line 2369

def not_
  self.class._from_rbseries(_s.not_)
end

#null_count ⇒ Integer

Count the null values in this Series.

Examples:

s = Polars::Series.new([1, nil, nil])
s.null_count
# => 2

Returns:

  • (Integer) 


2294
2295
2296
 
# File 'lib/polars/series.rb', line 2294

def null_count
  _s.null_count
end

#pct_change(n: 1) ⇒ Series

Computes percentage change between values.

Percentage change (as fraction) between current element and most-recent non-null element at least n period(s) before the current element.

Computes the change from the previous row by default.

Examples:

Polars::Series.new(0..9).pct_change
# =>
# shape: (10,)
# Series: '' [f64]
# [
#         null
#         inf
#         1.0
#         0.5
#         0.333333
#         0.25
#         0.2
#         0.166667
#         0.142857
#         0.125
# ]

Polars::Series.new([1, 2, 4, 8, 16, 32, 64, 128, 256, 512]).pct_change(n: 2)
# =>
# shape: (10,)
# Series: '' [f64]
# [
#         null
#         null
#         3.0
#         3.0
#         3.0
#         3.0
#         3.0
#         3.0
#         3.0
#         3.0
# ]

Parameters:

  • n (Integer) (defaults to: 1) —

    periods to shift for forming percent change.

Returns:



4657
4658
4659
 
# File 'lib/polars/series.rb', line 4657

def pct_change(n: 1)
  super
end

#peak_max ⇒ Series

Get a boolean mask of the local maximum peaks.

Examples:

s = Polars::Series.new("a", [1, 2, 3, 4, 5])
s.peak_max
# =>
# shape: (5,)
# Series: 'a' [bool]
# [
#         false
#         false
#         false
#         false
#         true
# ]

Returns:



4329
4330
4331
 
# File 'lib/polars/series.rb', line 4329

def peak_max
  super
end

#peak_min ⇒ Series

Get a boolean mask of the local minimum peaks.

Examples:

s = Polars::Series.new("a", [4, 1, 3, 2, 5])
s.peak_min
# =>
# shape: (5,)
# Series: 'a' [bool]
# [
#         false
#         true
#         false
#         true
#         false
# ]

Returns:



4350
4351
4352
 
# File 'lib/polars/series.rb', line 4350

def peak_min
  super
end

#pow(exponent) ⇒ Series

Raise to the power of the given exponent.

If the exponent is float, the result follows the dtype of exponent. Otherwise, it follows dtype of base.

Examples:

Raising integers to positive integers results in integers:

s = Polars::Series.new("foo", [1, 2, 3, 4])
s.pow(3)
# =>
# shape: (4,)
# Series: 'foo' [i64]
# [
#         1
#         8
#         27
#         64
# ]

In order to raise integers to negative integers, you can cast either the base or the exponent to float:

s.pow(-3.0)
# =>
# shape: (4,)
# Series: 'foo' [f64]
# [
#         1.0
#         0.125
#         0.037037
#         0.015625
# ]

Parameters:

  • exponent (Numeric) —

    The exponent. Accepts Series input.

Returns:



981
982
983
 
# File 'lib/polars/series.rb', line 981

def pow(exponent)
  to_frame.select_seq(F.col(name).pow(exponent)).to_series
end

#product ⇒ Numeric

Reduce this Series to the product value.

Examples:

s = Polars::Series.new("a", [1, 2, 3])
s.product
# => 6

Returns:

  • (Numeric) 


943
944
945
 
# File 'lib/polars/series.rb', line 943

def product
  to_frame.select(Polars.col(name).product).to_series[0]
end

#qcut(quantiles, labels: nil, left_closed: false, allow_duplicates: false, include_breaks: false) ⇒ Series

Bin continuous values into discrete categories based on their quantiles.

Examples:

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"
# ]

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"
# ]

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]   │
# └─────┴─────────────┴────────────┘

Parameters:

  • quantiles (Object) —

    Either an array of quantile probabilities between 0 and 1 or a positive integer determining the number of bins with uniform probability.

  • labels (Array) (defaults to: nil) —

    Names of the categories. The number of labels must be equal to the number of cut points plus one.

  • left_closed (Boolean) (defaults to: false) —

    Set the intervals to be left-closed instead of right-closed.

  • allow_duplicates (Boolean) (defaults to: false) —

    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.

  • include_breaks (Boolean) (defaults to: false) —

    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.

Returns:



1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
 
# File 'lib/polars/series.rb', line 1272

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

#quantile(quantile, interpolation: "nearest") ⇒ Float?

Get the quantile value of this Series.

Examples:

s = Polars::Series.new("a", [1, 2, 3])
s.quantile(0.5)
# => 2.0

Parameters:

  • quantile (Float, nil) —

    Quantile between 0.0 and 1.0.

  • interpolation ("nearest", "higher", "lower", "midpoint", "linear") (defaults to: "nearest") —

    Interpolation method.

Returns:

  • (Float, nil) 


1108
1109
1110
 
# File 'lib/polars/series.rb', line 1108

def quantile(quantile, interpolation: "nearest")
  _s.quantile(quantile, interpolation)
end

#rank(method: "average", reverse: false, seed: nil) ⇒ Series

Assign ranks to data, dealing with ties appropriately.

Examples:

The 'average' method:

s = Polars::Series.new("a", [3, 6, 1, 1, 6])
s.rank
# =>
# shape: (5,)
# Series: 'a' [f64]
# [
#         3.0
#         4.5
#         1.5
#         1.5
#         4.5
# ]

The 'ordinal' method:

s = Polars::Series.new("a", [3, 6, 1, 1, 6])
s.rank(method: "ordinal")
# =>
# shape: (5,)
# Series: 'a' [u32]
# [
#         3
#         4
#         1
#         2
#         5
# ]

Parameters:

  • method ("average", "min", "max", "dense", "ordinal", "random") (defaults to: "average") —

    The method used to assign ranks to tied elements. The following methods are available (default is 'average'):

    • 'average' : The average of the ranks that would have been assigned to all the tied values is assigned to each value.
    • 'min' : The minimum of the ranks that would have been assigned to all the tied values is assigned to each value. (This is also referred to as "competition" ranking.)
    • 'max' : The maximum of the ranks that would have been assigned to all the tied values is assigned to each value.
    • 'dense' : Like 'min', but the rank of the next highest element is assigned the rank immediately after those assigned to the tied elements.
    • 'ordinal' : All values are given a distinct rank, corresponding to the order that the values occur in the Series.
    • 'random' : Like 'ordinal', but the rank for ties is not dependent on the order that the values occur in the Series.
  • reverse (Boolean) (defaults to: false) —

    Reverse the operation.

  • seed (Integer) (defaults to: nil) —

    If method: "random", use this as seed.

Returns:



4556
4557
4558
 
# File 'lib/polars/series.rb', line 4556

def rank(method: "average", reverse: false, seed: nil)
  super
end

#rechunk(in_place: false) ⇒ Series

Create a single chunk of memory for this Series.

Examples:

s1 = Polars::Series.new("a", [1, 2, 3])
s1.n_chunks
# => 1

s2 = Polars::Series.new("a", [4, 5, 6])
s = Polars.concat([s1, s2], rechunk: false)
s.n_chunks
# => 2

s.rechunk(in_place: true)
# =>
# shape: (6,)
# Series: 'a' [i64]
# [
#         1
#         2
#         3
#         4
#         5
#         6
# ]

s.n_chunks
# => 1

Parameters:

  • in_place (Boolean) (defaults to: false) —

    In place or not.

Returns:



2833
2834
2835
2836
 
# File 'lib/polars/series.rb', line 2833

def rechunk(in_place: false)
  opt_s = _s.rechunk(in_place)
  in_place ? self : Utils.wrap_s(opt_s)
end

#reinterpret(signed: true) ⇒ Series

Reinterpret the underlying bits as a signed/unsigned integer.

This operation is only allowed for 64bit integers. For lower bits integers, you can safely use that cast operation.

Examples:

s = Polars::Series.new("a", [-(2**60), -2, 3])
s.reinterpret(signed: false)
# =>
# shape: (3,)
# Series: 'a' [u64]
# [
#         17293822569102704640
#         18446744073709551614
#         3
# ]

Parameters:

  • signed (Boolean) (defaults to: true) —

    If true, reinterpret as :i64. Otherwise, reinterpret as :u64.

Returns:



4434
4435
4436
 
# File 'lib/polars/series.rb', line 4434

def reinterpret(signed: true)
  super
end

#rename(name, in_place: false) ⇒ Series

Rename this Series.

Examples:

s = Polars::Series.new("a", [1, 2, 3])
s.rename("b")

Parameters:

  • name (String) —

    New name.

  • in_place (Boolean) (defaults to: false) —

    Modify the Series in-place.

Returns:



1560
1561
1562
1563
1564
1565
1566
1567
 
# File 'lib/polars/series.rb', line 1560

def rename(name, in_place: false)
  if in_place
    _s.rename(name)
    self
  else
    self.alias(name)
  end
end

#repeat_by(by) ⇒ Object

Repeat the elements in this Series as specified in the given expression.

The repeated elements are expanded into a List.

Parameters:

  • by (Object) —

    Numeric column that determines how often the values will be repeated. The column will be coerced to UInt32. Give this dtype to make the coercion a no-op.

Returns:



5506
5507
5508
 
# File 'lib/polars/series.rb', line 5506

def repeat_by(by)
  super
end

#replace(old, new = Expr::NO_DEFAULT, default: Expr::NO_DEFAULT, return_dtype: nil) ⇒ Series

Replace values by different values.

Examples:

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
# ]

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
# ]

Passing a mapping with replacements is also supported as syntactic sugar.

mapping = {2 => 100, 3 => 200}
s.replace(mapping)
# =>
# shape: (4,)
# Series: '' [i64]
# [
#         1
#         100
#         100
#         200
# ]

The original data type is preserved when replacing by values of a different data type.

s = Polars::Series.new(["x", "y", "z"])
mapping = {"x" => 1, "y" => 2, "z" => 3}
s.replace(mapping)
# =>
# shape: (3,)
# Series: '' [str]
# [
#         "1"
#         "2"
#         "3"
# ]

Parameters:

  • old (Object) —

    Value or sequence of values to replace. Also accepts a mapping of values to their replacement.

  • new (Object) (defaults to: Expr::NO_DEFAULT) —

    Value or sequence of values to replace by. Length must match the length of old or have length 1.

  • default (Object) (defaults to: Expr::NO_DEFAULT) —

    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.

  • return_dtype (Object) (defaults to: nil) —

    The data type of the resulting Series. If set to nil (default), the data type is determined automatically based on the other inputs.

Returns:



4896
4897
4898
 
# File 'lib/polars/series.rb', line 4896

def replace(old, new = Expr::NO_DEFAULT, default: Expr::NO_DEFAULT, return_dtype: nil)
  super
end

#replace_strict(old, new = Expr::NO_DEFAULT, default: Expr::NO_DEFAULT, return_dtype: nil) ⇒ Series

Replace all values by different values.

Examples:

Replace values by passing sequences to the old and new parameters.

s = Polars::Series.new([1, 2, 2, 3])
s.replace_strict([1, 2, 3], [100, 200, 300])
# =>
# shape: (4,)
# Series: '' [i64]
# [
#         100
#         200
#         200
#         300
# ]

Passing a mapping with replacements is also supported as syntactic sugar.

mapping = {1 => 100, 2 => 200, 3 => 300}
s.replace_strict(mapping)
# =>
# shape: (4,)
# Series: '' [i64]
# [
#         100
#         200
#         200
#         300
# ]

By default, an error is raised if any non-null values were not replaced. Specify a default to set all values that were not matched.

mapping = {2 => 200, 3 => 300}
s.replace_strict(mapping, default: -1)
# =>
# shape: (4,)
# Series: '' [i64]
# [
#         -1
#         200
#         200
#         300
# ]

The default can be another Series.

default = Polars::Series.new([2.5, 5.0, 7.5, 10.0])
s.replace_strict(2, 200, default: default)
# =>
# shape: (4,)
# Series: '' [f64]
# [
#         2.5
#         200.0
#         200.0
#         10.0
# ]

Replacing by values of a different data type sets the return type based on a combination of the new data type and the default data type.

s = Polars::Series.new(["x", "y", "z"])
mapping = {"x" => 1, "y" => 2, "z" => 3}
s.replace_strict(mapping)
# =>
# shape: (3,)
# Series: '' [i64]
# [
#         1
#         2
#         3
# ]

s.replace_strict(mapping, default: "x")
# =>
# shape: (3,)
# Series: '' [str]
# [
#         "1"
#         "2"
#         "3"
# ]

Set the return_dtype parameter to control the resulting data type directly.

s.replace_strict(mapping, return_dtype: Polars::UInt8)
# =>
# shape: (3,)
# Series: '' [u8]
# [
#         1
#         2
#         3
# ]

Parameters:

  • old (Object) —

    Value or sequence of values to replace. Also accepts a mapping of values to their replacement as syntactic sugar for replace_strict(old: Polars::Series.new(mapping.keys), new: Polars::Series.new(mapping.values)).

  • new (Object) (defaults to: Expr::NO_DEFAULT) —

    Value or sequence of values to replace by. Length must match the length of old or have length 1.

  • default (Object) (defaults to: Expr::NO_DEFAULT) —

    Set values that were not replaced to this value. If no default is specified, (default), an error is raised if any values were not replaced. Accepts expression input. Non-expression inputs are parsed as literals.

  • return_dtype (Object) (defaults to: nil) —

    The data type of the resulting Series. If set to nil (default), the data type is determined automatically based on the other inputs.

Returns:



5005
5006
5007
5008
5009
5010
5011
5012
 
# File 'lib/polars/series.rb', line 5005

def replace_strict(
  old,
  new = Expr::NO_DEFAULT,
  default: Expr::NO_DEFAULT,
  return_dtype: nil
)
  super
end

#reshape(dims) ⇒ Series

Reshape this Series to a flat Series or a Series of Lists.

Examples:

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]
# ]

square.reshape([9])
# =>
# shape: (9,)
# Series: 'foo' [i64]
# [
#         1
#         2
#         3
#         4
#         5
#         6
#         7
#         8
#         9
# ]

Parameters:

  • dims (Array) —

    Tuple of the dimension sizes. If a -1 is used in any of the dimensions, that dimension is inferred.

Returns:



5050
5051
5052
 
# File 'lib/polars/series.rb', line 5050

def reshape(dims)
  super
end

#reverse ⇒ Series

Return Series in reverse order.

Examples:

s = Polars::Series.new("a", [1, 2, 3], dtype: :i8)
s.reverse
# =>
# shape: (3,)
# Series: 'a' [i8]
# [
#         3
#         2
#         1
# ]

Returns:



2853
2854
2855
 
# File 'lib/polars/series.rb', line 2853

def reverse
  super
end

#rle ⇒ Series

Get the lengths of runs of identical values.

Examples:

s = Polars::Series.new("s", [1, 1, 2, 1, nil, 1, 3, 3])
s.rle.struct.unnest
# =>
# shape: (6, 2)
# ┌─────┬───────┐
# │ len ┆ value │
# │ --- ┆ ---   │
# │ u32 ┆ i64   │
# ╞═════╪═══════╡
# │ 2   ┆ 1     │
# │ 1   ┆ 2     │
# │ 1   ┆ 1     │
# │ 1   ┆ null  │
# │ 1   ┆ 1     │
# │ 2   ┆ 3     │
# └─────┴───────┘

Returns:



1315
1316
1317
 
# File 'lib/polars/series.rb', line 1315

def rle
  super
end

#rle_id ⇒ Series

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.

Examples:

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
# ]

Returns:



1343
1344
1345
 
# File 'lib/polars/series.rb', line 1343

def rle_id
  super
end

#rolling_kurtosis(window_size, fisher: true, bias: true, min_samples: nil, center: false) ⇒ Series

Note:

This functionality is considered unstable. It may be changed at any point without it being considered a breaking change.

Compute a rolling kurtosis.

The window at a given row will include the row itself, and the window_size - 1 elements before it.

Examples:

Polars::Series.new([1, 4, 2, 9]).rolling_kurtosis(3)
# =>
# shape: (4,)
# Series: '' [f64]
# [
#         null
#         null
#         -1.5
#         -1.5
# ]

Parameters:

  • window_size (Integer) —

    Integer size of the rolling window.

  • fisher (Boolean) (defaults to: true) —

    If true, Fisher's definition is used (normal ==> 0.0). If false, Pearson's definition is used (normal ==> 3.0).

  • bias (Boolean) (defaults to: true) —

    If false, the calculations are corrected for statistical bias.

  • min_samples (Integer) (defaults to: nil) —

    The number of values in the window that should be non-null before computing a result. If set to nil (default), it will be set equal to window_size.

  • center (Boolean) (defaults to: false) —

    Set the labels at the center of the window.

Returns:



4254
4255
4256
4257
4258
4259
4260
4261
4262
 
# File 'lib/polars/series.rb', line 4254

def rolling_kurtosis(
  window_size,
  fisher: true,
  bias: true,
  min_samples: nil,
  center: false
)
  super
end

#rolling_max(window_size, weights: nil, min_periods: nil, center: false) ⇒ Series

Apply a rolling max (moving max) over the values in this array.

A window of length window_size will traverse the array. The values that fill this window will (optionally) be multiplied with the weights given by the weight vector. The resulting values will be aggregated to their sum.

Examples:

s = Polars::Series.new("a", [100, 200, 300, 400, 500])
s.rolling_max(2)
# =>
# shape: (5,)
# Series: 'a' [i64]
# [
#         null
#         200
#         300
#         400
#         500
# ]

Parameters:

  • window_size (Integer) —

    The length of the window.

  • weights (Array) (defaults to: nil) —

    An optional slice with the same length as the window that will be multiplied elementwise with the values in the window.

  • min_periods (Integer) (defaults to: nil) —

    The number of values in the window that should be non-null before computing a result. If nil, it will be set equal to window size.

  • center (Boolean) (defaults to: false) —

    Set the labels at the center of the window

Returns:



3910
3911
3912
3913
3914
3915
3916
3917
 
# File 'lib/polars/series.rb', line 3910

def rolling_max(
  window_size,
  weights: nil,
  min_periods: nil,
  center: false
)
  super
end

#rolling_mean(window_size, weights: nil, min_periods: nil, center: false) ⇒ Series

Apply a rolling mean (moving mean) over the values in this array.

A window of length window_size will traverse the array. The values that fill this window will (optionally) be multiplied with the weights given by the weight vector. The resulting values will be aggregated to their sum.

Examples:

s = Polars::Series.new("a", [100, 200, 300, 400, 500])
s.rolling_mean(2)
# =>
# shape: (5,)
# Series: 'a' [f64]
# [
#         null
#         150.0
#         250.0
#         350.0
#         450.0
# ]

Parameters:

  • window_size (Integer) —

    The length of the window.

  • weights (Array) (defaults to: nil) —

    An optional slice with the same length as the window that will be multiplied elementwise with the values in the window.

  • min_periods (Integer) (defaults to: nil) —

    The number of values in the window that should be non-null before computing a result. If nil, it will be set equal to window size.

  • center (Boolean) (defaults to: false) —

    Set the labels at the center of the window

Returns:



3951
3952
3953
3954
3955
3956
3957
3958
 
# File 'lib/polars/series.rb', line 3951

def rolling_mean(
  window_size,
  weights: nil,
  min_periods: nil,
  center: false
)
  super
end

#rolling_median(window_size, weights: nil, min_periods: nil, center: false) ⇒ Series

Compute a rolling median.

Examples:

s = Polars::Series.new("a", [1.0, 2.0, 3.0, 4.0, 6.0, 8.0])
s.rolling_median(3)
# =>
# shape: (6,)
# Series: 'a' [f64]
# [
#         null
#         null
#         2.0
#         3.0
#         4.0
#         6.0
# ]

Parameters:

  • window_size (Integer) —

    The length of the window.

  • weights (Array) (defaults to: nil) —

    An optional slice with the same length as the window that will be multiplied elementwise with the values in the window.

  • min_periods (Integer) (defaults to: nil) —

    The number of values in the window that should be non-null before computing a result. If nil, it will be set equal to window size.

  • center (Boolean) (defaults to: false) —

    Set the labels at the center of the window

Returns:



4123
4124
4125
4126
4127
4128
4129
4130
 
# File 'lib/polars/series.rb', line 4123

def rolling_median(
  window_size,
  weights: nil,
  min_periods: nil,
  center: false
)
  super
end

#rolling_min(window_size, weights: nil, min_periods: nil, center: false) ⇒ Series

Apply a rolling min (moving min) over the values in this array.

A window of length window_size will traverse the array. The values that fill this window will (optionally) be multiplied with the weights given by the weight vector. The resulting values will be aggregated to their sum.

Examples:

s = Polars::Series.new("a", [100, 200, 300, 400, 500])
s.rolling_min(3)
# =>
# shape: (5,)
# Series: 'a' [i64]
# [
#         null
#         null
#         100
#         200
#         300
# ]

Parameters:

  • window_size (Integer) —

    The length of the window.

  • weights (Array) (defaults to: nil) —

    An optional slice with the same length as the window that will be multiplied elementwise with the values in the window.

  • min_periods (Integer) (defaults to: nil) —

    The number of values in the window that should be non-null before computing a result. If nil, it will be set equal to window size.

  • center (Boolean) (defaults to: false) —

    Set the labels at the center of the window

Returns:



3869
3870
3871
3872
3873
3874
3875
3876
 
# File 'lib/polars/series.rb', line 3869

def rolling_min(
  window_size,
  weights: nil,
  min_periods: nil,
  center: false
)
  super
end

#rolling_quantile(quantile, interpolation: "nearest", window_size: 2, weights: nil, min_periods: nil, center: false) ⇒ Series

Compute a rolling quantile.

Examples:

s = Polars::Series.new("a", [1.0, 2.0, 3.0, 4.0, 6.0, 8.0])
s.rolling_quantile(0.33, window_size: 3)
# =>
# shape: (6,)
# Series: 'a' [f64]
# [
#         null
#         null
#         2.0
#         3.0
#         4.0
#         6.0
# ]

s.rolling_quantile(0.33, interpolation: "linear", window_size: 3)
# =>
# shape: (6,)
# Series: 'a' [f64]
# [
#         null
#         null
#         1.66
#         2.66
#         3.66
#         5.32
# ]

Parameters:

  • quantile (Float) —

    Quantile between 0.0 and 1.0.

  • interpolation ("nearest", "higher", "lower", "midpoint", "linear") (defaults to: "nearest") —

    Interpolation method.

  • window_size (Integer) (defaults to: 2) —

    The length of the window.

  • weights (Array) (defaults to: nil) —

    An optional slice with the same length as the window that will be multiplied elementwise with the values in the window.

  • min_periods (Integer) (defaults to: nil) —

    The number of values in the window that should be non-null before computing a result. If nil, it will be set equal to window size.

  • center (Boolean) (defaults to: false) —

    Set the labels at the center of the window

Returns:



4179
4180
4181
4182
4183
4184
4185
4186
4187
4188
 
# File 'lib/polars/series.rb', line 4179

def rolling_quantile(
  quantile,
  interpolation: "nearest",
  window_size: 2,
  weights: nil,
  min_periods: nil,
  center: false
)
  super
end

#rolling_skew(window_size, bias: true, min_samples: nil, center: false) ⇒ Series

Compute a rolling skew.

Examples:

Polars::Series.new([1, 4, 2, 9]).rolling_skew(3)
# =>
# shape: (4,)
# Series: '' [f64]
# [
#         null
#         null
#         0.381802
#         0.47033
# ]

Parameters:

  • window_size (Integer) —

    Integer size of the rolling window.

  • bias (Boolean) (defaults to: true) —

    If false, the calculations are corrected for statistical bias.

  • min_samples (Integer) (defaults to: nil) —

    The number of values in the window that should be non-null before computing a result. If set to nil (default), it will be set equal to window_size.

  • center (Boolean) (defaults to: false) —

    Set the labels at the center of the window.

Returns:



4215
4216
4217
 
# File 'lib/polars/series.rb', line 4215

def rolling_skew(window_size, bias: true, min_samples: nil, center: false)
  super
end

#rolling_std(window_size, weights: nil, min_periods: nil, center: false, ddof: 1) ⇒ Series

Compute a rolling std dev.

A window of length window_size will traverse the array. The values that fill this window will (optionally) be multiplied with the weights given by the weight vector. The resulting values will be aggregated to their sum.

Examples:

s = Polars::Series.new("a", [1.0, 2.0, 3.0, 4.0, 6.0, 8.0])
s.rolling_std(3)
# =>
# shape: (6,)
# Series: 'a' [f64]
# [
#         null
#         null
#         1.0
#         1.0
#         1.527525
#         2.0
# ]

Parameters:

  • window_size (Integer) —

    The length of the window.

  • weights (Array) (defaults to: nil) —

    An optional slice with the same length as the window that will be multiplied elementwise with the values in the window.

  • min_periods (Integer) (defaults to: nil) —

    The number of values in the window that should be non-null before computing a result. If nil, it will be set equal to window size.

  • center (Boolean) (defaults to: false) —

    Set the labels at the center of the window

  • ddof (Integer) (defaults to: 1) —

    "Delta Degrees of Freedom": The divisor for a length N window is N - ddof

Returns:



4036
4037
4038
4039
4040
4041
4042
4043
4044
 
# File 'lib/polars/series.rb', line 4036

def rolling_std(
  window_size,
  weights: nil,
  min_periods: nil,
  center: false,
  ddof: 1
)
  super
end

#rolling_sum(window_size, weights: nil, min_periods: nil, center: false) ⇒ Series

Apply a rolling sum (moving sum) over the values in this array.

A window of length window_size will traverse the array. The values that fill this window will (optionally) be multiplied with the weights given by the weight vector. The resulting values will be aggregated to their sum.

Examples:

s = Polars::Series.new("a", [1, 2, 3, 4, 5])
s.rolling_sum(2)
# =>
# shape: (5,)
# Series: 'a' [i64]
# [
#         null
#         3
#         5
#         7
#         9
# ]

Parameters:

  • window_size (Integer) —

    The length of the window.

  • weights (Array) (defaults to: nil) —

    An optional slice with the same length as the window that will be multiplied elementwise with the values in the window.

  • min_periods (Integer) (defaults to: nil) —

    The number of values in the window that should be non-null before computing a result. If nil, it will be set equal to window size.

  • center (Boolean) (defaults to: false) —

    Set the labels at the center of the window

Returns:



3992
3993
3994
3995
3996
3997
3998
3999
 
# File 'lib/polars/series.rb', line 3992

def rolling_sum(
  window_size,
  weights: nil,
  min_periods: nil,
  center: false
)
  super
end

#rolling_var(window_size, weights: nil, min_periods: nil, center: false, ddof: 1) ⇒ Series

Compute a rolling variance.

A window of length window_size will traverse the array. The values that fill this window will (optionally) be multiplied with the weights given by the weight vector. The resulting values will be aggregated to their sum.

Examples:

s = Polars::Series.new("a", [1.0, 2.0, 3.0, 4.0, 6.0, 8.0])
s.rolling_var(3)
# =>
# shape: (6,)
# Series: 'a' [f64]
# [
#         null
#         null
#         1.0
#         1.0
#         2.333333
#         4.0
# ]

Parameters:

  • window_size (Integer) —

    The length of the window.

  • weights (Array) (defaults to: nil) —

    An optional slice with the same length as the window that will be multiplied elementwise with the values in the window.

  • min_periods (Integer) (defaults to: nil) —

    The number of values in the window that should be non-null before computing a result. If nil, it will be set equal to window size.

  • center (Boolean) (defaults to: false) —

    Set the labels at the center of the window

  • ddof (Integer) (defaults to: 1) —

    "Delta Degrees of Freedom": The divisor for a length N window is N - ddof

Returns:



4081
4082
4083
4084
4085
4086
4087
4088
4089
 
# File 'lib/polars/series.rb', line 4081

def rolling_var(
  window_size,
  weights: nil,
  min_periods: nil,
  center: false,
  ddof: 1
)
  super
end

#round(decimals = 0) ⇒ Series

Round underlying floating point data by decimals digits.

Examples:

s = Polars::Series.new("a", [1.12345, 2.56789, 3.901234])
s.round(2)
# =>
# shape: (3,)
# Series: 'a' [f64]
# [
#         1.12
#         2.57
#         3.9
# ]

Parameters:

  • decimals (Integer) (defaults to: 0) —

    number of decimals to round by.

Returns:



3363
3364
3365
 
# File 'lib/polars/series.rb', line 3363

def round(decimals = 0)
  super
end

#round_sig_figs(digits) ⇒ Series

Round to a number of significant figures.

Examples:

s = Polars::Series.new([0.01234, 3.333, 3450.0])
s.round_sig_figs(2)
# =>
# shape: (3,)
# Series: '' [f64]
# [
#         0.012
#         3.3
#         3500.0
# ]

Parameters:

  • digits (Integer) —

    Number of significant figures to round to.

Returns:



3385
3386
3387
 
# File 'lib/polars/series.rb', line 3385

def round_sig_figs(digits)
  super
end

#sample(n: nil, frac: nil, with_replacement: false, shuffle: false, seed: nil) ⇒ Series

Sample from this Series.

Examples:

s = Polars::Series.new("a", [1, 2, 3, 4, 5])
s.sample(n: 2, seed: 0)
# =>
# shape: (2,)
# Series: 'a' [i64]
# [
#         5
#         2
# ]

Parameters:

  • n (Integer) (defaults to: nil) —

    Number of items to return. Cannot be used with frac. Defaults to 1 if frac is nil.

  • frac (Float) (defaults to: nil) —

    Fraction of items to return. Cannot be used with n.

  • with_replacement (Boolean) (defaults to: false) —

    Allow values to be sampled more than once.

  • shuffle (Boolean) (defaults to: false) —

    Shuffle the order of sampled data points.

  • seed (Integer) (defaults to: nil) —

    Seed for the random number generator. If set to nil (default), a random seed is used.

Returns:



4291
4292
4293
4294
4295
4296
4297
4298
4299
4300
4301
4302
4303
4304
4305
4306
4307
4308
4309
4310
 
# File 'lib/polars/series.rb', line 4291

def sample(
  n: nil,
  frac: nil,
  with_replacement: false,
  shuffle: false,
  seed: nil
)
  if !n.nil? && !frac.nil?
    raise ArgumentError, "cannot specify both `n` and `frac`"
  end

  if n.nil? && !frac.nil?
    return Utils.wrap_s(_s.sample_frac(frac, with_replacement, shuffle, seed))
  end

  if n.nil?
    n = 1
  end
  Utils.wrap_s(_s.sample_n(n, with_replacement, shuffle, seed))
end

#scatter(idx, value) ⇒ Series Also known as: set_at_idx

Set values at the index locations.

Examples:

s = Polars::Series.new("a", [1, 2, 3])
s.set_at_idx(1, 10)
# =>
# shape: (3,)
# Series: 'a' [i64]
# [
#         1
#         10
#         3
# ]

Parameters:

  • idx (Object) —

    Integers representing the index locations.

  • value (Object) —

    Replacement values.

Returns:



3114
3115
3116
3117
3118
3119
3120
3121
3122
3123
3124
3125
3126
3127
3128
3129
3130
3131
3132
3133
3134
3135
 
# File 'lib/polars/series.rb', line 3114

def scatter(idx, value)
  if idx.is_a?(Integer)
    idx = [idx]
  end
  if idx.length == 0
    return self
  end

  idx = Series.new("", idx)
  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
    if idx.length > 0
      value = value.extend_constant(value[0], idx.length - 1)
    end
  elsif !value.is_a?(Series)
    value = Series.new("", value)
  end
  _s.scatter(idx._s, value._s)
  self
end

#search_sorted(element, side: "any", descending: false) ⇒ Integer

Find indices where elements should be inserted to maintain order.

Examples:

s = Polars::Series.new("set", [1, 2, 3, 4, 4, 5, 6, 7])
s.search_sorted(4)
# => 3

s.search_sorted(4, side: "left")
# => 3

s.search_sorted(4, side: "right")
# => 5

s.search_sorted([1, 4, 5])
# =>
# shape: (3,)
# Series: 'set' [u32]
# [
#         0
#         3
#         5
# ]

s.search_sorted([1, 4, 5], side: "left")
# =>
# shape: (3,)
# Series: 'set' [u32]
# [
#         0
#         3
#         5
# ]

s.search_sorted([1, 4, 5], side: "right")
# =>
# shape: (3,)
# Series: 'set' [u32]
# [
#         1
#         5
#         6
# ]

Parameters:

  • element (Object) —

    Expression or scalar value.

  • side ('any', 'left', 'right') (defaults to: "any") —

    If 'any', the index of the first suitable location found is given. If 'left', the index of the leftmost suitable location found is given. If 'right', return the rightmost suitable location found is given.

  • descending (Boolean) (defaults to: false) —

    Boolean indicating whether the values are descending or not (they are required to be sorted either way).

Returns:

  • (Integer) 


2233
2234
2235
2236
2237
2238
2239
 
# File 'lib/polars/series.rb', line 2233

def search_sorted(element, side: "any", descending: false)
  if element.is_a?(Integer) || element.is_a?(Float)
    return Polars.select(Polars.lit(self).search_sorted(element, side: side, descending: descending)).item
  end
  element = Series.new(element)
  Polars.select(Polars.lit(self).search_sorted(element, side: side, descending: descending)).to_series
end

#set(filter, value) ⇒ Series

Note:

Use of this function is frequently an anti-pattern, as it can block optimization (predicate pushdown, etc). Consider using Polars.when(predicate).then(value).otherwise(self) instead.

Set masked values.

Examples:

s = Polars::Series.new("a", [1, 2, 3])
s.set(s == 2, 10)
# =>
# shape: (3,)
# Series: 'a' [i64]
# [
#         1
#         10
#         3
# ]

Parameters:

  • filter (Series) —

    Boolean mask.

  • value (Object) —

    Value with which to replace the masked values.

Returns:



3090
3091
3092
 
# File 'lib/polars/series.rb', line 3090

def set(filter, value)
  Utils.wrap_s(_s.send("set_with_mask_#{DTYPE_TO_FFINAME.fetch(dtype.class)}", filter._s, value))
end

#set_sorted(reverse: false) ⇒ Series

Note:

This can lead to incorrect results if this Series is not sorted!! Use with care!

Flags the Series as sorted.

Enables downstream code to user fast paths for sorted arrays.

Examples:

s = Polars::Series.new("a", [1, 2, 3])
s.set_sorted.max
# => 3

Parameters:

  • reverse (Boolean) (defaults to: false) —

    If the Series order is reversed, e.g. descending.

Returns:



5265
5266
5267
 
# File 'lib/polars/series.rb', line 5265

def set_sorted(reverse: false)
  Utils.wrap_s(_s.set_sorted(reverse))
end

#shape ⇒ Array

Shape of this Series.

Examples:

s = Polars::Series.new("a", [1, 2, 3])
s.shape
# => [3]

Returns:



139
140
141
 
# File 'lib/polars/series.rb', line 139

def shape
  [_s.len]
end

#shift(periods = 1) ⇒ Series

Shift the values by a given period.

Examples:

s = Polars::Series.new("a", [1, 2, 3])
s.shift(1)
# =>
# shape: (3,)
# Series: 'a' [i64]
# [
#         null
#         1
#         2
# ]

s.shift(-1)
# =>
# shape: (3,)
# Series: 'a' [i64]
# [
#         2
#         3
#         null
# ]

Parameters:

  • periods (Integer) (defaults to: 1) —

    Number of places to shift (may be negative).

Returns:



3777
3778
3779
 
# File 'lib/polars/series.rb', line 3777

def shift(periods = 1)
  super
end

#shift_and_fill(periods, fill_value) ⇒ Series

Shift the values by a given period and fill the resulting null values.

Parameters:

  • periods (Integer) —

    Number of places to shift (may be negative).

  • fill_value (Object) —

    Fill nil values with the result of this expression.

Returns:



3789
3790
3791
 
# File 'lib/polars/series.rb', line 3789

def shift_and_fill(periods, fill_value)
  super
end

#shrink_dtype ⇒ Series

Shrink numeric columns to the minimal required datatype.

Shrink to the dtype needed to fit the extrema of this Series. This can be used to reduce memory pressure.

Examples:

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
# ]

Returns:



5309
5310
5311
 
# File 'lib/polars/series.rb', line 5309

def shrink_dtype
  Utils.wrap_s(_s.shrink_dtype)
end

#shrink_to_fit(in_place: false) ⇒ Series

Shrink Series memory usage.

Shrinks the underlying array capacity to exactly fit the actual data. (Note that this function does not change the Series data type).

Returns:



4372
4373
4374
4375
4376
4377
4378
4379
4380
4381
 
# File 'lib/polars/series.rb', line 4372

def shrink_to_fit(in_place: false)
  if in_place
    _s.shrink_to_fit
    self
  else
    series = clone
    series._s.shrink_to_fit
    series
  end
end

#shuffle(seed: nil) ⇒ Series

Shuffle the contents of this Series.

Examples:

s = Polars::Series.new("a", [1, 2, 3])
s.shuffle(seed: 1)
# =>
# shape: (3,)
# Series: 'a' [i64]
# [
#         2
#         3
#         1
# ]

Parameters:

  • seed (Integer, nil) (defaults to: nil) —

    Seed for the random number generator.

Returns:



5072
5073
5074
 
# File 'lib/polars/series.rb', line 5072

def shuffle(seed: nil)
  super
end

#sign ⇒ Series

Compute the element-wise indication of the sign.

Examples:

s = Polars::Series.new("a", [-9.0, -0.0, 0.0, 4.0, nil])
s.sign
# =>
# shape: (5,)
# Series: 'a' [f64]
# [
#         -1.0
#         -0.0
#         0.0
#         1.0
#         null
# ]

Returns:



3448
3449
3450
 
# File 'lib/polars/series.rb', line 3448

def sign
  super
end

#sin ⇒ Series

Compute the element-wise value for the sine.

Examples:

s = Polars::Series.new("a", [0.0, Math::PI / 2.0, Math::PI])
s.sin
# =>
# shape: (3,)
# Series: 'a' [f64]
# [
#         0.0
#         1.0
#         1.2246e-16
# ]

Returns:



3467
3468
3469
 
# File 'lib/polars/series.rb', line 3467

def sin
  super
end

#sinh ⇒ Series

Compute the element-wise value for the hyperbolic sine.

Examples:

s = Polars::Series.new("a", [1.0, 0.0, -1.0])
s.sinh
# =>
# shape: (3,)
# Series: 'a' [f64]
# [
#         1.175201
#         0.0
#         -1.175201
# ]

Returns:



3668
3669
3670
 
# File 'lib/polars/series.rb', line 3668

def sinh
  super
end

#skew(bias: true) ⇒ Float?

Compute the sample skewness of a data set.

For normally distributed data, the skewness should be about zero. For unimodal continuous distributions, a skewness value greater than zero means that there is more weight in the right tail of the distribution. The function skewtest can be used to determine if the skewness value is close enough to zero, statistically speaking.

Examples:

s = Polars::Series.new([1, 2, 2, 4, 5])
s.skew
# => 0.34776706224699483

Parameters:

  • bias (Boolean) (defaults to: true) —

    If false, the calculations are corrected for statistical bias.

Returns:

  • (Float, nil) 


4678
4679
4680
 
# File 'lib/polars/series.rb', line 4678

def skew(bias: true)
  _s.skew(bias)
end

#slice(offset, length = nil) ⇒ Series

Get a slice of this Series.

Examples:

s = Polars::Series.new("a", [1, 2, 3, 4])
s.slice(1, 2)
# =>
# shape: (2,)
# Series: 'a' [i64]
# [
#         2
#         3
# ]

Parameters:

  • offset (Integer) —

    Start index. Negative indexing is supported.

  • length (Integer, nil) (defaults to: nil) —

    Length of the slice. If set to nil, all rows starting at the offset will be selected.

Returns:



1750
1751
1752
 
# File 'lib/polars/series.rb', line 1750

def slice(offset, length = nil)
  self.class._from_rbseries(_s.slice(offset, length))
end

#sort(reverse: false, nulls_last: false, multithreaded: true, in_place: false) ⇒ Series

Sort this Series.

Examples:

s = Polars::Series.new("a", [1, 3, 4, 2])
s.sort
# =>
# shape: (4,)
# Series: 'a' [i64]
# [
#         1
#         2
#         3
#         4
# ]
s.sort(reverse: true)
# =>
# shape: (4,)
# Series: 'a' [i64]
# [
#         4
#         3
#         2
#         1
# ]

Parameters:

  • reverse (Boolean) (defaults to: false) —

    Reverse sort.

  • nulls_last (Boolean) (defaults to: false) —

    Place null values last instead of first.

  • multithreaded (Boolean) (defaults to: true) —

    Sort using multiple threads.

  • in_place (Boolean) (defaults to: false) —

    Sort in place.

Returns:



1975
1976
1977
1978
1979
1980
1981
1982
 
# File 'lib/polars/series.rb', line 1975

def sort(reverse: false, nulls_last: false, multithreaded: true, in_place: false)
  if in_place
    self._s = _s.sort(reverse, nulls_last, multithreaded)
    self
  else
    Utils.wrap_s(_s.sort(reverse, nulls_last, multithreaded))
  end
end

#sqrt ⇒ Series

Compute the square root of the elements.

Examples:

s = Polars::Series.new([1, 2, 3])
s.sqrt
# =>
# shape: (3,)
# Series: '' [f64]
# [
#         1.0
#         1.414214
#         1.732051
# ]

Returns:



576
577
578
 
# File 'lib/polars/series.rb', line 576

def sqrt
  super
end

#std(ddof: 1) ⇒ Float?

Get the standard deviation of this Series.

Examples:

s = Polars::Series.new("a", [1, 2, 3])
s.std
# => 1.0

Parameters:

  • ddof (Integer) (defaults to: 1) —

    “Delta Degrees of Freedom”: the divisor used in the calculation is N - ddof, where N represents the number of elements.

Returns:

  • (Float, nil) 


1055
1056
1057
1058
1059
1060
1061
 
# File 'lib/polars/series.rb', line 1055

def std(ddof: 1)
  if !is_numeric
    nil
  else
    to_frame.select(Polars.col(name).std(ddof: ddof)).to_series[0]
  end
end

#str ⇒ StringNameSpace

Create an object namespace of all string related methods.

Returns:



5485
5486
5487
 
# File 'lib/polars/series.rb', line 5485

def str
  StringNameSpace.new(self)
end

#struct ⇒ StructNameSpace

Create an object namespace of all struct related methods.

Returns:



5492
5493
5494
 
# File 'lib/polars/series.rb', line 5492

def struct
  StructNameSpace.new(self)
end

#sum ⇒ Numeric

Note:

Dtypes :i8, :u8, :i16, and :u16 are cast to :i64 before summing to prevent overflow issues.

Reduce this Series to the sum value.

Examples:

s = Polars::Series.new("a", [1, 2, 3])
s.sum
# => 6

Returns:

  • (Numeric) 


919
920
921
 
# File 'lib/polars/series.rb', line 919

def sum
  _s.sum
end

#tail(n = 10) ⇒ Series

Get the last n rows.

Examples:

s = Polars::Series.new("a", [1, 2, 3])
s.tail(2)
# =>
# shape: (2,)
# Series: 'a' [i64]
# [
#         2
#         3
# ]

Parameters:

  • n (Integer) (defaults to: 10) —

    Number of rows to return.

Returns:



1879
1880
1881
 
# File 'lib/polars/series.rb', line 1879

def tail(n = 10)
  to_frame.select(F.col(name).tail(n)).to_series
end

#tan ⇒ Series

Compute the element-wise value for the tangent.

Examples:

s = Polars::Series.new("a", [0.0, Math::PI / 2.0, Math::PI])
s.tan
# =>
# shape: (3,)
# Series: 'a' [f64]
# [
#         0.0
#         1.6331e16
#         -1.2246e-16
# ]

Returns:



3505
3506
3507
 
# File 'lib/polars/series.rb', line 3505

def tan
  super
end

#tanh ⇒ Series

Compute the element-wise value for the hyperbolic tangent.

Examples:

s = Polars::Series.new("a", [1.0, 0.0, -1.0])
s.tanh
# =>
# shape: (3,)
# Series: 'a' [f64]
# [
#         0.761594
#         0.0
#         -0.761594
# ]

Returns:



3706
3707
3708
 
# File 'lib/polars/series.rb', line 3706

def tanh
  super
end

#to_a ⇒ Array

Convert this Series to a Ruby Array. This operation clones data.

Examples:

s = Polars::Series.new("a", [1, 2, 3])
s.to_a
# => [1, 2, 3]

Returns:



2794
2795
2796
 
# File 'lib/polars/series.rb', line 2794

def to_a
  _s.to_a
end

#to_dummies(separator: "_", drop_first: false, drop_nulls: false) ⇒ DataFrame

Get dummy variables.

Examples:

s = Polars::Series.new("a", [1, 2, 3])
s.to_dummies
# =>
# shape: (3, 3)
# ┌─────┬─────┬─────┐
# │ a_1 ┆ a_2 ┆ a_3 │
# │ --- ┆ --- ┆ --- │
# │ u8  ┆ u8  ┆ u8  │
# ╞═════╪═════╪═════╡
# │ 1   ┆ 0   ┆ 0   │
# │ 0   ┆ 1   ┆ 0   │
# │ 0   ┆ 0   ┆ 1   │
# └─────┴─────┴─────┘

Parameters:

  • separator (String) (defaults to: "_") —

    Separator/delimiter used when generating column names.

  • drop_first (Boolean) (defaults to: false) —

    Remove the first category from the variable being encoded.

  • drop_nulls (Boolean) (defaults to: false) —

    If there are nil values in the series, a null column is not generated.

Returns:



1137
1138
1139
 
# File 'lib/polars/series.rb', line 1137

def to_dummies(separator: "_", drop_first: false, drop_nulls: false)
  Utils.wrap_df(_s.to_dummies(separator, drop_first, drop_nulls))
end

#to_frame(name = nil) ⇒ DataFrame

Cast this Series to a DataFrame.

Examples:

s = Polars::Series.new("a", [123, 456])
s.to_frame
# =>
# shape: (2, 1)
# ┌─────┐
# │ a   │
# │ --- │
# │ i64 │
# ╞═════╡
# │ 123 │
# │ 456 │
# └─────┘

s.to_frame("xyz")
# =>
# shape: (2, 1)
# ┌─────┐
# │ xyz │
# │ --- │
# │ i64 │
# ╞═════╡
# │ 123 │
# │ 456 │
# └─────┘

Returns:



818
819
820
821
822
823
 
# File 'lib/polars/series.rb', line 818

def to_frame(name = nil)
  if name
    return Utils.wrap_df(RbDataFrame.new([rename(name)._s]))
  end
  Utils.wrap_df(RbDataFrame.new([_s]))
end

#to_numo ⇒ Numo::NArray

Convert this Series to a Numo array. This operation clones data but is completely safe.

Examples:

s = Polars::Series.new("a", [1, 2, 3])
s.to_numo
# =>
# Numo::Int64#shape=[3]
# [1, 2, 3]

Returns:

  • (Numo::NArray) 


3057
3058
3059
3060
3061
3062
3063
 
# File 'lib/polars/series.rb', line 3057

def to_numo
  if is_datelike
    Numo::RObject.cast(to_a)
  else
    _s.to_numo
  end
end

#to_physical ⇒ Series

Cast to physical representation of the logical dtype.

  • :date -> :i32
  • :datetime -> :i64
  • :time -> :i64
  • :duration -> :i64
  • :cat -> :u32
  • other data types will be left unchanged.

Examples:

s = Polars::Series.new("values", ["a", nil, "x", "a"])
s.cast(:cat).to_physical
# =>
# shape: (4,)
# Series: 'values' [u32]
# [
#         0
#         null
#         1
#         0
# ]

Returns:



2782
2783
2784
 
# File 'lib/polars/series.rb', line 2782

def to_physical
  super
end

#to_s ⇒ String Also known as: inspect

Returns a string representing the Series.

Returns:



146
147
148
 
# File 'lib/polars/series.rb', line 146

def to_s
  _s.to_s
end

#top_k(k: 5) ⇒ Boolean

Return the k largest elements.

Examples:

s = Polars::Series.new("a", [2, 5, 1, 4, 3])
s.top_k(k: 3)
# =>
# shape: (3,)
# Series: 'a' [i64]
# [
#         5
#         4
#         3
# ]

Parameters:

  • k (Integer) (defaults to: 5) —

    Number of elements to return.

Returns:



2002
2003
2004
 
# File 'lib/polars/series.rb', line 2002

def top_k(k: 5)
  super
end

#top_k_by(by, k: 5, reverse: false) ⇒ Series

Return the k largest elements of the by column.

Non-null elements are always preferred over null elements, regardless of the value of reverse. The output is not guaranteed to be in any particular order, call sort after this function if you wish the output to be sorted.

Examples:

s = Polars::Series.new("a", [2, 5, 1, 4, 3])
s.top_k_by("a", k: 3)
# =>
# shape: (3,)
# Series: 'a' [i64]
# [
#         5
#         4
#         3
# ]

Parameters:

  • by (Object) —

    Column used to determine the largest elements. Accepts expression input. Strings are parsed as column names.

  • k (Integer) (defaults to: 5) —

    Number of elements to return.

  • reverse (Object) (defaults to: false) —

    Consider the k smallest elements of the by column (instead of the k largest). This can be specified per column by passing a sequence of booleans.

Returns:



2036
2037
2038
2039
2040
2041
2042
 
# File 'lib/polars/series.rb', line 2036

def top_k_by(
  by,
  k: 5,
  reverse: false
)
  super
end

#unique(maintain_order: false) ⇒ Series Also known as: uniq

Get unique elements in series.

Examples:

s = Polars::Series.new("a", [1, 2, 2, 3])
s.unique.sort
# =>
# shape: (3,)
# Series: 'a' [i64]
# [
#         1
#         2
#         3
# ]

Parameters:

  • maintain_order (Boolean) (defaults to: false) —

    Maintain order of data. This requires more work.

Returns:



2259
2260
2261
 
# File 'lib/polars/series.rb', line 2259

def unique(maintain_order: false)
  super
end

#unique_counts ⇒ Series

Return a count of the unique values in the order of appearance.

Examples:

s = Polars::Series.new("id", ["a", "b", "b", "c", "c", "c"])
s.unique_counts
# =>
# shape: (3,)
# Series: 'id' [u32]
# [
#         1
#         2
#         3
# ]

Returns:



1469
1470
1471
 
# File 'lib/polars/series.rb', line 1469

def unique_counts
  super
end

#upper_bound ⇒ Series

Return the upper bound of this Series' dtype as a unit Series.

Examples:

s = Polars::Series.new("s", [-1, 0, 1], dtype: Polars::Int8)
s.upper_bound
# =>
# shape: (1,)
# Series: 's' [i8]
# [
#         127
# ]

s = Polars::Series.new("s", [1.0, 2.5, 3.0], dtype: Polars::Float64)
s.upper_bound
# =>
# shape: (1,)
# Series: 's' [f64]
# [
#         inf
# ]

Returns:



4824
4825
4826
 
# File 'lib/polars/series.rb', line 4824

def upper_bound
  super
end

#value_counts(sort: false, parallel: false, name: nil, normalize: false) ⇒ DataFrame

Count the unique values in a Series.

Examples:

s = Polars::Series.new("a", [1, 2, 2, 3])
s.value_counts.sort("a")
# =>
# shape: (3, 2)
# ┌─────┬────────┐
# │ a   ┆ counts │
# │ --- ┆ ---    │
# │ i64 ┆ u32    │
# ╞═════╪════════╡
# │ 1   ┆ 1      │
# │ 2   ┆ 2      │
# │ 3   ┆ 1      │
# └─────┴────────┘

Parameters:

  • sort (Boolean) (defaults to: false) —

    Ensure the output is sorted from most values to least.

  • parallel (Boolean) (defaults to: false) —

    Execute the computation in parallel.

  • name (String) (defaults to: nil) —

    Give the resulting count column a specific name; if normalize is true this defaults to "proportion", otherwise defaults to "count".

  • normalize (Boolean) (defaults to: false) —

    If true, the count is returned as the relative frequency of unique values normalized to 1.0.

Returns:



1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
 
# File 'lib/polars/series.rb', line 1434

def value_counts(
  sort: false,
  parallel: false,
  name: nil,
  normalize: false
)
  if name.nil?
    if normalize
      name = "proportion"
    else
      name = "count"
    end
  end
  DataFrame._from_rbdf(
    self._s.value_counts(
      sort, parallel, name, normalize
    )
  )
end

#var(ddof: 1) ⇒ Float?

Get variance of this Series.

Examples:

s = Polars::Series.new("a", [1, 2, 3])
s.var
# => 1.0

Parameters:

  • ddof (Integer) (defaults to: 1) —

    “Delta Degrees of Freedom”: the divisor used in the calculation is N - ddof, where N represents the number of elements.

Returns:

  • (Float, nil) 


1075
1076
1077
1078
1079
1080
1081
 
# File 'lib/polars/series.rb', line 1075

def var(ddof: 1)
  if !is_numeric
    nil
  else
    to_frame.select(Polars.col(name).var(ddof: ddof)).to_series[0]
  end
end

#zip_with(mask, other) ⇒ Series

Take values from self or other based on the given mask.

Where mask evaluates true, take values from self. Where mask evaluates false, take values from other.

Examples:

s1 = Polars::Series.new([1, 2, 3, 4, 5])
s2 = Polars::Series.new([5, 4, 3, 2, 1])
s1.zip_with(s1 < s2, s2)
# =>
# shape: (5,)
# Series: '' [i64]
# [
#         1
#         2
#         3
#         2
#         1
# ]

mask = Polars::Series.new([true, false, true, false, true])
s1.zip_with(mask, s2)
# =>
# shape: (5,)
# Series: '' [i64]
# [
#         1
#         4
#         3
#         2
#         5
# ]

Parameters:

  • mask (Series) —

    Boolean Series.

  • other (Series) —

    Series of same type.

Returns:



3833
3834
3835
 
# File 'lib/polars/series.rb', line 3833

def zip_with(mask, other)
  Utils.wrap_s(_s.zip_with(mask._s, other._s))
end

#|(other) ⇒ Series

Bitwise OR.

Returns:



164
165
166
167
168
169
 
# File 'lib/polars/series.rb', line 164

def |(other)
  if !other.is_a?(Series)
    other = Series.new([other])
  end
  Utils.wrap_s(_s.bitor(other._s))
end