Class: Polars::ListNameSpace

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

Overview

Series.list namespace.

Instance Method Summary collapse

Dynamic Method Handling

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

Instance Method Details

#[](item) ⇒ Series

Get the value by index in the sublists.

Returns:



454
455
456
 
# File 'lib/polars/list_name_space.rb', line 454

def [](item)
  get(item)
end

#all ⇒ Series

Evaluate whether all boolean values in a list are true.

Examples:

s = Polars::Series.new(
  [[true, true], [false, true], [false, false], [nil], [], nil],
  dtype: Polars::List.new(Polars::Boolean)
)
s.list.all
# =>
# shape: (6,)
# Series: '' [bool]
# [
#         true
#         false
#         false
#         true
#         true
#         null
# ]

Returns:



34
35
36
 
# File 'lib/polars/list_name_space.rb', line 34

def all
  super
end

#any ⇒ Series

Evaluate whether any boolean value in a list is true.

Examples:

s = Polars::Series.new(
  [[true, true], [false, true], [false, false], [nil], [], nil],
  dtype: Polars::List.new(Polars::Boolean)
)
s.list.any
# =>
# shape: (6,)
# Series: '' [bool]
# [
#         true
#         true
#         false
#         false
#         false
#         null
# ]

Returns:



59
60
61
 
# File 'lib/polars/list_name_space.rb', line 59

def any
  super
end

#arg_max ⇒ Series

Retrieve the index of the maximum value in every sublist.

Examples:

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

Returns:



573
574
575
 
# File 'lib/polars/list_name_space.rb', line 573

def arg_max
  super
end

#arg_min ⇒ Series

Retrieve the index of the minimal value in every sublist.

Examples:

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

Returns:



555
556
557
 
# File 'lib/polars/list_name_space.rb', line 555

def arg_min
  super
end

#concat(other) ⇒ Series

Concat the arrays in a Series dtype List in linear time.

Examples:

s1 = Polars::Series.new("a", [["a", "b"], ["c"]])
s2 = Polars::Series.new("b", [["c"], ["d", nil]])
s1.list.concat(s2)
# =>
# shape: (2,)
# Series: 'a' [list[str]]
# [
#         ["a", "b", "c"]
#         ["c", "d", null]
# ]

Parameters:

  • other (Object) —

    Columns to concat into a List Series

Returns:



360
361
362
 
# File 'lib/polars/list_name_space.rb', line 360

def concat(other)
  super
end

#contains(item) ⇒ Series

Check if sublists contain the given item.

Examples:

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

Parameters:

  • item (Object) —

    Item that will be checked for membership.

Returns:



537
538
539
 
# File 'lib/polars/list_name_space.rb', line 537

def contains(item)
  super
end

#count_matches(element) ⇒ Series

Count how often the value produced by element occurs.

Examples:

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

Parameters:

  • element (Object) —

    An expression that produces a single value

Returns:



729
730
731
 
# File 'lib/polars/list_name_space.rb', line 729

def count_matches(element)
  super
end

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

Calculate the n-th discrete difference of every sublist.

Examples:

s = Polars::Series.new("a", [[1, 2, 3, 4], [10, 2, 1]])
s.list.diff
# =>
# shape: (2,)
# Series: 'a' [list[i64]]
# [
#         [null, 1, … 1]
#         [null, -8, -1]
# ]

Parameters:

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

    Number of slots to shift.

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

    How to handle null values.

Returns:



596
597
598
 
# File 'lib/polars/list_name_space.rb', line 596

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

#drop_nulls ⇒ Series

Drop all null values in the list.

The original order of the remaining elements is preserved.

Examples:

s = Polars::Series.new("values", [[nil, 1, nil, 2], [nil], [3, 4]])
s.list.drop_nulls
# =>
# shape: (3,)
# Series: 'values' [list[i64]]
# [
#         [1, 2]
#         []
#         [3, 4]
# ]

Returns:



99
100
101
 
# File 'lib/polars/list_name_space.rb', line 99

def drop_nulls
  super
end

#eval(expr) ⇒ Series

Run any polars expression against the lists' elements.

Examples:

df = Polars::DataFrame.new({"a" => [1, 8, 3], "b" => [4, 5, 2]})
df.with_column(
  Polars.concat_list(["a", "b"]).list.eval(Polars.element.rank).alias("rank")
)
# =>
# shape: (3, 3)
# ┌─────┬─────┬────────────┐
# │ a   ┆ b   ┆ rank       │
# │ --- ┆ --- ┆ ---        │
# │ i64 ┆ i64 ┆ list[f64]  │
# ╞═════╪═════╪════════════╡
# │ 1   ┆ 4   ┆ [1.0, 2.0] │
# │ 8   ┆ 5   ┆ [2.0, 1.0] │
# │ 3   ┆ 2   ┆ [2.0, 1.0] │
# └─────┴─────┴────────────┘

