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


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.

Raises:

  • (NotImplementedError) 


282
283
284
285
286
287
 
# File 'lib/polars/series.rb', line 282

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

#!=(other) ⇒ Series

Not equal.



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

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

#%(other) ⇒ Series

Returns the modulo.



262
263
264
265
266
267
 
# File 'lib/polars/series.rb', line 262

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.



148
149
150
151
152
153
 
# File 'lib/polars/series.rb', line 148

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

#*(other) ⇒ Series

Performs multiplication.



234
235
236
237
238
239
240
241
242
 
# File 'lib/polars/series.rb', line 234

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.



272
273
274
275
276
277
 
# File 'lib/polars/series.rb', line 272

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.



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

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

#-(other) ⇒ Series

Performs subtraction.



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

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

#-@ ⇒ Series

Performs negation.



292
293
294
 
# File 'lib/polars/series.rb', line 292

def -@
  0 - self
end

#/(other) ⇒ Series

Performs division.



247
248
249
250
251
252
253
254
255
256
257
 
# File 'lib/polars/series.rb', line 247

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.



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

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

#<=(other) ⇒ Series

Less than or equal.



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

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

#==(other) ⇒ Series

Equal.



178
179
180
 
# File 'lib/polars/series.rb', line 178

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

#>(other) ⇒ Series

Greater than.



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

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

#>=(other) ⇒ Series

Greater than or equal.



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

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

#[](item) ⇒ Object

Returns elements of the Series.

Raises:

  • (ArgumentError) 


310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
 
# File 'lib/polars/series.rb', line 310

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_idx(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.



341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
 
# File 'lib/polars/series.rb', line 341

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.



168
169
170
171
172
173
 
# File 'lib/polars/series.rb', line 168

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


3459
3460
3461
 
# File 'lib/polars/series.rb', line 3459

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

#abs ⇒ Series

Compute absolute values.



3500
3501
3502
 
# File 'lib/polars/series.rb', line 3500

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")


1060
1061
1062
1063
1064
 
# File 'lib/polars/series.rb', line 1060

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

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

Check if all boolean values in the column are true.



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

def all?(&block)
  if block_given?
    apply(&block).all?
  else
    to_frame.select(Polars.col(name).all).to_series[0]
  end
end

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

Check if any boolean value in the column is true.



414
415
416
417
418
419
420
 
# File 'lib/polars/series.rb', line 414

def any?(&block)
  if block_given?
    apply(&block).any?
  else
    to_frame.select(Polars.col(name).any).to_series[0]
  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
# ]


1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
 
# File 'lib/polars/series.rb', line 1313

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

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

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.apply { |x| x + 10 }
# =>
# shape: (3,)
# Series: 'a' [i64]
# [
#         11
#         12
#         13
# ]


2747
2748
2749
2750
2751
2752
2753
2754
 
# File 'lib/polars/series.rb', line 2747

def apply(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.apply_lambda(func, pl_return_dtype, skip_nulls))
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
# ]


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

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


2634
2635
2636
 
# File 'lib/polars/series.rb', line 2634

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


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

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


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

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


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

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


2658
2659
2660
 
# File 'lib/polars/series.rb', line 2658

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


1578
1579
1580
 
# File 'lib/polars/series.rb', line 1578

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


1566
1567
1568
 
# File 'lib/polars/series.rb', line 1566

def arg_min
  _s.arg_min
end

#arg_sort(reverse: false, nulls_last: false) ⇒ Series

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


1521
1522
1523
 
# File 'lib/polars/series.rb', line 1521

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


1854
1855
1856
 
# File 'lib/polars/series.rb', line 1854

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


1554
1555
1556
 
# File 'lib/polars/series.rb', line 1554

def arg_unique
  super
end

#argsort(reverse: false, nulls_last: false) ⇒ Series

Get the index values that would sort this Series.

Alias for #arg_sort.



1535
1536
1537
 
# File 'lib/polars/series.rb', line 1535

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

#arr ⇒ ArrayNameSpace

Create an object namespace of all array related methods.



3870
3871
3872
 
# File 'lib/polars/series.rb', line 3870

def arr
  ArrayNameSpace.new(self)
end

#bin ⇒ BinaryNameSpace

Create an object namespace of all binary related methods.



3877
3878
3879
 
# File 'lib/polars/series.rb', line 3877

def bin
  BinaryNameSpace.new(self)
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
# ]


1495
1496
1497
 
# File 'lib/polars/series.rb', line 1495

def bottom_k(k: 5)
  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
# ]


2001
2002
2003
 
# File 'lib/polars/series.rb', line 2001

def cast(dtype, strict: true)
  super
end

#cat ⇒ CatNameSpace

Create an object namespace of all categorical related methods.



3884
3885
3886
 
# File 'lib/polars/series.rb', line 3884

def cat
  CatNameSpace.new(self)
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
# ]


2392
2393
2394
 
# File 'lib/polars/series.rb', line 2392

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]


