Split/Unsplit a SingleCellExperiment by taxonomic ranks

Source: R/splitByRanks.R

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.

splitByRanks(x, ...)

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

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

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

unsplitByRanks(x, ...)

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

# S4 method for 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)

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.

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.

Examples

data(GlobalPatterns)
# print the available taxonomic ranks
taxonomyRanks(GlobalPatterns)
#> [1] "Kingdom" "Phylum"  "Class"   "Order"   "Family"  "Genus"   "Species"

# splitByRanks
altExps(GlobalPatterns) <- splitByRanks(GlobalPatterns)
altExps(GlobalPatterns)
#> List of length 7
#> names(7): Kingdom Phylum Class Order Family Genus Species
altExp(GlobalPatterns,"Kingdom")
#> class: TreeSummarizedExperiment 
#> dim: 2 26 
#> metadata(1): agglomerated_by_rank
#> assays(1): counts
#> rownames(2): Archaea Bacteria
#> rowData names(7): Kingdom Phylum ... Genus Species
#> colnames(26): CL3 CC1 ... Even2 Even3
#> colData names(7): X.SampleID Primer ... SampleType Description
#> reducedDimNames(0):
#> mainExpName: NULL
#> altExpNames(0):
#> rowLinks: a LinkDataFrame (2 rows)
#> rowTree: 1 phylo tree(s) (19216 leaves)
#> colLinks: NULL
#> colTree: NULL
altExp(GlobalPatterns,"Species")
#> class: TreeSummarizedExperiment 
#> dim: 944 26 
#> metadata(1): agglomerated_by_rank
#> assays(1): counts
#> rownames(944): Sulfolobusacidocaldarius Cenarchaeumsymbiosum ...
#>   Thermanaerovibrioacidaminovorans Jonquetellaanthropi
#> rowData names(7): Kingdom Phylum ... Genus Species
#> colnames(26): CL3 CC1 ... Even2 Even3
#> colData names(7): X.SampleID Primer ... SampleType Description
#> reducedDimNames(0):
#> mainExpName: NULL
#> altExpNames(0):
#> rowLinks: a LinkDataFrame (944 rows)
#> rowTree: 1 phylo tree(s) (19216 leaves)
#> colLinks: NULL
#> colTree: NULL

# unsplitByRanks
x <- unsplitByRanks(GlobalPatterns)
x
#> class: TreeSummarizedExperiment 
#> dim: 2692 26 
#> metadata(0):
#> assays(1): counts
#> rownames(2692): Kingdom:Archaea Kingdom:Bacteria ...
#>   Species:Thermanaerovibrioacidaminovorans Species:Jonquetellaanthropi
#> rowData names(8): Kingdom Phylum ... Species taxonomicLevel
#> colnames(26): CL3 CC1 ... Even2 Even3
#> colData names(7): X.SampleID Primer ... SampleType Description
#> reducedDimNames(0):
#> mainExpName: NULL
#> altExpNames(0):
#> rowLinks: NULL
#> rowTree: NULL
#> colLinks: NULL
#> colTree: NULL