Class: Polars::ListExpr

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

Overview

Namespace for list related expressions.

Instance Method Summary collapse

Instance Method Details

#[](item) ⇒ Expr

Get the value by index in the sublists.

Returns:



499
500
501
 
# File 'lib/polars/list_expr.rb', line 499

def [](item)
  get(item)
end

#agg(expr) ⇒ Expr

Run any polars aggregation expression against the lists' elements.

Examples:

df = Polars::DataFrame.new({"a" => [[1, nil], [42, 13], [nil, nil]]})
df.with_columns(null_count: Polars.col("a").list.agg(Polars.element.null_count))
# =>
# shape: (3, 2)
# ┌──────────────┬────────────┐
# │ a            ┆ null_count │
# │ ---          ┆ ---        │
# │ list[i64]    ┆ u32        │
# ╞══════════════╪════════════╡
# │ [1, null]    ┆ 1          │
# │ [42, 13]     ┆ 0          │
# │ [null, null] ┆ 2          │
# └──────────────┴────────────┘

df.with_columns(no_nulls: Polars.col("a").list.agg(Polars.element.drop_nulls))
# =>
# shape: (3, 2)
# ┌──────────────┬───────────┐
# │ a            ┆ no_nulls  │
# │ ---          ┆ ---       │
# │ list[i64]    ┆ list[i64] │
# ╞══════════════╪═══════════╡
# │ [1, null]    ┆ [1]       │
# │ [42, 13]     ┆ [42, 13]  │
# │ [null, null] ┆ []        │
# └──────────────┴───────────┘

Parameters:

  • expr (Expr) —

    Expression to run. Note that you can select an element with Polars.element.

Returns:



1079
1080
1081
 
# File 'lib/polars/list_expr.rb', line 1079

def agg(expr)
  Utils.wrap_expr(_rbexpr.list_agg(expr._rbexpr))
end

#all ⇒ Expr

Evaluate whether all boolean values in a list are true.

Examples:

df = Polars::DataFrame.new(
  {"a" => [[true, true], [false, true], [false, false], [nil], [], nil]}
)
df.with_columns(all: Polars.col("a").list.all)
# =>
# shape: (6, 2)
# ┌────────────────┬───────┐
# │ a              ┆ all   │
# │ ---            ┆ ---   │
# │ list[bool]     ┆ bool  │
# ╞════════════════╪═══════╡
# │ [true, true]   ┆ true  │
# │ [false, true]  ┆ false │
# │ [false, false] ┆ false │
# │ [null]         ┆ true  │
# │ []             ┆ true  │
# │ null           ┆ null  │
# └────────────────┴───────┘

Returns:



35
36
37
 
# File 'lib/polars/list_expr.rb', line 35

def all
  Utils.wrap_expr(_rbexpr.list_all)
end

#any ⇒ Expr

Evaluate whether any boolean value in a list is true.

Examples:

df = Polars::DataFrame.new(
  {"a" => [[true, true], [false, true], [false, false], [nil], [], nil]}
)
df.with_columns(any: Polars.col("a").list.any)
# =>
# shape: (6, 2)
# ┌────────────────┬───────┐
# │ a              ┆ any   │
# │ ---            ┆ ---   │
# │ list[bool]     ┆ bool  │
# ╞════════════════╪═══════╡
# │ [true, true]   ┆ true  │
# │ [false, true]  ┆ true  │
# │ [false, false] ┆ false │
# │ [null]         ┆ false │
# │ []             ┆ false │
# │ null           ┆ null  │
# └────────────────┴───────┘

Returns:



62
63
64
 
# File 'lib/polars/list_expr.rb', line 62

def any
  Utils.wrap_expr(_rbexpr.list_any)
end

#arg_max ⇒ Expr

Retrieve the index of the maximum value in every sublist.

Examples:

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

Returns:



767
768
769
 
# File 'lib/polars/list_expr.rb', line 767

def arg_max
  Utils.wrap_expr(_rbexpr.list_arg_max)
end

#arg_min ⇒ Expr

Retrieve the index of the minimal value in every sublist.

Examples:

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

Returns:



742
743
744
 
# File 'lib/polars/list_expr.rb', line 742

def arg_min
  Utils.wrap_expr(_rbexpr.list_arg_min)
