getBaselineDivergence: Beta diversity between the baseline and later time steps

In microbiome/miaTime: Microbiome Time Series Analysis

Beta diversity between the baseline and later time steps

Description

Calculates sample dissimilarity between the given baseline and other time points, optionally within a group (subject, reaction chamber, or similar). The corresponding time difference is returned as well. The method operates on SummarizedExperiment objects, and the results are stored in colData.

Usage

getBaselineDivergence(
  x,
  group = NULL,
  time_field,
  name_divergence = "divergence_from_baseline",
  name_timedifference = "time_from_baseline",
  assay.type = "counts",
  FUN = vegan::vegdist,
  method = "bray",
  baseline_sample = NULL,
  altexp = NULL,
  dimred = NULL,
  n_dimred = NULL,
  ...
)

Arguments

x	A SummarizedExperiment object.
group	Character scalar. Specifies the grouping factor (name of a colData field). If given, the divergence is calculated per group. e.g. subject, chamber, group etc.). (Default: NULL)
time_field	Character scalar. Specifies the name of the time series field in colData.
name_divergence	Character scalar. Shows beta diversity between samples. (Default: "time_divergence")
name_timedifference	Character scalar. Field name for adding the time difference between samples used to calculate beta diversity. (Default: "time_difference")
assay.type	Character scalar. Specifies which assay values are used in the dissimilarity estimation. (Default: "counts")
FUN	Function for dissimilarity calculation. The function must expect the input matrix as its first argument. With rows as samples and columns as features. (Default: vegan::vegdist)
method	Character scalar. Used to calculate the distance. Method is passed to the function that is specified by FUN. (Default: "bray")
baseline_sample	Character vector. Specifies the baseline sample(s) to be used. If the "group" argument is given, this must be a named vector; one element per group. (Default: NULL)
altexp	Character scalar or integer scalar. Specifies the alternative experiment containing the input data. (Default: NULL)
dimred	Character scalar or integer scalar. indicates the reduced dimension result in reducedDims to use in the estimation. (Default: NULL)
n_dimred	Integer vector. Specifies the dimensions to use if dimred is specified. (Default: NULL)
...	Arguments to be passed

Details

The group argument allows calculating divergence per group. Otherwise, this is done across all samples at once.

The baseline sample/s always need to belong to the data object i.e. they can be merged into it before applying this function. The reason is that they need to have comparable sample data, at least some time point information for calculating time differences w.r.t. baseline sample.

The baseline time point is by default defined as the smallest time point (per group). Alternatively, the user can provide the baseline vector, or a list of baseline vectors per group (named list per group).

Value

a SummarizedExperiment or TreeSummarizedExperiment containing the sample dissimilarity and corresponding time difference between samples (across n time steps), within each level of the grouping factor.

Examples

#library(miaTime)
library(TreeSummarizedExperiment)
library(dplyr)

data(hitchip1006)
tse <- mia::transformCounts(hitchip1006, method = "relabundance")

# Subset to speed up example
tse <- tse[, colData(tse)$subject %in% c("900", "934", "843", "875")]

tse2 <- getBaselineDivergence(tse,
                              group = "subject",
                              time_field = "time",
                              name_divergence = "divergence_from_baseline",
                              name_timedifference = "time_from_baseline",
                              assay.type="relabundance",
                              FUN = vegan::vegdist,
                              method="bray")

tse2 <- getBaselineDivergence(tse,
                              baseline_sample = "Sample-875",
                              group = "subject",
                              time_field = "time",
                              name_divergence = "divergence_from_baseline",
                              name_timedifference = "time_from_baseline",
                              assay.type="relabundance",
                              FUN = vegan::vegdist,
                              method="bray")

microbiome/miaTime documentation built on Aug. 24, 2024, 1:28 a.m.