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,
  ...,
  engine = c("auto", "in-memory", "streaming"),
  optimizations = pl\$QueryOptFlags(),
  type_coercion = deprecated(),
  predicate_pushdown = deprecated(),
  projection_pushdown = deprecated(),
  simplify_expression = deprecated(),
  slice_pushdown = deprecated(),
  comm_subplan_elim = deprecated(),
  comm_subexpr_elim = deprecated(),
  cluster_with_columns = deprecated(),
  no_optimization = deprecated()
)

# 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.

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.

optimizations A QueryOptFlags object to indicate optimization passes done during query optimization.

type_coercion Use the type_coercion property of a QueryOptFlags object, then pass that to the optimizations argument instead.

predicate_pushdown Use the predicate_pushdown property of a QueryOptFlags object, then pass that to the optimizations argument instead.

projection_pushdown Use the projection_pushdown property of a QueryOptFlags object, then pass that to the optimizations argument instead.

simplify_expression Use the simplify_expression property of a QueryOptFlags object, then pass that to the optimizations argument instead.

slice_pushdown Use the slice_pushdown property of a QueryOptFlags object, then pass that to the optimizations argument instead.

comm_subplan_elim Use the comm_subplan_elim property of a QueryOptFlags object, then pass that to the optimizations argument instead.

comm_subexpr_elim Use the comm_subexpr_elim property of a QueryOptFlags object, then pass that to the optimizations argument instead.

cluster_with_columns Use the cluster_with_columns property of a QueryOptFlags object, then pass that to the optimizations argument instead.

no_optimization Use the optimizations argument with pl$QueryOptFlags()$no_optimizations() instead.

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 │
#> └─────┴─────┘