Tool determines the barcode for each read in an Illumina lane.

This tool determines the numbers of reads containing barcode-matching sequences and provides statistics on the quality of these barcode matches.

Illumina sequences can contain at least two types of barcodes, sample and molecular (index). Sample barcodes (B in the read structure) are used to demultiplex pooled samples while index barcodes (M in the read structure) are used to differentiate multiple reads of a template when carrying out paired-end sequencing. Note that this tool only extracts sample (B) and not molecular barcodes (M).

Barcodes can be provided in the form of a list (BARCODE_FILE) or a string representing the barcode (BARCODE). The BARCODE_FILE contains multiple fields including 'barcode_sequence' (or 'barcode_sequence_1'), 'barcode_sequence_2' (optional), 'barcode_name', and 'library_name'. In contrast, the BARCODE argument is used for runs with reads containing a single barcode (nonmultiplexed) and can be added directly as a string of text e.g. BARCODE=CAATAGCG.

Data is output per lane/tile within the BaseCalls directory with the file name format of 's_{lane}_{tile}_barcode.txt'. These files contain the following tab-separated columns:

• Read subsequence at barcode position
• Y or N indicating if there was a barcode match
• Matched barcode sequence (empty if read did not match one of the barcodes)
• The number of mismatches if there was a barcode match
• The number of mismatches to the second best barcode if there was a barcode match

If there is no match but we're close to the threshold of calling it a match, we output the barcode that would have been matched but in lower case. Threshold values can be adjusted to accommodate barcode sequence mismatches from the reads. The metrics file produced by the ExtractIlluminaBarcodes program indicates the number of matches (and mismatches) between the barcode reads and the actual barcodes. These metrics are provided both per-barcode and per lane and can be found in the BaseCalls directory.

For poorly matching barcodes, the order of specification of barcodes can cause arbitrary output differences.

Usage example:

java -jar picard.jar ExtractIlluminaBarcodes \
              BASECALLS_DIR=/BaseCalls/ \
              LANE=1 \
          READ_STRUCTURE=25T8B25T \
              BARCODE_FILE=barcodes.txt \
              METRICS_FILE=metrics_output.txt 

Please see the ExtractIlluminaBarcodes.BarcodeMetric definitions for a complete description of the metrics produced by this tool.

---

Category Base Calling

---

Overview

Determine the barcode for each read in an Illumina lane. For each tile, a file is written to the basecalls directory of the form s___barcode.txt. An output file contains a line for each read in the tile, aligned with the regular basecall output The output file contains the following tab-separated columns: - read subsequence at barcode position - Y or N indicating if there was a barcode match - matched barcode sequence (empty if read did not match one of the barcodes). If there is no match but we're close to the threshold of calling it a match we output the barcode that would have been matched but in lower case

ExtractIlluminaBarcodes (Picard) specific arguments

This table summarizes the command-line arguments that are specific to this tool. For more details on each argument, see the list further down below the table or click on an argument name to jump directly to that entry in the list.

