expand {S4Vectors} | R Documentation

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

### See Also

- DataFrame objects.

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

[Package S4Vectors version 0.25.15 Index]