Warning

This site has been replaced by the new QIIME 2 “amplicon distribution” documentation, as of the 2025.4 release of QIIME 2. You can still access the content from the “old docs” here for the QIIME 2 2024.10 and earlier releases, but we recommend that you transition to the new documentation at https://amplicon-docs.qiime2.org. Content on this site is no longer updated and may be out of date.

Are you looking for:

the QIIME 2 homepage? That’s https://qiime2.org.
learning resources for microbiome marker gene (i.e., amplicon) analysis? See the QIIME 2 amplicon distribution documentation.
learning resources for microbiome metagenome analysis? See the MOSHPIT documentation.
installation instructions, plugins, books, videos, workshops, or resources? See the QIIME 2 Library.
general help? See the QIIME 2 Forum.

Old content beyond this point… 👴👵

filter-reads: Filter demultiplexed sequences by alignment to reference database.¶

Citations	Ben Langmead and Steven L Salzberg. Fast gapped-read alignment with bowtie 2. Nature methods, 9(4):357, 2012. Heng Li, Bob Handsaker, Alec Wysoker, Tim Fennell, Jue Ruan, Nils Homer, Gabor Marth, Goncalo Abecasis, Richard Durbin, and 1000 Genome Project Data Processing Subgroup. The sequence alignment/map format and samtools. Bioinformatics, 25(16):2078–2079, 06 2009. URL: https://doi.org/10.1093/bioinformatics/btp352, arXiv:https://academic.oup.com/bioinformatics/article-pdf/25/16/2078/531810/btp352.pdf, doi:10.1093/bioinformatics/btp352.

Citations

Ben Langmead and Steven L Salzberg. Fast gapped-read alignment with bowtie 2. Nature methods, 9(4):357, 2012.
Heng Li, Bob Handsaker, Alec Wysoker, Tim Fennell, Jue Ruan, Nils Homer, Gabor Marth, Goncalo Abecasis, Richard Durbin, and 1000 Genome Project Data Processing Subgroup. The sequence alignment/map format and samtools. Bioinformatics, 25(16):2078–2079, 06 2009. URL: https://doi.org/10.1093/bioinformatics/btp352, arXiv:https://academic.oup.com/bioinformatics/article-pdf/25/16/2078/531810/btp352.pdf, doi:10.1093/bioinformatics/btp352.

Command line interface
Artifact API

Docstring:

Usage: qiime quality-control filter-reads [OPTIONS]

  Filter out (or keep) demultiplexed single- or paired-end sequences that
  align to a reference database, using bowtie2 and samtools. This method can
  be used to filter out human DNA sequences and other contaminants in any
  FASTQ sequence data (e.g., shotgun genome or amplicon sequence data), or
  alternatively (when exclude_seqs is False) to only keep sequences that do
  align to the reference.

Inputs:
  --i-demultiplexed-sequences ARTIFACT SampleData[SequencesWithQuality¹ |
    PairedEndSequencesWithQuality²]
                          The sequences to be trimmed.              [required]
  --i-database ARTIFACT   Bowtie2 indexed database.
    Bowtie2Index                                                    [required]
Parameters:
  --p-n-threads NTHREADS  Number of alignment threads to launch.  [default: 1]
  --p-mode TEXT Choices('local', 'global')
                          Bowtie2 alignment settings. See bowtie2 manual for
                          more details.                     [default: 'local']
  --p-sensitivity TEXT Choices('very-fast', 'fast', 'sensitive',
    'very-sensitive')     Bowtie2 alignment sensitivity. See bowtie2 manual
                          for details.                  [default: 'sensitive']
  --p-ref-gap-open-penalty INTEGER
    Range(1, None)        Reference gap open penalty.             [default: 5]
  --p-ref-gap-ext-penalty INTEGER
    Range(1, None)        Reference gap extend penalty.           [default: 3]
  --p-exclude-seqs / --p-no-exclude-seqs
                          Exclude sequences that align to reference. Set this
                          option to False to exclude sequences that do not
                          align to the reference database.     [default: True]
Outputs:
  --o-filtered-sequences ARTIFACT SampleData[SequencesWithQuality¹ |
    PairedEndSequencesWithQuality²]
                          The resulting filtered sequences.         [required]
Miscellaneous:
  --output-dir PATH       Output unspecified results to a directory
  --verbose / --quiet     Display verbose output to stdout and/or stderr
                          during execution of this action. Or silence output
                          if execution is successful (silence is golden).
  --example-data PATH     Write example data and exit.
  --citations             Show citations and exit.
  --use-cache DIRECTORY   Specify the cache to be used for the intermediate
                          work of this action. If not provided, the default
                          cache under $TMP/qiime2/ will be used.
                          IMPORTANT FOR HPC USERS: If you are on an HPC system
                          and are using parallel execution it is important to
                          set this to a location that is globally accessible
                          to all nodes in the cluster.
  --help                  Show this message and exit.

Import:

from qiime2.plugins.quality_control.methods import filter_reads

Docstring:

Filter demultiplexed sequences by alignment to reference database.

Filter out (or keep) demultiplexed single- or paired-end sequences that
align to a reference database, using bowtie2 and samtools. This method can
be used to filter out human DNA sequences and other contaminants in any
FASTQ sequence data (e.g., shotgun genome or amplicon sequence data), or
alternatively (when exclude_seqs is False) to only keep sequences that do
align to the reference.

Parameters
----------
demultiplexed_sequences : SampleData[SequencesWithQuality¹ | PairedEndSequencesWithQuality²]
The sequences to be trimmed.
database : Bowtie2Index
Bowtie2 indexed database.
n_threads : Threads, optional
Number of alignment threads to launch.
mode : Str % Choices('local', 'global'), optional
Bowtie2 alignment settings. See bowtie2 manual for more details.
sensitivity : Str % Choices('very-fast', 'fast', 'sensitive', 'very-sensitive'), optional
Bowtie2 alignment sensitivity. See bowtie2 manual for details.
ref_gap_open_penalty : Int % Range(1, None), optional
Reference gap open penalty.
ref_gap_ext_penalty : Int % Range(1, None), optional
Reference gap extend penalty.
exclude_seqs : Bool, optional
Exclude sequences that align to reference. Set this option to False to
exclude sequences that do not align to the reference database.

Returns
-------
filtered_sequences : SampleData[SequencesWithQuality¹ | PairedEndSequencesWithQuality²]
The resulting filtered sequences.

filter-reads: Filter demultiplexed sequences by alignment to reference database.¶

Docstring:

Import:

Docstring:

Table of Contents

Quick search