Class: Polars::ArrayExpr

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

Overview

Namespace for array related expressions.

Instance Method Summary collapse

Instance Method Details

#agg(expr) ⇒ Expr

Run any polars aggregation expression against the arrays' elements.

Examples:

df = Polars::Series.new(
  "a", [[1, nil], [42, 13], [nil, nil]], dtype: Polars::Array.new(Polars::Int64, 2)
).to_frame
df.with_columns(null_count: Polars.col("a").arr.agg(Polars.element.null_count))
# =>
# shape: (3, 2)
# ┌───────────────┬────────────┐
# │ a             ┆ null_count │
# │ ---           ┆ ---        │
# │ array[i64, 2] ┆ u32        │
# ╞═══════════════╪════════════╡
# │ [1, null]     ┆ 1          │
# │ [42, 13]      ┆ 0          │
# │ [null, null]  ┆ 2          │
# └───────────────┴────────────┘
df.with_columns(no_nulls: Polars.col("a").arr.agg(Polars.element.drop_nulls))
# =>
# shape: (3, 2)
# ┌───────────────┬───────────┐
# │ a             ┆ no_nulls  │
# │ ---           ┆ ---       │
# │ array[i64, 2] ┆ 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:



1011
1012
1013
 
# File 'lib/polars/array_expr.rb', line 1011

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

#all(ignore_nulls: true) ⇒ Expr

Evaluate whether all boolean values are true for every subarray.

Examples:

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

Parameters:

  • ignore_nulls (Boolean) (defaults to: true) —
    • If set to true (default), null values are ignored. If there are no non-null values, the output is true.
    • If set to false, Kleene logic is used to deal with nulls: if the column contains any null values and no false values, the output is null.

Returns:



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

def all(ignore_nulls: true)
  agg(F.element.all(ignore_nulls: ignore_nulls))
end

#any(ignore_nulls: true) ⇒ Expr

Evaluate whether any boolean value is true for every subarray.

Examples:

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

Parameters:

  • ignore_nulls (Boolean) (defaults to: true) —
    • If set to true (default), null values are ignored. If there are no non-null values, the output is false.
    • If set to false, Kleene logic is used to deal with nulls: if the column contains any null values and no true values, the output is null.

Returns:



473
474
475
 
# File 'lib/polars/array_expr.rb', line 473

def any(ignore_nulls: true)
  agg(F.element.any(ignore_nulls: ignore_nulls))
end

#arg_max ⇒ Expr

Retrieve the index of the maximum value in every sub-array.

Examples:

df = Polars::DataFrame.new(
  {
    "a" => [[1, 2], [2, 1]]
  },
  schema: {"a" => Polars::Array.new(Polars::Int64, 2)}
)
df.with_columns(arg_max: Polars.col("a").arr.arg_max)
# =>
# shape: (2, 2)
# ┌───────────────┬─────────┐
# │ a             ┆ arg_max │
# │ ---           ┆ ---     │
# │ array[i64, 2] ┆ u32     │
# ╞═══════════════╪═════════╡
# │ [1, 2]        ┆ 1       │
# │ [2, 1]        ┆ 0       │
# └───────────────┴─────────┘

Returns:



637
638
639
 
# File 'lib/polars/array_expr.rb', line 637

def arg_max
  Utils.wrap_expr(_rbexpr.arr_arg_max)
end

#arg_min ⇒ Expr

Retrieve the index of the minimal value in every sub-array.

Examples:

df = Polars::DataFrame.new(
  {
    "a" => [[1, 2], [2, 1]]
  },
  schema: {"a" => Polars::Array.new(Polars::Int64, 2)}
)
df.with_columns(arg_min: Polars.col("a").arr.arg_min)
# =>
# shape: (2, 2)
# ┌───────────────┬─────────┐
# │ a             ┆ arg_min │
# │ ---           ┆ ---     │
# │ array[i64, 2] ┆ u32     │
# ╞═══════════════╪═════════╡
# │ [1, 2]        ┆ 0       │
# │ [2, 1]        ┆ 1       │
# └───────────────┴─────────┘

Returns:



611
612
613
 
# File 'lib/polars/array_expr.rb', line 611

def arg_min
  Utils.wrap_expr(_rbexpr.arr_arg_min)
end

#contains(item, nulls_equal: true) ⇒ Expr

Check if sub-arrays contain the given item.

Examples:

df = Polars::DataFrame.new(
  {"a" => [["a", "b"], ["x", "y"], ["a", "c"]]},
  schema: {"a" => Polars::Array.new(Polars::String, 2)}
)
df.with_columns(contains: Polars.col("a").arr.contains("a"))
# =>
# shape: (3, 2)
# ┌───────────────┬──────────┐
# │ a             ┆ contains │
# │ ---           ┆ ---      │
# │ array[str, 2] ┆ bool     │
# ╞═══════════════╪══════════╡
# │ ["a", "b"]    ┆ true     │
# │ ["x", "y"]    ┆ false    │
# │ ["a", "c"]    ┆ 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:



824
825
826
827
 
# File 'lib/polars/array_expr.rb', line 824

def contains(item, nulls_equal: true)
  item = Utils.parse_into_expression(item, str_as_lit: true)
  Utils.wrap_expr(_rbexpr.arr_contains(item, nulls_equal))
end

#count_matches(element) ⇒ Expr

Count how often the value produced by element occurs.

Examples:

df = Polars::DataFrame.new(
  {"a" => [[1, 2], [1, 1], [2, 2]]}, schema: {"a" => Polars::Array.new(Polars::Int64, 2)}
)
df.with_columns(number_of_twos: Polars.col("a").arr.count_matches(2))
# =>
# shape: (3, 2)
# ┌───────────────┬────────────────┐
# │ a             ┆ number_of_twos │
# │ ---           ┆ ---            │
# │ array[i64, 2] ┆ u32            │
# ╞═══════════════╪════════════════╡
# │ [1, 2]        ┆ 1              │
# │ [1, 1]        ┆ 0              │
# │ [2, 2]        ┆ 2              │
# └───────────────┴────────────────┘

Parameters:

  • element (Object) —

    An expression that produces a single value

Returns:



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

def count_matches(element)
  element = Utils.parse_into_expression(element, str_as_lit: true)
  Utils.wrap_expr(_rbexpr.arr_count_matches(element))
end

#eval(expr, as_list: false) ⇒ Expr

Run any polars expression against the arrays' elements.

Examples:

df = Polars::DataFrame.new({"a" => [1, 8, 3], "b" => [4, 5, 2]})
df.with_columns(rank: Polars.concat_arr("a", "b").arr.eval(Polars.element.rank))
# =>
# shape: (3, 3)
# ┌─────┬─────┬───────────────┐
# │ a   ┆ b   ┆ rank          │
# │ --- ┆ --- ┆ ---           │
# │ i64 ┆ i64 ┆ array[f64, 2] │
# ╞═════╪═════╪═══════════════╡
# │ 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.element

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

    Collect the resulting data as a list. This allows for expressions which output a variable amount of data.

Returns:



970
971
972
 
# File 'lib/polars/array_expr.rb', line 970

def eval(expr, as_list: false)
  Utils.wrap_expr(_rbexpr.arr_eval(expr._rbexpr, as_list))
end

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

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

Examples:

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

Parameters:

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

    Explode an empty array into a null.

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

    Explode a null array into a null.

Returns:



794
795
796
 
# File 'lib/polars/array_expr.rb', line 794

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

#first ⇒ Expr

Get the first value of the sub-arrays.

Examples:

df = Polars::DataFrame.new(
  {"a" => [[1, 2, 3], [4, 5, 6], [7, 8, 9]]},
  schema: {"a" => Polars::Array.new(Polars::Int32, 3)}
)
df.with_columns(first: Polars.col("a").arr.first)
# =>
# shape: (3, 2)
# ┌───────────────┬───────┐
# │ a             ┆ first │
# │ ---           ┆ ---   │
# │ array[i32, 3] ┆ i32   │
# ╞═══════════════╪═══════╡
# │ [1, 2, 3]     ┆ 1     │
# │ [4, 5, 6]     ┆ 4     │
# │ [7, 8, 9]     ┆ 7     │
# └───────────────┴───────┘

Returns:



699
700
701
 
# File 'lib/polars/array_expr.rb', line 699

def first
  get(0, null_on_oob: true)
end

#get(index, null_on_oob: false) ⇒ Expr