end

#concat(other) ⇒ Expr

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

Examples:

df = Polars::DataFrame.new(
  {
    "a" => [["a"], ["x"]],
    "b" => [["b", "c"], ["y", "z"]]
  }
)
df.select(Polars.col("a").list.concat("b"))
# =>
# shape: (2, 1)
# ┌─────────────────┐
# │ a               │
# │ ---             │
# │ list[str]       │
# ╞═════════════════╡
# │ ["a", "b", "c"] │
# │ ["x", "y", "z"] │
# └─────────────────┘

Parameters:

  • other (Object) —

    Columns to concat into a List Series

Returns:



447
448
449
450
451
452
453
454
455
456
457
458
459
460
 
# File 'lib/polars/list_expr.rb', line 447

def concat(other)
  if other.is_a?(::Array) && ![Expr, String, Series].any? { |c| other[0].is_a?(c) }
    return concat(Series.new([other]))
  end

  if !other.is_a?(::Array)
    other_list = [other]
  else
    other_list = other.dup
  end

  other_list.insert(0, Utils.wrap_expr(_rbexpr))
  Polars.concat_list(other_list)
end

#contains(item, nulls_equal: true) ⇒ Expr

Check if sublists contain the given item.

Examples:

df = Polars::DataFrame.new({"foo" => [[3, 2, 1], [], [1, 2]]})
df.select(Polars.col("foo").list.contains(1))
# =>
# shape: (3, 1)
# ┌───────┐
# │ foo   │
# │ ---   │
# │ bool  │
# ╞═══════╡
# │ true  │
# │ false │
# │ true  │
# └───────┘

Parameters:

  • item (Object) —

    Item that will be checked for membership

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

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

Returns:



688
689
690
 
# File 'lib/polars/list_expr.rb', line 688

def contains(item, nulls_equal: true)
  Utils.wrap_expr(_rbexpr.list_contains(Utils.parse_into_expression(item), nulls_equal))
end

#count_matches(element) ⇒ Expr

Count how often the value produced by element occurs.

Examples:

df = Polars::DataFrame.new({"listcol" => [[0], [1], [1, 2, 3, 2], [1, 2, 1], [4, 4]]})
df.select(Polars.col("listcol").list.count_matches(2).alias("number_of_twos"))
# =>
# shape: (5, 1)
# ┌────────────────┐
# │ number_of_twos │
# │ ---            │
# │ u32            │
# ╞════════════════╡
# │ 0              │
# │ 0              │
# │ 2              │
# │ 1              │
# │ 0              │
# └────────────────┘

Parameters:

  • element (Expr) —

    An expression that produces a single value

Returns:



938
939
940
 
# File 'lib/polars/list_expr.rb', line 938

def count_matches(element)
  Utils.wrap_expr(_rbexpr.list_count_matches(Utils.parse_into_expression(element)))
end

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

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:



790
791
792
 
# File 'lib/polars/list_expr.rb', line 790

def diff(n: 1, null_behavior: "ignore")
  Utils.wrap_expr(_rbexpr.list_diff(n, null_behavior))
end

#drop_nulls ⇒ Expr

Drop all null values in the list.

The original order of the remaining elements is preserved.

Examples:

df = Polars::DataFrame.new({"values" => [[nil, 1, nil, 2], [nil], [3, 4]]})
df.with_columns(drop_nulls: Polars.col("values").list.drop_nulls)
# =>
# shape: (3, 2)
# ┌────────────────┬────────────┐
# │ values         ┆ drop_nulls │
# │ ---            ┆ ---        │
# │ list[i64]      ┆ list[i64]  │
# ╞════════════════╪════════════╡
# │ [null, 1, … 2] ┆ [1, 2]     │
# │ [null]         ┆ []         │
# │ [3, 4]         ┆ [3, 4]     │
# └────────────────┴────────────┘

Returns:



107
108
109
 
# File 'lib/polars/list_expr.rb', line 107

def drop_nulls
  Utils.wrap_expr(_rbexpr.list_drop_nulls)
end

#eval(expr) ⇒ Expr

Run any polars expression against the lists' elements.

Examples:

