### Install microbiomeMarker Package

Source: https://context7.com/yiluheihei/microbiomemarker/llms.txt

Installs the stable release from Bioconductor or the development version from GitHub. Ensure BiocManager and remotes are installed first.

```r
if (!requireNamespace("BiocManager", quietly = TRUE))
    install.packages("BiocManager")
BiocManager::install("microbiomeMarker")
```

```r
if (!requireNamespace("remotes", quietly = TRUE))
    install.packages("remotes")
remotes::install_github("yiluheihei/microbiomeMarker")
```

--------------------------------

### Install microbiomeMarker Development Version from GitHub

Source: https://github.com/yiluheihei/microbiomemarker/blob/devel/README.md

Install the latest development version of the microbiomeMarker package directly from GitHub. Requires the 'remotes' package.

```r
if (!requireNamespace("remotes", quietly=TRUE))
  install.packages("remotes")
remotes::install_github("yiluheihei/microbiomeMarker")
```

--------------------------------

### GPL Notice for Terminal Interaction

Source: https://github.com/yiluheihei/microbiomemarker/blob/devel/LICENSE.md

Display this short notice when the program starts in interactive mode. It informs users about the program's warranty status and redistribution conditions.

```text
microbiomeMarker Copyright (C) 2020 Yang Cao
This program comes with ABSOLUTELY NO WARRANTY; for details type 'show w'.
This is free software, and you are welcome to redistribute it
under certain conditions; type 'show c' for details.
```

--------------------------------

### Install microbiomeMarker from Bioconductor

Source: https://github.com/yiluheihei/microbiomemarker/blob/devel/README.md

Use this code to install the stable release version of the microbiomeMarker package from Bioconductor. Ensure BiocManager is installed first.

```r
if (!requireNamespace("BiocManager", quietly = TRUE))
    install.packages("BiocManager")

BiocManager::install("microbiomeMarker")
```

--------------------------------

### Standard GPL Notice for Source Files

Source: https://github.com/yiluheihei/microbiomemarker/blob/devel/LICENSE.md

Include this notice at the beginning of each source file to state the copyright and licensing terms. It ensures the program is free software under the GNU GPL.

```text
<one line to give the program's name and a brief idea of what it does.>
Copyright (C) 2020 Yang Cao

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <http://www.gnu.org/licenses/>.
```

--------------------------------

### Import DADA2 Output to phyloseq

Source: https://context7.com/yiluheihei/microbiomemarker/llms.txt

Imports DADA2 ASV sequence tables, taxonomy tables, and sample metadata into a phyloseq object. ASV names are standardized, and raw sequences are stored.

```r
library(microbiomeMarker)

seq_tab <- readRDS(system.file("extdata", "dada2_seqtab.rds",
    package = "microbiomeMarker"))
tax_tab <- readRDS(system.file("extdata", "dada2_taxtab.rds",
    package = "microbiomeMarker"))
sam_tab <- read.table(
    system.file("extdata", "dada2_samdata.txt", package = "microbiomeMarker"),
    sep = "\t", header = TRUE, row.names = 1)

ps <- import_dada2(seq_tab = seq_tab, tax_tab = tax_tab, sam_tab = sam_tab)
ps
```

--------------------------------

### Initialize LEfSe Analysis

Source: https://github.com/yiluheihei/microbiomemarker/blob/devel/tests/testthat/_snaps/lefse.md

This code initializes the LEfSe analysis using the `mm_lefse` function. It indicates the normalization method and the identity method for microbial markers. The output shows the dimensions of the resulting microbiomeMarker object, including marker tables, OTU tables, sample data, and taxonomy tables.

```R
mm_lefse
```

--------------------------------

### Import QIIME2 Artifacts to phyloseq

Source: https://context7.com/yiluheihei/microbiomemarker/llms.txt

Reads QIIME2 artifacts (feature table, taxonomy, tree, representative sequences) and sample metadata into a phyloseq object. Ensure all necessary .qza and .tsv files are available.

```r
ps <- import_qiime2(
    otu_qza  = system.file("extdata", "table.qza",    package = "microbiomeMarker"),
    taxa_qza = system.file("extdata", "taxonomy.qza", package = "microbiomeMarker"),
    sam_tab  = system.file("extdata", "sample-metadata.tsv", package = "microbiomeMarker"),
    tree_qza = system.file("extdata", "tree.qza",     package = "microbiomeMarker")
)
ps
```

--------------------------------

### import_qiime2()

Source: https://context7.com/yiluheihei/microbiomemarker/llms.txt

Reads QIIME2 artifacts into a unified phyloseq object.

```APIDOC
## import_qiime2()

### Description
Reads QIIME2 `.qza` artifact files (feature table, taxonomy, phylogenetic tree, representative sequences) and a TSV sample metadata file into a unified `phyloseq` object.

### Parameters
#### Path Parameters
- **otu_qza** (file) - Required - Path to the QIIME2 feature table artifact (`.qza`).
- **taxa_qza** (file) - Required - Path to the QIIME2 taxonomy artifact (`.qza`).
- **sam_tab** (file) - Required - Path to the sample metadata file (TSV format).
- **tree_qza** (file) - Optional - Path to the QIIME2 phylogenetic tree artifact (`.qza`).

### Request Example
```r
ps <- import_qiime2(
    otu_qza  = system.file("extdata", "table.qza",    package = "microbiomeMarker"),
    taxa_qza = system.file("extdata", "taxonomy.qza", package = "microbiomeMarker"),
    sam_tab  = system.file("extdata", "sample-metadata.tsv", package = "microbiomeMarker"),
    tree_qza = system.file("extdata", "tree.qza",     package = "microbiomeMarker")
)
ps
```

### Response
#### Success Response (phyloseq-class)
- **ps** (phyloseq-class) - A phyloseq object containing the imported data.
```

