Longitudinal Per-Time-Point Differential Abundance Test

Performs differential abundance testing at each time point separately in longitudinal microbiome data using per-time LinDA fixed-effects models.

Usage

generate_taxa_per_time_test_long(
  data.obj,
  subject.var,
  time.var = NULL,
  group.var,
  adj.vars = NULL,
  feature.level,
  prev.filter = 0,
  abund.filter = 0,
  feature.dat.type = c("count", "proportion", "other"),
  ...
)

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.

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.

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).

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)

...

Additional arguments passed to other methods.

Value

A nested list structure where:

• First level: Named by time points (time.var 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)" for categorical variables, or variable name for continuous variables)

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

  • Variable: Feature/taxon name

  • Coefficient: Log2 fold change (categorical) or slope (continuous)

  • SE: Standard error of the coefficient

  • P.Value: Raw p-value from LinDA's statistical test

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

  • Mean.Abundance: Mean abundance across all samples at that time point

  • Prevalence: Proportion of samples where feature is present (non-zero)

Analysis is performed separately for each time point using LinDA fixed-effects models.

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 handles both count and proportion data types.

The function constructs a fixed-effects model formula based on the provided variables and performs filtering based on prevalence and abundance thresholds, with optional normalization for count data.

Importantly, the function conducts differential abundance analysis separately for each time point in the longitudinal data. This approach allows for the identification of taxa that show significant changes at specific time points, providing insights into the dynamics of the microbiome over time.

Examples

if (FALSE) { # \dontrun{
# Example 1: Analyzing the ECAM dataset
data("ecam.obj")

# Analyzing the impact of delivery method on microbial composition over months
result1 <- generate_taxa_per_time_test_long(
  data.obj = ecam.obj,
  subject.var = "studyid",
  time.var = "month_num",
  group.var = "delivery",
  adj.vars = "diet",
  feature.level = c("Phylum", "Class"),
  feature.dat.type = "proportion"
)

# Visualizing the results for the ECAM dataset
dotplot_ecam <- generate_taxa_per_time_dotplot_long(
  data.obj = ecam.obj,
  test.list = result1,
  group.var = "delivery",
  time.var = "month_num",
  feature.level = c("Phylum", "Class")
)

# Example 2: Analyzing the Type 2 Diabetes dataset
data("subset_T2D.obj")

# Longitudinal analysis of microbial changes in different racial groups
result2 <- generate_taxa_per_time_test_long(
  data.obj = subset_T2D.obj,
  subject.var = "subject_id",
  time.var = "visit_number_num",
  group.var = "subject_race",
  adj.vars = "sample_body_site",
  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 = result2,
  group.var = "subject_race",
  time.var = "visit_number_num",
  t0.level = unique(subset_T2D.obj$meta.dat$visit_number_num)[1],
  ts.levels = unique(subset_T2D.obj$meta.dat$visit_number_num)[-1],
  feature.level = c("Genus", "Family")
)
} # }