Combine multiple DataFrames, LazyFrames, or Series into a single object

Description

Usage

pl$concat(..., how = "vertical", rechunk = FALSE, parallel = TRUE)

Arguments

… \<dynamic-dots\> DataFrames, LazyFrames, Series. All elements must have the same class.

how

Strategy to concatenate items. Must be one of:

“vertical”: applies multiple vstack operations;
“vertical_relaxed”: same as “vertical”, but additionally coerces columns to their common supertype if they are mismatched (eg: Int32 to Int64);
“diagonal”: finds a union between the column schemas and fills missing column values with null;
“diagonal_relaxed”: same as “diagonal”, but additionally coerces columns to their common supertype if they are mismatched (eg: Int32 to Int64);
“horizontal”: stacks Series from DataFrames horizontally and fills with null if the lengths don’t match;
“align”, “align_full”, “align_left”, “align_right”: Combines frames horizontally, auto-determining the common key columns and aligning rows using the same logic as align_frames (note that “align” is an alias for “align_full”). The "align" strategy determines the type of join used to align the frames, equivalent to the "how" parameter on align_frames. Note that the common join columns are automatically coalesced, but other column collisions will raise an error (if you need more control over this you should use a suitable join method directly).

Series only support the “vertical” strategy.

rechunk Make sure that the result data is in contiguous memory.

parallel Only relevant for LazyFrames. This determines if the concatenated lazy computations may be executed in parallel.

Value

The same class (polars_data_frame, polars_lazy_frame or polars_series) as the input.

Examples

library("polars")

# default is 'vertical' strategy
df1 <- pl$DataFrame(a = 1L, b = 3L)
df2 <- pl$DataFrame(a = 2L, b = 4L)
pl$concat(df1, df2)

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

# 'a' is coerced to float64
df1 <- pl$DataFrame(a = 1L, b = 3L)
df2 <- pl$DataFrame(a = 2, b = 4L)
pl$concat(df1, df2, how = "vertical_relaxed")

#> shape: (2, 2)
#> ┌─────┬─────┐
#> │ a   ┆ b   │
#> │ --- ┆ --- │
#> │ f64 ┆ i32 │
#> ╞═════╪═════╡
#> │ 1.0 ┆ 3   │
#> │ 2.0 ┆ 4   │
#> └─────┴─────┘

df_h1 <- pl$DataFrame(l1 = 1:2, l2 = 3:4)
df_h2 <- pl$DataFrame(r1 = 5:6, r2 = 7:8, r3 = 9:10)
pl$concat(df_h1, df_h2, how = "horizontal")

#> shape: (2, 5)
#> ┌─────┬─────┬─────┬─────┬─────┐
#> │ l1  ┆ l2  ┆ r1  ┆ r2  ┆ r3  │
#> │ --- ┆ --- ┆ --- ┆ --- ┆ --- │
#> │ i32 ┆ i32 ┆ i32 ┆ i32 ┆ i32 │
#> ╞═════╪═════╪═════╪═════╪═════╡
#> │ 1   ┆ 3   ┆ 5   ┆ 7   ┆ 9   │
#> │ 2   ┆ 4   ┆ 6   ┆ 8   ┆ 10  │
#> └─────┴─────┴─────┴─────┴─────┘

# use 'diagonal' strategy to fill empty column values with nulls
df1 <- pl$DataFrame(a = 1L, b = 3L)
df2 <- pl$DataFrame(a = 2L, c = 4L)
pl$concat(df1, df2, how = "diagonal")

#> shape: (2, 3)
#> ┌─────┬──────┬──────┐
#> │ a   ┆ b    ┆ c    │
#> │ --- ┆ ---  ┆ ---  │
#> │ i32 ┆ i32  ┆ i32  │
#> ╞═════╪══════╪══════╡
#> │ 1   ┆ 3    ┆ null │
#> │ 2   ┆ null ┆ 4    │
#> └─────┴──────┴──────┘

df_a1 <- pl$DataFrame(id = 1:2, x = 3:4)
df_a2 <- pl$DataFrame(id = 2:3, y = 5:6)
df_a3 <- pl$DataFrame(id = c(1L, 3L), z = 7:8)
pl$concat(df_a1, df_a2, df_a3, how = "align")

#> shape: (3, 4)
#> ┌─────┬──────┬──────┬──────┐
#> │ id  ┆ x    ┆ y    ┆ z    │
#> │ --- ┆ ---  ┆ ---  ┆ ---  │
#> │ i32 ┆ i32  ┆ i32  ┆ i32  │
#> ╞═════╪══════╪══════╪══════╡
#> │ 1   ┆ 3    ┆ null ┆ 7    │
#> │ 2   ┆ 4    ┆ 5    ┆ null │
#> │ 3   ┆ null ┆ 6    ┆ 8    │
#> └─────┴──────┴──────┴──────┘

pl$concat(df_a1, df_a2, df_a3, how = "align_left")

#> shape: (2, 4)
#> ┌─────┬─────┬──────┬──────┐
#> │ id  ┆ x   ┆ y    ┆ z    │
#> │ --- ┆ --- ┆ ---  ┆ ---  │
#> │ i32 ┆ i32 ┆ i32  ┆ i32  │
#> ╞═════╪═════╪══════╪══════╡
#> │ 1   ┆ 3   ┆ null ┆ 7    │
#> │ 2   ┆ 4   ┆ 5    ┆ null │
#> └─────┴─────┴──────┴──────┘

pl$concat(df_a1, df_a2, df_a3, how = "align_right")

#> shape: (2, 4)
#> ┌─────┬──────┬──────┬─────┐
#> │ id  ┆ x    ┆ y    ┆ z   │
#> │ --- ┆ ---  ┆ ---  ┆ --- │
#> │ i32 ┆ i32  ┆ i32  ┆ i32 │
#> ╞═════╪══════╪══════╪═════╡
#> │ 1   ┆ null ┆ null ┆ 7   │
#> │ 3   ┆ null ┆ 6    ┆ 8   │
#> └─────┴──────┴──────┴─────┘