Argument name(s)	Default value	Summary
Required Arguments
--BARCODE	[]	Barcode sequence. These must be unique, and all the same length. This cannot be used with reads that have more than one barcode; use BARCODE_FILE in that case.
--BARCODE_FILE	null	Tab-delimited file of barcode sequences, barcode name and, optionally, library name. Barcodes must be unique and all the same length. Column headers must be 'barcode_sequence' (or 'barcode_sequence_1'), 'barcode_sequence_2' (optional), 'barcode_name', and 'library_name'.
--BASECALLS_DIR  -B	null	The Illumina basecalls directory.
--LANE  -L	null	Lane number.
--METRICS_FILE  -M	null	Per-barcode and per-lane metrics written to this file.
--READ_STRUCTURE  -RS	null	A description of the logical structure of clusters in an Illumina Run, i.e. a description of the structure IlluminaBasecallsToSam assumes the data to be in. It should consist of integer/character pairs describing the number of cycles and the type of those cycles (B for Sample Barcode, M for molecular barcode, T for Template, and S for skip). E.g. If the input data consists of 80 base clusters and we provide a read structure of "28T8M8B8S28T" then the sequence may be split up into four reads: * read one with 28 cycles (bases) of template * read two with 8 cycles (bases) of molecular barcode (ex. unique molecular barcode) * read three with 8 cycles (bases) of sample barcode * 8 cycles (bases) skipped. * read four with 28 cycles (bases) of template The skipped cycles would NOT be included in an output SAM/BAM file or in read groups therein.
Optional Tool Arguments
--arguments_file	[]	read one or more arguments files and add them to the command line
--COMPRESS_OUTPUTS  -GZIP	false	Compress output s_l_t_barcode.txt files using gzip and append a .gz extension to the file names.
--help  -h	false	display the help message
--MAX_MISMATCHES	1	Maximum mismatches for a barcode to be considered a match.
--MAX_NO_CALLS	2	Maximum allowable number of no-calls in a barcode read before it is considered unmatchable.
--MIN_MISMATCH_DELTA	1	Minimum difference between number of mismatches in the best and second best barcodes for a barcode to be considered a match.
--MINIMUM_BASE_QUALITY  -Q	0	Minimum base quality. Any barcode bases falling below this quality will be considered a mismatch even in the bases match.
--MINIMUM_QUALITY	2	The minimum quality (after transforming 0s to 1s) expected from reads. If qualities are lower than this value, an error is thrown.The default of 2 is what the Illumina's spec describes as the minimum, but in practice the value has been observed lower.
--NUM_PROCESSORS	1	Run this many PerTileBarcodeExtractors in parallel. If NUM_PROCESSORS = 0, number of cores is automatically set to the number of cores available on the machine. If NUM_PROCESSORS < 0 then the number of cores used will be the number available on the machine less NUM_PROCESSORS.
--OUTPUT_DIR	null	Where to write _barcode.txt files. By default, these are written to BASECALLS_DIR.
--version	false	display the version number for this tool
Optional Common Arguments
--COMPRESSION_LEVEL	5	Compression level for all compressed files created (e.g. BAM and VCF).
--CREATE_INDEX	false	Whether to create a BAM index when writing a coordinate-sorted BAM file.
--CREATE_MD5_FILE	false	Whether to create an MD5 digest for any BAM or FASTQ files created.
--GA4GH_CLIENT_SECRETS	client_secrets.json	Google Genomics API client_secrets.json file path.
--MAX_RECORDS_IN_RAM	500000	When writing files that need to be sorted, this will specify the number of records stored in RAM before spilling to disk. Increasing this number reduces the number of file handles needed to sort the file, and increases the amount of RAM needed.
--QUIET	false	Whether to suppress job-summary info on System.err.
--REFERENCE_SEQUENCE  -R	null	Reference sequence file.
--TMP_DIR	[]	One or more directories with space available to be used by this program for temporary storage of working files
--USE_JDK_DEFLATER  -use_jdk_deflater	false	Use the JDK Deflater instead of the Intel Deflater for writing compressed output
--USE_JDK_INFLATER  -use_jdk_inflater	false	Use the JDK Inflater instead of the Intel Inflater for reading compressed input
--VALIDATION_STRINGENCY	STRICT	Validation stringency for all SAM files read by this program. Setting stringency to SILENT can improve performance when processing a BAM file in which variable-length data (read, qualities, tags) do not otherwise need to be decoded.
--VERBOSITY	INFO	Control verbosity of logging.
Advanced Arguments
--showHidden	false	display hidden arguments

Argument details

Arguments in this list are specific to this tool. Keep in mind that other arguments are available that are shared with other tools (e.g. command-line GATK arguments); see Inherited arguments above.

---

--arguments_file / NA

read one or more arguments files and add them to the command line

List[File]  []

---

--BARCODE / NA

Barcode sequence. These must be unique, and all the same length. This cannot be used with reads that have more than one barcode; use BARCODE_FILE in that case.

Exclusion: This argument cannot be used at the same time as BARCODE_FILE.

R List[String]  []

---

--BARCODE_FILE / NA

Tab-delimited file of barcode sequences, barcode name and, optionally, library name. Barcodes must be unique and all the same length. Column headers must be 'barcode_sequence' (or 'barcode_sequence_1'), 'barcode_sequence_2' (optional), 'barcode_name', and 'library_name'.

Exclusion: This argument cannot be used at the same time as BARCODE.

R File  null

---

--BASECALLS_DIR / -B

The Illumina basecalls directory.

R File  null

---

--COMPRESS_OUTPUTS / -GZIP

Compress output s_l_t_barcode.txt files using gzip and append a .gz extension to the file names.

boolean  false

---

--COMPRESSION_LEVEL / NA

Compression level for all compressed files created (e.g. BAM and VCF).

int  5  [ [ -∞  ∞ ] ]

---

--CREATE_INDEX / NA

Whether to create a BAM index when writing a coordinate-sorted BAM file.

Boolean  false

---

--CREATE_MD5_FILE / NA

Whether to create an MD5 digest for any BAM or FASTQ files created.