--------------------------------

### Compare Differential Analysis Methods

Source: https://context7.com/yiluheihei/microbiomemarker/llms.txt

Benchmarks multiple differential abundance (DA) methods by simulating spike-ins and computing empirical power, FPR, FDR, and AUC over multiple repetitions. Requires specifying the phyloseq object, grouping variable, taxa rank, methods to compare, number of repetitions, and effect size.

```r
data(oxygen)

set.seed(123)
cmp <- compare_DA(
    ps        = oxygen,
    group     = "oxygenation",
    taxa_rank = "none",
    methods   = c("aldex", "ancombc", "deseq2", "edger", "lefse", "limma_voom"),
    n_rep     = 10,
    effect_size = 5,
    BPPARAM   = BiocParallel::SerialParam()
)

# Summarize: ranked by composite score = (AUC - 0.5) * power - FDR
summary(cmp, sort = "score")
```

--------------------------------

### run_ancombc()

Source: https://context7.com/yiluheihei/microbiomemarker/llms.txt

A wrapper for ANCOMBC that corrects for unobserved sampling fractions to enable inference on absolute abundance differences. It returns the ANCOM-BC W-statistic and adjusted p-values.

```APIDOC
## run_ancombc()

### Description
Wrapper around `ANCOMBC::ancombc()` that corrects for unobserved sampling fractions, enabling inference on absolute abundance differences. Returns the ANCOM-BC W-statistic as effect size along with adjusted p-values.

### Parameters
- **data**: A phyloseq object containing the microbiome data.
- **group**: The column name in the sample data to use for grouping.
- **taxa_rank**: The taxonomic rank to summarize to. Use "all" to summarize to the highest rank.
- **p_adjust**: Method for p-value adjustment (e.g., "holm").
- **prv_cut**: Cutoff for prevalence filtering (e.g., exclude taxa present in <10% samples).
- **struc_zero**: Boolean indicating whether to handle structural zeros.
- **pvalue_cutoff**: Cutoff for the adjusted p-value.

### Request Example
```r
data(enterotypes_arumugam)
ps2 <- phyloseq::subset_samples(
    enterotypes_arumugam,
    Enterotype %in% c("Enterotype 3", "Enterotype 2")
)

mm_ancombc <- run_ancombc(
    ps2,
    group         = "Enterotype",
    taxa_rank     = "all",
    p_adjust      = "holm",
    prv_cut       = 0.10,
    struc_zero    = FALSE,
    pvalue_cutoff = 0.05
)
```

### Response
Returns a `microbiomeMarker-class` object containing the identified markers and their associated statistics, including the W-statistic and adjusted p-values.
```

--------------------------------

### Visualize All Significance Level Annotations

Source: https://github.com/yiluheihei/microbiomemarker/blob/devel/tests/testthat/_snaps/multiple-groups-test.md

Displays the first few rows of annotations for all features, indicating significance levels across different comparisons. This helps in understanding the overall significance patterns for various microbial features.

```r
head(annotation_all)
```

--------------------------------

### compare_DA

Source: https://context7.com/yiluheihei/microbiomemarker/llms.txt

Evaluates and ranks multiple DA methods on the user's own data by spike-in simulation: artificial differential features are inserted, the methods are run on permuted data, and empirical power (spike detection rate), false positive rate (FPR), false discovery rate (FDR), and AUC are computed over `n_rep` repetitions.

```APIDOC
## compare_DA()

### Description
Evaluates and ranks multiple DA methods on the user's own data by spike-in simulation: artificial differential features are inserted, the methods are run on permuted data, and empirical power (spike detection rate), false positive rate (FPR), false discovery rate (FDR), and AUC are computed over `n_rep` repetitions.

### Parameters
- **ps** (object) - Input phyloseq object.
- **group** (string) - The column name in sample metadata to group by.
- **taxa_rank** (string) - The taxonomic rank to perform analysis on (e.g., "none").
- **methods** (vector) - A character vector of DA methods to compare (e.g., c("aldex", "ancombc", "deseq2", "edger", "lefse", "limma_voom")).
- **n_rep** (integer) - Number of repetitions for the simulation.
- **effect_size** (numeric) - The effect size to simulate for differential features.
- **BPPARAM** (object) - BiocParallel parameters for parallel processing.

### Request Example
```r
data(oxygen)

set.seed(123)
cmp <- compare_DA(
    ps        = oxygen,
    group     = "oxygenation",
    taxa_rank = "none",
    methods   = c("aldex", "ancombc", "deseq2", "edger", "lefse", "limma_voom"),
    n_rep     = 10,
    effect_size = 5,
    BPPARAM   = BiocParallel::SerialParam()
)

# Summarize: ranked by composite score = (AUC - 0.5) * power - FDR
summary(cmp, sort = "score")
```

### Response
- **summary** (object) - A summary table of the comparison results, including method call, AUC, FPR, power, FDR, and various scores.
```

--------------------------------

### Run ALDEx2 for Compositional Uncertainty

Source: https://context7.com/yiluheihei/microbiomemarker/llms.txt