1102
1103
1104
 
# File 'lib/polars/series.rb', line 1102

def chunk_lengths
  _s.chunk_lengths
end

#cleared ⇒ Series

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.cleared
# =>
# shape: (0,)
# Series: 'a' [bool]
# [
# ]


2273
2274
2275
 
# File 'lib/polars/series.rb', line 2273

def cleared
  len > 0 ? limit(0) : clone
end

#clip(min_val, max_val) ⇒ 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 LazyFunctions#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
# ]


3684
3685
3686
 
# File 'lib/polars/series.rb', line 3684

def clip(min_val, max_val)
  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 LazyFunctions#when for more information.



3714
3715
3716
 
# File 'lib/polars/series.rb', line 3714

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 LazyFunctions#when for more information.



3699
3700
3701
 
# File 'lib/polars/series.rb', line 3699

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


2515
2516
2517
 
# File 'lib/polars/series.rb', line 2515

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


2697
2698
2699
 
# File 'lib/polars/series.rb', line 2697

def cosh
  super
end

#count ⇒ Integer

Return the number of elements in the Series.

Examples:

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


1961
1962
1963
1964
1965
 
# File 'lib/polars/series.rb', line 1961

def count
  warn "`Series#count` will exclude null values in 0.9.0. Use `Series#length` instead."
  # len - null_count
  len
end

#cummax(reverse: false) ⇒ Series

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

Examples:

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


1191
1192
1193
 
# File 'lib/polars/series.rb', line 1191

def cummax(reverse: false)
  super
end

#cummin(reverse: false) ⇒ Series

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

Examples:

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


1169
1170
1171
 
# File 'lib/polars/series.rb', line 1169

def cummin(reverse: false)
  super
end

#cumprod(reverse: false) ⇒ Series

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.cumprod
# =>
# shape: (3,)
# Series: 'a' [i64]
# [
#         1
#         2
#         6
# ]


1217
1218
1219
 
# File 'lib/polars/series.rb', line 1217

def cumprod(reverse: false)
  super
end

#cumsum(reverse: false) ⇒ Series

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.cumsum
# =>
# shape: (3,)
# Series: 'a' [i64]
# [
#         1
#         3
#         6
# ]


1147
1148
1149
 
# File 'lib/polars/series.rb', line 1147

def cumsum(reverse: false)
  super
end

#cumulative_eval(expr, min_periods: 1, parallel: false) ⇒ 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' [f64]
# [
#         0.0
#         -3.0
#         -8.0
#         -15.0
#         -24.0
# ]


1046
1047
1048
 
# File 'lib/polars/series.rb', line 1046

def cumulative_eval(expr, min_periods: 1, parallel: false)
  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]   │
# └─────┴─────────────┴────────────┘


784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
 
# File 'lib/polars/series.rb', line 784

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


531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
 
# File 'lib/polars/series.rb', line 531

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.



3568
3569
3570
 
# File 'lib/polars/series.rb', line 3568

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


2430
2431
2432
2433
2434
2435
2436
2437
2438
2439
 
# File 'lib/polars/series.rb', line 2430

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.



481
482
483
 
# File 'lib/polars/series.rb', line 481

def drop_nans
  super
end

#drop_nulls ⇒ Series

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



474
475
476
 
# File 'lib/polars/series.rb', line 474

def drop_nulls
  super
end

#dt ⇒ DateTimeNameSpace

Create an object namespace of all datetime related methods.



3891
3892
3893
 
# File 'lib/polars/series.rb', line 3891

def dt
  DateTimeNameSpace.new(self)
end

