S4Vectors: expand-methods – R documentation

Become an expert in R — Interactive courses, Cheat Sheets, certificates and more!

expand-methods

Unlist the list-like columns of a DataFrame object

Description

expand transforms a DataFrame object into a new DataFrame object where the columns specified by the user are unlisted. The transformed DataFrame object has the same colnames as the original but typically more rows.

Usage

## S4 method for signature 'DataFrame'
expand(x, colnames, keepEmptyRows = FALSE, recursive = TRUE)

Arguments

`x`	A DataFrame object with list-like columns or a Vector object with list-like metadata columns (i.e. with list-like columns in `mcols(x)`).
`colnames`	A `character` or `numeric` vector containing the names or indices of the list-like columns to unlist. The order in which columns are unlisted is controlled by the column order in this vector. This defaults to all of the recursive (list-like) columns in `x`.
`keepEmptyRows`	A `logical` indicating if rows containing empty list elements in the specified `colnames` should be retained or dropped. When `TRUE`, list elements are replaced with NA and all rows are kept. When `FALSE`, rows with empty list elements in the `colnames` columns are dropped.
`recursive`	If `TRUE`, expand each column recursively, with the result representing their cartesian product. If `FALSE`, expand all of the columns in parallel, which requires that they all share the same skeleton.

Value

A DataFrame object that has been expanded row-wise to match the length of the unlisted columns.

Examples

library(IRanges)
aa <- CharacterList("a", paste0("d", 1:2), paste0("b", 1:3), c(), "c")
bb <- CharacterList(paste0("sna", 1:2),"foo", paste0("bar",1:3),c(),"hica")
df <- DataFrame(aa=aa, bb=bb, cc=11:15)

## Expand by all list-like columns (aa, bb), dropping rows with empty
## list elements:
expand(df)

## Expand the aa column only:
expand(df, colnames="aa", keepEmptyRows=TRUE)
expand(df, colnames="aa", keepEmptyRows=FALSE)

## Expand the aa and then the bb column:
expand(df, colnames=c("aa","bb"), keepEmptyRows=TRUE)
expand(df, colnames=c("aa","bb"), keepEmptyRows=FALSE)

## Expand the aa and dd column in parallel:
df$dd <- relist(seq_along(unlist(aa)), aa)
expand(df, colnames=c("aa","dd"), recursive=FALSE)

S4Vectors

Foundation of vector-like and list-like containers in Bioconductor

v0.28.1

Artistic-2.0

Authors

H. Pagès, M. Lawrence and P. Aboyoun

Initial release