Uses ALDEx2 with Monte Carlo sampling and CLR transformation to handle compositional uncertainty. Supports various statistical tests and normalization methods. Requires specifying group, method, and p-value adjustment.

```r
data(enterotypes_arumugam)
ps2 <- phyloseq::subset_samples(
    enterotypes_arumugam,
    Enterotype %in% c("Enterotype 3", "Enterotype 2")
)

mm_aldex <- run_aldex(
    ps2,
    group         = "Enterotype",
    taxa_rank     = "all",
    method        = "t.test",   # "wilcox.test", "kruskal", "glm_anova"
    denom         = "all",      # "iqlr", "zero", "lvha"
    mc_samples    = 128,
    p_adjust      = "BH",
    pvalue_cutoff = 0.05
)
marker_table(mm_aldex)
# feature  enrich_group  ef_aldex  pvalue  padj
```

--------------------------------

### normalize()

Source: https://context7.com/yiluheihei/microbiomemarker/llms.txt

Normalizes microbial abundance data using various methods.

```APIDOC
## normalize()

### Description
A unified S4 generic that accepts `phyloseq`, `otu_table`, `data.frame`, or `matrix` objects and applies one of eight normalization methods. Normalization factors (for TMM, RLE, CSS) are stored in `sample_data` for downstream use by differential analysis functions.

### Parameters
#### Path Parameters
- **object** (phyloseq, otu_table, data.frame, matrix) - Required - The input data object.
- **method** (character) - Required - The normalization method to apply. Options include "TSS", "TMM", "RLE", "CSS", "CLR", "CPM", "rarefy".

### Request Example
```r
data(caporaso)

# Total Sum Scaling (relative abundance)
ps_tss <- normalize(caporaso, method = "TSS")

# TMM — trimmed mean of m-values (robust to outliers)
ps_tmm <- normalize(caporaso, method = "TMM")

# RLE — relative log expression (DESeq2 default)
ps_rle <- normalize(caporaso, method = "RLE")

# CSS — cumulative sum scaling (metagenomeSeq default)
ps_css <- normalize(caporaso, method = "CSS")

# CLR — centered log-ratio (compositional data)
ps_clr <- normalize(caporaso, method = "CLR")

# CPM — counts per million (LEfSe default)
ps_cpm <- normalize(caporaso, method = "CPM")

# Rarefy to minimum library size
ps_rare <- normalize(caporaso, method = "rarefy")
```

### Response
#### Success Response (normalized object)
- **normalized_object** (phyloseq, otu_table, data.frame, matrix) - The input object with normalized abundance data. Normalization factors may be stored in `sample_data` for certain methods.
```

--------------------------------

### import_dada2()

Source: https://context7.com/yiluheihei/microbiomemarker/llms.txt

Converts DADA2 pipeline output into a phyloseq object for downstream analysis.

```APIDOC
## import_dada2()

### Description
Converts the ASV sequence table, taxonomy table, and sample metadata produced by DADA2 into a `phyloseq` object ready for downstream marker analysis. ASV names are automatically set to `ASV1`, `ASV2`, … and the raw sequences are stored as a `DNAStringSet` reference sequence slot.

### Parameters
#### Path Parameters
- **seq_tab** (object) - Required - DADA2 ASV sequence table.
- **tax_tab** (object) - Required - DADA2 taxonomy table.
- **sam_tab** (data.frame or file) - Required - Sample metadata.

### Request Example
```r
library(microbiomeMarker)

seq_tab <- readRDS(system.file("extdata", "dada2_seqtab.rds",
    package = "microbiomeMarker"))
tax_tab <- readRDS(system.file("extdata", "dada2_taxtab.rds",
    package = "microbiomeMarker"))
sam_tab <- read.table(
    system.file("extdata", "dada2_samdata.txt", package = "microbiomeMarker"),
    sep = "\t", header = TRUE, row.names = 1)

ps <- import_dada2(seq_tab = seq_tab, tax_tab = tax_tab, sam_tab = sam_tab)
ps
```

### Response
#### Success Response (phyloseq-class)
- **ps** (phyloseq-class) - A phyloseq object containing the imported data.
```

--------------------------------

### run_aldex()

Source: https://context7.com/yiluheihei/microbiomemarker/llms.txt

Applies ALDEx2's method using Monte Carlo sampling of Dirichlet distributions and CLR transformation. It supports various statistical tests for differential abundance, including t-test, Wilcoxon, Kruskal–Wallis, and GLM ANOVA.

```APIDOC
## run_aldex()

### Description
Uses Monte Carlo sampling of Dirichlet distributions and centered log-ratio (CLR) transformation to model compositional uncertainty. Supports t-test and Wilcoxon test (two groups) as well as Kruskal–Wallis and GLM ANOVA (multiple groups).

### Parameters
- **data**: A phyloseq object containing the microbiome data.
- **group**: The column name in the sample data to use for grouping.
- **taxa_rank**: The taxonomic rank to summarize to. Use "all" to summarize to the highest rank.
- **method**: The statistical test to use (e.g., "t.test", "wilcox.test", "kruskal", "glm_anova").
- **denom**: The denominator to use for CLR transformation (e.g., "all", "iqlr").
- **mc_samples**: Number of Monte Carlo samples to use.
- **p_adjust**: Method for p-value adjustment (e.g., "BH").
- **pvalue_cutoff**: Cutoff for the adjusted p-value.

### Request Example
```r
data(enterotypes_arumugam)
ps2 <- phyloseq::subset_samples(
    enterotypes_arumugam,
    Enterotype %in% c("Enterotype 3", "Enterotype 2")
)