Get the value by index in the sub-arrays.

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(
  {"arr" => [[1, 2, 3], [4, 5, 6], [7, 8, 9]], "idx" => [1, -2, 4]},
  schema: {"arr" => Polars::Array.new(Polars::Int32, 3), "idx" => Polars::Int32}
)
df.with_columns(get: Polars.col("arr").arr.get("idx", null_on_oob: true))
# =>
# shape: (3, 3)
# ┌───────────────┬─────┬──────┐
# │ arr           ┆ idx ┆ get  │
# │ ---           ┆ --- ┆ ---  │
# │ array[i32, 3] ┆ i32 ┆ i32  │
# ╞═══════════════╪═════╪══════╡
# │ [1, 2, 3]     ┆ 1   ┆ 2    │
# │ [4, 5, 6]     ┆ -2  ┆ 5    │
# │ [7, 8, 9]     ┆ 4   ┆ null │
# └───────────────┴─────┴──────┘

Parameters:

  • index (Integer) —

    Index to return per sub-array

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

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

Returns:



673
674
675
676
 
# File 'lib/polars/array_expr.rb', line 673

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

#head(n = 5, as_array: false) ⇒ Expr

Get the first n elements of the sub-arrays.

Examples:

df = Polars::DataFrame.new(
  {"a" => [[1, 2], [4, 3]]},
  schema: {"a" => Polars::Array.new(Polars::Int64, 2)}
)
df.select(Polars.col("a").arr.head(1))
# =>
# shape: (2, 1)
# ┌───────────┐
# │ a         │
# │ ---       │
# │ list[i64] │
# ╞═══════════╡
# │ [1]       │
# │ [4]       │
# └───────────┘
df = Polars::DataFrame.new(
  {"a" => [[1, 2], [4, 3]]},
  schema: {"a" => Polars::Array.new(Polars::Int64, 2)}
)
df.select(Polars.col("a").arr.head(1, as_array: true))
# =>
# shape: (2, 1)
# ┌───────────────┐
# │ a             │
# │ ---           │
# │ array[i64, 1] │
# ╞═══════════════╡
# │ [1]           │
# │ [4]           │
# └───────────────┘

Parameters:

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

    Number of values to return for each sublist.

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

    Return result as a fixed-length Array, otherwise as a List. If true n must be a constant value.

Returns:



135
136
137
 
# File 'lib/polars/array_expr.rb', line 135

def head(n = 5, as_array: false)
  slice(0, n, as_array: as_array)
end

#join(separator, ignore_nulls: true) ⇒ Expr

Join all string items in a sub-array and place a separator between them.

This errors if inner type of array != String.

Examples:

df = Polars::DataFrame.new(
  {"s" => [["a", "b"], ["x", "y"]], "separator" => ["*", "_"]},
  schema: {
    "s" => Polars::Array.new(Polars::String, 2),
    "separator" => Polars::String
  }
)
df.with_columns(join: Polars.col("s").arr.join(Polars.col("separator")))
# =>
# shape: (2, 3)
# ┌───────────────┬───────────┬──────┐
# │ s             ┆ separator ┆ join │
# │ ---           ┆ ---       ┆ ---  │
# │ array[str, 2] ┆ str       ┆ str  │
# ╞═══════════════╪═══════════╪══════╡
# │ ["a", "b"]    ┆ *         ┆ a*b  │
# │ ["x", "y"]    ┆ _         ┆ x_y  │
# └───────────────┴───────────┴──────┘

Parameters:

  • separator (String) —

    string to separate the items with

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

    Ignore null values (default).

    If set to false, null values will be propagated. If the sub-list contains any null values, the output is nil.

Returns:



761
762
763
764
 
# File 'lib/polars/array_expr.rb', line 761

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

#last ⇒ Expr

Get the last value of the sub-arrays.

Examples:

df = Polars::DataFrame.new(
  {"a" => [[1, 2, 3], [4, 5, 6], [7, 8, 9]]},
  schema: {"a" => Polars::Array.new(Polars::Int32, 3)}
)
df.with_columns(last: Polars.col("a").arr.last)
# =>
# shape: (3, 2)
# ┌───────────────┬──────┐
# │ a             ┆ last │
# │ ---           ┆ ---  │
# │ array[i32, 3] ┆ i32  │
# ╞═══════════════╪══════╡
# │ [1, 2, 3]     ┆ 3    │
# │ [4, 5, 6]     ┆ 6    │
# │ [7, 8, 9]     ┆ 9    │
# └───────────────┴──────┘

Returns:



724
725
726
 
# File 'lib/polars/array_expr.rb', line 724

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

#len ⇒ Expr

Return the number of elements in each array.

Examples:

df = Polars::DataFrame.new(
  {"a" => [[1, 2], [4, 3]]},
  schema: {"a" => Polars::Array.new(Polars::Int64, 2)}
)
df.select(Polars.col("a").arr.len)
# =>
# shape: (2, 1)
# ┌─────┐
# │ a   │
# │ --- │
# │ u32 │
# ╞═════╡
# │ 2   │
# │ 2   │
# └─────┘