boolean  false

---

--GA4GH_CLIENT_SECRETS / NA

Google Genomics API client_secrets.json file path.

String  client_secrets.json

---

--help / -h

display the help message

boolean  false

---

--LANE / -L

Lane number.

R Integer  null

---

--MAX_MISMATCHES / NA

Maximum mismatches for a barcode to be considered a match.

int  1  [ [ -∞  ∞ ] ]

---

--MAX_NO_CALLS / NA

Maximum allowable number of no-calls in a barcode read before it is considered unmatchable.

int  2  [ [ -∞  ∞ ] ]

---

--MAX_RECORDS_IN_RAM / NA

When writing files that need to be sorted, this will specify the number of records stored in RAM before spilling to disk. Increasing this number reduces the number of file handles needed to sort the file, and increases the amount of RAM needed.

Integer  500000  [ [ -∞  ∞ ] ]

---

--METRICS_FILE / -M

Per-barcode and per-lane metrics written to this file.

R File  null

---

--MIN_MISMATCH_DELTA / NA

Minimum difference between number of mismatches in the best and second best barcodes for a barcode to be considered a match.

int  1  [ [ -∞  ∞ ] ]

---

--MINIMUM_BASE_QUALITY / -Q

Minimum base quality. Any barcode bases falling below this quality will be considered a mismatch even in the bases match.

int  0  [ [ -∞  ∞ ] ]

---

--MINIMUM_QUALITY / NA

The minimum quality (after transforming 0s to 1s) expected from reads. If qualities are lower than this value, an error is thrown.The default of 2 is what the Illumina's spec describes as the minimum, but in practice the value has been observed lower.

int  2  [ [ -∞  ∞ ] ]

---

--NUM_PROCESSORS / NA

Run this many PerTileBarcodeExtractors in parallel. If NUM_PROCESSORS = 0, number of cores is automatically set to the number of cores available on the machine. If NUM_PROCESSORS < 0 then the number of cores used will be the number available on the machine less NUM_PROCESSORS.

int  1  [ [ -∞  ∞ ] ]

---

--OUTPUT_DIR / NA

Where to write _barcode.txt files. By default, these are written to BASECALLS_DIR.

File  null

---

--QUIET / NA

Whether to suppress job-summary info on System.err.

Boolean  false

---

--READ_STRUCTURE / -RS

A description of the logical structure of clusters in an Illumina Run, i.e. a description of the structure IlluminaBasecallsToSam assumes the data to be in. It should consist of integer/character pairs describing the number of cycles and the type of those cycles (B for Sample Barcode, M for molecular barcode, T for Template, and S for skip). E.g. If the input data consists of 80 base clusters and we provide a read structure of "28T8M8B8S28T" then the sequence may be split up into four reads: * read one with 28 cycles (bases) of template * read two with 8 cycles (bases) of molecular barcode (ex. unique molecular barcode) * read three with 8 cycles (bases) of sample barcode * 8 cycles (bases) skipped. * read four with 28 cycles (bases) of template The skipped cycles would NOT be included in an output SAM/BAM file or in read groups therein.

R String  null

---

--REFERENCE_SEQUENCE / -R

Reference sequence file.

File  null

---

--showHidden / -showHidden

display hidden arguments

boolean  false

---

--TMP_DIR / NA

One or more directories with space available to be used by this program for temporary storage of working files

List[File]  []

---

--USE_JDK_DEFLATER / -use_jdk_deflater

Use the JDK Deflater instead of the Intel Deflater for writing compressed output

Boolean  false

---

--USE_JDK_INFLATER / -use_jdk_inflater

Use the JDK Inflater instead of the Intel Inflater for reading compressed input

Boolean  false

---

--VALIDATION_STRINGENCY / NA

Validation stringency for all SAM files read by this program. Setting stringency to SILENT can improve performance when processing a BAM file in which variable-length data (read, qualities, tags) do not otherwise need to be decoded.

The --VALIDATION_STRINGENCY argument is an enumerated type (ValidationStringency), which can have one of the following values:

STRICT

LENIENT

SILENT

ValidationStringency  STRICT

---

--VERBOSITY / NA

Control verbosity of logging.

The --VERBOSITY argument is an enumerated type (LogLevel), which can have one of the following values:

ERROR

WARNING

INFO

DEBUG

LogLevel  INFO

---

--version / NA

display the version number for this tool

boolean  false

---

Return to top

---

GATK version 4.1.1.0 built at Sat, 23 Nov 2019 17:29:19 -0500.