mm_aldex <- run_aldex(
    ps2,
    group         = "Enterotype",
    taxa_rank     = "all",
    method        = "t.test",
    denom         = "all",
    mc_samples    = 128,
    p_adjust      = "BH",
    pvalue_cutoff = 0.05
)
```

### Response
Returns a `microbiomeMarker-class` object containing the identified markers and their associated statistics, including the ALDEx2 effect size and adjusted p-values.
```

--------------------------------

### Run ANCOM for Differential Abundance Testing

Source: https://context7.com/yiluheihei/microbiomemarker/llms.txt

Tests differential abundance using ANCOM by comparing pairwise log ratios. Features are declared markers based on W-statistic and W_cutoff. Supports two-group and multi-group comparisons.

```r
data(enterotypes_arumugam)
ps2 <- phyloseq::subset_samples(
    enterotypes_arumugam,
    Enterotype %in% c("Enterotype 3", "Enterotype 2")
)

mm_ancom <- run_ancom(
    ps2,
    group         = "Enterotype",
    taxa_rank     = "all",
    norm          = "TSS",
    p_adjust      = "BH",
    pvalue_cutoff = 0.05,
    W_cutoff      = 0.75
)
marker_table(mm_ancom)
# feature  enrich_group  ef_CLR_diff_mean  W
```

--------------------------------

### run_deseq2()

Source: https://context7.com/yiluheihei/microbiomemarker/llms.txt

Applies DESeq2's moderated negative binomial model for differential expression analysis. It uses the Wald test for two-group comparisons and the Likelihood Ratio Test (LRT) for multi-group comparisons. Raw counts are required, with RLE normalization as the default.

```APIDOC
## run_deseq2()

### Description
Applies DESeq2's moderated negative binomial model. Uses the Wald test for two-group comparisons and the Likelihood Ratio Test (LRT) for multi-group comparisons. Raw (un-normalized) counts are required; RLE normalization is the default and recommended choice.

### Parameters
- **data**: A phyloseq object containing the microbiome data.
- **group**: The column name in the sample data to use for grouping.
- **taxa_rank**: The taxonomic rank to summarize to. Use "all" to summarize to the highest rank.
- **norm**: Normalization method (e.g., "RLE").
- **fitType**: Type of fit for the dispersion-mean relationship (e.g., "parametric").
- **sfType**: Type of size factor estimation (e.g., "poscounts").
- **p_adjust**: Method for p-value adjustment (e.g., "BH").
- **pvalue_cutoff**: Cutoff for the adjusted p-value.

### Request Example
```r
data(enterotypes_arumugam)
ps2 <- phyloseq::subset_samples(
    enterotypes_arumugam,
    Enterotype %in% c("Enterotype 3", "Enterotype 2")
) |> phyloseq::subset_taxa(Phylum %in% c("Firmicutes"))

mm_deseq2 <- run_deseq2(
    ps2,
    group         = "Enterotype",
    taxa_rank     = "all",
    norm          = "RLE",
    fitType       = "parametric",
    sfType        = "poscounts",
    p_adjust      = "BH",
    pvalue_cutoff = 0.05
)
```

### Response
Returns a `microbiomeMarker-class` object containing the identified markers and their associated statistics, including log fold change and adjusted p-values.
```

--------------------------------

### Print Marker Table with Limma-Voom

Source: https://github.com/yiluheihei/microbiomemarker/blob/devel/tests/testthat/_snaps/limma-voom.md

Prints the marker table generated by Limma-Voom analysis. This is useful for inspecting differential expression results, including feature names, enrichment groups, log fold changes, p-values, and adjusted p-values.

```R
print(marker_table(mm_lv), digits = 5)
```

--------------------------------

### Run limma-voom for Differential Abundance

Source: https://context7.com/yiluheihei/microbiomemarker/llms.txt

Applies voom mean-variance trend estimation and empirical Bayes moderated linear model fitting. Effective for low counts or unequal library sizes. Requires specifying the grouping variable, contrast, and normalization method.

```r
data(enterotypes_arumugam)

mm_limma <- run_limma_voom(
    enterotypes_arumugam,
    group         = "Enterotype",
    contrast      = c("Enterotype 3", "Enterotype 2"),  # reference, treatment
    taxa_rank     = "all",
    norm          = "TMM",
    p_adjust      = "none",
    pvalue_cutoff = 0.01
)
marker_table(mm_limma)
```

--------------------------------

### run_limma_voom

Source: https://context7.com/yiluheihei/microbiomemarker/llms.txt

Applies voom mean-variance trend estimation followed by empirical Bayes moderated linear model fitting via limma. Particularly effective for samples with low counts or unequal library sizes.

```APIDOC
## run_limma_voom()

### Description
Applies voom mean-variance trend estimation followed by empirical Bayes moderated linear model fitting via limma. Particularly effective for samples with low counts or unequal library sizes.

### Parameters
- **data** (object) - Input data, typically a phyloseq object.
- **group** (string) - The column name in sample metadata to group by.
- **contrast** (vector) - A character vector specifying the contrast for comparison (e.g., c("group1", "group2")).
- **taxa_rank** (string) - The taxonomic rank to perform analysis on (e.g., "Genus", "all").
- **norm** (string) - Normalization method to use (e.g., "TMM").
- **p_adjust** (string) - Method for p-value adjustment (e.g., "none", "BH").
- **pvalue_cutoff** (numeric) - Cutoff for p-value.

### Request Example
```r
data(enterotypes_arumugam)

