q2-demux

This QIIME 2 plugin supports demultiplexing of single-end and paired-end sequence reads and visualization of sequence quality information.

version: 2025.10.0.dev0

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

user support:

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

Actions¶

demux emp-single¶

Demultiplex sequence data (i.e., map barcode reads to sample ids) for data generated with the Earth Microbiome Project (EMP) amplicon sequencing protocol. Details about this protocol can be found at http://www.earthmicrobiome.org/protocols-and-standards/

Citations¶

Hamday et al., 2008; Hamday & Knight, 2009

Inputs¶

seqs: RawSequences | EMPSingleEndSequences | EMPPairedEndSequences

The single-end sequences to be demultiplexed.[required]

Parameters¶

barcodes: MetadataColumn[Categorical]

The sample metadata column containing the per-sample barcodes.[required]

golay_error_correction: Bool

Perform 12nt Golay error correction on the barcode reads.[default: True]

rev_comp_barcodes: Bool

If provided, the barcode sequence reads will be reverse complemented prior to demultiplexing.[default: False]

rev_comp_mapping_barcodes: Bool

If provided, the barcode sequences in the sample metadata will be reverse complemented prior to demultiplexing.[default: False]

ignore_description_mismatch: Bool

If enabled, ignore mismatches in sequence record description fields.[default: False]

Outputs¶

per_sample_sequences: SampleData[SequencesWithQuality]

The resulting demultiplexed sequences.[required]

error_correction_details: ErrorCorrectionDetails

Detail about the barcode error corrections.[required]

Examples¶

demux¶

wget -O 'sequences.qza' \
  'https://amplicon-docs.qiime2.org/en/latest/data/examples/demux/emp-single/1/sequences.qza'

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

qiime demux emp-single \
  --i-seqs sequences.qza \
  --m-barcodes-file sample-metadata.tsv \
  --m-barcodes-column barcode-sequence \
  --o-per-sample-sequences demux.qza \
  --o-error-correction-details demux-details.qza

from qiime2 import Artifact
from qiime2 import Metadata
from urllib import request
import qiime2.plugins.demux.actions as demux_actions

url = 'https://amplicon-docs.qiime2.org/en/latest/data/examples/demux/emp-single/1/sequences.qza'
fn = 'sequences.qza'
request.urlretrieve(url, fn)
sequences = Artifact.load(fn)

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

metadata_column_mdc = sample_metadata_md.get_column('barcode-sequence')
demux, demux_details = demux_actions.emp_single(
    seqs=sequences,
    barcodes=metadata_column_mdc,
)

library(reticulate)

Artifact <- import("qiime2")$Artifact
Metadata <- import("qiime2")$Metadata
demux_actions <- import("qiime2.plugins.demux.actions")
request <- import("urllib")$request

url <- 'https://amplicon-docs.qiime2.org/en/latest/data/examples/demux/emp-single/1/sequences.qza'
fn <- 'sequences.qza'
request$urlretrieve(url, fn)
sequences <- Artifact$load(fn)

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

metadata_column_mdc <- sample_metadata_md$get_column('barcode-sequence')
action_results <- demux_actions$emp_single(
    seqs=sequences,
    barcodes=metadata_column_mdc,
)
demux <- action_results$per_sample_sequences
demux_details <- action_results$error_correction_details

from q2_demux._examples import emp_single

emp_single(use)

demux emp-paired¶

Demultiplex paired-end sequence data (i.e., map barcode reads to sample ids) for data generated with the Earth Microbiome Project (EMP) amplicon sequencing protocol. Details about this protocol can be found at http://www.earthmicrobiome.org/protocols-and-standards/

Citations¶

Hamday et al., 2008; Hamday & Knight, 2009

Inputs¶

seqs: EMPPairedEndSequences

The paired-end sequences to be demultiplexed.[required]

Parameters¶

barcodes: MetadataColumn[Categorical]

The sample metadata column containing the per-sample barcodes.[required]

golay_error_correction: Bool

Perform 12nt Golay error correction on the barcode reads.[default: True]

rev_comp_barcodes: Bool

If provided, the barcode sequence reads will be reverse complemented prior to demultiplexing.[default: False]

rev_comp_mapping_barcodes: Bool

If provided, the barcode sequences in the sample metadata will be reverse complemented prior to demultiplexing.[default: False]

ignore_description_mismatch: Bool

If enabled, ignore mismatches in sequence record description fields.[default: False]

Outputs¶

per_sample_sequences: SampleData[PairedEndSequencesWithQuality]

The resulting demultiplexed sequences.[required]

error_correction_details: ErrorCorrectionDetails

Detail about the barcode error corrections.[required]

demux partition-samples-single¶

Partition demultiplexed single end sequences into individual samples or the number of partitions specified.

Inputs¶

demux: SampleData[SequencesWithQuality¹ | JoinedSequencesWithQuality²]

The demultiplexed sequences to partition.[required]

Parameters¶

num_partitions: Int % Range(1, None)

The number of partitions to split the demultiplexed sequences into. Defaults to partitioning into individual samples.[optional]