#dtype ⇒ Symbol

Get the data type of this Series.



91
92
93
 
# File 'lib/polars/series.rb', line 91

def dtype
  _s.dtype
end

#each ⇒ Object

Returns an enumerator.



299
300
301
302
303
304
305
 
# File 'lib/polars/series.rb', line 299

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


1008
1009
1010
 
# File 'lib/polars/series.rb', line 1008

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

#equals(other, null_equal: false, strict: 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


1948
1949
1950
 
# File 'lib/polars/series.rb', line 1948

def equals(other, null_equal: false, strict: false)
  _s.equals(other._s, null_equal, strict)
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


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

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) ⇒ Series

Exponentially-weighted moving average.



3754
3755
3756
3757
3758
3759
3760
3761
3762
3763
 
# File 'lib/polars/series.rb', line 3754

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

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

Exponentially-weighted moving standard deviation.



3768
3769
3770
3771
3772
3773
3774
3775
3776
3777
3778
 
# File 'lib/polars/series.rb', line 3768

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

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

Exponentially-weighted moving variance.



3783
3784
3785
3786
3787
3788
3789
3790
3791
3792
3793
 
# File 'lib/polars/series.rb', line 3783

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

#exp ⇒ Series

Compute the exponential, element-wise.



467
468
469
 
# File 'lib/polars/series.rb', line 467

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


1925
1926
1927
 
# File 'lib/polars/series.rb', line 1925

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


3818
3819
3820
 
# File 'lib/polars/series.rb', line 3818

def extend_constant(value, n)
  Utils.wrap_s(_s.extend_constant(value, n))
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
# ]


2298
2299
2300
 
# File 'lib/polars/series.rb', line 2298

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


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

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


1348
1349
1350
1351
1352
1353
 
# File 'lib/polars/series.rb', line 1348

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

#flags ⇒ Hash

Get flags that are set on the Series.



98
99
100
101
102
103
104
105
106
107
 
# File 'lib/polars/series.rb', line 98

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


2371
2372
2373
 
# File 'lib/polars/series.rb', line 2371

def floor
  Utils.wrap_s(_s.floor)
end

#has_validity ⇒ Boolean

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.



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

def has_validity
  _s.has_validity
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
# ]


1372
1373
1374
 
# File 'lib/polars/series.rb', line 1372

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

#inner_dtype ⇒ Symbol

Get the inner dtype in of a List typed Series.



112
113
114
 
# File 'lib/polars/series.rb', line 112

def inner_dtype
  _s.inner_dtype
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
# ]


3493
3494
3495
 
# File 'lib/polars/series.rb', line 3493

def interpolate(method: "linear")
  super
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


2123
2124
2125
 
# File 'lib/polars/series.rb', line 2123

def is_boolean
  dtype == Boolean
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


2095
2096
2097
 
# File 'lib/polars/series.rb', line 2095

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


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

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


1665
1666
1667
 
# File 'lib/polars/series.rb', line 1665

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


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

def is_finite
  super
end

#is_first ⇒ Series

Get a mask of the first unique value.



1881
1882
1883
 
# File 'lib/polars/series.rb', line 1881

def is_first
  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


2110
2111
2112
 
# File 'lib/polars/series.rb', line 2110

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

#is_in(other) ⇒ 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])
s2.is_in(s)
# =>
# shape: (2,)
# Series: 'b' [bool]
# [
#         true
#         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
# ]


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

def is_in(other)
  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
# ]


1744
1745
1746
 
# File 'lib/polars/series.rb', line 1744

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


1764
1765
1766
 
# File 'lib/polars/series.rb', line 1764

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


1784
1785
1786
 
# File 'lib/polars/series.rb', line 1784

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


1706
1707
1708
 
# File 'lib/polars/series.rb', line 1706

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


1686
1687
1688
 
# File 'lib/polars/series.rb', line 1686

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


2082
2083
2084
 
# File 'lib/polars/series.rb', line 2082

def is_numeric
  [Int8, Int16, Int32, Int64, UInt8, UInt16, UInt32, UInt64, Float32, Float64].include?(dtype)
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
# ]


1874
1875
1876
 
# File 'lib/polars/series.rb', line 1874

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


2138
2139
2140
 
# File 'lib/polars/series.rb', line 2138