mm_limma <- run_limma_voom(
    enterotypes_arumugam,
    group         = "Enterotype",
    contrast      = c("Enterotype 3", "Enterotype 2"),  # reference, treatment
    taxa_rank     = "all",
    norm          = "TMM",
    p_adjust      = "none",
    pvalue_cutoff = 0.01
)
marker_table(mm_limma)
```

### Response
- **marker_table** (object) - A table containing differential expression results, including feature, enrich_group, ef_logFC, pvalue, and padj.
```

--------------------------------

### Run edgeR for Negative Binomial Differential Expression

Source: https://context7.com/yiluheihei/microbiomemarker/llms.txt

Applies edgeR's GLM framework for differential expression using negative binomial models. Offers QLFT (recommended) and LRT test options. Requires specifying group, method, normalization, and p-value adjustment.

```r
data(enterotypes_arumugam)
ps2 <- phyloseq::subset_samples(
    enterotypes_arumugam,
    Enterotype %in% c("Enterotype 3", "Enterotype 2")
)

mm_edger <- run_edger(
    ps2,
    group         = "Enterotype",
    taxa_rank     = "all",
    method        = "QLFT",   # or "LRT"
    norm          = "TMM",
    p_adjust      = "BH",
    pvalue_cutoff = 0.05
)
marker_table(mm_edger)
```

--------------------------------

### run_edger()

Source: https://context7.com/yiluheihei/microbiomemarker/llms.txt

Applies edgeR's GLM framework for differential expression analysis in microbiome count data. It offers two testing options: quasi-likelihood F-test (QLFT) and likelihood ratio test (LRT). TMM normalization is the default.

```APIDOC
## run_edger()

### Description
Applies edgeR's GLM framework to microbiome count data. Two test options are available: quasi-likelihood F-test (QLFT, recommended for stricter error control) and likelihood ratio test (LRT). TMM normalization is the default.

### Parameters
- **data**: A phyloseq object containing the microbiome data.
- **group**: The column name in the sample data to use for grouping.
- **taxa_rank**: The taxonomic rank to summarize to. Use "all" to summarize to the highest rank.
- **method**: The testing method to use (e.g., "QLFT", "LRT").
- **norm**: Normalization method (e.g., "TMM").
- **p_adjust**: Method for p-value adjustment (e.g., "BH").
- **pvalue_cutoff**: Cutoff for the adjusted p-value.

### Request Example
```r
data(enterotypes_arumugam)
ps2 <- phyloseq::subset_samples(
    enterotypes_arumugam,
    Enterotype %in% c("Enterotype 3", "Enterotype 2")
)

mm_edger <- run_edger(
    ps2,
    group         = "Enterotype",
    taxa_rank     = "all",
    method        = "QLFT",
    norm          = "TMM",
    p_adjust      = "BH",
    pvalue_cutoff = 0.05
)
```

### Response
Returns a `microbiomeMarker-class` object containing the identified markers and their associated statistics, including effect size and adjusted p-values.
```

--------------------------------

### run_ancom()

Source: https://context7.com/yiluheihei/microbiomemarker/llms.txt

Tests for differential abundance by comparing pairwise log ratios between all features. A feature is considered a marker if its W-statistic exceeds a specified cutoff. Supports both two-group and multi-group comparisons.

```APIDOC
## run_ancom()

### Description
Tests differential abundance by comparing pairwise log ratios between all features. A feature is declared a marker when its W-statistic (number of pairwise comparisons it wins) exceeds `W_cutoff * (n_taxa - 1)`. Supports two-group (Wilcoxon) and multi-group (Kruskal–Wallis / AOV) comparisons.

### Parameters
- **data**: A phyloseq object containing the microbiome data.
- **group**: The column name in the sample data to use for grouping.
- **taxa_rank**: The taxonomic rank to summarize to. Use "all" to summarize to the highest rank.
- **norm**: Normalization method to apply (e.g., "TSS").
- **p_adjust**: Method for p-value adjustment (e.g., "BH").
- **pvalue_cutoff**: Cutoff for the adjusted p-value.
- **W_cutoff**: Cutoff for the W-statistic.

### Request Example
```r
data(enterotypes_arumugam)
ps2 <- phyloseq::subset_samples(
    enterotypes_arumugam,
    Enterotype %in% c("Enterotype 3", "Enterotype 2")
)

mm_ancom <- run_ancom(
    ps2,
    group         = "Enterotype",
    taxa_rank     = "all",
    norm          = "TSS",
    p_adjust      = "BH",
    pvalue_cutoff = 0.05,
    W_cutoff      = 0.75
)
```

### Response
Returns a `microbiomeMarker-class` object containing the identified markers and their associated statistics, including the W-statistic.
```

--------------------------------

### Run DESeq2 for Negative Binomial Differential Expression

Source: https://context7.com/yiluheihei/microbiomemarker/llms.txt

Applies DESeq2's moderated negative binomial model for differential expression. Requires raw counts and specifies normalization, fit type, and p-value adjustment. Supports Wald test (two-group) and LRT (multi-group).