Parameters:

  • expr (Expr) —

    Expression to run. Note that you can select an element with Polars.first, or Polars.col

Returns:



805
806
807
 
# File 'lib/polars/list_name_space.rb', line 805

def eval(expr)
  super
end

#explode ⇒ Series

Returns a column with a separate row for every list element.

Examples:

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

Returns:



705
706
707
 
# File 'lib/polars/list_name_space.rb', line 705

def explode
  super
end

#filter(predicate) ⇒ Series

Filter elements in each list by a boolean expression, returning a new Series of lists.

Examples:

s = Polars::Series.new("a", [[1, 4], [8, 5], [3, 2]])
s.list.filter(Polars.element % 2 == 0)
# =>
# shape: (3,)
# Series: 'a' [list[i64]]
# [
#         [4]
#         [8]
#         [2]
# ]

Parameters:

  • predicate (Object) —

    A boolean expression evaluated on each list element. Use Polars.element to refer to the current element.

Returns:



828
829
830
 
# File 'lib/polars/list_name_space.rb', line 828

def filter(predicate)
  super
end

#first ⇒ Series

Get the first value of the sublists.

Examples:

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

Returns:



496
497
498
 
# File 'lib/polars/list_name_space.rb', line 496

def first
  super
end

#gather(indices, null_on_oob: false) ⇒ Series

Take sublists by multiple indices.

The indices may be defined in a single column, or by sublists in another column of dtype List.

Examples:

s = Polars::Series.new("a", [[3, 2, 1], [], [1, 2]])
s.list.gather([0, 2], null_on_oob: true)
# =>
# shape: (3,)
# Series: 'a' [list[i64]]
# [
#         [3, 1]
#         [null, null]
#         [1, null]
# ]

Parameters:

  • indices (Object) —

    Indices to return per sublist

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

    Behavior if an index is out of bounds: True -> set as null False -> raise an error Note that defaulting to raising an error is much cheaper

Returns:



420
421
422
423
424
425
 
# File 'lib/polars/list_name_space.rb', line 420

def gather(
  indices,
  null_on_oob: false
)
  super
end

#gather_every(n, offset = 0) ⇒ Series

Take every n-th value start from offset in sublists.

Examples:

s = Polars::Series.new("a", [[1, 2, 3], [], [6, 7, 8, 9]])
s.list.gather_every(2, 1)
# =>
# shape: (3,)
# Series: 'a' [list[i64]]
# [
#         [2]
#         []
#         [7, 9]
# ]

Parameters:

  • n (Integer) —

    Gather every n-th element.

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

    Starting index.

Returns:



447
448
449
 
# File 'lib/polars/list_name_space.rb', line 447

def gather_every(n, offset = 0)
  super
end

#get(index, null_on_oob: false) ⇒ Series

Get the value by index in the sublists.

So index 0 would return the first item of every sublist and index -1 would return the last item of every sublist if an index is out of bounds, it will return a nil.

Examples:

s = Polars::Series.new("a", [[3, 2, 1], [], [1, 2]])
s.list.get(0, null_on_oob: true)
# =>
# shape: (3,)
# Series: 'a' [i64]
# [
#         3
#         null
#         1
# ]

Parameters:

  • index (Integer) —

    Index to return per sublist

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

    Behavior if an index is out of bounds: true -> set as null false -> raise an error

Returns:



390
391
392
 
# File 'lib/polars/list_name_space.rb', line 390

def get(index, null_on_oob: false)
  super
end

#head(n = 5) ⇒ Series

Slice the first n values of every sublist.

Examples:

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

Parameters:

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

    Number of values to return for each sublist.

Returns:



662
663
664
 
# File 'lib/polars/list_name_space.rb', line 662

def head(n = 5)
  super
end

#join(separator) ⇒ Series

Join all string items in a sublist and place a separator between them.

This errors if inner type of list != Utf8.

Examples:

s = Polars::Series.new([["foo", "bar"], ["hello", "world"]])
s.list.join("-")
# =>
# shape: (2,)
# Series: '' [str]
# [
#         "foo-bar"
#         "hello-world"
# ]

Parameters:

  • separator (String) —

    string to separate the items with

Returns:



477
478
479
 
# File 'lib/polars/list_name_space.rb', line 477

def join(separator)
  super
end

#last ⇒ Series

Get the last value of the sublists.

Examples:

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

Returns:



515
516
517
 
# File 'lib/polars/list_name_space.rb', line 515

def last
  super
end

#len ⇒ Series Also known as: lengths

Get the length of the arrays as UInt32.

Examples:

