agglomerate-methods: Agglomerate data using taxonomic information
In microbiome/mia: Microbiome analysis

agglomerate-methods

R Documentation

Agglomerate data using taxonomic information

Description

Agglomeration functions can be used to sum-up data based on specific criteria such as taxonomic ranks, variables or prevalence.

Usage

agglomerateByRank(x, ...)

mergeFeaturesByRank(x, ...)

## 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 'SummarizedExperiment'
mergeFeaturesByRank(
  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 'SingleCellExperiment'
mergeFeaturesByRank(x, ..., altexp = NULL, strip_altexp = TRUE)

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

## S4 method for signature 'TreeSummarizedExperiment'
mergeFeaturesByRank(x, ..., agglomerate.tree = FALSE)

agglomerateByPrevalence(x, ...)

## S4 method for signature 'SummarizedExperiment'
agglomerateByPrevalence(
  x,
  rank = taxonomyRanks(x)[1L],
  other_label = "Other",
  ...
)

Arguments

`x`	a `SummarizedExperiment` object
`...`	arguments passed to `agglomerateByRank` function for `SummarizedExperiment` objects, to `getPrevalence` and `getPrevalentTaxa` and used in `agglomeratebyPrevalence`, to `mergeRows` and `sumCountsAcrossFeatures`. `remove_empty_ranks`A single boolean value for selecting whether to remove those columns of rowData that include only NAs after agglomeration. (By default: `remove_empty_ranks = FALSE`) `make_unique`A single boolean value for selecting whether to make rownames unique. (By default: `make_unique = TRUE`) `detection`Detection threshold for absence/presence. Either an absolute value compared directly to the values of `x` or a relative value between 0 and 1, if `as_relative = FALSE`. `prevalence`Prevalence threshold (in 0 to 1). The required prevalence is strictly greater by default. To include the limit, set `include_lowest` to `TRUE`. `as.relative`Logical scalar: Should the detection threshold be applied on compositional (relative) abundances? (default: `FALSE`)
`rank`	a single character defining a taxonomic rank. Must be a value of `taxonomyRanks()` 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.
`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`)
`agglomerate.tree`	`TRUE` or `FALSE`: should `rowTree()` also be agglomerated? (Default: `agglomerate.tree = FALSE`)
`agglomerateTree`	alias for `agglomerate.tree`.
`other_label`	A single `character` valued used as the label for the summary of non-prevalent taxa. (default: `other_label = "Other"`)

Details

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

Agglomeration sums up the values of assays at the specified taxonomic level. With certain assays, e.g. those that include binary or negative values, this summing can produce meaningless values. In those cases, consider performing agglomeration first, and then applying the transformation afterwards.

agglomerateByPrevalence sums up the values of assays at the taxonomic level specified by rank (by default the highest taxonomic level available) and selects the summed results that exceed the given population prevalence at the given detection level. The other summed values (below the threshold) are agglomerated in an additional row taking the name indicated by other_label (by default "Other").

Value

agglomerateByRank returns a taxonomically-agglomerated, optionally-pruned object of the same class as x.

agglomerateByPrevalence returns a taxonomically-agglomerated object of the same class as x and based on prevalent taxonomic results.

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)

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

 # If assay contains binary or negative values, summing might lead to meaningless
 # values, and you will get a warning. In these cases, you might want to do 
 # agglomeration again at chosen taxonomic level.
 tse <- transformAssay(GlobalPatterns, method = "pa")
 tse <- agglomerateByRank(tse, rank = "Genus")
 tse <- transformAssay(tse, method = "pa")

# removing empty labels by setting na.rm = TRUE
sum(is.na(rowData(GlobalPatterns)$Family))
x3 <- agglomerateByRank(GlobalPatterns, rank="Family", na.rm = TRUE)
nrow(x3) # different from x2

# Because all the rownames are from the same rank, rownames do not include 
# prefixes, in this case "Family:". 
print(rownames(x3[1:3,]))

# To add them, use getTaxonomyLabels function.
rownames(x3) <- getTaxonomyLabels(x3, with_rank = TRUE)
print(rownames(x3[1:3,]))

# use 'remove_empty_ranks' to remove columns that include only NAs
x4 <- agglomerateByRank(GlobalPatterns, rank="Phylum", remove_empty_ranks = TRUE)
head(rowData(x4))

# If the assay contains NAs, you might want to consider replacing them,
# since summing-up NAs lead to NA
x5 <- GlobalPatterns
# Replace first value with NA
assay(x5)[1,1] <- NA
x6 <- agglomerateByRank(x5, "Kingdom")
head( assay(x6) )
# Replace NAs with 0. This is justified when we are summing-up counts.
assay(x5)[ is.na(assay(x5)) ] <- 0
x6 <- agglomerateByRank(x5, "Kingdom")
head( assay(x6) )

## Look at enterotype dataset...
data(enterotype)
## Print the available taxonomic ranks. Shows only 1 available rank,
## not useful for agglomerateByRank
taxonomyRanks(enterotype)
## Data can be aggregated based on prevalent taxonomic results
tse <- GlobalPatterns
tse <- agglomerateByPrevalence(tse,
                              rank = "Phylum",
                              detection = 1/100,
                              prevalence = 50/100,
                              as_relative = TRUE)

tse

# Here data is aggregated at the taxonomic level "Phylum". The five phyla
# that exceed the population prevalence threshold of 50/100 represent the 
# five first rows of the assay in the aggregated data. The sixth and last row
# named by default "Other" takes the summed up values of all the other phyla 
# that are below the prevalence threshold.

assay(tse)[,1:5]

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