```r
data(enterotypes_arumugam)
ps2 <- phyloseq::subset_samples(
    enterotypes_arumugam,
    Enterotype %in% c("Enterotype 3", "Enterotype 2")
) |> phyloseq::subset_taxa(Phylum %in% c("Firmicutes"))

mm_deseq2 <- run_deseq2(
    ps2,
    group         = "Enterotype",
    taxa_rank     = "all",
    norm          = "RLE",        # recommended for DESeq2
    fitType       = "parametric",
    sfType        = "poscounts",
    p_adjust      = "BH",
    pvalue_cutoff = 0.05
)
marker_table(mm_deseq2)
# feature  enrich_group  ef_logFC  pvalue  padj
```

--------------------------------

### Convert phyloseq to edgeR DGEList

Source: https://context7.com/yiluheihei/microbiomemarker/llms.txt

Converts a phyloseq object to an edgeR DGEList object, including sample metadata and taxonomy as gene annotations. Enables direct use of edgeR's full API.

```r
data(caporaso)
dge <- phyloseq2edgeR(caporaso)
dge
```

--------------------------------

### Normalize Microbial Abundance Data

Source: https://context7.com/yiluheihei/microbiomemarker/llms.txt

Applies one of eight normalization methods to microbial abundance data. Normalization factors for TMM, RLE, and CSS are stored in sample_data.

```r
data(caporaso)

# Total Sum Scaling (relative abundance)
ps_tss <- normalize(caporaso, method = "TSS")

# TMM — trimmed mean of m-values (robust to outliers)
ps_tmm <- normalize(caporaso, method = "TMM")

# RLE — relative log expression (DESeq2 default)
ps_rle <- normalize(caporaso, method = "RLE")

# CSS — cumulative sum scaling (metagenomeSeq default)
ps_css <- normalize(caporaso, method = "CSS")

# CLR — centered log-ratio (compositional data)
ps_clr <- normalize(caporaso, method = "CLR")

# CPM — counts per million (LEfSe default)
ps_cpm <- normalize(caporaso, method = "CPM")

# Rarefy to minimum library size
ps_rare <- normalize(caporaso, method = "rarefy")
```

--------------------------------

### Plot Abundance Box Plots for Markers

Source: https://context7.com/yiluheihei/microbiomemarker/llms.txt

Creates side-by-side box plots of per-group abundance distribution for identified markers. Useful for visually verifying differential abundance. Requires a marker object and the grouping variable.

```r
data(enterotypes_arumugam)
mm <- run_limma_voom(
    enterotypes_arumugam,
    "Enterotype",
    contrast      = c("Enterotype 3", "Enterotype 2"),
    pvalue_cutoff = 0.01,
    p_adjust      = "none"
)

plot_abundance(mm, group = "Enterotype")
```

--------------------------------

### Print Post Hoc Test Results

Source: https://github.com/yiluheihei/microbiomemarker/blob/devel/tests/testthat/_snaps/multiple-groups-test.md

Prints the detailed results of a post hoc test, including comparisons, difference in means, p-values, and confidence intervals. Use this to inspect the statistical significance of pairwise comparisons between groups.

```r
print(res_test, digits = 5)
```

--------------------------------

### Display ANCOM Results Head

Source: https://github.com/yiluheihei/microbiomemarker/blob/devel/tests/testthat/_snaps/ancom.md

Prints the first few rows of the ANCOM results. Useful for a quick overview of the top markers and their associated statistics.

```r
print(head(curr_marker), digits = 5)
```

--------------------------------

### phyloseq2edgeR

Source: https://context7.com/yiluheihei/microbiomemarker/llms.txt

Converts a `phyloseq` object to an edgeR `DGEList` object, including sample metadata and taxonomy as gene annotations, enabling direct use of edgeR's full API.

```APIDOC
## phyloseq2edgeR()

### Description
Converts a `phyloseq` object to an edgeR `DGEList` object, including sample metadata and taxonomy as gene annotations, enabling direct use of edgeR's full API.

### Parameters
- **phyloseq_obj** (object) - A `phyloseq` object.

### Request Example
```r
data(caporaso)
dge <- phyloseq2edgeR(caporaso)
dge
```

### Response
- **DGEList object** - An edgeR `DGEList` object.
```

--------------------------------

### Plot Circular Phylogenetic Cladogram of Markers

Source: https://context7.com/yiluheihei/microbiomemarker/llms.txt

Renders a circular phylogenetic cladogram highlighting marker taxa. Node size encodes mean relative abundance, and clade labels annotate taxa at configurable ranks. Requires a marker table and specifies colors, whether to show only markers, and clade label level.

```r
data(kostic_crc)
kostic_small <- phyloseq::subset_taxa(kostic_crc, Phylum == "Firmicutes")

mm_lefse <- run_lefse(
    kostic_small,
    group           = "DIAGNOSIS",
    wilcoxon_cutoff = 0.01,
    kw_cutoff       = 0.01,
    lda_cutoff      = 4,
    multigrp_strat  = TRUE
)

# Two colors: one per enriched group (matched alphabetically)
plot_cladogram(
    mm_lefse,
    color             = c("darkgreen", "red"),
    only_marker       = FALSE,
    clade_label_level = 4,
    alpha             = 0.2
)
```

--------------------------------

### Visualize Single Significance Level Annotation

Source: https://github.com/yiluheihei/microbiomemarker/blob/devel/tests/testthat/_snaps/multiple-groups-test.md

Generates annotations for visualizing the significance levels of comparisons. This is useful for creating plots where significance is indicated by asterisks or 'NS.' (Not Significant).

```r
annotation_single
```

--------------------------------

### run_lefse()

Source: https://context7.com/yiluheihei/microbiomemarker/llms.txt