def is_utf8
  dtype == String
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



3654
3655
3656
 
# File 'lib/polars/series.rb', line 3654

def kurtosis(fisher: true, bias: true)
  _s.kurtosis(fisher, bias)
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


1975
1976
1977
 
# File 'lib/polars/series.rb', line 1975

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


1240
1241
1242
 
# File 'lib/polars/series.rb', line 1240

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

#list ⇒ ListNameSpace

Create an object namespace of all list related methods.



3863
3864
3865
 
# File 'lib/polars/series.rb', line 3863

def list
  ListNameSpace.new(self)
end

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

Compute the logarithm to a given base.



453
454
455
 
# File 'lib/polars/series.rb', line 453

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

#log10 ⇒ Series

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



460
461
462
 
# File 'lib/polars/series.rb', line 460

def log10
  super
end

#max ⇒ Object

Get the maximum value in this Series.

Examples:

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


629
630
631
 
# File 'lib/polars/series.rb', line 629

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


598
599
600
 
# File 'lib/polars/series.rb', line 598

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


695
696
697
 
# File 'lib/polars/series.rb', line 695

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


617
618
619
 
# File 'lib/polars/series.rb', line 617

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


2456
2457
2458
 
# File 'lib/polars/series.rb', line 2456

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


1121
1122
1123
 
# File 'lib/polars/series.rb', line 1121

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


3412
3413
3414
 
# File 'lib/polars/series.rb', line 3412

def n_unique
  _s.n_unique
end

#name ⇒ String

Get the name of this Series.



119
120
121
 
# File 'lib/polars/series.rb', line 119

def name
  _s.name
end

#nan_max ⇒ Object

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



636
637
638
 
# File 'lib/polars/series.rb', line 636

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

#nan_min ⇒ Object

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



643
644
645
 
# File 'lib/polars/series.rb', line 643

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

#new_from_index(index, length) ⇒ Series

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



3846
3847
3848
 
# File 'lib/polars/series.rb', line 3846

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.



438
439
440
441
442
443
444
 
# File 'lib/polars/series.rb', line 438

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

#null_count ⇒ Integer

Count the null values in this Series.



1643
1644
1645
 
# File 'lib/polars/series.rb', line 1643

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


3619
3620
3621
 
# File 'lib/polars/series.rb', line 3619

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


3379
3380
3381
 
# File 'lib/polars/series.rb', line 3379

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


3400
3401
3402
 
# File 'lib/polars/series.rb', line 3400

def peak_min
  super
end

#product ⇒ Numeric

Reduce this Series to the product value.



605
606
607
 
# File 'lib/polars/series.rb', line 605

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


869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
 
# File 'lib/polars/series.rb', line 869

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


712
713
714
 
# File 'lib/polars/series.rb', line 712

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

#rank(method: "average", reverse: false) ⇒ 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
# ]


3556
3557
3558
 
# File 'lib/polars/series.rb', line 3556

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

#rechunk(in_place: false) ⇒ Series

Create a single chunk of memory for this Series.



2050
2051
2052
2053
 
# File 'lib/polars/series.rb', line 2050

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.



3472
3473
3474
 
# File 'lib/polars/series.rb', line 3472

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")


1078
1079
1080
1081
1082
1083
1084
1085
 
# File 'lib/polars/series.rb', line 1078

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

#reshape(dims) ⇒ Series

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



3725
3726
3727
 
# File 'lib/polars/series.rb', line 3725

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


2070
2071
2072
 
# File 'lib/polars/series.rb', line 2070

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)
# ┌─────────┬────────┐
# │ lengths ┆ values │
# │ ---     ┆ ---    │
# │ i32     ┆ i64    │
# ╞═════════╪════════╡
# │ 2       ┆ 1      │
# │ 1       ┆ 2      │
# │ 1       ┆ 1      │
# │ 1       ┆ null   │
# │ 1       ┆ 1      │
# │ 2       ┆ 3      │
# └─────────┴────────┘


912
913
914
 
# File 'lib/polars/series.rb', line 912

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


940
941
942
 
# File 'lib/polars/series.rb', line 940

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


2928
2929
2930
2931
2932
2933
2934
2935
2936
2937
2938
2939
2940
2941
2942
2943
2944
 
# File 'lib/polars/series.rb', line 2928

