R: Agglomerate data using taxonomic information

agglomerate-methods {mia}

R Documentation

Agglomerate data using taxonomic information

Description

agglomerateByRank can be used to sum up data based on the association to certain taxonomic ranks given as rowData. Only available taxonomicRanks can be used.

Usage

## S4 method for signature 'SummarizedExperiment'
agglomerateByRank(
  x,
  rank = taxonomyRanks(x)[1],
  onRankOnly = FALSE,
  na.rm = FALSE,
  empty.fields = c(NA, "", " ", "\t", "-", "_"),
  ...
)

## S4 method for signature 'SingleCellExperiment'
agglomerateByRank(x, ..., altexp = NULL, strip_altexp = TRUE)

## S4 method for signature 'TreeSummarizedExperiment'
agglomerateByRank(x, ..., agglomerateTree = FALSE)

Arguments

`x`	a `SummarizedExperiment` object
`rank`	a single character defining a taxonomic rank. Must be a value of `taxonomicRanks()` function.
`onRankOnly`	`TRUE` or `FALSE`: Should information only from the specified rank be used or from ranks equal and above? See details. (default: `onRankOnly = FALSE`)
`na.rm`	`TRUE` or `FALSE`: Should taxa with an empty rank be removed? Use it with caution, since empty entries on the selected rank will be dropped. This setting can be tweaked by defining `empty.fields` to your needs. (default: `na.rm = TRUE`)
`empty.fields`	a `character` value defining, which values should be regarded as empty. (Default: `c(NA, "", " ", "\t")`). They will be removed if `na.rm = TRUE` before agglomeration.
`...`	arguments passed to `agglomerateByRank` function for `SummarizedExperiment` objects, `mergeRows` and `sumCountsAcrossFeatures`.
`altexp`	String or integer scalar specifying an alternative experiment containing the input data.
`strip_altexp`	`TRUE` or `FALSE`: Should alternative experiments be removed prior to agglomeration? This prevents to many nested alternative experiments by default (default: `strip_altexp = TRUE`)
`agglomerateTree`	`TRUE` or `FALSE`: should `rowTree()` also be agglomerated? (Default: `agglomerateTree = FALSE`)

Details

Based on the available taxonomic data and its structure setting onRankOnly = TRUE has certain implications on the interpretability of your results. If no loops exist (loops meaning two higher ranks containing the same lower rank), the results should be comparable. you can check for loops using detectLoop.

Value

A taxonomically-agglomerated, optionally-pruned object of the same class as x.

Examples

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

# agglomerate at the Family taxonomic rank
x1 <- agglomerateByRank(GlobalPatterns, rank="Family")
## How many taxa before/after agglomeration?
nrow(GlobalPatterns)
nrow(x1)

# with agglomeration of the tree
x2 <- agglomerateByRank(GlobalPatterns, rank="Family",
                        agglomerateTree = TRUE)
nrow(x2) # same number of rows, but
rowTree(x1) # ... different
rowTree(x2) # ... tree

# removing empty labels by setting na.rm = TRUE
sum(is.na(rowData(GlobalPatterns)$Family))

## Look at enterotype dataset...
data(enterotype)
## print the available taxonomic ranks. Shows only 1 rank available
## not useful for agglomerateByRank
taxonomyRanks(enterotype)

[Package mia version 1.0.8 Index]