Collect columns into a struct column

Description

Usage

pl$struct(..., .schema = NULL)

Arguments

… \<dynamic-dots\> Name-value pairs of objects to be converted to polars expressions by the as_polars_expr() function. Characters are parsed as column names, other non-expression inputs are parsed as literals. Each name will be used as the expression name.

.schema Optional schema that explicitly defines the struct field dtypes. If no columns or expressions are provided, .schema keys are used to define columns.

Value

A polars expression

Examples

library("polars")

# Collect all columns of a dataframe into a struct by passing pl$all().
df <- pl$DataFrame(
  int = 1:2,
  str = c("a", "b"),
  bool = c(TRUE, NA),
  list = list(1:2, 3L),
)
df$select(pl$struct(pl$all())$alias("my_struct"))

#> shape: (2, 1)
#> ┌─────────────────────┐
#> │ my_struct           │
#> │ ---                 │
#> │ struct[4]           │
#> ╞═════════════════════╡
#> │ {1,"a",true,[1, 2]} │
#> │ {2,"b",null,[3]}    │
#> └─────────────────────┘

# Collect selected columns into a struct by either passing a list of
# columns, or by specifying each column as a positional argument.
df$select(pl$struct("int", FALSE)$alias("my_struct"))

#> shape: (2, 1)
#> ┌───────────┐
#> │ my_struct │
#> │ ---       │
#> │ struct[2] │
#> ╞═══════════╡
#> │ {1,false} │
#> │ {2,false} │
#> └───────────┘

# Name each struct field.
df$select(pl$struct(p = "int", q = "bool")$alias("my_struct"))$schema

#> $my_struct
#> Struct(`p`=Int32, `q`=Boolean)

# Pass a schema to specify the datatype of each field in the struct:
struct_schema <- list(int = pl$UInt32, list = pl$List(pl$Float32))
df$select(
  new_struct = pl$struct(pl$col("int", "list"), .schema = struct_schema)
)$unnest("new_struct")

#> shape: (2, 2)
#> ┌─────┬────────────┐
#> │ int ┆ list       │
#> │ --- ┆ ---        │
#> │ u32 ┆ list[f32]  │
#> ╞═════╪════════════╡
#> │ 1   ┆ [1.0, 2.0] │
#> │ 2   ┆ [3.0]      │
#> └─────┴────────────┘