Alpha Diversity Association Test (Paired)
Source:R/generate_alpha_test_pair.R
generate_alpha_test_pair.RdTests associations between alpha diversity and time/group variables using mixed-effects models for paired/longitudinal designs.
Usage
generate_alpha_test_pair(
data.obj,
alpha.obj = NULL,
alpha.name = NULL,
depth = NULL,
subject.var,
time.var,
group.var = NULL,
adj.vars = NULL,
change.base = NULL
)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_objor importers likemStat_import_qiime2_as_data_obj.- alpha.obj
A list containing pre-calculated alpha diversity indices. If NULL and alpha diversity is needed, it will be calculated automatically. Names should match the alpha.name parameter (e.g., "shannon", "simpson"). See
mStat_calculate_alpha_diversity.- alpha.name
Character vector specifying which alpha diversity indices to analyze. Options include:
"shannon": Shannon diversity index
"simpson": Simpson diversity index
"observed_species": Observed species richness
"chao1": Chao1 richness estimator
"ace": ACE richness estimator
"pielou": Pielou's evenness
"faith_pd": Faith's phylogenetic diversity (requires a tree)
- depth
Numeric value or NULL. Rarefaction depth for rarefaction workflows. If NULL, uses the minimum sample depth.
- 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.
- change.base
A value indicating the base level for the time variable. If provided, the specified level will be used as the reference category in the model. Default is NULL (first level used).
Examples
data(peerj32.obj)
generate_alpha_test_pair(
data.obj = peerj32.obj,
alpha.obj = NULL,
alpha.name = c("shannon", "simpson", "ace"),
subject.var = "subject",
time.var = "time",
group.var = NULL
)
#> Warning: It appears the data may not have been rarefied. Please verify.
#> Calculating shannon diversity...
#> Calculating simpson diversity...
#> Calculating ace diversity...
#> Diversity calculations complete.
#> Simplifying the random-effects structure due to overparameterization.
#> Simplifying the random-effects structure due to overparameterization.
#> Simplifying the random-effects structure due to overparameterization.
#> $shannon
#> # A tibble: 2 × 5
#> Term Estimate Std.Error Statistic P.Value
#> <chr> <dbl> <dbl> <dbl> <dbl>
#> 1 (Intercept) 3.58 0.0226 158. 8.10e-55
#> 2 time2 0.0256 0.0261 0.982 3.37e- 1
#>
#> $simpson
#> # A tibble: 2 × 5
#> Term Estimate Std.Error Statistic P.Value
#> <chr> <dbl> <dbl> <dbl> <dbl>
#> 1 (Intercept) 0.951 0.00238 400. 4.96e-74
#> 2 time2 0.00303 0.00299 1.01 3.23e- 1
#>
#> $ace
#> # A tibble: 2 × 5
#> Term Estimate Std.Error Statistic P.Value
#> <chr> <dbl> <dbl> <dbl> <dbl>
#> 1 (Intercept) 101. 1.86 54.0 4.45e-30
#> 2 time2 3.29 1.45 2.27 3.39e- 2
#>
generate_alpha_test_pair(
data.obj = peerj32.obj,
alpha.obj = NULL,
alpha.name = c("shannon", "simpson", "ace"),
subject.var = "subject",
time.var = "time",
group.var = NULL,
change.base = "2"
)
#> Warning: It appears the data may not have been rarefied. Please verify.
#> Calculating shannon diversity...
#> Calculating simpson diversity...
#> Calculating ace diversity...
#> Diversity calculations complete.
#> Simplifying the random-effects structure due to overparameterization.
#> Simplifying the random-effects structure due to overparameterization.
#> Simplifying the random-effects structure due to overparameterization.
#> $shannon
#> # A tibble: 2 × 5
#> Term Estimate Std.Error Statistic P.Value
#> <chr> <dbl> <dbl> <dbl> <dbl>
#> 1 (Intercept) 3.59 0.0185 194. 1.19e-35
#> 2 time.L -0.0181 0.0184 -0.982 3.37e- 1
#>
#> $simpson
#> # A tibble: 2 × 5
#> Term Estimate Std.Error Statistic P.Value
#> <chr> <dbl> <dbl> <dbl> <dbl>
#> 1 (Intercept) 0.953 0.00185 515. 1.50e-44
#> 2 time.L -0.00214 0.00212 -1.01 3.23e- 1
#>
#> $ace
#> # A tibble: 2 × 5
#> Term Estimate Std.Error Statistic P.Value
#> <chr> <dbl> <dbl> <dbl> <dbl>
#> 1 (Intercept) 102. 1.72 59.6 6.44e-25
#> 2 time.L -2.33 1.02 -2.27 3.39e- 2
#>
generate_alpha_test_pair(
data.obj = peerj32.obj,
alpha.obj = NULL,
alpha.name = c("shannon", "simpson", "ace"),
subject.var = "subject",
time.var = "time",
group.var = "group"
)
#> Warning: It appears the data may not have been rarefied. Please verify.
#> Calculating shannon diversity...
#> Calculating simpson diversity...
#> Calculating ace diversity...
#> Diversity calculations complete.
#> Simplifying the random-effects structure due to overparameterization.
#> Simplifying the random-effects structure due to overparameterization.
#> Simplifying the random-effects structure due to overparameterization.
#> $shannon
#> # A tibble: 4 × 5
#> Term Estimate Std.Error Statistic P.Value
#> <chr> <dbl> <dbl> <dbl> <dbl>
#> 1 (Intercept) 3.51 0.0356 98.6 8.55e-47
#> 2 groupPlacebo 0.104 0.0446 2.34 2.47e- 2
#> 3 time2 0.0606 0.0432 1.40 1.76e- 1
#> 4 groupPlacebo:time2 -0.0551 0.0541 -1.02 3.21e- 1
#>
#> $simpson
#> # A tibble: 4 × 5
#> Term Estimate Std.Error Statistic P.Value
#> <chr> <dbl> <dbl> <dbl> <dbl>
#> 1 (Intercept) 0.945 0.00384 247. 4.08e-64
#> 2 groupPlacebo 0.00920 0.00481 1.91 6.29e- 2
#> 3 time2 0.00610 0.00501 1.22 2.38e- 1
#> 4 groupPlacebo:time2 -0.00482 0.00628 -0.768 4.52e- 1
#>
#> $ace
#> # A tibble: 4 × 5
#> Term Estimate Std.Error Statistic P.Value
#> <chr> <dbl> <dbl> <dbl> <dbl>
#> 1 (Intercept) 97.9 3.11 31.5 9.18e-23
#> 2 groupPlacebo 4.27 3.90 1.09 2.83e- 1
#> 3 time2 4.94 2.42 2.04 5.47e- 2
#> 4 groupPlacebo:time2 -2.59 3.03 -0.853 4.04e- 1
#>
generate_alpha_test_pair(
data.obj = peerj32.obj,
alpha.obj = NULL,
alpha.name = c("shannon", "simpson", "ace"),
subject.var = "subject",
time.var = "time",
group.var = "group",
adj.vars = "sex"
)
#> Warning: It appears the data may not have been rarefied. Please verify.
#> Calculating shannon diversity...
#> Calculating simpson diversity...
#> Calculating ace diversity...
#> Diversity calculations complete.
#> Simplifying the random-effects structure due to overparameterization.
#> Simplifying the random-effects structure due to overparameterization.
#> Simplifying the random-effects structure due to overparameterization.
#> $shannon
#> # A tibble: 5 × 5
#> Term Estimate Std.Error Statistic P.Value
#> <chr> <dbl> <dbl> <dbl> <dbl>
#> 1 (Intercept) 3.53 0.0372 95.0 1.54e-43
#> 2 sexmale -0.0575 0.0354 -1.62 1.21e- 1
#> 3 groupPlacebo 0.0993 0.0437 2.27 2.89e- 2
#> 4 time2 0.0606 0.0432 1.40 1.76e- 1
#> 5 groupPlacebo:time2 -0.0551 0.0541 -1.02 3.21e- 1
#>
#> $simpson
#> # A tibble: 5 × 5
#> Term Estimate Std.Error Statistic P.Value
#> <chr> <dbl> <dbl> <dbl> <dbl>
#> 1 (Intercept) 0.947 0.00404 234. 1.02e-59
#> 2 sexmale -0.00488 0.00371 -1.32 2.04e- 1
#> 3 groupPlacebo 0.00877 0.00477 1.84 7.39e- 2
#> 4 time2 0.00610 0.00501 1.22 2.38e- 1
#> 5 groupPlacebo:time2 -0.00482 0.00628 -0.768 4.52e- 1
#>
#> $ace
#> # A tibble: 5 × 5
#> Term Estimate Std.Error Statistic P.Value
#> <chr> <dbl> <dbl> <dbl> <dbl>
#> 1 (Intercept) 97.0 3.45 28.1 5.35e-20
#> 2 sexmale 2.45 3.78 0.648 5.25e- 1
#> 3 groupPlacebo 4.49 3.96 1.13 2.68e- 1
#> 4 time2 4.94 2.42 2.04 5.47e- 2
#> 5 groupPlacebo:time2 -2.59 3.03 -0.853 4.04e- 1
#>
data("subset_pairs.obj")
generate_alpha_test_pair(
data.obj = subset_pairs.obj,
alpha.obj = NULL,
alpha.name = c("shannon", "simpson", "ace"),
subject.var = "MouseID",
time.var = "Antibiotic",
group.var = "Sex"
)
#> Warning: It appears the data may not have been rarefied. Please verify.
#> Calculating shannon diversity...
#> Calculating simpson diversity...
#> Calculating ace diversity...
#> Diversity calculations complete.
#> Simplifying the random-effects structure due to overparameterization.
#> Simplifying the random-effects structure due to overparameterization.
#> Simplifying the random-effects structure due to overparameterization.
#> $shannon
#> # A tibble: 4 × 5
#> Term Estimate Std.Error Statistic P.Value
#> <chr> <dbl> <dbl> <dbl> <dbl>
#> 1 (Intercept) 1.55 0.0947 16.3 1.11e-26
#> 2 SexM -0.390 0.135 -2.88 5.20e- 3
#> 3 AntibioticWeek 2 -0.0691 0.115 -0.601 5.51e- 1
#> 4 SexM:AntibioticWeek 2 0.474 0.165 2.88 6.33e- 3
#>
#> $simpson
#> # A tibble: 4 × 5
#> Term Estimate Std.Error Statistic P.Value
#> <chr> <dbl> <dbl> <dbl> <dbl>
#> 1 (Intercept) 0.631 0.0331 19.1 4.46e-31
#> 2 SexM -0.130 0.0474 -2.75 7.49e- 3
#> 3 AntibioticWeek 2 -0.0372 0.0412 -0.904 3.71e- 1
#> 4 SexM:AntibioticWeek 2 0.177 0.0589 3.01 4.43e- 3
#>
#> $ace
#> # A tibble: 4 × 5
#> Term Estimate Std.Error Statistic P.Value
#> <chr> <dbl> <dbl> <dbl> <dbl>
#> 1 (Intercept) 72.8 3.59 20.3 1.01e-33
#> 2 SexM -4.24 5.13 -0.827 4.11e- 1
#> 3 AntibioticWeek 2 -6.19 5.06 -1.23 2.27e- 1
#> 4 SexM:AntibioticWeek 2 8.15 7.23 1.13 2.66e- 1
#>
generate_alpha_test_pair(
data.obj = subset_pairs.obj,
alpha.obj = NULL,
alpha.name = c("shannon", "simpson", "ace"),
subject.var = "MouseID",
time.var = "Antibiotic",
group.var = "Sex",
change.base = "Week 2"
)
#> Warning: It appears the data may not have been rarefied. Please verify.
#> Calculating shannon diversity...
#> Calculating simpson diversity...
#> Calculating ace diversity...
#> Diversity calculations complete.
#> Simplifying the random-effects structure due to overparameterization.
#> Simplifying the random-effects structure due to overparameterization.
#> Simplifying the random-effects structure due to overparameterization.
#> $shannon
#> # A tibble: 4 × 5
#> Term Estimate Std.Error Statistic P.Value
#> <chr> <dbl> <dbl> <dbl> <dbl>
#> 1 (Intercept) 1.51 0.0752 20.1 7.72e-23
#> 2 SexM -0.153 0.108 -1.42 1.63e- 1
#> 3 Antibiotic.L 0.0489 0.0813 0.601 5.51e- 1
#> 4 SexM:Antibiotic.L -0.335 0.116 -2.88 6.33e- 3
#>
#> $simpson
#> # A tibble: 4 × 5
#> Term Estimate Std.Error Statistic P.Value
#> <chr> <dbl> <dbl> <dbl> <dbl>
#> 1 (Intercept) 0.612 0.0259 23.6 1.72e-25
#> 2 SexM -0.0413 0.0371 -1.11 2.72e- 1
#> 3 Antibiotic.L 0.0263 0.0291 0.904 3.71e- 1
#> 4 SexM:Antibiotic.L -0.125 0.0417 -3.01 4.43e- 3
#>
#> $ace
#> # A tibble: 4 × 5
#> Term Estimate Std.Error Statistic P.Value
#> <chr> <dbl> <dbl> <dbl> <dbl>
#> 1 (Intercept) 69.7 2.55 27.4 5.61e-28
#> 2 SexM -0.167 3.64 -0.0458 9.64e- 1
#> 3 Antibiotic.L 4.38 3.58 1.23 2.27e- 1
#> 4 SexM:Antibiotic.L -5.76 5.12 -1.13 2.66e- 1
#>