s = Polars::Series.new([[1, 2, 3], [5]])
s.list.len
# =>
# shape: (2,)
# Series: '' [u32]
# [
#         3
#         1
# ]

Returns:



77
78
79
 
# File 'lib/polars/list_name_space.rb', line 77

def len
  super
end

#max ⇒ Series

Compute the max value of the arrays in the list.

Examples:

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

Returns:



166
167
168
 
# File 'lib/polars/list_name_space.rb', line 166

def max
  super
end

#mean ⇒ Series

Compute the mean value of the arrays in the list.

Examples:

s = Polars::Series.new("values", [[3, 1], [3, 3]])
s.list.mean
# =>
# shape: (2,)
# Series: 'values' [f64]
# [
#         2.0
#         3.0
# ]

Returns:



202
203
204
 
# File 'lib/polars/list_name_space.rb', line 202

def mean
  super
end

#median ⇒ Series

Compute the median value of the arrays in the list.

Examples:

s = Polars::Series.new("values", [[-1, 0, 1], [1, 10]])
s.list.median
# =>
# shape: (2,)
# Series: 'values' [f64]
# [
#         0.0
#         5.5
# ]

Returns:



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

def median
  super
end

#min ⇒ Series

Compute the min value of the arrays in the list.

Examples:

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

Returns:



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

def min
  super
end

#n_unique ⇒ Series

Count the number of unique values in every sub-lists.

Examples:

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

Returns:



338
339
340
 
# File 'lib/polars/list_name_space.rb', line 338

def n_unique
  super
end

#reverse ⇒ Series

Reverse the arrays in the list.

Examples:

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

Returns:



302
303
304
 
# File 'lib/polars/list_name_space.rb', line 302

def reverse
  super
end

#sample(n: nil, fraction: nil, with_replacement: false, shuffle: false, seed: nil) ⇒ Series

Sample from this list.

Examples:

s = Polars::Series.new("values", [[1, 2, 3], [4, 5]])
s.list.sample(n: Polars::Series.new("n", [2, 1]), seed: 1)
# =>
# shape: (2,)
# Series: 'values' [list[i64]]
# [
#         [2, 3]
#         [5]
# ]

