splitByRanks {mia} | 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 `taxonomicRanks()` 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`: `x`, with objects of `x` agglomerated for selected ranks as `altExps`.

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.

### See Also

`mergeRows`, `sumCountsAcrossFeatures`, `agglomerateByRank`, `altExps`, `splitAltExps`

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

[Package mia version 1.2.7 Index]