Identifies microbiome biomarkers using the LEfSe algorithm, which includes Kruskal–Wallis rank-sum test, pairwise Wilcoxon tests, and bootstrapped LDA to compute effect sizes. It returns features with their log LDA score and Kruskal–Wallis p-value.

```APIDOC
## run_lefse()

### Description
Identifies microbiome biomarkers using the LEfSe algorithm: Kruskal–Wallis rank-sum test across classes, pairwise Wilcoxon tests within subclasses, and bootstrapped LDA to compute effect sizes. Returns features with `lda` (log LDA score) and Kruskal–Wallis `pvalue`.

### Parameters
- **data**: A phyloseq object containing the microbiome data.
- **group**: The column name in the sample data to use for grouping.
- **taxa_rank**: The taxonomic rank to summarize to. Use "all" to summarize to the highest rank.
- **norm**: Normalization method to apply (e.g., "CPM", "TSS").
- **kw_cutoff**: Cutoff for the Kruskal–Wallis test p-value.
- **wilcoxon_cutoff**: Cutoff for the Wilcoxon test p-value.
- **lda_cutoff**: Cutoff for the LDA effect size.
- **multigrp_strat**: Boolean indicating whether to use multi-group stratification.

### Request Example
```r
data(kostic_crc)
kostic_small <- phyloseq::subset_taxa(kostic_crc, Phylum == "Firmicutes")

mm_lefse <- run_lefse(
    kostic_small,
    group            = "DIAGNOSIS",
    taxa_rank        = "all",
    norm             = "CPM",
    kw_cutoff        = 0.01,
    wilcoxon_cutoff  = 0.01,
    lda_cutoff       = 4,
    multigrp_strat   = TRUE
)
```

### Response
Returns a `microbiomeMarker-class` object containing the identified markers and their associated statistics.
```

--------------------------------

### plot_abundance

Source: https://context7.com/yiluheihei/microbiomemarker/llms.txt

Creates side-by-side box plots showing the per-group abundance distribution for each identified marker. Useful for visually verifying the direction and magnitude of differential abundance.

```APIDOC
## plot_abundance()

### Description
Creates side-by-side box plots showing the per-group abundance distribution for each identified marker. Useful for visually verifying the direction and magnitude of differential abundance.

### Parameters
- **marker_table** (object) - The output from a differential abundance analysis function.
- **group** (string) - The column name in sample metadata to group by.

### Request Example
```r
data(enterotypes_arumugam)
mm <- run_limma_voom(
    enterotypes_arumugam,
    "Enterotype",
    contrast      = c("Enterotype 3", "Enterotype 2"),
    pvalue_cutoff = 0.01,
    p_adjust      = "none"
)

plot_abundance(mm, group = "Enterotype")
```

### Response
- **ggplot2 object** - A box plot visualizing marker abundance across groups.
```

--------------------------------

### Run ANCOM-BC for Bias-Corrected Differential Abundance

Source: https://context7.com/yiluheihei/microbiomemarker/llms.txt

Applies ANCOM-BC to correct for unobserved sampling fractions and infer absolute abundance differences. Requires specifying group, taxa rank, p-value adjustment, and cutoffs for prevalence and p-value.

```r
data(enterotypes_arumugam)
ps2 <- phyloseq::subset_samples(
    enterotypes_arumugam,
    Enterotype %in% c("Enterotype 3", "Enterotype 2")
)

mm_ancombc <- run_ancombc(
    ps2,
    group         = "Enterotype",
    taxa_rank     = "all",
    p_adjust      = "holm",
    prv_cut       = 0.10,   # exclude taxa present in <10% samples
    struc_zero    = FALSE,
    pvalue_cutoff = 0.05
)
marker_table(mm_ancombc)
# feature  enrich_group  ef_W  pvalue  padj
```

--------------------------------

### Convert phyloseq to DESeqDataSet

Source: https://context7.com/yiluheihei/microbiomemarker/llms.txt

Utility function to convert a phyloseq object to a DESeqDataSet for use with DESeq2. Preserves sample metadata and taxonomy. Non-integer counts are rounded with a warning.

```r
data(caporaso)
dds <- phyloseq2DESeq2(caporaso, design = ~ SampleType)
dds
```

--------------------------------

### Print EdgeR Marker Table

Source: https://github.com/yiluheihei/microbiomemarker/blob/devel/tests/testthat/_snaps/edgeR.md

This code prints the marker table generated by the `marker_table` function in EdgeR. It is used to display the results of differential abundance analysis, showing identified markers and their taxonomic classifications.

```R
print(marker_table(mm_edger), digits = 5)
```

--------------------------------

### Welch's T-Test for Two Groups

Source: https://github.com/yiluheihei/microbiomemarker/blob/devel/tests/testthat/_snaps/two-group-test.md

This snippet shows the output of applying Welch's t-test for identifying microbiome markers between two groups. It indicates the normalization method, marker identity method, and the dimensions of the marker, OTU, sample, and taxonomy tables.

```R
mm_welch
    Output
      microbiomeMarker-class inherited from phyloseq-class
      normalization method:              [ TSS ]
      microbiome marker identity method: [ welch.test ]
      marker_table() Marker Table:       [ 3 microbiome markers with 5 variables ]
      otu_table()    OTU Table:          [ 244 taxa and  39 samples ]
      sample_data()  Sample Data:        [ 39 samples by  9 sample variables ]
      tax_table()    Taxonomy Table:     [ 244 taxa by 1 taxonomic ranks ]
```

--------------------------------