Parameters:

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

    Number of items to return. Cannot be used with fraction. Defaults to 1 if fraction is nil.

  • fraction (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 generated for each sample operation.

Returns:



130
131
132
 
# File 'lib/polars/list_name_space.rb', line 130

def sample(n: nil, fraction: nil, with_replacement: false, shuffle: false, seed: nil)
  super
end

#set_difference(other) ⇒ Series

Compute the SET DIFFERENCE between the elements in this list and the elements of other.

Examples:

a = Polars::Series.new([[1, 2, 3], [], [nil, 3], [5, 6, 7]])
b = Polars::Series.new([[2, 3, 4], [3], [3, 4, nil], [6, 8]])
a.list.set_difference(b)
# =>
# shape: (4,)
# Series: '' [list[i64]]
# [
#         [1]
#         []
#         []
#         [5, 7]
# ]

Parameters:

  • other (Object) —

    Right hand side of the set operation.

Returns:



876
877
878
 
# File 'lib/polars/list_name_space.rb', line 876

def set_difference(other)
  super
end

#set_intersection(other) ⇒ Series

Compute the SET INTERSECTION between the elements in this list and the elements of other.

Examples:

a = Polars::Series.new([[1, 2, 3], [], [nil, 3], [5, 6, 7]])
b = Polars::Series.new([[2, 3, 4], [3], [3, 4, nil], [6, 8]])
a.list.set_intersection(b)
# =>
# shape: (4,)
# Series: '' [list[i64]]
# [
#         [2, 3]
#         []
#         [null, 3]
#         [6]
# ]

Parameters:

  • other (Object) —

    Right hand side of the set operation.

Returns:



900
901
902
 
# File 'lib/polars/list_name_space.rb', line 900

def set_intersection(other)
  super
end

#set_symmetric_difference(other) ⇒ Series

Compute the SET SYMMETRIC DIFFERENCE between the elements in this list and the elements of other.

Examples:

a = Polars::Series.new([[1, 2, 3], [], [nil, 3], [5, 6, 7]])
b = Polars::Series.new([[2, 3, 4], [3], [3, 4, nil], [6, 8]])
a.list.set_symmetric_difference(b)
# =>
# shape: (4,)
# Series: '' [list[i64]]
# [
#         [1, 4]
#         [3]
#         [4]
#         [5, 7, 8]
# ]

Parameters:

  • other (Object) —

    Right hand side of the set operation.

Returns:



924
925
926
 
# File 'lib/polars/list_name_space.rb', line 924

def set_symmetric_difference(other)
  super
end

#set_union(other) ⇒ Series

Compute the SET UNION between the elements in this list and the elements of other.

Examples:

a = Polars::Series.new([[1, 2, 3], [], [nil, 3], [5, 6, 7]])
b = Polars::Series.new([[2, 3, 4], [3], [3, 4, nil], [6, 8]])
a.list.set_union(b)
# =>
# shape: (4,)
# Series: '' [list[i64]]
# [
#         [1, 2, … 4]
#         [3]
#         [null, 3, 4]
#         [5, 6, … 8]
# ]

Parameters:

  • other (Object) —

    Right hand side of the set operation.

Returns:



852
853
854
 
# File 'lib/polars/list_name_space.rb', line 852

def set_union(other)
  super
end

#shift(periods = 1) ⇒ Series

Shift values by the given period.

Examples:

s = Polars::Series.new("a", [[1, 2, 3, 4], [10, 2, 1]])
s.list.shift
# =>
# shape: (2,)
# Series: 'a' [list[i64]]
# [
#         [null, 1, … 3]
#         [null, 10, 2]
# ]

Parameters:

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

    Number of places to shift (may be negative).

Returns:



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

def shift(periods = 1)
  super
end

#slice(offset, length = nil) ⇒ Series

Slice every sublist.

Examples:

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

Parameters:

  • offset (Integer) —

    Start index. Negative indexing is supported.

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

    Length of the slice. If set to nil (default), the slice is taken to the end of the list.

Returns:



641
642
643
 
# File 'lib/polars/list_name_space.rb', line 641

def slice(offset, length = nil)
  super
end

#sort(reverse: false) ⇒ Series

Sort the arrays in the list.

Examples:

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

Returns:



284
285
286
 
# File 'lib/polars/list_name_space.rb', line 284

def sort(reverse: false)
  super
end

#std(ddof: 1) ⇒ Series

Compute the std value of the arrays in the list.

Examples:

s = Polars::Series.new("values", [[-1, 0, 1], [1, 10]])
s.list.std
# =>
# shape: (2,)
# Series: 'values' [f64]
# [
#         1.0
#         6.363961
# ]

Returns:



238
239
240
 
# File 'lib/polars/list_name_space.rb', line 238

def std(ddof: 1)
  super
end

#sum ⇒ Series

Sum all the arrays in the list.

Examples:

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

Returns:



148
149
150
 
# File 'lib/polars/list_name_space.rb', line 148

def sum
  super
end

#tail(n = 5) ⇒ Series

Slice the last n values of every sublist.

Examples:

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

Parameters:

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

    Number of values to return for each sublist.

Returns:



683
684
685
 
# File 'lib/polars/list_name_space.rb', line 683

def tail(n = 5)
  super
end

#to_array(width) ⇒ Series

Convert a List column into an Array column with the same inner data type.

Examples:

s = Polars::Series.new([[1, 2], [3, 4]], dtype: Polars::List.new(Polars::Int8))
s.list.to_array(2)
# =>
# shape: (2,)
# Series: '' [array[i8, 2]]
# [
#         [1, 2]
#         [3, 4]
# ]

Parameters:

  • width (Integer) —

    Width of the resulting Array column.

Returns:



750
751
752
 
# File 'lib/polars/list_name_space.rb', line 750

def to_array(width)
  super
end

#to_struct(n_field_strategy: "first_non_null", name_generator: nil) ⇒ Series

Convert the series of type List to a series of type Struct.

Examples:

df = Polars::DataFrame.new({"a" => [[1, 2, 3], [1, 2]]})
df.select([Polars.col("a").list.to_struct])
# =>
# shape: (2, 1)
# ┌────────────┐
# │ a          │
# │ ---        │
# │ struct[3]  │
# ╞════════════╡
# │ {1,2,3}    │
# │ {1,2,null} │
# └────────────┘

Parameters:

  • n_field_strategy ("first_non_null", "max_width") (defaults to: "first_non_null") —

    Strategy to determine the number of fields of the struct.

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

    A custom function that can be used to generate the field names. Default field names are field_0, field_1 .. field_n

Returns:



777
778
779
 
# File 'lib/polars/list_name_space.rb', line 777

def to_struct(n_field_strategy: "first_non_null", name_generator: nil)
  super
end

#unique ⇒ Series

Get the unique/distinct values in the list.

Examples:

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

Returns:



320
321
322
 
# File 'lib/polars/list_name_space.rb', line 320

def unique
  super
end

#var(ddof: 1) ⇒ Series

Compute the var value of the arrays in the list.

Examples:

s = Polars::Series.new("values", [[-1, 0, 1], [1, 10]])
s.list.var
# =>
# shape: (2,)
# Series: 'values' [f64]
# [
#         1.0
#         40.5
# ]

Returns:



256
257
258
 
# File 'lib/polars/list_name_space.rb', line 256

def var(ddof: 1)
  super
end