calculateUniFrac {mia} | R Documentation

## Calculate weighted or unweighted (Fast) UniFrac distance

### Description

This function calculates the (Fast) UniFrac distance for all sample-pairs in a `TreeSummarizedExperiment` object.

### Usage

    ## S4 method for signature 'ANY,phylo'
    calculateUniFrac(
      x,
      tree,
      weighted = FALSE,
      normalized = TRUE,
      BPPARAM = SerialParam()
    )

    ## S4 method for signature 'TreeSummarizedExperiment,missing'
    calculateUniFrac(
      x,
      abund_values = exprs_values,
      exprs_values = "counts",
      transposed = FALSE,
      ...
    )

    runUniFrac(
      x,
      tree,
      weighted = FALSE,
      normalized = TRUE,
      BPPARAM = SerialParam()
    )

### Arguments

`x` | a numeric matrix or a `TreeSummarizedExperiment` object containing a tree. Please note that `runUniFrac` expects a matrix with samples per row and not per column. This is implemented to be compatible with other distance calculations such as `dist` as much as possible.
`tree` | if `x` is a matrix, a `phylo` object matching the matrix. This means that the phylo object and the columns should relate to the same type of features (aka. microorganisms).
`weighted` | `TRUE` or `FALSE`: Should use weighted-UniFrac calculation? Weighted-UniFrac takes into account the relative abundance of species/taxa shared between samples, whereas unweighted-UniFrac only considers presence/absence. Default is `FALSE`, meaning the unweighted-UniFrac distance is calculated for all pairs of samples.
`normalized` | `TRUE` or `FALSE`: Should the output be normalized such that values range from 0 to 1 independent of branch length values? Default is `TRUE`. Note that (unweighted) `UniFrac` is always normalized by total branch-length, and so this value is ignored when `weighted == FALSE`.
`BPPARAM` | A `BiocParallelParam` object specifying whether the UniFrac calculation should be parallelized.
`abund_values` | a single `character` value for specifying which assay to use for calculation.
`exprs_values` | a single `character` value for specifying which assay to use for calculation. (Please use `abund_values` instead. At some point `exprs_values` will be disabled.)
`transposed` | Logical scalar, is x transposed with cells in rows?
`...` | optional arguments not used.

### Details

Please note that if `calculateUniFrac` is used as a `FUN` for `runMDS`, the argument `ntop` has to be set to `nrow(x)`.

### Value

a sample-by-sample distance matrix, suitable for NMDS, etc.

### Author(s)

Paul J. McMurdie. Adapted for mia by Felix G.M. Ernst

### References

http://bmf.colorado.edu/unifrac/

The main implementation (Fast UniFrac) is adapted from the algorithm's description in:

Hamady, Lozupone, and Knight, “Fast UniFrac: facilitating high-throughput phylogenetic analyses of microbial communities including analysis of pyrosequencing and PhyloChip data.” The ISME Journal (2010) 4, 17–27.

See also additional descriptions of UniFrac in the following articles:

Lozupone, Hamady and Knight, “UniFrac - An Online Tool for Comparing Microbial Community Diversity in a Phylogenetic Context.”, BMC Bioinformatics 2006, 7:371

Lozupone, Hamady, Kelley and Knight, “Quantitative and qualitative (beta) diversity measures lead to different insights into factors that structure microbial communities.” Appl Environ Microbiol. 2007

Lozupone C, Knight R. “UniFrac: a new phylogenetic method for comparing microbial communities.” Appl Environ Microbiol. 2005 71 (12):8228-35.

### Examples

    data(esophagus)
    library(scater)
    calculateUniFrac(esophagus, weighted = FALSE)
    calculateUniFrac(esophagus, weighted = TRUE)
    calculateUniFrac(esophagus, weighted = TRUE, normalized = FALSE)
    # for using calculateUniFrac in conjunction with runMDS the tree argument
    # has to be given separately. In addition, subsetting using ntop must
    # be disabled
    esophagus <- runMDS(esophagus, FUN = calculateUniFrac, name = "UniFrac",
                        tree = rowTree(esophagus),
                        exprs_values = "counts",
                        ntop = nrow(esophagus))
    reducedDim(esophagus)

[Package mia version 1.2.7 Index]