q2-taxa

This QIIME 2 plugin provides functionality for working with and visualizing taxonomic annotations of features.

version: 2026.1.0.dev0

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

user support:

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

Actions¶

taxa collapse¶

Collapse groups of features that have the same taxonomic assignment through the specified level. The frequencies of all features will be summed when they are collapsed.

Inputs¶

table: FeatureTable[Frequency]

Feature table to be collapsed.[required]

taxonomy: FeatureData[Taxonomy]

Taxonomic annotations for features in the provided feature table. All features in the feature table must have a corresponding taxonomic annotation. Taxonomic annotations that are not present in the feature table will be ignored.[required]

Parameters¶

level: Int

The taxonomic level at which the features should be collapsed. All ouput features will have exactly this many levels of taxonomic annotation.[required]

Outputs¶

collapsed_table: FeatureTable[Frequency]

The resulting feature table, where all features are now taxonomic annotations with the user-specified number of levels.[required]

Examples¶

collapse¶

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

wget -O 'taxonomy.qza' \
  'https://amplicon-docs.qiime2.org/en/latest/data/examples/taxa/collapse/1/taxonomy.qza'

qiime taxa collapse \
  --i-table table.qza \
  --i-taxonomy taxonomy.qza \
  --p-level 6 \
  --o-collapsed-table collapsed-table-l6.qza

from qiime2 import Artifact
from urllib import request
import qiime2.plugins.taxa.actions as taxa_actions

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

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

collapsed_table_l6, = taxa_actions.collapse(
    table=table,
    taxonomy=taxonomy,
    level=6,
)

library(reticulate)

Artifact <- import("qiime2")$Artifact
request <- import("urllib")$request
taxa_actions <- import("qiime2.plugins.taxa.actions")

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

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

action_results <- taxa_actions$collapse(
    table=table,
    taxonomy=taxonomy,
    level=6L,
)
collapsed_table_l6 <- action_results$collapsed_table

from q2_taxa._examples import collapse_example

collapse_example(use)

taxa filter-table¶

This method filters features from a table based on their taxonomic annotations. Features can be retained in the resulting table by specifying one or more include search terms, and can be filtered out of the resulting table by specifying one or more exclude search terms. If both include and exclude are provided, the inclusion critera will be applied before the exclusion critera. Either include or exclude terms (or both) must be provided. Any samples that have a total frequency of zero after filtering will be removed from the resulting table.

Inputs¶

table: FeatureTable[Frequency¹ | PresenceAbsence²]

Feature table to be filtered.[required]

taxonomy: FeatureData[Taxonomy]

Taxonomic annotations for features in the provided feature table. All features in the feature table must have a corresponding taxonomic annotation. Taxonomic annotations for features that are not present in the feature table will be ignored.[required]

Parameters¶

include: Str

One or more search terms that indicate which taxa should be included in the resulting table. If providing more than one term, terms should be delimited by the query-delimiter character. By default, all taxa will be included.[optional]

exclude: Str

One or more search terms that indicate which taxa should be excluded from the resulting table. If providing more than one term, terms should be delimited by the query-delimiter character. By default, no taxa will be excluded.[optional]

query_delimiter: Str

The string used to delimit multiple search terms provided to include or exclude. This parameter should only need to be modified if the default delimiter (a comma) is used in the provided taxonomic annotations.[default: ',']

mode: Str % Choices('exact', 'contains')

Mode for determining if a search term matches a taxonomic annotation. "contains" requires that the annotation has the term as a substring; "exact" requires that the annotation is a perfect match to a search term.[default: 'contains']

Outputs¶

filtered_table: FeatureTable[Frequency¹ | PresenceAbsence²]

The taxonomy-filtered feature table.[required]

taxa filter-seqs¶

This method filters sequences based on their taxonomic annotations. Features can be retained in the result by specifying one or more include search terms, and can be filtered out of the result by specifying one or more exclude search terms. If both include and exclude are provided, the inclusion critera will be applied before the exclusion critera. Either include or exclude terms (or both) must be provided.

Inputs¶

sequences: FeatureData[Sequence]

Feature sequences to be filtered.[required]

taxonomy: FeatureData[Taxonomy]

Taxonomic annotations for features in the provided feature sequences. All features in the feature sequences must have a corresponding taxonomic annotation. Taxonomic annotations for features that are not present in the feature sequences will be ignored.[required]

Parameters¶

include: Str

One or more search terms that indicate which taxa should be included in the resulting sequences. If providing more than one term, terms should be delimited by the query-delimiter character. By default, all taxa will be included.[optional]

exclude: Str

One or more search terms that indicate which taxa should be excluded from the resulting sequences. If providing more than one term, terms should be delimited by the query-delimiter character. By default, no taxa will be excluded.[optional]

query_delimiter: Str

The string used to delimit multiple search terms provided to include or exclude. This parameter should only need to be modified if the default delimiter (a comma) is used in the provided taxonomic annotations.[default: ',']

mode: Str % Choices('exact', 'contains')

Mode for determining if a search term matches a taxonomic annotation. "contains" requires that the annotation has the term as a substring; "exact" requires that the annotation is a perfect match to a search term.[default: 'contains']