Outputs¶

partitioned_demux: Collection[SampleData[SequencesWithQuality¹ | JoinedSequencesWithQuality²]]

The partitioned demultiplexed sequences.[required]

demux partition-samples-paired¶

Partition demultiplexed paired end sequences into individual samples or the number of partitions specified.

Inputs¶

demux: SampleData[PairedEndSequencesWithQuality]

The demultiplexed sequences to partition.[required]

Parameters¶

num_partitions: Int % Range(1, None)

The number of partitions to split the demultiplexed sequences into. Defaults to partitioning into individual samples.[optional]

Outputs¶

partitioned_demux: Collection[SampleData[PairedEndSequencesWithQuality]]

The partitioned demultiplexed sequences.[required]

demux tabulate-read-counts¶

Generate a per-sample count of sequence reads.

Inputs¶

sequences: List[SampleData[SequencesWithQuality | PairedEndSequencesWithQuality | JoinedSequencesWithQuality]]

One or more collections of demultiplexed sequences.[required]

Outputs¶

counts: ImmutableMetadata

<no description>[required]

demux subsample-single¶

Generate a random subsample of single-end sequences containing approximately the fraction of input sequences specified by the fraction parameter. The number of output samples will always be equal to the number of input samples, even if some of those samples contain no sequences after subsampling.

Inputs¶

sequences: SampleData[SequencesWithQuality | PairedEndSequencesWithQuality]

The demultiplexed sequences to be subsampled.[required]

Parameters¶

fraction: Float % Range(0, 1, inclusive_start=False)

The fraction of sequences to retain in subsample.[required]

drop_empty: Bool

Whether to drop empty samples.[default: False]

Outputs¶

subsampled_sequences: SampleData[SequencesWithQuality]

The subsampled sequences.[required]

demux subsample-paired¶

Generate a random subsample of paired-end sequences containing approximately the fraction of input sequences specified by the fraction parameter. The number of output samples will always be equal to the number of input samples, even if some of those samples contain no sequences after subsampling.

Inputs¶

sequences: SampleData[PairedEndSequencesWithQuality]

The demultiplexed sequences to be subsampled.[required]

Parameters¶

fraction: Float % Range(0, 1, inclusive_start=False)

The fraction of sequences to retain in subsample.[required]

drop_empty: Bool

Whether to drop empty samples.[default: False]

Outputs¶

subsampled_sequences: SampleData[PairedEndSequencesWithQuality]

The subsampled sequences.[required]

demux filter-samples¶

Filter samples indicated in given metadata out of demultiplexed data. Specific samples can be further selected with the WHERE clause, and the exclude_ids parameter allows for filtering of all samples not specified.

Inputs¶

demux: SampleData[SequencesWithQuality¹ | PairedEndSequencesWithQuality² | JoinedSequencesWithQuality³]

The demultiplexed data from which samples should be filtered.[required]

Parameters¶

metadata: Metadata

Sample metadata indicating which sample ids to filter. The optional where parameter may be used to filter ids based on specified conditions in the metadata. The optional exclude_ids parameter may be used to exclude the ids specified in the metadata from the filter.[required]

where: Str

Optional SQLite WHERE clause specifying sample metadata criteria that must be met to be included in the filtered data. If not provided, all samples in metadata that are also in the demultiplexed data will be retained.[optional]

exclude_ids: Bool

Defaults to False. If True, the samples selected by the metadata and optional where parameter will be excluded from the filtered data.[default: False]

Outputs¶

filtered_demux: SampleData[SequencesWithQuality¹ | PairedEndSequencesWithQuality² | JoinedSequencesWithQuality³]

Filtered demultiplexed data.[required]

demux summarize¶

Summarize counts per sample for all samples, and generate interactive positional quality plots based on n randomly selected sequences.

Inputs¶

data: SampleData[SequencesWithQuality | PairedEndSequencesWithQuality | JoinedSequencesWithQuality]

The demultiplexed sequences to be summarized.[required]

Parameters¶

n: Int

The number of sequences that should be selected at random for quality score plots. The quality plots will present the average positional qualities across all of the sequences selected. If input sequences are paired end, plots will be generated for both forward and reverse reads for the same n sequences.[default: 10000]

Outputs¶

visualization: Visualization

<no description>[required]

Examples¶

demux¶

wget -O 'demux.qza' \
  'https://amplicon-docs.qiime2.org/en/latest/data/examples/demux/summarize/1/demux.qza'

qiime demux summarize \
  --i-data demux.qza \
  --o-visualization visualization.qzv

from qiime2 import Artifact
from urllib import request
import qiime2.plugins.demux.actions as demux_actions

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

visualization_viz, = demux_actions.summarize(
    data=demux,
)

library(reticulate)

Artifact <- import("qiime2")$Artifact
demux_actions <- import("qiime2.plugins.demux.actions")
request <- import("urllib")$request

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

action_results <- demux_actions$summarize(
    data=demux,
)
visualization_viz <- action_results$visualization

from q2_demux._examples import summarize

summarize(use)