Skip to content

Get several values by index in a list

Source code

Description

This allows to extract several values per list. To extract a single value by index, use $list$get().

Usage

<Expr>$list$gather(index, null_on_oob = FALSE)

Arguments

index An Expr or something coercible to an Expr, that can return several single indices. Values are 0-indexed (so index 0 would return the first item of every sublist) and negative values start from the end (index -1 returns the last item). If the index is out of bounds, it will return a null. Strings are parsed as column names.
null_on_oob If TRUE, return null if an index is out of bounds. Otherwise, raise an error.

Value

Expr

Examples

library(polars)

df = pl$DataFrame(
  a = list(c(3, 2, 1), 1, c(1, 2)),
  idx = list(0:1, integer(), c(1L, 999L))
)
df$with_columns(
  gathered = pl$col("a")$list$gather("idx", null_on_oob = TRUE)
)

#> shape: (3, 3)
#> ┌─────────────────┬───────────┬─────────────┐
#> │ a               ┆ idx       ┆ gathered    │
#> │ ---             ┆ ---       ┆ ---         │
#> │ list[f64]       ┆ list[i32] ┆ list[f64]   │
#> ╞═════════════════╪═══════════╪═════════════╡
#> │ [3.0, 2.0, 1.0] ┆ [0, 1]    ┆ [3.0, 2.0]  │
#> │ [1.0]           ┆ []        ┆ []          │
#> │ [1.0, 2.0]      ┆ [1, 999]  ┆ [2.0, null] │
#> └─────────────────┴───────────┴─────────────┘

df$with_columns(
  gathered = pl$col("a")$list$gather(2, null_on_oob = TRUE)
)

#> shape: (3, 3)
#> ┌─────────────────┬───────────┬───────────┐
#> │ a               ┆ idx       ┆ gathered  │
#> │ ---             ┆ ---       ┆ ---       │
#> │ list[f64]       ┆ list[i32] ┆ list[f64] │
#> ╞═════════════════╪═══════════╪═══════════╡
#> │ [3.0, 2.0, 1.0] ┆ [0, 1]    ┆ [1.0]     │
#> │ [1.0]           ┆ []        ┆ [null]    │
#> │ [1.0, 2.0]      ┆ [1, 999]  ┆ [null]    │
#> └─────────────────┴───────────┴───────────┘

# by some column name, must cast to an Int/Uint type to work
df$with_columns(
  gathered = pl$col("a")$list$gather(pl$col("a")$cast(pl$List(pl$UInt64)), null_on_oob = TRUE)
)

#> shape: (3, 3)
#> ┌─────────────────┬───────────┬──────────────────┐
#> │ a               ┆ idx       ┆ gathered         │
#> │ ---             ┆ ---       ┆ ---              │
#> │ list[f64]       ┆ list[i32] ┆ list[f64]        │
#> ╞═════════════════╪═══════════╪══════════════════╡
#> │ [3.0, 2.0, 1.0] ┆ [0, 1]    ┆ [null, 1.0, 2.0] │
#> │ [1.0]           ┆ []        ┆ [null]           │
#> │ [1.0, 2.0]      ┆ [1, 999]  ┆ [2.0, null]      │
#> └─────────────────┴───────────┴──────────────────┘