def rolling_max(
  window_size,
  weights: nil,
  min_periods: nil,
  center: false
)
  to_frame
    .select(
      Polars.col(name).rolling_max(
        window_size,
        weights: weights,
        min_periods: min_periods,
        center: center
      )
    )
    .to_series
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
# ]


2978
2979
2980
2981
2982
2983
2984
2985
2986
2987
2988
2989
2990
2991
2992
2993
2994
 
# File 'lib/polars/series.rb', line 2978

def rolling_mean(
  window_size,
  weights: nil,
  min_periods: nil,
  center: false
)
  to_frame
    .select(
      Polars.col(name).rolling_mean(
        window_size,
        weights: weights,
        min_periods: min_periods,
        center: center
      )
    )
    .to_series
end

#rolling_median(window_size, weights: nil, min_periods: nil, center: false, warn_if_unsorted: true) ⇒ 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
# ]


3188
3189
3190
3191
3192
3193
3194
3195
3196
3197
3198
3199
3200
3201
3202
3203
3204
3205
3206
3207
3208
3209
3210
 
# File 'lib/polars/series.rb', line 3188

def rolling_median(
  window_size,
  weights: nil,
  min_periods: nil,
  center: false,
  warn_if_unsorted: true
)
  if min_periods.nil?
    min_periods = window_size
  end

  to_frame
    .select(
      Polars.col(name).rolling_median(
        window_size,
        weights: weights,
        min_periods: min_periods,
        center: center,
        warn_if_unsorted: warn_if_unsorted
      )
    )
    .to_series
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
# ]


2878
2879
2880
2881
2882
2883
2884
2885
2886
2887
2888
2889
2890
2891
2892
2893
2894
 
# File 'lib/polars/series.rb', line 2878

def rolling_min(
  window_size,
  weights: nil,
  min_periods: nil,
  center: false
)
  to_frame
    .select(
      Polars.col(name).rolling_min(
        window_size,
        weights: weights,
        min_periods: min_periods,
        center: center
      )
    )
    .to_series
end

#rolling_quantile(quantile, interpolation: "nearest", window_size: 2, weights: nil, min_periods: nil, center: false, warn_if_unsorted: true) ⇒ 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
#         1.0
#         2.0
#         3.0
#         4.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
# ]


3259
3260
3261
3262
3263
3264
3265
3266
3267
3268
3269
3270
3271
3272
3273
3274
3275
3276
3277
3278
3279
3280
3281
3282
3283
3284
3285
 
# File 'lib/polars/series.rb', line 3259

def rolling_quantile(
  quantile,
  interpolation: "nearest",
  window_size: 2,
  weights: nil,
  min_periods: nil,
  center: false,
  warn_if_unsorted: true
)
  if min_periods.nil?
    min_periods = window_size
  end

  to_frame
    .select(
      Polars.col(name).rolling_quantile(
        quantile,
        interpolation: interpolation,
        window_size: window_size,
        weights: weights,
        min_periods: min_periods,
        center: center,
        warn_if_unsorted: warn_if_unsorted
      )
    )
    .to_series
end

#rolling_skew(window_size, bias: true) ⇒ Series

Compute a rolling skew.

Examples:

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


3310
3311
3312
 
# File 'lib/polars/series.rb', line 3310

def rolling_skew(window_size, bias: true)
  super
end

#rolling_std(window_size, weights: nil, min_periods: nil, center: false, ddof: 1, warn_if_unsorted: true) ⇒ 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
# ]


3079
3080
3081
3082
3083
3084
3085
3086
3087
3088
3089
3090
3091
3092
3093
3094
3095
3096
3097
3098
3099
 
# File 'lib/polars/series.rb', line 3079

def rolling_std(
  window_size,
  weights: nil,
  min_periods: nil,
  center: false,
  ddof: 1,
  warn_if_unsorted: true
)
  to_frame
    .select(
      Polars.col(name).rolling_std(
        window_size,
        weights: weights,
        min_periods: min_periods,
        center: center,
        ddof: ddof,
        warn_if_unsorted: warn_if_unsorted
      )
    )
    .to_series
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
# ]


3028
3029
3030
3031
3032
3033
3034
3035
3036
3037
3038
3039
3040
3041
3042
3043
3044
 
