Skip to contents

Longitudinal Change-From-Baseline Taxa Test

Source: R/generate_taxa_change_per_time_test_long.R
generate_taxa_change_per_time_test_long.Rd

Analyzes taxa abundance changes from baseline at each follow-up time point, testing for group differences in change scores using linear models.

Usage

generate_taxa_change_per_time_test_long(
  data.obj,
  subject.var,
  time.var = NULL,
  t0.level = NULL,
  ts.levels = NULL,
  group.var,
  adj.vars = NULL,
  feature.level,
  feature.change.func = "relative change",
  feature.dat.type = c("count", "proportion", "other"),
  prev.filter = 0,
  abund.filter = 0,
  ...
)

Arguments

data.obj

A MicrobiomeStat data object, which is a list containing at minimum the following components:

  • feature.tab: A matrix of feature abundances (taxa/genes as rows, samples as columns)

  • meta.dat: A data frame of sample metadata (samples as rows)

Optional components include:

  • feature.ann: A matrix/data frame of feature annotations (e.g., taxonomy)

  • tree: A phylogenetic tree object (class "phylo")

  • feature.agg.list: Pre-aggregated feature tables by taxonomy

Data objects can be created using converters like mStat_convert_phyloseq_to_data_obj or importers like mStat_import_qiime2_as_data_obj.

subject.var

Character string specifying the column name in meta.dat that uniquely identifies each subject or sample unit. Required for longitudinal and paired designs to track repeated measurements.

time.var

Character string specifying the column name in meta.dat containing the time variable. Required for longitudinal and paired analyses. Supports character/factor labels (e.g., "baseline", "week4") and numeric values. Some trend/volatility methods require numeric or coercible-to-numeric time values.

t0.level

Character or numeric value specifying the baseline time point for longitudinal or paired analyses. Should match a value in the time.var column.

ts.levels

Character vector specifying the follow-up time points for longitudinal or paired analyses. Should match values in the time.var column.

group.var

Character string specifying the column name in meta.dat containing the grouping variable (e.g., treatment, condition, phenotype). Used for between-group comparisons.

adj.vars

Character vector specifying column names in meta.dat to be used as covariates for adjustment in statistical models. These variables will be included as fixed effects.

feature.level

Character vector specifying the taxonomic or annotation level(s) for analysis. Should match column names in feature.ann, such as "Phylum", "Family", "Genus", etc. Use "original" to analyze at the original feature level without aggregation.

feature.change.func

Function or character specifying change calculation method: "relative change", "absolute change", "log fold change", or custom function. Default is "relative change".

feature.dat.type

Character string specifying the data type of feature.tab. One of:

  • "count": Raw count data (will be normalized)

  • "proportion": Relative abundance data (should sum to 1 per sample)

  • "other": Pre-transformed data (no transformation applied)

prev.filter

Numeric value between 0 and 1. Features with prevalence (proportion of non-zero samples) below this threshold will be excluded from analysis. Default is usually 0 (no filtering).

abund.filter

Numeric value. Features with mean abundance below this threshold will be excluded from analysis. Default is usually 0 (no filtering).

...

Additional arguments passed to other methods.

Value

A nested list structure where:

  • First level: Named by follow-up time points (ts.levels)

  • Second level: Named by feature.level (e.g., "Phylum", "Genus")

  • Third level: Named by tested comparisons between groups (e.g., "Level vs Reference (Reference)")

  • Each final element is a data.frame with the following columns:

    • Variable: Feature/taxon name

    • Coefficient: Effect size of the change from baseline (interpretation depends on feature.change.func)

    • SE: Standard error of the coefficient from the linear model

    • P.Value: Raw p-value from standard linear model (lm)

    • Adjusted.P.Value: FDR-adjusted p-value (Benjamini-Hochberg)

    • Mean.Abundance: Mean abundance across all samples

    • Prevalence: Proportion of samples where feature is present

This function is a wrapper that calls generate_taxa_change_test_pair separately for each follow-up time point, analyzing changes from baseline at each time point.

This function is especially useful for longitudinal microbiome studies, facilitating the exploration of temporal patterns in microbial communities. By analyzing different time points against a baseline, it helps to uncover significant temporal shifts in the abundance of various taxa.

The function is tailored for investigations that aim to monitor changes in microbial communities over time, such as in response to treatments or environmental changes. The structured output assists in interpreting temporal trends and identifying key taxa that contribute to these changes.

Details

The function integrates various data manipulations, normalization procedures, and statistical tests to assess the significance of taxa changes over time or between groups. It allows for the adjustment of covariates and is capable of handling both count and proportion data types.

The function uses a standard linear model (lm) to analyze the data. It handles fixed effects to account for the influence of different variables on the taxa. Filtering is performed based on prevalence and abundance thresholds, and normalization and aggregation procedures are applied as necessary.

A key feature of the function is its ability to conduct differential abundance analysis separately for each time point in the longitudinal data. This method is particularly effective for identifying significant changes in taxa at specific time points, offering insights into the temporal dynamics of the microbiome.

Examples

if (FALSE) { # \dontrun{
# Example1: Analyzing the Type 2 Diabetes dataset
data("subset_T2D.obj")
# Longitudinal analysis of microbial changes in different racial groups
result <- generate_taxa_change_per_time_test_long(
  data.obj = subset_T2D.obj,
  subject.var = "subject_id",
  time.var = "visit_number",
  t0.level = unique(subset_T2D.obj$meta.dat$visit_number)[1],
  ts.levels = unique(subset_T2D.obj$meta.dat$visit_number)[-1],
  group.var = "subject_race",
  adj.vars = "subject_gender",
  prev.filter = 0.1,
  abund.filter = 0.001,
  feature.level = c("Genus", "Family"),
  feature.dat.type = "count"
)
# Visualizing the results for the Type 2 Diabetes dataset
dotplot_T2D <- generate_taxa_per_time_dotplot_long(
  data.obj = subset_T2D.obj,
  test.list = result,
  t0.level = unique(subset_T2D.obj$meta.dat$visit_number)[1],
  ts.levels = unique(subset_T2D.obj$meta.dat$visit_number)[-1],
  group.var = "subject_race",
  time.var = "visit_number",
  feature.level = c("Genus", "Family")
)
result2 <- generate_taxa_change_per_time_test_long(
  data.obj = subset_T2D.obj,
  subject.var = "subject_id",
  time.var = "visit_number",
  t0.level = unique(subset_T2D.obj$meta.dat$visit_number)[1],
  ts.levels = unique(subset_T2D.obj$meta.dat$visit_number)[-1],
  group.var = "subject_race",
  adj.vars = NULL,
  prev.filter = 0.1,
  abund.filter = 0.001,
  feature.level = c("Genus", "Family"),
  feature.dat.type = "count"
)
} # }