q2-composition

This QIIME 2 plugin supports methods for compositional data analysis.

version: 2025.10.0.dev0

website: https://github.com/qiime2/q2-composition

user support:

Please post to the QIIME 2 forum for help with this plugin: https://forum.qiime2.org

Actions¶

Artifact Classes¶

Formats¶

composition add-pseudocount¶

Increment all counts in table by pseudocount.

Inputs¶

table: FeatureTable[Frequency]

The feature table to which pseudocounts should be added.[required]

Parameters¶

pseudocount: Int

The value to add to all counts in the feature table.[default: 1]

Outputs¶

composition_table: FeatureTable[Composition]

The resulting feature table.[required]

composition ancombc¶

Apply Analysis of Compositions of Microbiomes with Bias Correction (ANCOM-BC) to identify features that are differentially abundant across groups.

Citations¶

Lin & Peddada, 2020

Inputs¶

table: FeatureTable[Frequency]

The feature table to be used for ANCOM-BC computation.[required]

Parameters¶

metadata: Metadata

The sample metadata.[required]

formula: Str

How the microbial absolute abundances for each taxon depend on the variables within the metadata.[required]

p_adj_method: Str % Choices('holm', 'hochberg', 'hommel', 'bonferroni', 'BH', 'BY', 'fdr', 'none')

Method to adjust p-values.[default: 'holm']

prv_cut: Float

A numerical fraction between 0-1. Taxa with prevalences less than this value will be excluded from the analysis.[default: 0.1]

lib_cut: Int

A numerical threshold for filtering samples based on library sizes. Samples with library sizes less than this value will be excluded from the analysis.[default: 0]

reference_levels: List[Str]

Define the reference level(s) to be used for categorical columns found in the formula. These categorical factors are dummy coded relative to the reference(s) provided. The syntax is as follows: "column_name::column_value"[optional]

tol: Float

The iteration convergence tolerance for the E-M algorithm.[default: 1e-05]

max_iter: Int

The maximum number of iterations for the E-M algorithm.[default: 100]

conserve: Bool

Whether to use a conservative variance estimator for the test statistic. It is recommended if the sample size is small and/or the number of differentially abundant taxa is believed to be large.[default: False]

alpha: Float

Level of significance.[default: 0.05]

Outputs¶

differentials: FeatureData[DifferentialAbundance]

The calculated per-feature differentials.[required]

Examples¶

ancombc_single_formula¶

wget -O 'table.qza' \
  'https://amplicon-docs.qiime2.org/en/latest/data/examples/composition/ancombc/1/table.qza'

wget -O 'metadata.tsv' \
  'https://amplicon-docs.qiime2.org/en/latest/data/examples/composition/ancombc/1/metadata.tsv'

qiime composition ancombc \
  --i-table table.qza \
  --m-metadata-file metadata.tsv \
  --p-formula bodysite \
  --o-differentials dataloaf.qza

from qiime2 import Artifact
from qiime2 import Metadata
from urllib import request
import qiime2.plugins.composition.actions as composition_actions

url = 'https://amplicon-docs.qiime2.org/en/latest/data/examples/composition/ancombc/1/table.qza'
fn = 'table.qza'
request.urlretrieve(url, fn)
table = Artifact.load(fn)

url = 'https://amplicon-docs.qiime2.org/en/latest/data/examples/composition/ancombc/1/metadata.tsv'
fn = 'metadata.tsv'
request.urlretrieve(url, fn)
metadata_md = Metadata.load(fn)

dataloaf, = composition_actions.ancombc(
    table=table,
    metadata=metadata_md,
    formula='bodysite',
)

library(reticulate)

Artifact <- import("qiime2")$Artifact
Metadata <- import("qiime2")$Metadata
composition_actions <- import("qiime2.plugins.composition.actions")
request <- import("urllib")$request

url <- 'https://amplicon-docs.qiime2.org/en/latest/data/examples/composition/ancombc/1/table.qza'
fn <- 'table.qza'
request$urlretrieve(url, fn)
table <- Artifact$load(fn)

url <- 'https://amplicon-docs.qiime2.org/en/latest/data/examples/composition/ancombc/1/metadata.tsv'
fn <- 'metadata.tsv'
request$urlretrieve(url, fn)
metadata_md <- Metadata$load(fn)

action_results <- composition_actions$ancombc(
    table=table,
    metadata=metadata_md,
    formula='bodysite',
)
dataloaf <- action_results$differentials