# File 'lib/polars/series.rb', line 3028

def rolling_sum(
  window_size,
  weights: nil,
  min_periods: nil,
  center: false
)
  to_frame
    .select(
      Polars.col(name).rolling_sum(
        window_size,
        weights: weights,
        min_periods: min_periods,
        center: center
      )
    )
    .to_series
end

#rolling_var(window_size, weights: nil, min_periods: nil, center: false, ddof: 1, warn_if_unsorted: true) ⇒ 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
# ]


3134
3135
3136
3137
3138
3139
3140
3141
3142
3143
3144
3145
3146
3147
3148
3149
3150
3151
3152
3153
3154
 
# File 'lib/polars/series.rb', line 3134

def rolling_var(
  window_size,
  weights: nil,
  min_periods: nil,
  center: false,
  ddof: 1,
  warn_if_unsorted: true
)
  to_frame
    .select(
      Polars.col(name).rolling_var(
        window_size,
        weights: weights,
        min_periods: min_periods,
        center: center,
        ddof: ddof,
        warn_if_unsorted: warn_if_unsorted
      )
    )
    .to_series
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
# ]


2414
2415
2416
 
# File 'lib/polars/series.rb', line 2414

def round(decimals = 0)
  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]
# [
#     1
#     5
# ]


3341
3342
3343
3344
3345
3346
3347
3348
3349
3350
3351
3352
3353
3354
3355
3356
3357
3358
3359
3360
 
# File 'lib/polars/series.rb', line 3341

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


2235
2236
2237
2238
2239
2240
2241
2242
2243
2244
2245
2246
2247
2248
2249
2250
2251
2252
2253
2254
2255
2256
 
# File 'lib/polars/series.rb', line 2235

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") ⇒ Integer

Find indices where elements should be inserted to maintain order.



1588
1589
1590
1591
1592
1593
1594
 
# File 'lib/polars/series.rb', line 1588

def search_sorted(element, side: "any")
  if element.is_a?(Integer) || element.is_a?(Float)
    return Polars.select(Polars.lit(self).search_sorted(element, side: side)).item
  end
  element = Series.new(element)
  Polars.select(Polars.lit(self).search_sorted(element, side: side)).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
# ]


2211
2212
2213
 
# File 'lib/polars/series.rb', line 2211

def set(filter, value)
  Utils.wrap_s(_s.send("set_with_mask_#{DTYPE_TO_FFINAME.fetch(dtype)}", 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


3839
3840
3841
 
# File 'lib/polars/series.rb', line 3839

def set_sorted(reverse: false)
  Utils.wrap_s(_s.set_sorted(reverse))
end

#shape ⇒ Array

Shape of this Series.



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

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


2786
2787
2788
 
# File 'lib/polars/series.rb', line 2786

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.



2798
2799
2800
 
# File 'lib/polars/series.rb', line 2798

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.



3856
3857
3858
 
# File 'lib/polars/series.rb', line 3856

def shrink_dtype
  super
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).



3422
3423
3424
3425
3426
3427
3428
3429
3430
3431
 
# File 'lib/polars/series.rb', line 3422

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


3747
3748
3749
 
# File 'lib/polars/series.rb', line 3747

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' [i64]
# [
#         -1
#         0
#         0
#         1
#         null
# ]


2477
2478
2479
 
# File 'lib/polars/series.rb', line 2477

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


2496
2497
2498
 
# File 'lib/polars/series.rb', line 2496

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


2678
2679
2680
 
# File 'lib/polars/series.rb', line 2678

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.



3635
3636
3637
 
# File 'lib/polars/series.rb', line 3635

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


1264
1265
1266
 
# File 'lib/polars/series.rb', line 1264

def slice(offset, length = nil)
  super
end

#sort(reverse: false, 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
# ]


1446
1447
1448
1449
1450
1451
1452
1453
 
# File 'lib/polars/series.rb', line 1446

def sort(reverse: false, in_place: false)
  if in_place
    self._s = _s.sort(reverse)
    self
  else
    Utils.wrap_s(_s.sort(reverse))
  end
end

#sqrt ⇒ Series

Compute the square root of the elements.



407
408
409
 
# File 'lib/polars/series.rb', line 407

def sqrt
  self**0.5
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


659
660
661
662
663
664
665
 
# File 'lib/polars/series.rb', line 659

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.



3898
3899
3900
 
# File 'lib/polars/series.rb', line 3898

def str
  StringNameSpace.new(self)
end

#struct ⇒ StructNameSpace

Create an object namespace of all struct related methods.



3905
3906
3907
 
# File 'lib/polars/series.rb', line 3905

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


586
587
588
 
# File 'lib/polars/series.rb', line 586

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


1393
1394
1395
 
# File 'lib/polars/series.rb', line 1393

def tail(n = 10)
  to_frame.select(Utils.col(name).tail(n)).to_series
end

#take(indices) ⇒ Series

Take values by index.

Examples:

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


1636
1637
1638
 
# File 'lib/polars/series.rb', line 1636

def take(indices)
  to_frame.select(Polars.col(name).take(indices)).to_series
end

#take_every(n) ⇒ Series

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

Examples:

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


1411
1412
1413
 
# File 'lib/polars/series.rb', line 1411

def take_every(n)
  super
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
# ]


2534
2535
2536
 
# File 'lib/polars/series.rb', line 2534

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


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

def tanh
  super
end

#time_unit ⇒ String

Get the time unit of underlying Datetime Series as "ns", "us", or "ms".



133
134
135
 
# File 'lib/polars/series.rb', line 133

def time_unit
  _s.time_unit
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]