Outputs¶

filtered_sequences: FeatureData[Sequence]

The taxonomy-filtered feature sequences.[required]

taxa barplot¶

This visualizer produces an interactive barplot visualization of taxonomies. Interactive features include multi-level sorting, plot recoloring, sample relabeling, and SVG figure export. This visualizer is planned to be replaced with the current barplot2 visualizer in this plugin. We are interested in user feedback on barplot2, so please consider trying it out and letting us know how it works for you.

Inputs¶

table: FeatureTable[Frequency | PresenceAbsence]

Feature table to visualize at various taxonomic levels.[required]

taxonomy: FeatureData[Taxonomy]

Taxonomic annotations for features in the provided feature table. All features in the feature table must have a corresponding taxonomic annotation. Taxonomic annotations that are not present in the feature table will be ignored. If no taxonomy is provided, the feature IDs will be used as labels.[optional]

Parameters¶

metadata: Metadata

The sample metadata.[optional]

level_delimiter: Str

Attempt to parse hierarchical taxonomic information from feature IDs by separating levels with this character. This parameter is ignored if a taxonomy is provided as input.[optional]

Outputs¶

visualization: Visualization

<no description>[required]

Examples¶

barplot¶

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

wget -O 'taxonomy.qza' \
  'https://amplicon-docs.qiime2.org/en/latest/data/examples/taxa/barplot/1/taxonomy.qza'

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

qiime taxa barplot \
  --i-table table.qza \
  --i-taxonomy taxonomy.qza \
  --m-metadata-file sample-metadata.tsv \
  --o-visualization taxa-bar-plots.qzv

from qiime2 import Artifact
from qiime2 import Metadata
from urllib import request
import qiime2.plugins.taxa.actions as taxa_actions

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

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

url = 'https://amplicon-docs.qiime2.org/en/latest/data/examples/taxa/barplot/1/sample-metadata.tsv'
fn = 'sample-metadata.tsv'
request.urlretrieve(url, fn)
sample_metadata_md = Metadata.load(fn)

taxa_bar_plots_viz, = taxa_actions.barplot(
    table=table,
    taxonomy=taxonomy,
    metadata=sample_metadata_md,
)

library(reticulate)

Artifact <- import("qiime2")$Artifact
Metadata <- import("qiime2")$Metadata
request <- import("urllib")$request
taxa_actions <- import("qiime2.plugins.taxa.actions")

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

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

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

action_results <- taxa_actions$barplot(
    table=table,
    taxonomy=taxonomy,
    metadata=sample_metadata_md,
)
taxa_bar_plots_viz <- action_results$visualization

from q2_taxa._examples import barplot_example

barplot_example(use)

taxa barplot2¶

This is an early release of a replacement for the barplot visualizer in this plugin. As of 2025.10, this should be considered experimental, and we are very interested in community feedback on this new visualizer. This command will eventually be removed when this visualizer replaces the barplot visualizer.

Inputs¶

table: FeatureTable[Frequency | PresenceAbsence | RelativeFrequency]

Feature table to visualize at various taxonomic levels.[required]

taxonomy: FeatureData[Taxonomy]

Taxonomic annotations for features in the provided feature table. All features in the feature table must have a corresponding taxonomic annotation. Taxonomic annotations that are not present in the feature table will be ignored. If no taxonomy is provided, the feature IDs will be used as labels.[optional]

Parameters¶

metadata: Metadata

The sample metadata.[optional]

level_delimiter: Str

Attempt to parse hierarchical taxonomic information from feature IDs by separating levels with this character. This parameter is ignored if a taxonomy is provided as input.[optional]

Outputs¶

visualization: Visualization

<no description>[required]

Examples¶

barplot¶

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

wget -O 'taxonomy.qza' \
  'https://amplicon-docs.qiime2.org/en/latest/data/examples/taxa/barplot2/1/taxonomy.qza'

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

qiime taxa barplot2 \
  --i-table table.qza \
  --i-taxonomy taxonomy.qza \
  --m-metadata-file sample-metadata.tsv \
  --o-visualization taxa-bar-plots.qzv

from qiime2 import Artifact
from qiime2 import Metadata
from urllib import request
import qiime2.plugins.taxa.actions as taxa_actions

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

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

url = 'https://amplicon-docs.qiime2.org/en/latest/data/examples/taxa/barplot2/1/sample-metadata.tsv'
fn = 'sample-metadata.tsv'
request.urlretrieve(url, fn)
sample_metadata_md = Metadata.load(fn)

taxa_bar_plots_viz, = taxa_actions.barplot2(
    table=table,
    taxonomy=taxonomy,
    metadata=sample_metadata_md,
)

library(reticulate)

Artifact <- import("qiime2")$Artifact
Metadata <- import("qiime2")$Metadata
request <- import("urllib")$request
taxa_actions <- import("qiime2.plugins.taxa.actions")

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

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

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

action_results <- taxa_actions$barplot2(
    table=table,
    taxonomy=taxonomy,
    metadata=sample_metadata_md,
)
taxa_bar_plots_viz <- action_results$visualization

from q2_taxa._examples import barplot2_example

barplot2_example(use)