from q2_composition._examples import ancombc_single_formula

ancombc_single_formula(use)

ancombc_multi_formula_with_reference_levels¶

wget -O 'table.qza' \
  'https://amplicon-docs.qiime2.org/en/latest/data/examples/composition/ancombc/2/table.qza'

wget -O 'metadata.tsv' \
  'https://amplicon-docs.qiime2.org/en/latest/data/examples/composition/ancombc/2/metadata.tsv'

qiime composition ancombc \
  --i-table table.qza \
  --m-metadata-file metadata.tsv \
  --p-formula 'bodysite + animal' \
  --p-reference-levels bodysite::tongue animal::dog \
  --o-differentials dataloaf.qza

from qiime2 import Artifact
from qiime2 import Metadata
from urllib import request
import qiime2.plugins.composition.actions as composition_actions

url = 'https://amplicon-docs.qiime2.org/en/latest/data/examples/composition/ancombc/2/table.qza'
fn = 'table.qza'
request.urlretrieve(url, fn)
table = Artifact.load(fn)

url = 'https://amplicon-docs.qiime2.org/en/latest/data/examples/composition/ancombc/2/metadata.tsv'
fn = 'metadata.tsv'
request.urlretrieve(url, fn)
metadata_md = Metadata.load(fn)

dataloaf, = composition_actions.ancombc(
    table=table,
    metadata=metadata_md,
    formula='bodysite + animal',
    reference_levels=['bodysite::tongue', 'animal::dog'],
)

library(reticulate)

Artifact <- import("qiime2")$Artifact
Metadata <- import("qiime2")$Metadata
composition_actions <- import("qiime2.plugins.composition.actions")
request <- import("urllib")$request

url <- 'https://amplicon-docs.qiime2.org/en/latest/data/examples/composition/ancombc/2/table.qza'
fn <- 'table.qza'
request$urlretrieve(url, fn)
table <- Artifact$load(fn)

url <- 'https://amplicon-docs.qiime2.org/en/latest/data/examples/composition/ancombc/2/metadata.tsv'
fn <- 'metadata.tsv'
request$urlretrieve(url, fn)
metadata_md <- Metadata$load(fn)

action_results <- composition_actions$ancombc(
    table=table,
    metadata=metadata_md,
    formula='bodysite + animal',
    reference_levels=list('bodysite::tongue', 'animal::dog'),
)
dataloaf <- action_results$differentials

from q2_composition._examples import ancombc_multi_formula_with_reference_levels

ancombc_multi_formula_with_reference_levels(use)

composition ancombc2¶

Calls the ancombc2 function of the ANCOMBC software package. See the ANCOM-BC2 publication and source code for details.

Citations¶

Lin & Peddada, 2024

Inputs¶

table: FeatureTable[Frequency]

The feature table to be used for ANCOM-BC2 computation.[required]

Parameters¶

metadata: Metadata

The per-sample metadata.[required]

fixed_effects_formula: Str

A formula that expresses how the feature absolute abundances in the feature table depend on the fixed effects of variables (columns) in the metadata. Do not include the dependent variable. Reference the formula function in the stats R package for a specification of valid formulae.[required]

random_effects_formula: Str

A formula that expresses how the feature absolute abundances in the feature table depend on the random effects of variables (columns) in the metadata. Do not include the dependent variable. For example, to specify MyVariable as a random intercept use the syntax (1 | MyVariable). Reference the lmerTest R package for a specification of valid formulae.[optional]

reference_levels: List[Str]

Specify reference levels for one or more categorical metadata variables (columns). The method of specification is "column_name::column_value". E.g. "sex::female" sets the "female" category of the "sex" variable to be the reference level. Separate multiple specifications by spaces.[optional]

p_adjust_method: Str

The method used to adjust p-values. Choose from "holm", "hochberg", "hommel", "bonferroni", "BH", "BY", "fdr", "none". See the p.adjust method in the stats R package for explanations of each option.[default: 'holm']

prevalence_cutoff: Float % Range(0.0, 1.0, inclusive_end=True)

Features with prevalences less than this threshold will be excluded from the analysis.[default: 0.1]

group: Str

The name of the group variable in the metadata. The group variable must be categorical and is required to detect structural zeros.[optional]

structural_zeros: Bool

Whether to detect structurual zeros based on the group variable. Refer to the ANCOM-BC2 paper for an expalanation of the use of structural zeros.[default: False]