Returns:



32
33
34
 
# File 'lib/polars/array_expr.rb', line 32

def len
  Utils.wrap_expr(_rbexpr.arr_len)
end

#max ⇒ Expr

Compute the max values of the sub-arrays.

Examples:

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

Returns:



231
232
233
 
# File 'lib/polars/array_expr.rb', line 231

def max
  Utils.wrap_expr(_rbexpr.arr_max)
end

#mean ⇒ Expr

Compute the mean of the values of the sub-arrays.

Examples:

df = Polars::DataFrame.new(
  {"a" => [[1, 2, 3], [1, 1, 16]]},
  schema: {"a" => Polars::Array.new(Polars::Int64, 3)}
)
df.select(Polars.col("a").arr.mean)
# =>
# shape: (2, 1)
# ┌─────┐
# │ a   │
# │ --- │
# │ f64 │
# ╞═════╡
# │ 2.0 │
# │ 6.0 │
# └─────┘

Returns:



327
328
329
 
# File 'lib/polars/array_expr.rb', line 327

def mean
  Utils.wrap_expr(_rbexpr.arr_mean)
end

#median ⇒ Expr

Compute the median of the values of the sub-arrays.

Examples:

df = Polars::DataFrame.new(
  {"a" => [[1, 2], [4, 3]]},
  schema: {"a" => Polars::Array.new(Polars::Int64, 2)}
)
df.select(Polars.col("a").arr.median)
# =>
# shape: (2, 1)
# ┌─────┐
# │ a   │
# │ --- │
# │ f64 │
# ╞═════╡
# │ 1.5 │
# │ 3.5 │
# └─────┘

Returns:



351
352
353
 
# File 'lib/polars/array_expr.rb', line 351

def median
  Utils.wrap_expr(_rbexpr.arr_median)
end

#min ⇒ Expr

Compute the min values of the sub-arrays.

Examples:

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

Returns:



207
208
209
 
# File 'lib/polars/array_expr.rb', line 207

def min
  Utils.wrap_expr(_rbexpr.arr_min)
end

#n_unique ⇒ Expr

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

Examples:

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

Returns:



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

def n_unique
  agg(F.element.n_unique)
end

#reverse ⇒ Expr

Reverse the arrays in this column.

Examples:

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

Returns:



585
586
587
 
# File 'lib/polars/array_expr.rb', line 585

def reverse
  eval(F.element.reverse)
end

#shift(n = 1) ⇒ Expr

Note:

This method is similar to the LAG operation in SQL when the value for n is positive. With a negative value for n, it is similar to LEAD.

Shift array values by the given number of indices.

Examples:

By default, array values are shifted forward by one index.

df = Polars::DataFrame.new(
  {"a" => [[1, 2, 3], [4, 5, 6]]}, schema: {"a" => Polars::Array.new(Polars::Int64, 3)}
)
df.with_columns(shift: Polars.col("a").arr.shift)
# =>
# shape: (2, 2)
# ┌───────────────┬───────────────┐
# │ a             ┆ shift         │
# │ ---           ┆ ---           │
# │ array[i64, 3] ┆ array[i64, 3] │
# ╞═══════════════╪═══════════════╡
# │ [1, 2, 3]     ┆ [null, 1, 2]  │
# │ [4, 5, 6]     ┆ [null, 4, 5]  │
# └───────────────┴───────────────┘

Pass a negative value to shift in the opposite direction instead.

df.with_columns(shift: Polars.col("a").arr.shift(-2))
# =>
# shape: (2, 2)
# ┌───────────────┬─────────────────┐
# │ a             ┆ shift           │
# │ ---           ┆ ---             │
# │ array[i64, 3] ┆ array[i64, 3]   │
# ╞═══════════════╪═════════════════╡
# │ [1, 2, 3]     ┆ [3, null, null] │
# │ [4, 5, 6]     ┆ [6, null, null] │
# └───────────────┴─────────────────┘

Parameters:

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

    Number of indices to shift forward. If a negative value is passed, values are shifted in the opposite direction instead.

Returns:



941
942
943
944
 
# File 'lib/polars/array_expr.rb', line 941

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

#slice(offset, length = nil, as_array: false) ⇒ Expr

Slice every subarray.

Examples:

df = Polars::DataFrame.new(
  {"a" => [[1, 2], [4, 3]]},
  schema: {"a" => Polars::Array.new(Polars::Int64, 2)}
)
df.select(Polars.col("a").arr.slice(0, 1))
# =>
# shape: (2, 1)
# ┌───────────┐
# │ a         │
# │ ---       │
# │ list[i64] │
# ╞═══════════╡
# │ [1]       │
# │ [4]       │
# └───────────┘
df = Polars::DataFrame.new(
  {"a" => [[1, 2], [4, 3]]},
  schema: {"a" => Polars::Array.new(Polars::Int64, 2)}
)
df.select(Polars.col("a").arr.slice(0, 1, as_array: true))
# =>
# shape: (2, 1)
# ┌───────────────┐
# │ a             │
# │ ---           │
# │ array[i64, 1] │
# ╞═══════════════╡
# │ [1]           │
# │ [4]           │
# └───────────────┘

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.

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

    Return result as a fixed-length Array, otherwise as a List. If true length and offset must be constant values.

Returns:



82
83
84
85
86
87
88
89
90
 
# File 'lib/polars/array_expr.rb', line 82

def slice(
  offset,
  length = nil,
  as_array: false
)
  offset = Utils.parse_into_expression(offset)
  length = !length.nil? ? Utils.parse_into_expression(length) : nil
  Utils.wrap_expr(_rbexpr.arr_slice(offset, length, as_array))
end

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

Sort the arrays in this column.

Examples:

df = Polars::DataFrame.new(
  {
    "a" => [[3, 2, 1], [9, 1, 2]],
  },
  schema: {"a" => Polars::Array.new(Polars::Int64, 3)}
)
df.with_columns(sort: Polars.col("a").arr.sort)
# =>
# shape: (2, 2)
# ┌───────────────┬───────────────┐
# │ a             ┆ sort          │
# │ ---           ┆ ---           │
# │ array[i64, 3] ┆ array[i64, 3] │
# ╞═══════════════╪═══════════════╡
# │ [3, 2, 1]     ┆ [1, 2, 3]     │
# │ [9, 1, 2]     ┆ [1, 2, 9]     │
# └───────────────┴───────────────┘
df.with_columns(sort: Polars.col("a").arr.sort(descending: true))
# =>
# shape: (2, 2)
# ┌───────────────┬───────────────┐
# │ a             ┆ sort          │
# │ ---           ┆ ---           │
# │ array[i64, 3] ┆ array[i64, 3] │
# ╞═══════════════╪═══════════════╡
# │ [3, 2, 1]     ┆ [3, 2, 1]     │
# │ [9, 1, 2]     ┆ [9, 2, 1]     │
# └───────────────┴───────────────┘

Parameters:

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

    Sort in descending order.

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

    Place null values last.

Returns:



559
560
561
 
# File 'lib/polars/array_expr.rb', line 559

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

#std(ddof: 1) ⇒ Expr

Compute the std of the values of the sub-arrays.

Examples:

df = Polars::DataFrame.new(
  {"a" => [[1, 2], [4, 3]]},
  schema: {"a" => Polars::Array.new(Polars::Int64, 2)}
)
df.select(Polars.col("a").arr.std)
# =>
# shape: (2, 1)
# ┌──────────┐
# │ a        │
# │ ---      │
# │ f64      │
# ╞══════════╡
# │ 0.707107 │
# │ 0.707107 │
# └──────────┘

Returns:



279
280
281
 
# File 'lib/polars/array_expr.rb', line 279

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

#sum ⇒ Expr

Compute the sum values of the sub-arrays.

Examples:

df = Polars::DataFrame.new(
  {"a" => [[1, 2], [4, 3]]},
  schema: {"a" => Polars::Array.new(Polars::Int64, 2)}
)
df.select(Polars.col("a").arr.sum)
# =>
# shape: (2, 1)
# ┌─────┐
# │ a   │
# │ --- │
# │ i64 │
# ╞═════╡
# │ 3   │
# │ 7   │
# └─────┘

Returns:



255
256
257
 
# File 'lib/polars/array_expr.rb', line 255

def sum
  Utils.wrap_expr(_rbexpr.arr_sum)
end

#tail(n = 5, as_array: false) ⇒ Expr

Slice the last n values of every sublist.

Examples:

df = Polars::DataFrame.new(
  {"a" => [[1, 2], [4, 3]]},
  schema: {"a" => Polars::Array.new(Polars::Int64, 2)}
)
df.select(Polars.col("a").arr.tail(1))
# =>
# shape: (2, 1)
# ┌───────────┐
# │ a         │
# │ ---       │
# │ list[i64] │
# ╞═══════════╡
# │ [2]       │
# │ [3]       │
# └───────────┘
df = Polars::DataFrame.new(
  {"a" => [[1, 2], [4, 3]]},
  schema: {"a" => Polars::Array.new(Polars::Int64, 2)}
)
df.select(Polars.col("a").arr.tail(1, as_array: true))
# =>
# shape: (2, 1)
# ┌───────────────┐
# │ a             │
# │ ---           │
# │ array[i64, 1] │
# ╞═══════════════╡
# │ [2]           │
# │ [3]           │
# └───────────────┘

Parameters:

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

    Number of values to return for each sublist.

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

    Return result as a fixed-length Array, otherwise as a List. If true n must be a constant value.

Returns:



182
183
184
185
 
# File 'lib/polars/array_expr.rb', line 182

def tail(n = 5, as_array: false)
  n = Utils.parse_into_expression(n)
  Utils.wrap_expr(_rbexpr.arr_tail(n, as_array))
end

#to_list ⇒ Expr

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

Examples:

df = Polars::DataFrame.new(
  {"a" => [[1, 2], [3, 4]]},
  schema: {"a" => Polars::Array.new(Polars::Int8, 2)}
)
df.select(Polars.col("a").arr.to_list)
# =>
# shape: (2, 1)
# ┌──────────┐
# │ a        │
# │ ---      │
# │ list[i8] │
# ╞══════════╡
# │ [1, 2]   │
# │ [3, 4]   │
# └──────────┘

Returns:



431
432
433
 
# File 'lib/polars/array_expr.rb', line 431

def to_list
  Utils.wrap_expr(_rbexpr.arr_to_list)
end

#to_struct(fields: nil) ⇒ Expr

Convert the Series of type Array to a Series of type Struct.

Examples:

Convert array to struct with default field name assignment:

s1 = Polars::Series.new("n", [[0, 1, 2], [3, 4, 5]], dtype: Polars::Array.new(Polars::Int8, 3))
s2 = s1.arr.to_struct
s2.struct.fields
# => ["field_0", "field_1", "field_2"]

Convert array to struct with field name assignment by function/index:

s3 = s1.arr.to_struct(fields: ->(idx) { "n%02d" % idx })
s3.struct.fields
# => ["n00", "n01", "n02"]

Convert array to struct with field name assignment by index from a list of names:

s1.arr.to_struct(fields: ["one", "two", "three"]).struct.unnest
# =>
# shape: (2, 3)
# ┌─────┬─────┬───────┐
# │ one ┆ two ┆ three │
# │ --- ┆ --- ┆ ---   │
# │ i8  ┆ i8  ┆ i8    │
# ╞═════╪═════╪═══════╡
# │ 0   ┆ 1   ┆ 2     │
# │ 3   ┆ 4   ┆ 5     │
# └─────┴─────┴───────┘

Parameters:

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

    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.

Returns:



890
891
892
893
894
895
896
897
898
899
 
# File 'lib/polars/array_expr.rb', line 890

def to_struct(fields: nil)
  if fields.is_a?(Enumerable)
    field_names = fields.to_a
    rbexpr = _rbexpr.arr_to_struct(nil)
    Utils.wrap_expr(rbexpr).struct.rename_fields(field_names)
  else
    rbexpr = _rbexpr.arr_to_struct(fields)
    Utils.wrap_expr(rbexpr)
  end
end

#unique(maintain_order: false) ⇒ Expr

Get the unique/distinct values in the array.

Examples:

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

Parameters:

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

    Maintain order of data. This requires more work.

Returns:



379
380
381
382
383
 
# File 'lib/polars/array_expr.rb', line 379

def unique(maintain_order: false)
  eval(
    F.element.unique(maintain_order: maintain_order), as_list: true
  )
end

#var(ddof: 1) ⇒ Expr

Compute the var of the values of the sub-arrays.

Examples:

df = Polars::DataFrame.new(
  {"a" => [[1, 2], [4, 3]]},
  schema: {"a" => Polars::Array.new(Polars::Int64, 2)}
)
df.select(Polars.col("a").arr.var)
# =>
# shape: (2, 1)
# ┌─────┐
# │ a   │
# │ --- │
# │ f64 │
# ╞═════╡
# │ 0.5 │
# │ 0.5 │
# └─────┘

Returns:



303
304
305
 
# File 'lib/polars/array_expr.rb', line 303

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