Skip to contents

Computes adjusted distance matrices for a set of variables using a dynamic model matrix.

Usage

mStat_calculate_adjusted_distance(data.obj, dist.obj, adj.vars, dist.name)

Arguments

data.obj

A MicrobiomeStat data object. This central component contains:

  • feature.tab: Matrix representation linking research objects and samples.

  • meta.dat: Data frame with rows representing samples and columns as annotations.

  • feature.ann: Matrix annotations with classification data.

  • phylogenetic tree: (Optional) Tree depicting evolutionary relationships.

  • feature.agg.list: (Optional) Aggregated results from feature.tab and feature.ann.

dist.obj

Distance matrix between samples, usually calculated using mStat_calculate_beta_diversity function. If NULL, beta diversity will be automatically computed from data.obj using mStat_calculate_beta_diversity.

adj.vars

Character vector listing variable names intended for adjustment.

dist.name

Character vector specifying names of distance matrices present in `dist.obj`.

Value

A list of adjusted distance matrices. Each matrix is named according to the `dist.name` parameter.

Details

Calculate Adjusted Distances Based on Specified Adjustment Variables

This function provides a way to calculate distances adjusted for specified variables in a dataset. It incorporates the results of multidimensional scaling (MDS) and adjusts distances based on a linear model.

The function uses cmdscale for multidimensional scaling and then adjusts the resultant distances based on a linear model using the variables provided in `adj.vars`.

Examples

if (FALSE) { # \dontrun{
data("subset_T2D.obj")
subset_T2D.dist.obj <- mStat_calculate_beta_diversity(subset_T2D.obj, c("BC","Jaccard"))
adj.dist.obj <- mStat_calculate_adjusted_distance(
data.obj = subset_T2D.obj,
dist.obj = subset_T2D.dist.obj,
adj.vars = c("subject_gender", "subject_race"),
dist.name = c("BC"))
} # }
data("peerj32.obj")
peerj32.dist.obj <- mStat_calculate_beta_diversity(peerj32.obj, c("BC"))
#> Warning: It appears the data may not have been rarefied. Please verify.
#> Initializing distance objects...
#> Calculating Bray-Curtis dissimilarity...
#> All calculations complete.
adj.dist.obj <- mStat_calculate_adjusted_distance(
data.obj = peerj32.obj,
dist.obj = peerj32.dist.obj,
adj.vars = c("sex"),
dist.name = c("BC"))
#> Calculating adjusted distances using the provided adjustment variables and distance matrices...
#> Additive constant c* is being added to the non-diagonal dissimilarities to ensure they are Euclidean.