Determine abundant and rare taxa. Rare taxa can be further classified to conditionally rare and permanently rare.

Source: R/AllGenerics.R, R/getAbundant.R

These functions determine abundant and rare taxa based on the abundances of taxa. Compared to getPrevalent and getRare, these functions determine abundant and rare taxa based on abundance while the first mentioned are based on prevalence.

getAbundant(x, ...)

getLowAbundant(x, ...)

getConditionallyLowAbundant(x, ...)

getPermanentlyLowAbundant(x, ...)

getAbundanceClass(x, ...)

addAbundanceClass(x, ...)

# S4 method for class 'SingleCellExperiment'
getAbundant(x, ...)

# S4 method for class 'SummarizedExperiment'
getAbundant(x, assay.type = "relabundance", ...)

# S4 method for class 'ANY'
getAbundant(x, abundant.th = 1/100, ...)

# S4 method for class 'SingleCellExperiment'
getLowAbundant(x, ...)

# S4 method for class 'SummarizedExperiment'
getLowAbundant(x, assay.type = "relabundance", abundant.th = 1/100, ...)

# S4 method for class 'ANY'
getLowAbundant(x, abundant.th = 1/100, ...)

# S4 method for class 'SingleCellExperiment'
getConditionallyLowAbundant(x, ...)

# S4 method for class 'SummarizedExperiment'
getConditionallyLowAbundant(x, assay.type = "relabundance", ...)

# S4 method for class 'ANY'
getConditionallyLowAbundant(x, abundant.th = 1/100, crt.th = 100, ...)

# S4 method for class 'SingleCellExperiment'
getPermanentlyLowAbundant(x, ...)

# S4 method for class 'SummarizedExperiment'
getPermanentlyLowAbundant(x, assay.type = "relabundance", ...)

# S4 method for class 'ANY'
getPermanentlyLowAbundant(x, abundant.th = 1/100, prt.th = 5, ...)

# S4 method for class 'SingleCellExperiment'
getAbundanceClass(x, ...)

# S4 method for class 'SummarizedExperiment'
getAbundanceClass(x, assay.type = "relabundance", ...)

# S4 method for class 'ANY'
getAbundanceClass(x, abundant.th = 1/100, crt.th = 100, prt.th = 5, ...)

# S4 method for class 'SingleCellExperiment'
addAbundanceClass(x, ...)

# S4 method for class 'SummarizedExperiment'
addAbundanceClass(x, name = "abundance_class", ...)

Arguments

x

a SummarizedExperiment object.

...

additional arguments.

assay.type

Character scalar. Specifies the name of assay used in calculation. (Default: "relabundance")

abundant.th

Numeric scalar. Specifies threshold that is used to separate abundant features from rare. (Default: 1/100)

crt.th

Numeric scalar. Specifies threshold that is used to separate conditionally rare features from other rare features. (Default: 100)

prt.th

Numeric scalar. Specifies threshold that is used to separate permanently rare features from other rare features. (Default: 5)

name

Character scalar. Specifies name of column in rowData where the results will be stored. (Default: "abundance_class")

Value

For getAbundant, getLowAbundant, getConditionallyLowAbundant, and getPermanentlyLowAbundant a vector of taxa. For getAbudanceClass a vector of abundance classes for each feature. For addAbudanceClass, a SummarizedExperiment object.

Details

These functions identify abundant and rare taxa in a dataset. Abundant taxa are characterized by high average abundance across the dataset, while rare taxa are characterized by consistently low abundance.

Conditionally rare taxa exhibit variable abundance, being abundant in some samples and rare in others. In contrast, permanently rare taxa consistently maintain low abundance across all samples.

  • Abundant taxa: Taxa with an average abundance exceeding abundant.th.

  • Low abundant / rare taxa: Taxa with an average abundance not exceeding abundant.th. Optionally, if specified, they must also satisfy the condition \(crt.th >= \frac{abundance_{max}}{abundance_{min}} > prt.th\).

  • Conditionally rare or low abundant taxa (CRT): Taxa with an average abundance not exceeding abundant.th and with a maximum-to-minimum abundance ratio (\(\frac{abundance_{max}}{abundance_{min}}\)) greater than crt.th.

  • Permanently rare or low abundant taxa (PRT): Taxa with an average abundance not exceeding abundant.th and with a maximum-to-minimum abundance ratio (\(\frac{abundance_{max}}{abundance_{min}}\)) less than or equal to prt.th.

