Deprecation notice:
The demultiplexing within the Guppy basecaller should be used in preference to that found within this project. Guppy is rountinely updated and will provide ongoing updates for new sequencing kits.
Guppy can be downloaded from: https://community.nanoporetech.com/downloads
This repository is now unsupported and we do not recommend its use. Please contact Oxford Nanopore: support@nanoporetech.com for help with your application if it is not possible to upgrade to our new resources, or we are missing key features.
qcat is a Python command-line tool for demultiplexing Oxford Nanopore reads from FASTQ files. It accepts basecalled FASTQ files and splits the reads into into separate FASTQ files based on their barcode. Qcat makes the demultiplexing algorithms used in albacore/guppy and EPI2ME available to be used locally with FASTQ files. Currently qcat implements the EPI2ME algorithm. In the next version we will add the albacore/guppy algorithm.
| Algorithm | Status | Description |
|---|---|---|
| Guppy/Albacore | not yet available | Using this mode, qcat will produce demultiplexing results identical to Albacore. |
| EPI2ME | available | Using this mode, qcat will produce demultiplexing results identical to EPI2ME's demultiplexing workflow |
In addition, qcat supports demultiplexing of datasets prepared using dual or combinatorial barcodes (see "How to run qcat?" section for more information).
If you want to demultiplex your reads during basecalling, please use albacore.
v1.1.0
- Add RAB214
v1.0.7
- Fix PBC and PBK adapter trimming
v1.0.6
- Fixed issue with file names in dual barcoding mode
- Resolved problem when using –tsv and -b at the same time
- Min. read length filter added
- Fixed YAMLLoadWarning
- Linux or MacOS
For the vast majority of datasets, it will be sufficient to run qcat using default parameters:
$ qcat -f <fastq_file> -b <output folder>After qcat finished, please check to summary output to verify that a barcode was assigned to most of the reads.
Conda (recommended)
To install qcat using conda, make sure you have Miniconda3 installed and the bioconda channels set up. After bioconda is set up, you can install qcat as follows:
$ conda install qcatPIP
If you want to install qcat using pip, please make sure to use python3.
$ pip install --user qcatTo install qcat using pip for all users on a system, run (requires root permissions):
$ pip install qcatDocker
If you have docker available on your computer, you can run qcat using the following command without any prior installation:
$ docker run -ti -v `pwd`:`pwd` -w `pwd` quay.io/biocontainers/qcat:1.0.0--py_0 qcat -f ./input_file.fastq -b ./output_folder/When running qcat using the above command, the input and output folders have to be in the current working directory. If you want to read from or write to locations other than your working directory, please adjust the -v parameter accordingly.
Manually install from source
To install qcat manually, please make sure you have python3 and git available, and install as follows:
$ git clone https://github.com/nanoporetech/qcat.git
$ cd qcat
$ python3 setup.py installDemultiplexing multiple FASTQ files from a folder
$ cat input_folder/*.fastq | qcat -b <output folder>Demultiplexing a single FASTQ file
$ qcat -f <fastq_file> -b <output folder>Demultiplexing dual/combinatorial barcoding datasets
$ qcat --dual -f <fastq_file> -b <output folder>Qcat will give you a summary of what barcodes where found and how many on the command line. For example:
Adapters detected in 191 of 193 reads
LWB001 191: | ################### | 98.96 %
none 2: | | 1.04 %
Barcodes detected in 191 of 193 adapters
barcode01 191: | ################### | 98.96 %
none 2: | | 1.04 %
Demultiplexing finished in 0.69sIn addition, you will get an output folder with a single FASTQ file per barcode:
$ ls -R tmp/output/
barcode01.fastq none.fastqThese files can be used for downstream analysis.
Currently Albacore and EPI2ME use different algorithms for demultiplexing. To provide maximum compatibility, qcat will support both algorithms. Eventually, both algorithms will be consolidated.
Qcat works similarity to porechop. However, porechop was recently deprecated.
When invoked without -f/--fastq, qcat will wait for input from standard in. Press Ctrl+C to stop qcat and either rerun wiht -f/--fastq:
$ qcat -f input_file.fastq -b output_folder/or make sure to use a pipe to provide the input FASTQ file. E.g.:
$ cat input_file.fastq | qcat -b output_folder/A simple option is to pipe all FASTQ files into qcat:
$ cat basecalled/*.fastq | qcat -b output_folder/Alternatively, you can concatenate all FASTQ files into a single file first:
$ cat basecalled/*.fastq > single_file.fastqand use -f/--fastq:
$ qcat -f single_file.fastq -b output_folder/I want to use Albacore's algorithm for demultiplexing, but get a warning saying "Demultiplexing mode guppy currently not supported. Falling back to epi2me."
Currently, Albacore's demultiplexing algorithm is only supported when running the qcat docker image. In the next version, we will support other ways of running Guppy/Albacore demultiplexing as well.
Currently qcat only supports demultiplexing. However, in the future we plan to add a trimming only mode as well.
In simple mode qcat will only search for barcode sequences without trying to determine which barcoding kit was used. ONLY USE THIS MODE FOR TESTING/DEBUGGING PURPOSE. Albacore and EPI2ME mode will be faster and give you better results.
| Kit | Description |
|---|---|
| Auto | Auto detect kit |
| RBK001 | Rapid barcoding kit |
| RBK004 | Rapid barcoding kit v4 |
| NBD103/NBD104 | Native barcoding kit with barcodes 1-12 |
| NBD114 | Native barcoding kit with barcodes 13-24 |
| NBD104/NBD114 | Native barcoding kit with barcodes 1-24 |
| PBC001 | PCR Barcoding Kit with 12 barcodes |
| PBC096 | PCR Barcoding Kit with 96 barcodes |
| RPB004/RLB001 | Rapid PCR Barcoding Kit (SQK-RPB004) and Rapid Low Input by PCR Barcoding Kit |
| PBK004/LWB001 | Low Input by PCR Barcoding Kit |
| RAB204 | 16S Rapid Amplicon Barcoding Kit with 12 Barcodes |
| VMK001 | Voltrax Barcoding Kit with 4 barcodes |
usage: qcat [-h] [-V] [-l LOG] [--quiet] [-f FASTQ] [-b BARCODE_DIR]
[-o OUTPUT] [--min-score MIN_QUAL] [--detect-middle] [-t THREADS]
[--tsv] [--trim]
[-k {Auto,PBC096,RBK004,NBD104/NBD114,PBK004/LWB001,RBK001,RAB204,VMK001,PBC001,NBD114,NBD103/NBD104,DUAL,RPB004/RLB001}]
[--list-kits] [--guppy | --epi2me | --dual | --simple]
[--no-batch] [--filter-barcodes]
[--simple-barcodes {standard,extended}]
Python command-line tool for demultiplexing Oxford Nanopore reads from FASTQ files
optional arguments:
-h, --help show this help message and exit
-V, --version show program's version number and exit
-l LOG, --log LOG Print debug information
--quiet Don't print summary
General settings:
-f FASTQ, --fastq FASTQ
Barcoded read file
-b BARCODE_DIR, --barcode_dir BARCODE_DIR
If specified, qcat will demultiplex reads to this
folder
-o OUTPUT, --output OUTPUT
Output file trimmed reads will be written to (default:
stdout).
--min-score MIN_QUAL Minimum barcode score. Barcode calls with a lower
score will be discarded. Must be between 0 and 100.
(default: 60)
--detect-middle Search for adapters in the whole read
-t THREADS, --threads THREADS
Number of threads. Only works with in guppy mode
--tsv Prints a tsv file containing barcode information each
read to stdout.
--trim Remove adapter and barcode sequences from reads.
-k {Auto,PBC096,RBK004,NBD104/NBD114,PBK004/LWB001,RBK001,RAB204,VMK001,PBC001,NBD114,NBD103/NBD104,DUAL,RPB004/RLB001}, --kit {Auto,PBC096,RBK004,NBD104/NBD114,PBK004/LWB001,RBK001,RAB204,VMK001,PBC001,NBD114,NBD103/NBD104,DUAL,RPB004/RLB001}
Sequencing kit. Specifying the correct kit will
improve sensitivity and specificity and runtime
(default: auto)
--list-kits List all supported kits
Demultiplexing modes:
--guppy Use Guppy's demultiplexing algorithm (default: false)
--epi2me Use EPI2ME's demultiplexing algorithm (default: true)
--dual Use dual barcoding algorithm
--simple Use simple demultiplexing algorithm. Only looks for
barcodes, not for adapter sequences. Use only for
testing purposes!
EPI2ME options (only valid with --epi2me):
--no-batch Don't use information from multiple reads for kit
detection (default: false)
--filter-barcodes Filter rare barcode calls when run in batch mode
Simple options (only valid with --simple):
--simple-barcodes {standard,extended}
Use 12 (standard) or 96 (extended) barcodes for
demultiplexing
Licence and Copyright
© 2018 Oxford Nanopore Technologies Ltd.
qcat is distributed under the terms of the Mozilla Public License 2.0.
Research Release
Research releases are provided as technology demonstrators to provide early access to features or stimulate Community development of tools. Support for this software will be minimal and is only provided directly by the developers. Feature requests, improvements, and discussions are welcome and can be implemented by forking and pull requests. However much as we would like to rectify every issue and piece of feedback users may have, the developers may have limited resource for support of this software. Research releases may be unstable and subject to rapid iteration by Oxford Nanopore Technologies.