mia: Microbiome analysis

splitByRanks

R Documentation

Split/Unsplit a `SingleCellExperiment` by taxonomic ranks

Description

splitByRanks takes a SummarizedExperiment, splits it along the taxonomic ranks, aggregates the data per rank, converts the input to a SingleCellExperiment objects and stores the aggregated data as alternative experiments.

Usage

splitByRanks(x, ...)

## S4 method for signature 'SummarizedExperiment'
splitByRanks(x, ranks = taxonomyRanks(x), na.rm = TRUE, ...)

## S4 method for signature 'SingleCellExperiment'
splitByRanks(x, ranks = taxonomyRanks(x), na.rm = TRUE, ...)

## S4 method for signature 'TreeSummarizedExperiment'
splitByRanks(x, ranks = taxonomyRanks(x), na.rm = TRUE, ...)

unsplitByRanks(x, ...)

## S4 method for signature 'SingleCellExperiment'
unsplitByRanks(x, ranks = taxonomyRanks(x), keep_reducedDims = FALSE, ...)

## S4 method for signature 'TreeSummarizedExperiment'
unsplitByRanks(x, ranks = taxonomyRanks(x), keep_reducedDims = FALSE, ...)

Arguments

`x`	a `SummarizedExperiment` object
`...`	arguments passed to `agglomerateByRank` function for `SummarizedExperiment` objects and other functions. See `agglomerateByRank` for more details.
`ranks`	a character vector defining taxonomic ranks. Must all be values of `taxonomyRanks()` function.
`na.rm`	`TRUE` or `FALSE`: Should taxa with an empty rank be removed? Use it with caution, since results with NA on the selected rank will be dropped. This setting can be tweaked by defining `empty.fields` to your needs. (default: `na.rm = TRUE`)
`keep_reducedDims`	`TRUE` or `FALSE`: Should the `reducedDims(x)` be transferred to the result? Please note, that this breaks the link between the data used to calculate the reduced dims. (default: `keep_reducedDims = FALSE`)

Details

unsplitByRanks takes these alternative experiments and flattens them again into a single SummarizedExperiment.

splitByRanks will use by default all available taxonomic ranks, but this can be controlled by setting ranks manually. NA values are removed by default, since they would not make sense, if the result should be used for unsplitByRanks at some point. The input data remains unchanged in the returned SingleCellExperiment objects.

unsplitByRanks will remove any NA value on each taxonomic rank so that no ambiguous data is created. In additional, a column taxonomicLevel is created or overwritten in the rowData to specify from which alternative experiment this originates from. This can also be used for splitAltExps to split the result along the same factor again. The input data from the base objects is not returned, only the data from the altExp(). Be aware that changes to rowData of the base object are not returned, whereas only the colData of the base object is kept.

Value

For splitByRanks: SummarizedExperiment objects in a SimpleList.

For unsplitByRanks: x, with rowData and assay data replaced by the unsplit data. colData of x is kept as well and any existing rowTree is dropped as well, since existing rowLinks are not valid anymore.

Examples

data(GlobalPatterns)
# print the available taxonomic ranks
taxonomyRanks(GlobalPatterns)

# splitByRanks
altExps(GlobalPatterns) <- splitByRanks(GlobalPatterns)
altExps(GlobalPatterns)
altExp(GlobalPatterns,"Kingdom")
altExp(GlobalPatterns,"Species")

# unsplitByRanks
x <- unsplitByRanks(GlobalPatterns)
x

microbiome/mia documentation built on April 27, 2024, 4:04 a.m.