### phyloseq2DESeq2

Source: https://context7.com/yiluheihei/microbiomemarker/llms.txt

Utility function that converts a `phyloseq` object to a `DESeqDataSet` for direct use with DESeq2 functions. Non-integer counts are rounded with a warning; sample metadata and taxonomy are preserved.

```APIDOC
## phyloseq2DESeq2()

### Description
Utility function that converts a `phyloseq` object to a `DESeqDataSet` for direct use with DESeq2 functions. Non-integer counts are rounded with a warning; sample metadata and taxonomy are preserved.

### Parameters
- **phyloseq_obj** (object) - A `phyloseq` object.
- **design** (formula) - A formula specifying the experimental design for DESeq2.

### Request Example
```r
data(caporaso)
dds <- phyloseq2DESeq2(caporaso, design = ~ SampleType)
dds
```

### Response
- **DESeqDataSet object** - A `DESeqDataSet` object ready for use with DESeq2.
```

--------------------------------

### run_sl

Source: https://context7.com/yiluheihei/microbiomemarker/llms.txt

Identifies biomarkers via machine learning classification using repeated k-fold cross-validation for hyperparameter tuning. Markers are selected by variable importance score. Supports logistic regression (`"LR"`), random forest (`"RF"`), and support vector machine (`"SVM"`); only two-group comparisons are supported.

```APIDOC
## run_sl()

### Description
Identifies biomarkers via machine learning classification using repeated k-fold cross-validation for hyperparameter tuning. Markers are selected by variable importance score. Supports logistic regression (`"LR"`), random forest (`"RF"`), and support vector machine (`"SVM"`); only two-group comparisons are supported.

### Parameters
- **data** (object) - Input data, typically a phyloseq object.
- **group** (string) - The column name in sample metadata to group by.
- **taxa_rank** (string) - The taxonomic rank to perform analysis on (e.g., "Genus").
- **method** (string) - Machine learning method to use (`"LR"`, `"RF"`, `"SVM"`).
- **nfolds** (integer) - Number of folds for cross-validation.
- **nrepeats** (integer) - Number of repeats for cross-validation.
- **top_n** (integer) - Number of top markers to select based on importance.
- **norm** (string) - Normalization method to use (e.g., "TSS").

### Request Example
```r
data(enterotypes_arumugam)
ps_small <- phyloseq::subset_taxa(
    enterotypes_arumugam,
    Phylum %in% c("Firmicutes", "Bacteroidetes")
)

set.seed(2021)
mm_sl <- run_sl(
    ps_small,
    group      = "Gender",
    taxa_rank  = "Genus",
    method     = "RF",       # "LR", "RF", "SVM"
    nfolds     = 5,
    nrepeats   = 3,
    top_n      = 15,         # select top 15 by importance
    norm       = "TSS"
)
marker_table(mm_sl)
```

### Response
- **marker_table** (object) - A table containing identified biomarkers, including feature, enrich_group, and ef_imp.
```

--------------------------------

### T-Test for Two Groups

Source: https://github.com/yiluheihei/microbiomemarker/blob/devel/tests/testthat/_snaps/two-group-test.md

This snippet displays the output of a standard t-test for identifying microbiome markers between two groups. It details the normalization method, marker identity method, and the structure of the resulting marker, OTU, sample, and taxonomy tables.

```R
mm_t
    Output
      microbiomeMarker-class inherited from phyloseq-class
      normalization method:              [ TSS ]
      microbiome marker identity method: [ t.test ]
      marker_table() Marker Table:       [ 2 microbiome markers with 5 variables ]
      otu_table()    OTU Table:          [ 244 taxa and  39 samples ]
      sample_data()  Sample Data:        [ 39 samples by  9 sample variables ]
      tax_table()    Taxonomy Table:     [ 244 taxa by 1 taxonomic ranks ]
```

--------------------------------

### plot_cladogram

Source: https://context7.com/yiluheihei/microbiomemarker/llms.txt

Renders a circular phylogenetic cladogram (powered by ggtree) where marker taxa are highlighted by enriched group, node size encodes mean relative abundance, and clade labels annotate taxa at configurable rank levels.

```APIDOC
## plot_cladogram()

### Description
Renders a circular phylogenetic cladogram (powered by ggtree) where marker taxa are highlighted by enriched group, node size encodes mean relative abundance, and clade labels annotate taxa at configurable rank levels.

### Parameters
- **marker_table** (object) - The output from a differential abundance analysis function (e.g., `run_lefse`).
- **color** (vector) - A vector of colors to use for highlighting enriched groups.
- **only_marker** (logical) - If TRUE, only displays marker taxa.
- **clade_label_level** (integer) - The taxonomic rank level for clade labels.
- **alpha** (numeric) - Transparency level for the plot.

### Request Example
```r
data(kostic_crc)
kostic_small <- phyloseq::subset_taxa(kostic_crc, Phylum == "Firmicutes")

mm_lefse <- run_lefse(
    kostic_small,
    group           = "DIAGNOSIS",
    wilcoxon_cutoff = 0.01,
    kw_cutoff       = 0.01,
    lda_cutoff      = 4,
    multigrp_strat  = TRUE
)

# Two colors: one per enriched group (matched alphabetically)
plot_cladogram(
    mm_lefse,
    color             = c("darkgreen", "red"),
    only_marker       = FALSE,
    clade_label_level = 4,
    alpha             = 0.2
)
```

### Response
- **ggplot2 object** - A phylogenetic cladogram plot.
```