Create a Polars DataFrame from an R object

Description

The as_polars_df() function creates a polars DataFrame from various R objects. Because Polars DataFrame can be converted to a struct type Series and vice versa, objects that are converted to a struct type type Series by as_polars_series() are supported by this function.

Usage

as_polars_df(x, ...)

# Default S3 method:
as_polars_df(x, ...)

# S3 method for class 'polars_series'
as_polars_df(x, ..., column_name = NULL, from_struct = TRUE)

# S3 method for class 'polars_data_frame'
as_polars_df(x, ...)

# S3 method for class 'polars_group_by'
as_polars_df(x, ...)

# S3 method for class 'polars_lazy_frame'
as_polars_df(
  x,
  ...,
  type_coercion = TRUE,
  predicate_pushdown = TRUE,
  projection_pushdown = TRUE,
  simplify_expression = TRUE,
  slice_pushdown = TRUE,
  comm_subplan_elim = TRUE,
  comm_subexpr_elim = TRUE,
  cluster_with_columns = TRUE,
  no_optimization = FALSE,
  engine = c("auto", "in-memory", "streaming", "old-streaming")
)

# S3 method for class 'list'
as_polars_df(x, ...)

# S3 method for class 'data.frame'
as_polars_df(x, ...)

# S3 method for class ''NULL''
as_polars_df(x, ...)

Arguments

x An R object.

… Additional arguments passed to the methods.

column_name A character or NULL. If not NULL, name/rename the Series column in the new DataFrame. If NULL, the column name is taken from the Series name.

from_struct A logical. If TRUE (default) and the Series data type is a struct, the \$struct$unnest() method is used to create a DataFrame from the struct Series. In this case, the column_name argument is ignored.

type_coercion A logical, indicats type coercion optimization.

predicate_pushdown A logical, indicats predicate pushdown optimization.

projection_pushdown A logical, indicats projection pushdown optimization.

simplify_expression A logical, indicats simplify expression optimization.

slice_pushdown A logical, indicats slice pushdown optimization.

comm_subplan_elim A logical, indicats tring to cache branching subplans that occur on self-joins or unions.

comm_subexpr_elim A logical, indicats tring to cache common subexpressions.

cluster_with_columns A logical, indicats to combine sequential independent calls to with_columns.

no_optimization A logical. If TRUE, turn off (certain) optimizations.

engine

The engine name to use for processing the query. One of the followings:

“auto” (default): Select the engine automatically. The “in-memory” engine will be selected for most cases.
“in-memory”: Use the in-memory engine.
“streaming”: Use the (new) streaming engine.
“old-streaming”: Use the old streaming engine.

Details

Default S3 method

Basically, this method is a shortcut for as_polars_series(x, …)$struct$unnest(). Before converting the object to a Series, the infer_polars_dtype() function is used to check if the object can be converted to a struct dtype.

S3 method for list

The argument … (except name) is passed to as_polars_series() for each element of the list.
All elements of the list must be converted to Series by as_polars_series().
All of the Series must be converted to the same length, except for the case of length 1, which will be recycled to match the length of the other Series if they have a length other than 1.
The name of the each element is used as the column name of the DataFrame. For unnamed elements, the column name will be an empty string ““ or if the element is a Series, the column name will be the name of the Series.

S3 method for data.frame

The argument … (except name) is passed to as_polars_series() for each column.
All columns must be converted to the same length of Series by as_polars_series().

S3 method for polars_series

This is a shortcut for \<Series>$to_frame() or \<Series>$struct$unnest(), depending on the from_struct argument and the Series data type. The column_name argument is passed to the name argument of the $to_frame() method.

S3 method for polars_lazy_frame

This is a shortcut for \<LazyFrame>$collect().

Value

A polars DataFrame

Examples

library("polars")

# list
as_polars_df(list(a = 1:2, b = c("foo", "bar")))

#> shape: (2, 2)
#> ┌─────┬─────┐
#> │ a   ┆ b   │
#> │ --- ┆ --- │
#> │ i32 ┆ str │
#> ╞═════╪═════╡
#> │ 1   ┆ foo │
#> │ 2   ┆ bar │
#> └─────┴─────┘

# data.frame
as_polars_df(data.frame(a = 1:2, b = c("foo", "bar")))

#> shape: (2, 2)
#> ┌─────┬─────┐
#> │ a   ┆ b   │
#> │ --- ┆ --- │
#> │ i32 ┆ str │
#> ╞═════╪═════╡
#> │ 1   ┆ foo │
#> │ 2   ┆ bar │
#> └─────┴─────┘

# polars_series
s_int <- as_polars_series(1:2, "a")
s_struct <- as_polars_series(
  data.frame(a = 1:2, b = c("foo", "bar")),
  "struct"
)

# Use the Series as a column
as_polars_df(s_int)

#> shape: (2, 1)
#> ┌─────┐
#> │ a   │
#> │ --- │
#> │ i32 │
#> ╞═════╡
#> │ 1   │
#> │ 2   │
#> └─────┘

as_polars_df(s_struct, column_name = "values", from_struct = FALSE)

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

# Unnest the struct data
as_polars_df(s_struct)

#> shape: (2, 2)
#> ┌─────┬─────┐
#> │ a   ┆ b   │
#> │ --- ┆ --- │
#> │ i32 ┆ str │
#> ╞═════╪═════╡
#> │ 1   ┆ foo │
#> │ 2   ┆ bar │
#> └─────┴─────┘