References

Sizhong Y. et al. (2017) Community structure of rare methanogenic archaea: insight from a single functional group- FEMS Microbiol. Ecol. 93(11). https://doi.org/10.1093/femsec/fix126

See also

getPrevalent and getRare

Examples


data(GlobalPatterns)
tse <- GlobalPatterns

# Agglomerate to family level
tse <- agglomerateByRank(tse, rank = "Family")
# Transform to relative abundances. Note that we add pseudocount. This is
# because otherwise we cannot calculate CRT and PRT due to zeroes and
# zero division in calculating abundance ratio.
tse <- transformAssay(tse, method = "relabundance", pseudocount = TRUE)
#> A pseudocount of 0.5 was applied.

# Get abundant taxa
abundant <- getAbundant(tse, assay.type = "relabundance")
abundant |> head()
#> [1] "ACK-M1"             "Bacteroidaceae"     "Bifidobacteriaceae"
#> [4] "Clostridiaceae"     "Comamonadaceae"     "Crenotrichaceae"   

# Get all rare taxa that have average relative abundance below 10%
rare <- getLowAbundant(
    tse, assay.type = "relabundance", abundant.th = 10/100)
rare |> head()
#> [1] "125ds10"    "211ds20"    "5B-12"      "A714017"    "AEGEAN_185"
#> [6] "AKIW874"   

# Get rare taxa that are not permanently or conditionally rare
rare <- getLowAbundant(
    tse, assay.type = "relabundance", prt.th = 5, crt.th = 100)
rare |> head()
#> [1] "Actinopolysporaceae"     "Anaeroplasmataceae"     
#> [3] "BSV43"                   "Blattabacteriaceae"     
#> [5] "Celerinatantimonadaceae" "Chlamydomonadaceae"     

# Get permanently rare taxa
prt <- getPermanentlyLowAbundant(
    tse, assay.type = "relabundance", prt.th = 5)
prt |> head()
#> character(0)

# Get conditionally rare taxa
prt <- getConditionallyLowAbundant(
    tse, assay.type = "relabundance", crt.th = 100)
prt |> head()
#> [1] "125ds10"    "211ds20"    "5B-12"      "A714017"    "AEGEAN_185"
#> [6] "AKIW874"   

# To classify all features, one can use *AbundantClass function
tse <- addAbundanceClass(tse)
# When one uses add* function, the results are stored to rowData
rowData(tse)
#> DataFrame with 341 rows and 8 columns
#>               Kingdom         Phylum               Class              Order
#>           <character>    <character>         <character>        <character>
#> 125ds10      Bacteria Proteobacteria Gammaproteobacteria  Oceanospirillales
#> 211ds20      Bacteria Proteobacteria Gammaproteobacteria  Oceanospirillales
#> 5B-12        Bacteria    Chloroflexi             Bljii12            AKYG885
#> A714017      Bacteria         SAR406                AB16        Arctic96B-7
#> ACK-M1       Bacteria Actinobacteria      Actinobacteria    Actinomycetales
#> ...               ...            ...                 ...                ...
#> kpj58rc      Bacteria            OP3              koll11              GIF10
#> ntu14        Bacteria Actinobacteria      Actinobacteria   Acidimicrobiales
#> pMC2A33       Archaea  Euryarchaeota      Thermoplasmata                 E2
#> vadinHA31    Bacteria    Tenericutes     Erysipelotrichi Erysipelotrichales
#> wb1_P06      Bacteria Actinobacteria      Actinobacteria   Acidimicrobiales
#>                Family       Genus     Species abundance_class
#>           <character> <character> <character>     <character>
#> 125ds10       125ds10          NA          NA             crt
#> 211ds20       211ds20          NA          NA             crt
#> 5B-12           5B-12          NA          NA             crt
#> A714017       A714017          NA          NA             crt
#> ACK-M1         ACK-M1          NA          NA        abundant
#> ...               ...         ...         ...             ...
#> kpj58rc       kpj58rc          NA          NA             crt
#> ntu14           ntu14          NA          NA             crt
#> pMC2A33       pMC2A33          NA          NA             crt
#> vadinHA31   vadinHA31          NA          NA             crt
#> wb1_P06       wb1_P06          NA          NA             crt