asymptotic_cutoff: Bool

Whether to classify a taxon as a structural zero using its asymptotic lower bound. Generally, it is recommended to set this parameter when the sample size per group is relatively large (n > 30). When this parameter is not set, a feature is classified as a structural zero in a group if its frequency is zero in that group. See the ANCOM-BC2 publication for details.[default: False]

alpha: Float % Range(0.0, 1.0, inclusive_start=False, inclusive_end=True)

The significance level.[default: 0.05]

num_processes: Threads

The number of processes to create that can be run in parallel.[default: 1]

Outputs¶

ancombc2_output: FeatureData[ANCOMBC2Output]

The estimated log fold changes and their standard errors for the variables included in the mixed effects model. Also includes the structural zero designations if the structural_zeros parameter is passed.[required]

Examples¶

single-variable¶

wget -O 'table.qza' \
  'https://amplicon-docs.qiime2.org/en/latest/data/examples/composition/ancombc2/1/table.qza'

wget -O 'metadata.tsv' \
  'https://amplicon-docs.qiime2.org/en/latest/data/examples/composition/ancombc2/1/metadata.tsv'

qiime composition ancombc2 \
  --i-table table.qza \
  --m-metadata-file metadata.tsv \
  --p-fixed-effects-formula bodysite \
  --o-ancombc2-output abc2-output.qza

from qiime2 import Artifact
from qiime2 import Metadata
from urllib import request
import qiime2.plugins.composition.actions as composition_actions

url = 'https://amplicon-docs.qiime2.org/en/latest/data/examples/composition/ancombc2/1/table.qza'
fn = 'table.qza'
request.urlretrieve(url, fn)
table = Artifact.load(fn)

url = 'https://amplicon-docs.qiime2.org/en/latest/data/examples/composition/ancombc2/1/metadata.tsv'
fn = 'metadata.tsv'
request.urlretrieve(url, fn)
metadata_md = Metadata.load(fn)

abc2_output, = composition_actions.ancombc2(
    table=table,
    metadata=metadata_md,
    fixed_effects_formula='bodysite',
)

library(reticulate)

Artifact <- import("qiime2")$Artifact
Metadata <- import("qiime2")$Metadata
composition_actions <- import("qiime2.plugins.composition.actions")
request <- import("urllib")$request

url <- 'https://amplicon-docs.qiime2.org/en/latest/data/examples/composition/ancombc2/1/table.qza'
fn <- 'table.qza'
request$urlretrieve(url, fn)
table <- Artifact$load(fn)

url <- 'https://amplicon-docs.qiime2.org/en/latest/data/examples/composition/ancombc2/1/metadata.tsv'
fn <- 'metadata.tsv'
request$urlretrieve(url, fn)
metadata_md <- Metadata$load(fn)

action_results <- composition_actions$ancombc2(
    table=table,
    metadata=metadata_md,
    fixed_effects_formula='bodysite',
)
abc2_output <- action_results$ancombc2_output

from q2_composition._examples import ancombc2_single_formula

ancombc2_single_formula(use)

multi-variable-reference¶

wget -O 'table.qza' \
  'https://amplicon-docs.qiime2.org/en/latest/data/examples/composition/ancombc2/2/table.qza'

wget -O 'metadata.tsv' \
  'https://amplicon-docs.qiime2.org/en/latest/data/examples/composition/ancombc2/2/metadata.tsv'

qiime composition ancombc2 \
  --i-table table.qza \
  --m-metadata-file metadata.tsv \
  --p-fixed-effects-formula 'bodysite + animal' \
  --p-reference-levels bodysite::tongue animal::dog \
  --o-ancombc2-output abc2-output.qza

from qiime2 import Artifact
from qiime2 import Metadata
from urllib import request
import qiime2.plugins.composition.actions as composition_actions

url = 'https://amplicon-docs.qiime2.org/en/latest/data/examples/composition/ancombc2/2/table.qza'
fn = 'table.qza'
request.urlretrieve(url, fn)
table = Artifact.load(fn)

url = 'https://amplicon-docs.qiime2.org/en/latest/data/examples/composition/ancombc2/2/metadata.tsv'
fn = 'metadata.tsv'
request.urlretrieve(url, fn)
metadata_md = Metadata.load(fn)

abc2_output, = composition_actions.ancombc2(
    table=table,
    metadata=metadata_md,
    fixed_effects_formula='bodysite + animal',
    reference_levels=['bodysite::tongue', 'animal::dog'],
)

