estimateDivergence {mia} | R Documentation

## Estimate divergence

### Description

This function estimates a divergence within samples.

### Usage

    estimateDivergence(
      x,
      abund_values = "counts",
      name = "divergence",
      reference = "median",
      FUN = vegan::vegdist,
      method = "bray",
      ...
    )

    ## S4 method for signature 'SummarizedExperiment'
    estimateDivergence(
      x,
      abund_values = "counts",
      name = "divergence",
      reference = "median",
      FUN = vegan::vegdist,
      method = "bray",
      ...
    )

### Arguments

`x` | a `SummarizedExperiment` object
`abund_values` | the name of the assay used for calculation of the sample-wise estimates
`name` | a name for the column of the colData the results should be stored in. By defaut, `name` is `"divergence"`.
`reference` | a numeric vector that has length equal to number of features, or a non-empty character value; either 'median' or 'mean'. `reference` specifies the reference that is used to calculate `divergence`. by default, `reference` is `"median"`.
`FUN` | a `function` for distance calculation. The function must expect the input matrix as its first argument. With rows as samples and columns as features. By default, `FUN` is `vegan::vegdist`.
`method` | a method that is used to calculate the distance. Method is passed to the function that is specified by `FUN`. By default, `method` is `"bray"`.
`...` | optional arguments

### Details

Microbiota divergence (heterogeneity / spread) within a given sample set can be quantified by the average sample dissimilarity or beta diversity with respect to a given reference sample.

This measure is sensitive to sample size. Subsampling or bootstrapping can be applied to equalize sample sizes between comparisons.

### Value

`x` with additional `colData` named `*name*`

### Author(s)

Leo Lahti and Tuomas Borman. Contact: microbiome.github.io

### See Also

`plotColData`

- `estimateRichness`

- `estimateEvenness`

- `estimateDominance`

- `calculateDistance`

### Examples

    data(GlobalPatterns)
    tse <- GlobalPatterns

    # By default, reference is median of all samples. The name of column where results
    # is "divergence" by default, but it can be specified.
    tse <- estimateDivergence(tse)

    # The method that are used to calculate distance in divergence and
    # reference can be specified. Here, euclidean distance and dist function from
    # stats package are used. Reference is the first sample.
    tse <- estimateDivergence(tse, name = "divergence_first_sample",
                              reference = assays(tse)$counts[,1],
                              FUN = stats::dist, method = "euclidean")

    # Reference can also be median or mean of all samples.
    # By default, divergence is calculated by using median. Here, mean is used.
    tse <- estimateDivergence(tse, name = "divergence_average", reference = "mean")

    # All three divergence results are stored in colData.
    colData(tse)

[Package mia version 1.2.7 Index]