2040
2041
2042
 
# File 'lib/polars/series.rb', line 2040

def to_a
  _s.to_a
end

#to_dummies(separator: "_", drop_first: 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   │
# └─────┴─────┴─────┘


734
735
736
 
# File 'lib/polars/series.rb', line 734

def to_dummies(separator: "_", drop_first: false)
  Utils.wrap_df(_s.to_dummies(separator, drop_first))
end

#to_frame ⇒ DataFrame

Cast this Series to a DataFrame.



488
489
490
 
# File 'lib/polars/series.rb', line 488

def to_frame
  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]


2156
2157
2158
2159
2160
2161
2162
2163
2164
2165
2166
2167
2168
2169
2170
2171
2172
2173
2174
2175
2176
2177
2178
2179
2180
2181
2182
2183
2184
 
# File 'lib/polars/series.rb', line 2156

def to_numo
  if !has_validity
    if is_datelike
      Numo::RObject.cast(to_a)
    elsif is_numeric
      # TODO make more efficient
      {
        UInt8 => Numo::UInt8,
        UInt16 => Numo::UInt16,
        UInt32 => Numo::UInt32,
        UInt64 => Numo::UInt64,
        Int8 => Numo::Int8,
        Int16 => Numo::Int16,
        Int32 => Numo::Int32,
        Int64 => Numo::Int64,
        Float32 => Numo::SFloat,
        Float64 => Numo::DFloat
      }.fetch(dtype).cast(to_a)
    elsif is_boolean
      Numo::Bit.cast(to_a)
    else
      _s.to_numo
    end
  elsif 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
# ]


2028
2029
2030
 
# File 'lib/polars/series.rb', line 2028

def to_physical
  super
end

#to_s ⇒ String Also known as: inspect

Returns a string representing the Series.



140
141
142
 
# File 'lib/polars/series.rb', line 140

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


1473
1474
1475
 
# File 'lib/polars/series.rb', line 1473

def top_k(k: 5)
  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
# ]


1614
1615
1616
 
# File 'lib/polars/series.rb', line 1614

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


984
985
986
 
# File 'lib/polars/series.rb', line 984

def unique_counts
  super
end

#value_counts(sort: 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      │
# └─────┴────────┘


965
966
967
 
# File 'lib/polars/series.rb', line 965

def value_counts(sort: false)
  Utils.wrap_df(_s.value_counts(sort))
end

#var(ddof: 1) ⇒ Float?

Get variance of this Series.

Examples:

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


679
680
681
682
683
684
685
 
# File 'lib/polars/series.rb', line 679

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


2842
2843
2844
 
# File 'lib/polars/series.rb', line 2842

def zip_with(mask, other)
  Utils.wrap_s(_s.zip_with(mask._s, other._s))
end

#|(other) ⇒ Series

Bitwise OR.



158
159
160
161
162
163
 
# File 'lib/polars/series.rb', line 158

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