df = Polars::DataFrame.new({"a" => [1, 8, 3], "b" => [4, 5, 2]})
df.with_columns(
  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:



1040
1041
1042
 
# File 'lib/polars/list_expr.rb', line 1040

def eval(expr)
  Utils.wrap_expr(_rbexpr.list_eval(expr._rbexpr))
end

#explode(empty_as_null: true, keep_nulls: true) ⇒ Expr

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

Examples:

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

Parameters:

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

    Explode an empty list into a null.

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

    Explode a null list into a null.

Returns:



911
912
913
 
# File 'lib/polars/list_expr.rb', line 911

def explode(empty_as_null: true, keep_nulls: true)
  Utils.wrap_expr(_rbexpr.explode(empty_as_null, keep_nulls))
end

#filter(predicate) ⇒ Expr

Filter elements in each list by a boolean expression.

Examples:

df = Polars::DataFrame.new({"a" => [1, 8, 3], "b" => [4, 5, 2]})
df.with_columns(
  evens: Polars.concat_list("a", "b").list.filter(Polars.element % 2 == 0)
)
# =>
# shape: (3, 3)
# ┌─────┬─────┬───────────┐
# │ a   ┆ b   ┆ evens     │
# │ --- ┆ --- ┆ ---       │
# │ i64 ┆ i64 ┆ list[i64] │
# ╞═════╪═════╪═══════════╡
# │ 1   ┆ 4   ┆ [4]       │
# │ 8   ┆ 5   ┆ [8]       │
# │ 3   ┆ 2   ┆ [2]       │
# └─────┴─────┴───────────┘

Parameters:

  • predicate (Object) —

    A boolean expression that is evaluated per list element. You can refer to the current element with Polars.element.

Returns:



1107
1108
1109
 
# File 'lib/polars/list_expr.rb', line 1107

def filter(predicate)
  Utils.wrap_expr(_rbexpr.list_filter(predicate._rbexpr))
end

#first ⇒ Expr

Get the first value of the sublists.

Examples:

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

Returns:



597
598
599
 
# File 'lib/polars/list_expr.rb', line 597

def first
  get(0, null_on_oob: true)
end

#gather(indices, null_on_oob: false) ⇒ Expr

Take sublists by multiple indices.

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

Examples:

df = Polars::DataFrame.new({"a" => [[3, 2, 1], [], [1, 2, 3, 4, 5]]})
df.with_columns(gather: Polars.col("a").list.gather([0, 4], null_on_oob: true))
# =>
# shape: (3, 2)
# ┌─────────────┬──────────────┐
# │ a           ┆ gather       │
# │ ---         ┆ ---          │
# │ list[i64]   ┆ list[i64]    │
# ╞═════════════╪══════════════╡
# │ [3, 2, 1]   ┆ [3, null]    │
# │ []          ┆ [null, null] │
# │ [1, 2, … 5] ┆ [1, 5]       │
# └─────────────┴──────────────┘

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:



532
533
534
535
 
# File 'lib/polars/list_expr.rb', line 532

def gather(indices, null_on_oob: false)
  indices = Utils.parse_into_expression(indices)
  Utils.wrap_expr(_rbexpr.list_gather(indices, null_on_oob))
end

#gather_every(n, offset = 0) ⇒ Expr

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

Examples:

df = Polars::DataFrame.new(
  {
    "a" => [[1, 2, 3, 4, 5], [6, 7, 8], [9, 10, 11, 12]],
    "n" => [2, 1, 3],
    "offset" => [0, 1, 0]
  }
)
df.with_columns(
  gather_every: Polars.col("a").list.gather_every(
    Polars.col("n"), Polars.col("offset")
  )
)
# =>
# shape: (3, 4)
# ┌───────────────┬─────┬────────┬──────────────┐
# │ a             ┆ n   ┆ offset ┆ gather_every │
# │ ---           ┆ --- ┆ ---    ┆ ---          │
# │ list[i64]     ┆ i64 ┆ i64    ┆ list[i64]    │
# ╞═══════════════╪═════╪════════╪══════════════╡
# │ [1, 2, … 5]   ┆ 2   ┆ 0      ┆ [1, 3, 5]    │
# │ [6, 7, 8]     ┆ 1   ┆ 1      ┆ [7, 8]       │
# │ [9, 10, … 12] ┆ 3   ┆ 0      ┆ [9, 12]      │
# └───────────────┴─────┴────────┴──────────────┘

Parameters:

  • n (Integer) —

    Gather every n-th element.

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

    Starting index.

Returns:



570
571
572
573
574
575
576
577
 
# File 'lib/polars/list_expr.rb', line 570

def gather_every(
  n,
  offset = 0
)
  n = Utils.parse_into_expression(n)
  offset = Utils.parse_into_expression(offset)
  Utils.wrap_expr(_rbexpr.list_gather_every(n, offset))
end

#get(index, null_on_oob: false) ⇒ Expr

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:

df = Polars::DataFrame.new({"foo" => [[3, 2, 1], [], [1, 2]]})
df.select(Polars.col("foo").list.get(0, null_on_oob: true))
# =>
# shape: (3, 1)
# ┌──────┐
# │ foo  │
# │ ---  │
# │ 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:



491
492
493
494
 
# File 'lib/polars/list_expr.rb', line 491

def get(index, null_on_oob: false)
  index = Utils.parse_into_expression(index)
  Utils.wrap_expr(_rbexpr.list_get(index, null_on_oob))
end

#head(n = 5) ⇒ Expr

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:



859
860
861
 
# File 'lib/polars/list_expr.rb', line 859

def head(n = 5)
  slice(0, n)
end

#item(allow_empty: false) ⇒ Expr

Get the single value of the sublists.

This errors if the sublist length is not exactly one.

Examples:

df = Polars::DataFrame.new({"a" => [[3], [1], [2]]})
df.with_columns(item: Polars.col("a").list.item)
# =>
# shape: (3, 2)
# ┌───────────┬──────┐
# │ a         ┆ item │
# │ ---       ┆ ---  │
# │ list[i64] ┆ i64  │
# ╞═══════════╪══════╡
# │ [3]       ┆ 3    │
# │ [1]       ┆ 1    │
# │ [2]       ┆ 2    │
# └───────────┴──────┘

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

Parameters:

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

    Allow having no values to return null.

Returns:



661
662
663
 
# File 'lib/polars/list_expr.rb', line 661

def item(allow_empty: false)
  agg(F.element.item(allow_empty: allow_empty))
end

#join(separator, ignore_nulls: true) ⇒ Expr

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

This errors if inner type of list != :str.

Examples:

df = Polars::DataFrame.new({"s" => [["a", "b", "c"], ["x", "y"]]})
df.select(Polars.col("s").list.join(" "))
# =>
# shape: (2, 1)
# ┌───────┐
# │ s     │
# │ ---   │
# │ str   │
# ╞═══════╡
# │ a b c │
# │ x y   │
# └───────┘

Parameters:

  • separator (String) —

    string to separate the items with

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

    Ignore null values (default).

Returns:



716
717
718
719
 
# File 'lib/polars/list_expr.rb', line 716

def join(separator, ignore_nulls: true)
  separator = Utils.parse_into_expression(separator, str_as_lit: true)
  Utils.wrap_expr(_rbexpr.list_join(separator, ignore_nulls))
end

#last ⇒ Expr

Get the last value of the sublists.

Examples:

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

Returns:



619
620
621
 
# File 'lib/polars/list_expr.rb', line 619

def last
  get(-1, null_on_oob: true)
end

#len ⇒ Expr

Get the length of the arrays as :u32.

Examples:

df = Polars::DataFrame.new({"foo" => [1, 2], "bar" => [["a", "b"], ["c"]]})
df.select(Polars.col("bar").list.len)
# =>
# shape: (2, 1)
# ┌─────┐
# │ bar │
# │ --- │
# │ u32 │
# ╞═════╡
# │ 2   │
# │ 1   │
# └─────┘

Returns:



83
84
85
 
# File 'lib/polars/list_expr.rb', line 83

def len
  Utils.wrap_expr(_rbexpr.list_len)
end

#max ⇒ Expr

Compute the max value of the lists in the array.

Examples:

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

Returns:



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

def max
  Utils.wrap_expr(_rbexpr.list_max)
end

#mean ⇒ Expr

Compute the mean value of the lists in the array.

Examples:

df = Polars::DataFrame.new({"values" => [[1], [2, 3]]})
df.select(Polars.col("values").list.mean)
# =>
# shape: (2, 1)
# ┌────────┐
# │ values │
# │ ---    │
# │ f64    │
# ╞════════╡
# │ 1.0    │
# │ 2.5    │
# └────────┘

Returns:



241
242
243
 
# File 'lib/polars/list_expr.rb', line 241

def mean
  Utils.wrap_expr(_rbexpr.list_mean)
end

#median ⇒ Expr

Compute the median value of the lists in the array.

Examples:

df = Polars::DataFrame.new({"values" => [[-1, 0, 1], [1, 10]]})
df.with_columns(Polars.col("values").list.median.alias("median"))
# =>
# shape: (2, 2)
# ┌────────────┬────────┐
# │ values     ┆ median │
# │ ---        ┆ ---    │
# │ list[i64]  ┆ f64    │
# ╞════════════╪════════╡
# │ [-1, 0, 1] ┆ 0.0    │
# │ [1, 10]    ┆ 5.5    │
# └────────────┴────────┘

Returns:



262
263
264
 
# File 'lib/polars/list_expr.rb', line 262

def median
  Utils.wrap_expr(_rbexpr.list_median)
end

#min ⇒ Expr

Compute the min value of the lists in the array.

Examples:

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

Returns:



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

def min
  Utils.wrap_expr(_rbexpr.list_min)
end

#n_unique ⇒ Expr

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

Examples:

df = Polars::DataFrame.new(
  {
    "a" => [[1, 1, 2], [2, 3, 4]]
  }
)
df.with_columns(n_unique: Polars.col("a").list.n_unique)
# =>
# shape: (2, 2)
# ┌───────────┬──────────┐
# │ a         ┆ n_unique │
# │ ---       ┆ ---      │
# │ list[i64] ┆ u32      │
# ╞═══════════╪══════════╡
# │ [1, 1, 2] ┆ 2        │
# │ [2, 3, 4] ┆ 3        │
# └───────────┴──────────┘

Returns:



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

def n_unique
  Utils.wrap_expr(_rbexpr.list_n_unique)
end

#reverse ⇒ Expr

Reverse the arrays in the list.

Examples:

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

Returns:



369
370
371
 
# File 'lib/polars/list_expr.rb', line 369

def reverse
  Utils.wrap_expr(_rbexpr.list_reverse)
end

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

Sample from this list.

Examples:

df = Polars::DataFrame.new({"values" => [[1, 2, 3], [4, 5]], "n" => [2, 1]})
df.with_columns(sample: Polars.col("values").list.sample(n: Polars.col("n"), seed: 1))
# =>
# shape: (2, 3)
# ┌───────────┬─────┬───────────┐
# │ values    ┆ n   ┆ sample    │
# │ ---       ┆ --- ┆ ---       │
# │ list[i64] ┆ i64 ┆ list[i64] │
# ╞═══════════╪═════╪═══════════╡
# │ [1, 2, 3] ┆ 2   ┆ [2, 3]    │
# │ [4, 5]    ┆ 1   ┆ [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:



141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
 
# File 'lib/polars/list_expr.rb', line 141

def sample(n: nil, fraction: nil, with_replacement: false, shuffle: false, seed: nil)
  if !n.nil? && !fraction.nil?
    msg = "cannot specify both `n` and `fraction`"
    raise ArgumentError, msg
  end

  if !fraction.nil?
    fraction = Utils.parse_into_expression(fraction)
    return Utils.wrap_expr(
      _rbexpr.list_sample_fraction(
        fraction, with_replacement, shuffle, seed
      )
    )
  end

  n = 1 if n.nil?
  n = Utils.parse_into_expression(n)
  Utils.wrap_expr(_rbexpr.list_sample_n(n, with_replacement, shuffle, seed))
end

#set_difference(other) ⇒ Expr

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

Examples:

df = Polars::DataFrame.new(
  {
    "a" => [[1, 2, 3], [], [nil, 3], [5, 6, 7]],
    "b" => [[2, 3, 4], [3], [3, 4, nil], [6, 8]]
  }
)
df.with_columns(difference: Polars.col("a").list.set_difference("b"))
# =>
# shape: (4, 3)
# ┌───────────┬──────────────┬────────────┐
# │ a         ┆ b            ┆ difference │
# │ ---       ┆ ---          ┆ ---        │
# │ list[i64] ┆ list[i64]    ┆ list[i64]  │
# ╞═══════════╪══════════════╪════════════╡
# │ [1, 2, 3] ┆ [2, 3, 4]    ┆ [1]        │
# │ []        ┆ [3]          ┆ []         │
# │ [null, 3] ┆ [3, 4, null] ┆ []         │
# │ [5, 6, 7] ┆ [6, 8]       ┆ [5, 7]     │
# └───────────┴──────────────┴────────────┘

Parameters:

  • other (Object) —

    Right hand side of the set operation.

Returns:



1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
 
# File 'lib/polars/list_expr.rb', line 1179

def set_difference(other)
  if other.respond_to?(:each)
    if !other.is_a?(::Array) && !other.is_a?(Series) && !other.is_a?(DataFrame)
      other = other.to_a
    end
    other = F.lit(other)._rbexpr
  else
    other = Utils.parse_into_expression(other)
  end
  Utils.wrap_expr(_rbexpr.list_set_operation(other, "difference"))
end

#set_intersection(other) ⇒ Expr

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

Examples:

df = Polars::DataFrame.new(
  {
    "a" => [[1, 2, 3], [], [nil, 3], [5, 6, 7]],
    "b" => [[2, 3, 4], [3], [3, 4, nil], [6, 8]]
  }
)
df.with_columns(intersection: Polars.col("a").list.set_intersection("b"))
# =>
# shape: (4, 3)
# ┌───────────┬──────────────┬──────────────┐
# │ a         ┆ b            ┆ intersection │
# │ ---       ┆ ---          ┆ ---          │
# │ list[i64] ┆ list[i64]    ┆ list[i64]    │
# ╞═══════════╪══════════════╪══════════════╡
# │ [1, 2, 3] ┆ [2, 3, 4]    ┆ [2, 3]       │
# │ []        ┆ [3]          ┆ []           │
# │ [null, 3] ┆ [3, 4, null] ┆ [null, 3]    │
# │ [5, 6, 7] ┆ [6, 8]       ┆ [6]          │
# └───────────┴──────────────┴──────────────┘

Parameters:

  • other (Object) —

    Right hand side of the set operation.

Returns:



1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
 
# File 'lib/polars/list_expr.rb', line 1218

def set_intersection(other)
  if other.respond_to?(:each)
    if !other.is_a?(::Array) && !other.is_a?(Series) && !other.is_a?(DataFrame)
      other = other.to_a
    end
    other = F.lit(other)._rbexpr
  else
    other = Utils.parse_into_expression(other)
  end
  Utils.wrap_expr(_rbexpr.list_set_operation(other, "intersection"))
end

#set_symmetric_difference(other) ⇒ Expr

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

Examples:

df = Polars::DataFrame.new(
  {
    "a" => [[1, 2, 3], [], [nil, 3], [5, 6, 7]],
    "b" => [[2, 3, 4], [3], [3, 4, nil], [6, 8]]
  }
)
df.with_columns(sdiff: Polars.col("b").list.set_symmetric_difference("a"))
# =>
# shape: (4, 3)
# ┌───────────┬──────────────┬───────────┐
# │ a         ┆ b            ┆ sdiff     │
# │ ---       ┆ ---          ┆ ---       │
# │ list[i64] ┆ list[i64]    ┆ list[i64] │
# ╞═══════════╪══════════════╪═══════════╡
# │ [1, 2, 3] ┆ [2, 3, 4]    ┆ [4, 1]    │
# │ []        ┆ [3]          ┆ [3]       │
# │ [null, 3] ┆ [3, 4, null] ┆ [4]       │
# │ [5, 6, 7] ┆ [6, 8]       ┆ [8, 5, 7] │
# └───────────┴──────────────┴───────────┘

Parameters:

  • other (Object) —

    Right hand side of the set operation.

Returns:



1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
 
# File 'lib/polars/list_expr.rb', line 1257

def set_symmetric_difference(other)
  if other.respond_to?(:each)
    if !other.is_a?(::Array) && !other.is_a?(Series) && !other.is_a?(DataFrame)
      other = other.to_a
    end
    other = F.lit(other)._rbexpr
  else
    other = Utils.parse_into_expression(other)
  end
  Utils.wrap_expr(_rbexpr.list_set_operation(other, "symmetric_difference"))
end

#set_union(other) ⇒ Expr

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

Examples:

df = Polars::DataFrame.new(
  {
    "a" => [[1, 2, 3], [], [nil, 3], [5, 6, 7]],
    "b" => [[2, 3, 4], [3], [3, 4, nil], [6, 8]]
  }
)
df.with_columns(
  union: Polars.col("a").list.set_union("b")
)
# =>
# shape: (4, 3)
# ┌───────────┬──────────────┬──────────────┐
# │ a         ┆ b            ┆ union        │
# │ ---       ┆ ---          ┆ ---          │
# │ list[i64] ┆ list[i64]    ┆ list[i64]    │
# ╞═══════════╪══════════════╪══════════════╡
# │ [1, 2, 3] ┆ [2, 3, 4]    ┆ [1, 2, … 4]  │
# │ []        ┆ [3]          ┆ [3]          │
# │ [null, 3] ┆ [3, 4, null] ┆ [null, 3, 4] │
# │ [5, 6, 7] ┆ [6, 8]       ┆ [5, 6, … 8]  │
# └───────────┴──────────────┴──────────────┘

Parameters:

  • other (Object) —

    Right hand side of the set operation.

Returns:



1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
 
# File 'lib/polars/list_expr.rb', line 1140

def set_union(other)
  if other.respond_to?(:each)
    if !other.is_a?(::Array) && !other.is_a?(Series) && !other.is_a?(DataFrame)
      other = other.to_a
    end
    other = F.lit(other)._rbexpr
  else
    other = Utils.parse_into_expression(other)
  end
  Utils.wrap_expr(_rbexpr.list_set_operation(other, "union"))
end

#shift(n = 1) ⇒ Expr

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:

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

    Number of places to shift (may be negative).

Returns:



811
812
813
814
 
# File 'lib/polars/list_expr.rb', line 811

def shift(n = 1)
  n = Utils.parse_into_expression(n)
  Utils.wrap_expr(_rbexpr.list_shift(n))
end

#slice(offset, length = nil) ⇒ Expr

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:



836
837
838
839
840
 
# File 'lib/polars/list_expr.rb', line 836

def slice(offset, length = nil)
  offset = Utils.parse_into_expression(offset, str_as_lit: false)
  length = Utils.parse_into_expression(length, str_as_lit: false)
  Utils.wrap_expr(_rbexpr.list_slice(offset, length))
end

#sort(descending: false, nulls_last: false) ⇒ Expr

Sort the arrays in the list.

Examples:

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

Parameters:

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

    Sort in descending order.

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

    Place null values last.

Returns:



344
345
346
 
# File 'lib/polars/list_expr.rb', line 344

def sort(descending: false, nulls_last: false)
  Utils.wrap_expr(_rbexpr.list_sort(descending, nulls_last))
end

#std(ddof: 1) ⇒ Expr

Compute the std value of the lists in the array.

Examples:

df = Polars::DataFrame.new({"values" => [[-1, 0, 1], [1, 10]]})
df.with_columns(Polars.col("values").list.std.alias("std"))
# =>
# shape: (2, 2)
# ┌────────────┬──────────┐
# │ values     ┆ std      │
# │ ---        ┆ ---      │
# │ list[i64]  ┆ f64      │
# ╞════════════╪══════════╡
# │ [-1, 0, 1] ┆ 1.0      │
# │ [1, 10]    ┆ 6.363961 │
# └────────────┴──────────┘

Parameters:

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

    “Delta Degrees of Freedom”: the divisor used in the calculation is N - ddof, where N represents the number of elements. By default ddof is 1.

Returns:



288
289
290
 
# File 'lib/polars/list_expr.rb', line 288

def std(ddof: 1)
  Utils.wrap_expr(_rbexpr.list_std(ddof))
end

#sum ⇒ Expr

Sum all the lists in the array.

Examples:

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

Returns:



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

def sum
  Utils.wrap_expr(_rbexpr.list_sum)
end

#tail(n = 5) ⇒ Expr

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:



880
881
882
883
 
# File 'lib/polars/list_expr.rb', line 880

def tail(n = 5)
  n = Utils.parse_into_expression(n)
  Utils.wrap_expr(_rbexpr.list_tail(n))
end

#to_array(width) ⇒ Expr

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

Examples:

df = Polars::DataFrame.new(
  {"a" => [[1, 2], [3, 4]]},
  schema: {"a" => Polars::List.new(Polars::Int8)}
)
df.with_columns(array: Polars.col("a").list.to_array(2))
# =>
# shape: (2, 2)
# ┌──────────┬──────────────┐
# │ a        ┆ array        │
# │ ---      ┆ ---          │
# │ list[i8] ┆ array[i8, 2] │
# ╞══════════╪══════════════╡
# │ [1, 2]   ┆ [1, 2]       │
# │ [3, 4]   ┆ [3, 4]       │
# └──────────┴──────────────┘

Parameters:

  • width (Integer) —

    Width of the resulting Array column.

Returns:



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

def to_array(width)
  Utils.wrap_expr(_rbexpr.list_to_array(width))
end

#to_struct(n_field_strategy: nil, fields: nil, upper_bound: nil) ⇒ Expr

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

Examples:

df = Polars::DataFrame.new({"n" => [[0, 1], [0, 1, 2]]})
df.with_columns(struct: Polars.col("n").list.to_struct(upper_bound: 2))
# =>
# shape: (2, 2)
# ┌───────────┬───────────┐
# │ n         ┆ struct    │
# │ ---       ┆ ---       │
# │ list[i64] ┆ struct[2] │
# ╞═══════════╪═══════════╡
# │ [0, 1]    ┆ {0,1}     │
# │ [0, 1, 2] ┆ {0,1}     │
# └───────────┴───────────┘

Parameters:

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

    Deprecated and ignored.

  • fields (defaults to: nil) —

    pArray If the name and number of the desired fields is known in advance a list of field names can be given, which will be assigned by index. Otherwise, to dynamically assign field names, a custom function can be used; if neither are set, fields will be field_0, field_1 .. field_n.

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

    A polars LazyFrame needs to know the schema at all times, so the caller must provide an upper bound of the number of struct fields that will be created; if set incorrectly, subsequent operations may fail. (For example, an all.sum expression will look in the current schema to determine which columns to select).

    When operating on a DataFrame, the schema does not need to be tracked or pre-determined, as the result will be eagerly evaluated, so you can leave this parameter unset.

Returns:



1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
 
# File 'lib/polars/list_expr.rb', line 1004

def to_struct(n_field_strategy: nil, fields: nil, upper_bound: nil)
  if !fields.is_a?(::Array)
    if fields.nil?
      fields = upper_bound.times.map { |i| "field_#{i}" }
    else
      fields = upper_bound.times.map { |i| fields.(i) }
    end
  end

  Utils.wrap_expr(_rbexpr.list_to_struct(fields))
end

#unique(maintain_order: false) ⇒ Expr

Get the unique/distinct values in the list.

Examples:

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

Returns:



393
394
395
 
# File 'lib/polars/list_expr.rb', line 393

def unique(maintain_order: false)
  Utils.wrap_expr(_rbexpr.list_unique(maintain_order))
end

#var(ddof: 1) ⇒ Expr

Compute the var value of the lists in the array.

Examples:

df = Polars::DataFrame.new({"values" => [[-1, 0, 1], [1, 10]]})
df.with_columns(Polars.col("values").list.var.alias("var"))
# =>
# shape: (2, 2)
# ┌────────────┬──────┐
# │ values     ┆ var  │
# │ ---        ┆ ---  │
# │ list[i64]  ┆ f64  │
# ╞════════════╪══════╡
# │ [-1, 0, 1] ┆ 1.0  │
# │ [1, 10]    ┆ 40.5 │
# └────────────┴──────┘

Parameters:

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

    “Delta Degrees of Freedom”: the divisor used in the calculation is N - ddof, where N represents the number of elements. By default ddof is 1.

Returns:



314
315
316
 
# File 'lib/polars/list_expr.rb', line 314

def var(ddof: 1)
  Utils.wrap_expr(_rbexpr.list_var(ddof))
end