library(reticulate)

Artifact <- import("qiime2")$Artifact
Metadata <- import("qiime2")$Metadata
composition_actions <- import("qiime2.plugins.composition.actions")
request <- import("urllib")$request

url <- 'https://amplicon-docs.qiime2.org/en/latest/data/examples/composition/ancombc2/2/table.qza'
fn <- 'table.qza'
request$urlretrieve(url, fn)
table <- Artifact$load(fn)

url <- 'https://amplicon-docs.qiime2.org/en/latest/data/examples/composition/ancombc2/2/metadata.tsv'
fn <- 'metadata.tsv'
request$urlretrieve(url, fn)
metadata_md <- Metadata$load(fn)

action_results <- composition_actions$ancombc2(
    table=table,
    metadata=metadata_md,
    fixed_effects_formula='bodysite + animal',
    reference_levels=list('bodysite::tongue', 'animal::dog'),
)
abc2_output <- action_results$ancombc2_output

from q2_composition._examples import ancombc2_multi_formula_with_reference_levels

ancombc2_multi_formula_with_reference_levels(use)

composition ancom¶

Apply Analysis of Composition of Microbiomes (ANCOM) to identify features that are differentially abundant across groups.

Citations¶

Mandal et al., 2015

Inputs¶

table: FeatureTable[Composition]

The feature table to be used for ANCOM computation.[required]

Parameters¶

metadata: MetadataColumn[Categorical]

The categorical sample metadata column to test for differential abundance across.[required]

transform_function: Str % Choices('sqrt', 'log', 'clr')

The method applied to transform feature values before generating volcano plots.[default: 'clr']

difference_function: Str % Choices('mean_difference', 'f_statistic')

The method applied to visualize fold difference in feature abundances across groups for volcano plots.[optional]

filter_missing: Bool

If True, samples with missing metadata values will be filtered from the table prior to analysis. If False, an error will be raised if there are any missing metadata values.[default: False]

Outputs¶

visualization: Visualization

<no description>[required]

composition ancombc2-visualizer¶

Displays ANCOMBC2 Log-Fold Change values in a barplot and allows filtering based on p-value and standard error. If a taxonomy is provided, features can be filtered by taxonomy using an interactive tree.

Inputs¶

data: FeatureData[ANCOMBC2Output]

The ANCOMBC2 output to visualize.[required]

taxonomy: FeatureData[Taxonomy]

The taxonomy associated with the features present in the ANCOMBC2 data.[optional]

Outputs¶

visualization: Visualization

<no description>[required]

composition tabulate¶

Generate tabular view of ANCOM-BC or ANCOM-BC2 output, which includes per-page views for the log-fold change (lfc), standard error (se), P values, Q values, and W scores.

Inputs¶

data: FeatureData[DifferentialAbundance | ANCOMBC2Output]

The ANCOM-BC or ANCOM-BC2 output to be tabulated.[required]

Outputs¶

visualization: Visualization

<no description>[required]

composition da-barplot¶

Generate bar plot views of ANCOM-BC output. One plot will be present per column in the ANCOM-BC output. The significance_threshold, effect_size_threshold and feature_ids filter results are intersected, such that only features that remain after all three filters have been applied will be present in the output.

Inputs¶

data: FeatureData[DifferentialAbundance]

The ANCOM-BC output to be plotted.[required]

Parameters¶

effect_size_label: Str

Label for effect sizes in data.[default: 'lfc']

feature_id_label: Str

Label for feature ids in data.[default: 'id']

error_label: Str

Label for effect size errors in data.[default: 'se']

significance_label: Str

Label for statistical significance level in data.[default: 'q_val']

significance_threshold: Float % Range(0.0, 1.0, inclusive_end=True)

Exclude features with statistical significance level greater (i.e., less significant) than this threshold.[default: 1.0]

effect_size_threshold: Float % Range(0.0, None)

Exclude features with an absolute value of effect size less than this threshold.[default: 0.0]

feature_ids: Metadata

Exclude features if their ids are not included in this index.[optional]

level_delimiter: Str

If feature ids encode hierarchical information, split the levels when generating feature labels in the visualization using this delimiter.[optional]

label_limit: Int

Set the maximum length that will be viewable for axis labels. You can set this parameter if your axis labels are being cut off.[optional]

Outputs¶

visualization: Visualization

<no description>[required]