Picard

Adds comments to the header of a BAM file.This tool makes a copy of the input bam file, with a modified header that includes the comments specified at the command line (prefixed by @CO). Use double quotes to wrap comments that include whitespace or special characters.

Note that this tool cannot be run on SAM files.

Usage example:

java -jar picard.jar AddCommentsToBam \
      I=input.bam \
      O=modified_bam.bam \
      C=comment_1 \
      C="comment 2"

Replace read groups in a BAM file.This tool enables the user to replace all read groups in the INPUT file with a single new read group and assign all reads to this read group in the OUTPUT BAM file.

For more information about read groups, see the GATK Dictionary entry.

This tool accepts INPUT BAM and SAM files or URLs from the Global Alliance for Genomics and Health (GA4GH) (see http://ga4gh.org/#/documentation).

Usage example:

java -jar picard.jar AddOrReplaceReadGroups \
      I=input.bam \
      O=output.bam \
      RGID=4 \
      RGLB=lib1 \
      RGPL=illumina \
      RGPU=unit1 \
      RGSM=20

Designs oligonucleotide baits for hybrid selection reactions.

This tool is used to design custom bait sets for hybrid selection experiments. The following files are input into BaitDesigner: a (TARGET) interval list indicating the sequences of interest, e.g. exons with their respective coordinates, a reference sequence, and a unique identifier string (DESIGN_NAME).

The tool will output interval_list files of both bait and target sequences as well as the actual bait sequences in FastA format. At least two baits are output for each target sequence, with greater numbers for larger intervals. Although the default values for both bait size (120 bases) nd offsets (80 bases) are suitable for most applications, these values can be customized. Offsets represent the distance between sequential baits on a contiguous stretch of target DNA sequence.

The tool will also output a pooled set of 55,000 (default) oligonucleotides representing all of the baits redundantly. This redundancy achieves a uniform concentration of oligonucleotides for synthesis by a vendor as well as equal numbersof each bait to prevent bias during the hybrid selection reaction.

Usage example:

java -jar picard.jar BaitDesigner \
      TARGET=targets.interval_list \
      DESIGN_NAME=new_baits \
      R=reference_sequence.fasta 

Create BFQ files from a BAM file for use by the maq aligner. BFQ is a binary version of the FASTQ file format. This tool creates bfq files from a BAM file for use by the maq aligner.

Usage example:

java -jar picard.jar BamToBfq \
      I=input.bam \
      ANALYSIS_DIR=analysis_dir \
      OUTPUT_FILE_PREFIX=output_file_1 \
      PAIRED_RUN=false

Generate index statistics from a BAM fileThis tool calculates statistics from a BAM index (.bai) file, emulating the behavior of the "samtools idxstats" command. The statistics collected include counts of aligned and unaligned reads as well as all records with no start coordinate. The input to the tool is the BAM file name but it must be accompanied by a corresponding index file.

Usage example:

java -jar picard.jar BamIndexStats \
      I=input.bam \
      O=output

Converts a BED file to a Picard Interval List. This tool provides easy conversion from BED to the Picard interval_list format which is required by many Picard processing tools. Note that the coordinate system of BED files is such that the first base or position in a sequence is numbered "0", while in interval_list files it is numbered "1".

BED files contain sequence data displayed in a flexible format that includes nine optional fields, in addition to three required fields within the annotation tracks. The required fields of a BED file include:

     chrom - The name of the chromosome (e.g. chr20) or scaffold (e.g. scaffold10671) 
     chromStart - The starting position of the feature in the chromosome or scaffold. The first base in a chromosome is numbered "0" 
     chromEnd - The ending position of the feature in the chromosome or scaffold.  The chromEnd base is not included in the display of the feature. For example, the first 100 bases of a chromosome are defined as chromStart=0, chromEnd=100, and span the bases numbered 0-99.

      -Sequence name (SN) - The name of the sequence in the file for identification purposes, can be chromosome number e.g. chr20 
      -Start position - Interval start position (starts at +1) 
      -End position - Interval end position (1-based, end inclusive) 
      -Strand - Indicates +/- strand for the interval (either + or -) 
      -Interval name - (Each interval should have a unique name) 

    - A file with .dict extension generated using Picard's CreateSequenceDictionaryTool
    - A reference.fa or reference.fasta file with a reference.dict in the same directory
    - Another IntervalList with @SQ lines in the header from which to generate a dictionary
    - A VCF that contains #contig lines from which to generate a sequence dictionary
    - A SAM or BAM file with @SQ lines in the header from which to generate a dictionary

Usage example:

java -jar picard.jar BedToIntervalList \
      I=input.bed \
      O=list.interval_list \
      SD=reference_sequence.dict

Generates a BAM index ".bai" file. This tool creates an index file for the input BAM that allows fast look-up of data in a BAM file, lke an index on a database. Note that this tool cannot be run on SAM files, and that the input BAM file must be sorted in coordinate order.

Usage example:

java -jar picard.jar BuildBamIndex \
      I=input.bam

Creates a hash code based on the read groups (RG). This tool creates a hash code based on identifying information in the read groups (RG) of a ".BAM" or "SAM" file header. Addition or removal of RGs changes the hash code, enabling the user to quickly determine if changes have been made to the read group information.

Usage example:

java -jar picard.jar CalculateReadGroupChecksum \
      I=input.bam

Cleans the provided SAM/BAM, soft-clipping beyond-end-of-reference alignments and setting MAPQ to 0 for unmapped reads

Produces a summary of alignment metrics from a SAM or BAM file. This tool takes a SAM/BAM file input and produces metrics detailing the quality of the read alignments as well as the proportion of the reads that passed machine signal-to-noise threshold quality filters. Note that these quality filters are specific to Illumina data; for additional information, please see the corresponding GATK Dictionary entry.

Note: Metrics labeled as percentages are actually expressed as fractions!

Usage example:

    java -jar picard.jar CollectAlignmentSummaryMetrics \
          R=reference_sequence.fasta \
          I=input.bam \
          O=output.txt

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

Chart the nucleotide distribution per cycle in a SAM or BAM fileThis tool produces a chart of the nucleotide distribution per cycle in a SAM or BAM file in order to enable assessment of systematic errors at specific positions in the reads.

Interpretation notes

Note on quality trimming

Note: Metrics labeled as percentages are actually expressed as fractions!

Usage example:

java -jar picard.jar CollectBaseDistributionByCycle \
      CHART=collect_base_dist_by_cycle.pdf \
      I=input.bam \
      O=output.txt

Collect metrics regarding GC bias. This tool collects information about the relative proportions of guanine (G) and cytosine (C) nucleotides in a sample. Regions of high and low G + C content have been shown to interfere with mapping/aligning, ultimately leading to fragmented genome assemblies and poor coverage in a phenomenon known as 'GC bias'. Detailed information on the effects of GC bias on the collection and analysis of sequencing data can be found at DOI: 10.1371/journal.pone.0062856/.

The GC bias statistics are always output in a detailed long-form version, but a summary can also be produced. Both the detailed metrics and the summary metrics are output as tables '.txt' files) and an accompanying chart that plots the data ('.pdf' file).

Detailed metrics

Summary metrics

Note: Metrics labeled as percentages are actually expressed as fractions!

Usage Example:

java -jar picard.jar CollectGcBiasMetrics \
      I=input.bam \
      O=gc_bias_metrics.txt \
      CHART=gc_bias_metrics.pdf \
      S=summary_metrics.txt \
      R=reference_sequence.fasta

Classify PF-Failing reads in a HiSeqX Illumina Basecalling directory into various categories.

This tool categorizes the reads that did not pass filter (PF-Failing) into four groups. These groups are based on a heuristic that was derived by looking at a few titration experiments.

After examining the called bases from the first 24 cycles of each read, the PF-Failed reads are grouped into the following four categories:

• MISALIGNED - The first 24 basecalls of a read are uncalled (numNs~24). These types of reads appear to be flow cell artifacts because reads were only found near tile boundaries and were concentration (library) independent
• EMPTY - All 24 bases are called (numNs~0) but the number of bases with quality scores greater than two is less than or equal to eight (numQGtTwo<=8). These reads were location independent within the tiles and were inversely proportional to the library concentration
• POLYCLONAL - All 24 bases were called and numQGtTwo>=12, were independent of their location with the tiles, and were directly proportional to the library concentration. These reads are likely the result of PCR artifacts
• UNKNOWN - The remaining reads that are PF-Failing but did not fit into any of the groups listed above

The tool defaults to the SUMMARY output which indicates the number of PF-Failed reads per tile and groups them into the categories described above accordingly.

A DETAILED metrics option is also available that subdivides the SUMMARY outputs by the x- y- position of these reads within each tile. To obtain the DETAILED metric table, you must add the PROB_EXPLICIT_READS option to your command line and set the value between 0 and 1. This value represents the fractional probability of PF-Failed reads to send to output. For example, if PROB_EXPLICIT_READS=0, then no metrics will be output. If PROB_EXPLICIT_READS=1, then it will provide detailed metrics for all (100%) of the reads. It follows that setting the PROB_EXPLICIT_READS=0.5, will provide detailed metrics for half of the PF-Failed reads.

Note: Metrics labeled as percentages are actually expressed as fractions!

Usage example: (SUMMARY Metrics)

java -jar picard.jar CollectHiSeqXPfFailMetrics \
      BASECALLS_DIR=/BaseCalls/ \
      OUTPUT=/metrics/ \
      LANE=001

Usage example: (DETAILED Metrics)

java -jar picard.jar CollectHiSeqXPfFailMetrics \
      BASECALLS_DIR=/BaseCalls/ \
      OUTPUT=/Detail_metrics/ \
      LANE=001 \
      PROB_EXPLICIT_READS=1

Collects hybrid-selection (HS) metrics for a SAM or BAM file. This tool takes a SAM/BAM file input and collects metrics that are specific for sequence datasets generated through hybrid-selection. Hybrid-selection (HS) is the most commonly used technique to capture exon-specific sequences for targeted sequencing experiments such as exome sequencing; for more information, please see the corresponding GATK Dictionary entry.

This tool requires an aligned SAM or BAM file as well as bait and target interval files in Picard interval_list format. You should use the bait and interval files that correspond to the capture kit that was used to generate the capture libraries for sequencing, which can generally be obtained from the kit manufacturer. If the baits and target intervals are provided in BED format, you can convert them to the Picard interval_list format using Picard's BedToInterval tool.

If a reference sequence is provided, this program will calculate both AT_DROPOUT and GC_DROPOUT metrics. Dropout metrics are an attempt to measure the reduced representation of reads, in regions that deviate from 50% G/C content. This reduction in the number of aligned reads is due to the increased numbers of errors associated with sequencing regions with excessive or deficient numbers of G/C bases, ultimately leading to poor mapping efficiencies and lowcoverage in the affected regions.

If you are interested in getting G/C content and mean sequence depth information for every target interval, use the PER_TARGET_COVERAGE option.

Note: Metrics labeled as percentages are actually expressed as fractions!

Usage Example:

java -jar picard.jar CollectHsMetrics \
      I=input.bam \
      O=hs_metrics.txt \
      R=reference_sequence.fasta \
      BAIT_INTERVALS=bait.interval_list \
      TARGET_INTERVALS=target.interval_list

Please see CollectHsMetrics for detailed descriptions of the output metrics produced by this tool.

Collects Illumina Basecalling metrics for a sequencing run.

This tool will produce per-barcode and per-lane basecall metrics for each sequencing run. Mean values for each metric are determined using data from all of the tiles. This tool requires the following data, LANE(#), BASECALLS_DIR, READ_STRUCTURE, and an input file listing the sample barcodes. Program will provide metrics including: the total numbers of bases, reads, and clusters, as well as the fractions of each bases, reads, and clusters that passed Illumina quality filters (PF) both per barcode and per lane. For additional information on Illumina's PF quality metric, please see the corresponding GATK Dictionary entry.

The input barcode_list.txt file is a file containing all of the sample and molecular barcodes and can be obtained from the ExtractIlluminaBarcodes tool.

Usage example:

java -jar picard.jar CollectIlluminaBasecallingMetrics \
      BASECALLS_DIR=/BaseCalls/ \
      LANE=001 \
      READ_STRUCTURE=25T8B25T \
      INPUT=barcode_list.txt 

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

Collects Illumina lane metrics for the given BaseCalling analysis directory. This tool produces quality control metrics on cluster density for each lane of an Illumina flowcell. This tool takes Illumina TileMetrics data and places them into directories containing lane- and phasing-level metrics. In this context, phasing refers to the fraction of molecules that fall behind or jump ahead (prephasing) during a read cycle.

Usage example:

java -jar picard.jar CollectIlluminaLaneMetrics \
      RUN_DIR=test_run \
      OUTPUT_DIRECTORY=Lane_output_metrics \
      OUTPUT_PREFIX=experiment1 \
      READ_STRUCTURE=25T8B25T 

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

This tool provides useful metrics for validating library construction including the insert size distribution and read orientation of paired-end libraries.

The CollectInsertSizeMetrics tool outputs the percentages of read pairs in each of the three orientations (FR, RF, and TANDEM) as a histogram. In addition, the insert size distribution is output as both a histogram (.insert_size_Histogram.pdf) and as a data table (.insert_size_metrics.txt).

Note: Metrics labeled as percentages are actually expressed as fractions!

Usage example:

java -jar picard.jar CollectInsertSizeMetrics \
      I=input.bam \
      O=insert_size_metrics.txt \
      H=insert_size_histogram.pdf \
      M=0.5

Collect jumping library metrics.

This tool collects high-level metrics about the presence of outward-facing (jumping) and inward-facing (non-jumping) read pairs within a SAM or BAM file.For a brief primer on jumping libraries, see the GATK Dictionary

This program gets all data for computation from the first read in each pair in which the mapping quality (MQ) tag is set with the mate's mapping quality. If the MQ tag is not set, then the program assumes that the mate's MQ is greater than or equal to MINIMUM_MAPPING_QUALITY (default value is 0).

Note: Metrics labeled as percentages are actually expressed as fractions!

Usage example:

java -jar picard.jar CollectJumpingLibraryMetrics \
      I=input.bam  \
      O=jumping_metrics.txt

Collect multiple classes of metrics. This 'meta-metrics' tool runs one or more of the metrics collection modules at the same time to cut down on the time spent reading in data from input files. Available modules include CollectAlignmentSummaryMetrics, CollectInsertSizeMetrics, QualityScoreDistribution, MeanQualityByCycle, CollectBaseDistributionByCycle, CollectGcBiasMetrics, RnaSeqMetrics, CollectSequencingArtifactMetrics, and CollectQualityYieldMetrics. The tool produces outputs of '.pdf' and '.txt' files for each module, except for the CollectAlignmentSummaryMetrics module, which outputs only a '.txt' file. Output files are named by specifying a base name (without any file extensions).

Currently all programs are run with default options and fixed output extensions, but this may become more flexible in future. Specifying a reference sequence file is required.

Note: Metrics labeled as percentages are actually expressed as fractions!

Usage example (all modules on by default):

java -jar picard.jar CollectMultipleMetrics \
      I=input.bam \
      O=multiple_metrics \
      R=reference_sequence.fasta 

Usage example (two modules only):

Collect metrics to assess oxidative artifacts.This tool collects metrics quantifying the error rate resulting from oxidative artifacts. For a brief primer on oxidative artifacts, see the GATK Dictionary.

This tool calculates the Phred-scaled probability that an alternate base call results from an oxidation artifact. This probability score is based on base context, sequencing read orientation, and the characteristic low allelic frequency. Please see the following reference for an in-depth discussion of the OxoG error rate.

Lower probability values implicate artifacts resulting from 8-oxoguanine, while higher probability values suggest that an alternate base call is due to either some other type of artifact or is a real variant.

Usage example:

java -jar picard.jar CollectOxoGMetrics \
      I=input.bam \
      O=oxoG_metrics.txt \
      R=reference_sequence.fasta

Collect metrics about reads that pass quality thresholds and Illumina-specific filters. This tool evaluates the overall quality of reads within a bam file containing one read group. The output indicates the total numbers of bases within a read group that pass a minimum base quality score threshold and (in the case of Illumina data) pass Illumina quality filters as described in the GATK Dictionary entry.

Note on base quality score options

Usage Example:

java -jar picard.jar CollectQualityYieldMetrics \
       I=input.bam \
       O=quality_yield_metrics.txt \

Collect whole genome sequencing-related metrics. This tool computes metrics that are useful for evaluating coverage and performance of whole genome sequencing experiments. These metrics include the percentages of reads that pass minimal base- and mapping- quality filters as well as coverage (read-depth) levels.

The histogram output is optional and for a given run, displays two separate outputs on the y-axis while using a single set of values for the x-axis. Specifically, the first column in the histogram table (x-axis) is labeled 'coverage' and represents different possible coverage depths. However, it also represents the range of values for the base quality scores and thus should probably be labeled 'sequence depth and base quality scores'. The second and third columns (y-axes) correspond to the numbers of bases at a specific sequence depth 'count' and the numbers of bases at a particular base quality score 'baseq_count' respectively.

Although similar to the CollectWgsMetrics tool, the default thresholds for CollectRawWgsMetrics are less stringent. For example, the CollectRawWgsMetrics have base and mapping quality score thresholds set to '3' and '0' respectively, while the CollectWgsMetrics tool has the default threshold values set to '20' (at time of writing). Nevertheless, both tools enable the user to input specific threshold values.

Note: Metrics labeled as percentages are actually expressed as fractions!

Usage example:

java -jar picard.jar CollectRawWgsMetrics \
      I=input.bam \
      O=raw_wgs_metrics.txt \
      R=reference_sequence.fasta \
      INCLUDE_BQ_HISTOGRAM=true

Calculate PCR-related metrics from targeted sequencing data.

This tool calculates a set of PCR-related metrics from an aligned SAM or BAM file containing targeted sequencing data. It is appropriate for data produced with multiple small-target technologies including exome sequencing an custom amplicon panels such as the Illumina TruSeq Custom Amplicon (TSCA) kit.

If a reference sequence is provided, AT/GC dropout metrics will be calculated and the PER_TARGET_COVERAGE option can be used to output GC content and mean coverage information for each target. The AT/GC dropout metrics indicate the degree of inadequate coverage of a particular region based on its AT or GC content. The PER_TARGET_COVERAGE option can be used to output GC content and mean sequence depth information for every target interval.

Note: Metrics labeled as percentages are actually expressed as fractions!

Usage Example

java -jar picard.jar CollectTargetedPcrMetrics \
       I=input.bam \
       O=pcr_metrics.txt \
       R=reference_sequence.fasta \
       AMPLICON_INTERVALS=amplicon.interval_list \
       TARGET_INTERVALS=targets.interval_list 

Produces RNA alignment metrics for a SAM or BAM file.

This tool takes a SAM/BAM file containing the aligned reads from an RNAseq experiment and produces metrics describing the distribution of the bases within the transcripts. It calculates the total numbers and the fractions of nucleotides within specific genomic regions including untranslated regions (UTRs), introns, intergenic sequences (between discrete genes), and peptide-coding sequences (exons). This tool also determines the numbers of bases that pass quality filters that are specific to Illumina data (PF_BASES). For more information please see the corresponding GATK Dictionary entry.

Other metrics include the median coverage (depth), the ratios of 5 prime /3 prime-biases, and the numbers of reads with the correct/incorrect strand designation. The 5 prime /3 prime-bias results from errors introduced by reverse transcriptase enzymes during library construction, ultimately leading to the over-representation of either the 5 prime or 3 prime ends of transcripts. Please see the CollectRnaSeqMetrics definitions for details on how these biases are calculated.

The sequence input must be a valid SAM/BAM file containing RNAseq data aligned by an RNAseq-aware genome aligner such a STAR or TopHat. The tool also requires a REF_FLAT file, a tab-delimited file containing information about the location of RNA transcripts, exon start and stop sites, etc. For an example refFlat file for GRCh38, see refFlat.txt.gz at http://hgdownload.cse.ucsc.edu/goldenPath/hg38/database. The first five lines of the tab-limited text file appear as follows.

DDX11L1	NR_046018	chr1	+	11873	14409	14409	14409	3	11873,12612,13220,	12227,12721,14409,WASH7P	NR_024540	chr1	-	14361	29370	29370	29370	11	14361,14969,15795,16606,16857,17232,17605,17914,18267,24737,29320,	14829,15038,15947,16765,17055,17368,17742,18061,18366,24891,29370,DLGAP2-AS1	NR_103863	chr8_KI270926v1_alt	-	33083	35050	35050	35050	3	33083,33761,35028,	33281,33899,35050,MIR570	NR_030296	chr3	+	195699400	195699497	195699497	195699497	1	195699400,	195699497,MIR548A3	NR_030330	chr8	-	104484368	104484465	104484465	104484465	1	104484368,	104484465,

Note: Metrics labeled as percentages are actually expressed as fractions!

Usage example:

java -jar picard.jar CollectRnaSeqMetrics \
      I=input.bam \
      O=output.RNA_Metrics \
      REF_FLAT=ref_flat.txt \
      STRAND=SECOND_READ_TRANSCRIPTION_STRAND \
      RIBOSOMAL_INTERVALS=ribosomal.interval_list

Collects metrics from reduced representation bisulfite sequencing (Rrbs) data.

This tool uses reduced representation bisulfite sequencing (Rrbs) data to determine cytosine methylation status across all reads of a genomic DNA sequence. For a primer on bisulfite sequencing and cytosine methylation, please see the corresponding GATK Dictionary entry.

Briefly, bisulfite reduction converts un-methylated cytosine (C) to uracil (U) bases. Methylated sites are not converted because they are resistant to bisulfite reduction. Subsequent to PCR amplification of the reaction products, bisulfite reduction manifests as [C -> T (+ strand) or G -> A (- strand)] base conversions. Thus, conversion rates can be calculated from the reads as follows: [CR = converted/(converted + unconverted)]. Since methylated cytosines are protected against Rrbs-mediated conversion, the methylation rate (MR) is as follows:[MR = unconverted/(converted + unconverted) = (1 - CR)].

The CpG CollectRrbsMetrics tool outputs three files including summary and detail metrics tables as well as a PDF file containing four graphs. These graphs are derived from the summary table and include a comparison of conversion rates for both CpG and non-CpG sites, the distribution of total numbers of CpG sites as a function of the CpG conversion rates, the distribution of CpG sites by the level of read coverage (depth), and the numbers of reads discarded resulting from either exceeding the mismatch rate or size (too short). The detailed metrics table includes the coordinates of all of the CpG sites for the experiment as well as the conversion rates observed for each site.

Usage example:

java -jar picard.jar CollectRrbsMetrics \
      R=reference_sequence.fasta \
      I=input.bam \
      M=basename_for_metrics_files

Please see the CollectRrbsMetrics definitions for a complete description of both the detail and summary metrics produced by this tool.

Collect metrics to quantify single-base sequencing artifacts.

This tool examines two sources of sequencing errors associated with hybrid selection protocols. These errors are divided into two broad categories, pre-adapter and bait-bias. Pre-adapter errors can arise from laboratory manipulations of a nucleic acid sample e.g. shearing and occur prior to the ligation of adapters for PCR amplification (hence the name pre-adapter).

Bait-bias artifacts occur during or after the target selection step, and correlate with substitution rates that are 'biased', or higher for sites having one base on the reference/positive strand relative to sites having the complementary base on that strand. For example, during the target selection step, a (G>T) artifact might result in a higher substitution rate at sites with a G on the positive strand (and C on the negative), relative to sites with the flip (C positive)/(G negative). This is known as the 'G-Ref' artifact.

For additional information on these types of artifacts, please see the corresponding GATK dictionary entries on bait-bias and pre-adapter artifacts.

This tool produces four files; summary and detail metrics files for both pre-adapter and bait-bias artifacts. The detailed metrics show the error rates for each type of base substitution within every possible triplet base configuration. Error rates associated with these substitutions are Phred-scaled and provided as quality scores, the lower the value, the more likely it is that an alternate base call is due to an artifact. The summary metrics provide likelihood information on the 'worst-case' errors.

Usage example:

java -jar picard.jar CollectSequencingArtifactMetrics \
     I=input.bam \
     O=artifact_metrics.txt \
     R=reference_sequence.fasta

Collects per-sample and aggregate (spanning all samples) metrics from the provided VCF file.

Collect metrics about coverage and performance of whole genome sequencing (WGS) experiments.

This tool collects metrics about the fractions of reads that pass base- and mapping-quality filters as well as coverage (read-depth) levels for WGS analyses. Both minimum base- and mapping-quality values as well as the maximum read depths (coverage cap) are user defined.

Note: Metrics labeled as percentages are actually expressed as fractions!

Usage Example:

java -jar picard.jar CollectWgsMetrics \
       I=input.bam \
       O=collect_wgs_metrics.txt \
       R=reference_sequence.fasta 

Collect metrics about coverage and performance of whole genome sequencing (WGS) experiments. This tool collects metrics about the percentages of reads that pass base- and mapping- quality filters as well as coverage (read-depth) levels. Both minimum base- and mapping-quality values as well as the maximum read depths (coverage cap) are user defined. This extends CollectWgsMetrics by including metrics related only to siteswith non-zero (>0) coverage.

Note: Metrics labeled as percentages are actually expressed as fractions!

Usage Example:

java -jar picard.jar CollectWgsMetricsWithNonZeroCoverage \
       I=input.bam \
       O=collect_wgs_metrics.txt \
       CHART=collect_wgs_metrics.pdf  \
       R=reference_sequence.fasta 

Compare two metrics files.This tool compares the metrics and histograms generated from metric tools to determine if the generated results are identical. This tool is useful to test and compare outputs when code changes are implemented. It is not meant for use by end-users of this toolkit.

The tool's output simply indicates whether two metrics files are equal or not equal.

Usage example:

java -jar picard.jar CompareMetrics \
      metricfile1.txt \
      metricfile2.txt

Compare two input ".sam" or ".bam" files. This tool initially compares the headers of SAM or BAM files. If the file headers are comparable, the tool will examine and compare readUnmapped flag, reference name, start position and strand between the SAMRecords. The tool summarizes information on the number of read pairs that match or mismatch, and of reads that are missing or unmapped (stratified by direction: forward or reverse).

Usage example:

java -jar picard.jar CompareSAMs \
      file_1.bam \
      file_2.bam

Extract OxoG metrics from generalized artifacts metrics.

This tool extracts 8-oxoguanine (OxoG) artifact metrics from the output of CollectSequencingArtifactsMetrics (a tool that provides detailed information on a variety of artifacts found in sequencing libraries) and converts them to the CollectOxoGMetrics tool's output format. This conveniently eliminates the need to run CollectOxoGMetrics if we already ran CollectSequencingArtifactsMetrics in our pipeline. See the documentation for CollectSequencingArtifactsMetrics and CollectOxoGMetrics for additional information on these tools.

Note that only the base of the CollectSequencingArtifactsMetrics output file name is required for the (INPUT_BASE) parameter. For example, if the file name is artifact_metrics.txt.bait_bias_detail_metrics or artifact_metrics.txt.pre_adapter_detail_metrics, only the file name base 'artifact_metrics' is required on the command line for this parameter. An output file called 'artifact_metrics.oxog_metrics' will be generated automatically. Finally, to run this tool successfully, the REFERENCE_SEQUENCE must be provided.

Usage example:

java -jar picard.jar ConvertSequencingArtifactToOxoG \
     I=artifact_metrics \
     R=reference.fasta

Creates a sequence dictionary for a reference sequence. This tool creates a sequence dictionary file (with ".dict" extension) from a reference sequence provided in FASTA format, which is required by many processing and analysis tools. The output file contains a header but no SAMRecords, and the header contains only sequence records.

The reference sequence can be gzipped (both .fasta and .fasta.gz are supported).

Usage example:

java -jar picard.jar CreateSequenceDictionary \ 
      R=reference.fasta \ 
      O=reference.dict

Downsample a SAM or BAM file. This tool applies a random downsampling algorithm to a SAM or BAM file to retain only a random subset of the reads. Reads in a mate-pair are either both kept or both discarded. Reads marked as not primary alignments are all discarded. Each read is given a probability P of being retained so that runs performed with the exact same input in the same order and with the same value for RANDOM_SEED will produce the same results.All reads for a template are kept or discarded as a unit, with the goal of retaining readsfrom PROBABILITY * input templates. While this will usually result in approximately PROBABILITY * input reads being retained also, for very small PROBABILITIES this may not be the case. A number of different downsampling strategies are supported using the STRATEGY option: ConstantMemory: Downsamples a stream or file of SAMRecords using a hash-projection strategy such that it can run in constant memory. The downsampling is stochastic, and therefore the actual retained proportion will vary around the requested proportion. Due to working in fixed memory this strategy is good for large inputs, and due to the stochastic nature the accuracy of this strategy is highest with a high number of output records, and diminishes at low output volumes. HighAccuracy: Attempts (but does not guarantee) to provide accuracy up to a specified limit. Accuracy is defined as emitting a proportion of reads as close to the requested proportion as possible. In order to do so this strategy requires memory that is proportional to the number of template names in the incoming stream of reads, and will thus require large amounts of memory when running on large input files. Chained: Attempts to provide a compromise strategy that offers some of the advantages of both the ConstantMemory and HighAccuracy strategies. Uses a ConstantMemory strategy to downsample the incoming stream to approximately the desired proportion, and then a HighAccuracy strategy to finish. Works in a single pass, and will provide accuracy close to (but often not as good as) HighAccuracy while requiring memory proportional to the set of reads emitted from the ConstantMemory strategy to the HighAccuracy strategy. Works well when downsampling large inputs to small proportions (e.g. downsampling hundreds of millions of reads and retaining only 2%. Should be accurate 99.9% of the time when the input contains >= 50,000 templates (read names). For smaller inputs, HighAccuracy is recommended instead.

Usage example:

java -jar picard.jar DownsampleSam \
      I=input.bam \
      O=downsampled.bam

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_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

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 

Estimates the numbers of unique molecules in a sequencing library.

This tool outputs quality metrics for a sequencing library preparation.Library complexity refers to the number of unique DNA fragments present in a given library. Reductions in complexity resulting from PCR amplification during library preparation will ultimately compromise downstream analyses via an elevation in the number of duplicate reads. PCR-associated duplication artifacts can result from: inadequate amounts of starting material (genomic DNA, cDNA, etc.), losses during cleanups, and size selection issues. Duplicate reads can also arise from optical duplicates resulting from sequencing-machine optical sensor artifacts.

This tool attempts to estimate library complexity from sequence of read pairs alone. Reads are sorted by the first N bases (5 by default) of the first read and then the first N bases of the second read of a pair. Read pairs are considered to be duplicates if they match each other with no gaps and an overall mismatch rate less than or equal to MAX_DIFF_RATE (0.03 by default). Reads of poor quality are filtered out to provide a more accurate estimate. The filtering removes reads with any poor quality bases as defined by a read's MIN_MEAN_QUALITY (20 is the default value) across either the first or second read. Unpaired reads are ignored in this computation.

The algorithm attempts to detect optical duplicates separately from PCR duplicates and excludes these in the calculation of library size. Also, since there is no alignment information used in this algorithm, an additional filter is applied to the data as follows. After examining all reads, a histogram is built in which the number of reads in a duplicate set is compared with the number of of duplicate sets. All bins that contain exactly one duplicate set are then removed from the histogram as outliers prior to the library size estimation.

Usage example:

java -jar picard.jar EstimateLibraryComplexity \
     I=input.bam \
     O=est_lib_complex_metrics.txt

Converts a FASTQ file to an unaligned BAM or SAM file. This tool extracts read sequences and base qualities from the input FASTQ file and writes them out to a new file in unaligned BAM (uBAM) format. Read group information can be provided on the command line.

Three versions of FASTQ quality scales are supported: FastqSanger, FastqSolexa and FastqIllumina (see http://maq.sourceforge.net/fastq.shtml for details). Input FASTQ files can be in GZip format (with .gz extension).

Usage example:

java -jar picard.jar FastqToSam \
      F1=file_1.fastq \
      O=fastq_to_bam.bam \
      SM=for_tool_testing 

Provides a large, configurable, FIFO buffer that can be used to buffer input and output streams between programs with a buffer size that is larger than that offered by native unix FIFOs (usually 64k).

Finds mendelian violations of all types within a VCF. Takes in VCF or BCF and a pedigree file and looks for high confidence calls where the genotype of the offspring is incompatible with the genotypes of the parents. Assumes the existence of format fields AD, DP, GT, GQ, and PL fields. Take note that the implementation assumes that reads from the PAR will be mapped to the female chromosomerather than the male. This requires that the PAR in the male chromosome be masked so that the aligner has a single coting to map to. This is normally done for the public releases of the human reference. Usage example: java -jar picard.jar FindMendelianViolations I=input.vcf \ TRIO=family.ped \ OUTPUT=mendelian.txt \ MIN_DP=20

Checks if all fingerprints within a set of files appear to come from the same individual. The fingerprints are calculated initially at the readgroup level (if present) but can be "rolled-up" by library, sample or file, to increase power and provide results at the desired resolution. Regular output is in a "Moltenized" format, one row per comparison. In this format the output will include the LOD score and also tumor-aware LOD score which can help assess identity even in the presence of a severe LOH sample with high purity. A matrix output is also available to facilitate visual inspection of crosscheck results. A separate CLP, ClusterCrosscheckMetrics, can cluster the results as a connected graph according to LOD greater than a threshold.

Clusters the results from a CrosscheckFingerprints into groups that are connected according to a large enough LOD score.

Computes a fingerprint from the supplied input file (SAM/BAM or VCF) file and compares it to the expected fingerprint genotypes provided. The key output is a LOD score which represents the relative likelihood of the sequence data originating from the same sample as the genotypes vs. from a random sample. Two outputs are produced: (1) a summary metrics file that gives metrics at the single sample level (if the input was a VCF) or at the read level (lane or index within a lane) (if the input was a SAM/BAM) versus a set of known genotypes for the expected sample, and (2) a detail metrics file that contains an individual SNP/Haplotype comparison within a fingerprint comparison. The two files may be specified individually using the SUMMARY_OUTPUT and DETAIL_OUTPUT options. Alternatively the OUTPUT option may be used instead to give the base of the two output files, with the summary metrics having a file extension 'fingerprinting_summary_metrics' and the detail metrics having a file extension 'fingerprinting_detail_metrics'.

Subset read data from a SAM or BAM fileThis tool takes a SAM or BAM file and subsets it to a new file that either excludes or only includes either aligned or unaligned reads (set using FILTER), or specific reads based on a list of reads names supplied in the READ_LIST_FILE.

Usage example:

java -jar picard.jar FilterSamReads \
       I=input.bam \ 
       O=output.bam \
       READ_LIST_FILE=read_names.txt      FILTER=filter_value

Applies one or more hard filters to a VCF file to filter out genotypes and variants.

Verify mate-pair information between mates and fix if needed.This tool ensures that all mate-pair information is in sync between each read and its mate pair. If no OUTPUT file is supplied then the output is written to a temporary file and then copied over the INPUT file. Reads marked with the secondary alignment flag are written to the output file unchanged.

Usage example:

java -jar picard.jar FixMateInformation \
       I=input.bam \ 
       O=fixed_mate.bam

Concatenate one or more BAM files as efficiently as possibleThis tool performs a rapid "gather" operation on BAM files after scatter operations where the same process has been performed on different regions of a BAM file creating many smaller BAM files that now need to be concatenated (reassembled) back together.

Assumes that the list of BAM files provided as INPUT are in the order that they should be concatenated and simply concatenates the bodies of the BAM files while retaining the header from the first file. Operates via copying of the gzip blocks directly for speed but also supports generation of an MD5 on the output and indexing of the output BAM file. Only supports BAM files, does not support SAM files.

Usage example:

java -jar picard.jar GatherBamFiles \
      I=input1.bam \ 
      I=input2.bam \ 
      O=gathered_files.bam

Gathers multiple VCF files from a scatter operation into a single VCF file. Input files must be supplied in genomic order and must not have events at overlapping positions.

Evaluate genotype concordance between callsets.This tool evaluates the concordance between genotype calls for samples in different callsets where one is being considered as the truth (aka standard, or reference) and the other as the call that is being evaluated for accuracy.

Usage example:

java -jar picard.jar GenotypeConcordance \
      CALL_VCF=input.vcf \
      CALL_SAMPLE=sample_name \
      O=gc_concordance.vcf \
      TRUTH_VCF=truth_set.vcf \
      TRUTH_SAMPLE=truth_sample#

Output Metrics:

• Output metrics include GenotypeConcordanceContingencyMetrics, GenotypeConcordanceSummaryMetrics, and GenotypeConcordanceDetailMetrics. For each set of metrics, the data is broken into separate sections for SNPs and INDELs. Note that only SNP and INDEL variants are considered, MNP, Symbolic, and Mixed classes of variants are not included.
• GenotypeConcordanceContingencyMetrics enumerate the constituents of each contingent in a callset including true-positive (TP), true-negative (TN), false-positive (FP), and false-negative (FN) calls. See http://broadinstitute.github.io/picard/picard-metric-definitions.html#GenotypeConcordanceContingencyMetrics for more details.
• GenotypeConcordanceDetailMetrics include the numbers of SNPs and INDELs for each contingent genotype as well as the number of validated genotypes. See http://broadinstitute.github.io/picard/picard-metric-definitions.html#GenotypeConcordanceDetailMetrics for more details.
• GenotypeConcordanceSummaryMetrics provide specific details for the variant caller performance on a callset including: values for sensitivity, specificity, and positive predictive values. See http://broadinstitute.github.io/picard/picard-metric-definitions.html#GenotypeConcordanceSummaryMetrics for more details.

• Truthset - A callset (typically in VCF format) containing variant calls and genotypes that have been cross-validated with multiple technologies e.g. Genome In A Bottle Consortium (GIAB) (https://sites.stanford.edu/abms/giab)
• TP - True positives are variant calls that match a 'truthset'
• FP - False-positives are reference sites miscalled as variant
• FN - False-negatives are variant sites miscalled as reference
• TN - True negatives are correctly called reference sites
• Validated genotypes - are TP sites where the exact genotype (HET or HOM-VAR) has been validated

VCF Output:

• The concordance state will be stored in the "CONC_ST" tag in the INFO field.
• The truth sample name will be "truth" and call sample name will be "call".

Generate FASTQ file(s) from Illumina basecall read data.

This tool generates FASTQ files from data in an Illumina BaseCalls output directory. Separate FASTQ files are created for each template, barcode, and index (molecular barcode) read. Briefly, the template reads are the target sequence of your experiment, the barcode sequence reads facilitate sample demultiplexing, and the index reads help mitigate instrument phasing errors. For additional information on the read types, please see the following reference here.

In the absence of sample pooling (multiplexing) and/or barcodes, then an OUTPUT_PREFIX (file directory) must be provided as the sample identifier. For multiplexed samples, a MULTIPLEX_PARAMS file must be specified. The MULTIPLEX_PARAMS file contains the list of sample barcodes used to sort template, barcode, and index reads. It is essentially the same as the BARCODE_FILE used in theExtractIlluminaBarcodes tool.

Files from this tool use the following naming format: {prefix}.{type}_{number}.fastq with the {prefix} indicating the sample barcode, the {type} indicating the types of reads e.g. index, barcode, or blank (if it contains a template read). The {number} indicates the read number, either first (1) or second (2) for paired-end sequencing.

Usage examples:

Example 1: Sample(s) with either no barcode or barcoded without multiplexing 
java -jar picard.jar IlluminaBasecallsToFastq \
      READ_STRUCTURE=25T8B25T \
      BASECALLS_DIR=basecallDirectory \
      LANE=001 \
      OUTPUT_PREFIX=noBarcode.1 \
      RUN_BARCODE=run15 \
      FLOWCELL_BARCODE=abcdeACXX 

Example 2: Multiplexed samples 
java -jar picard.jar IlluminaBasecallsToFastq \
      READ_STRUCTURE=25T8B25T \
      BASECALLS_DIR=basecallDirectory \
      LANE=001 \
      MULTIPLEX_PARAMS=demultiplexed_output.txt \
      RUN_BARCODE=run15 \
      FLOWCELL_BARCODE=abcdeACXX 

The FLOWCELL_BARCODE is required if emitting Casava 1.8-style read name headers.

Transforms raw Illumina sequencing data into an unmapped SAM or BAM file.

The IlluminaBaseCallsToSam program collects, demultiplexes, and sorts reads across all of the tiles of a lane via barcode to produce an unmapped SAM/BAM file. An unmapped BAM file is often referred to as a uBAM. All barcode, sample, and library data is provided in the LIBRARY_PARAMS file. Note, this LIBRARY_PARAMS file should be formatted according to the specifications indicated below. The following is an example of a properly formatted LIBRARY_PARAMS file:

The BARCODES_DIR file is produced by the ExtractIlluminaBarcodes tool for each lane of a flow cell.

Usage example:

java -jar picard.jar IlluminaBasecallsToSam \
      BASECALLS_DIR=/BaseCalls/ \
      LANE=001 \
      READ_STRUCTURE=25T8B25T \
      RUN_BARCODE=run15 \
      IGNORE_UNEXPECTED_BARCODES=true \
      LIBRARY_PARAMS=library.params 

Asserts the validity for specified Illumina basecalling data.

This tool will check that the basecall directory and the internal files are available, exist, and are reasonably sized for every tile and cycle. Reasonably sized means non-zero sized for files that exist per tile and equal size for binary files that exist per cycle or per tile. If DATA_TYPES {Position, BaseCalls, QualityScores, PF, or Barcodes} are not specified, then the default data types used by IlluminaBasecallsToSam are used. CheckIlluminaDirectory DOES NOT check that the individual records in a file are well-formed.

Usage example:

java -jar picard.jar CheckIlluminaDirectory \
      BASECALLS_DIR=/BaseCalls/  \
      READ_STRUCTURE=25T8B25T \
      LANES=1 \
      DATA_TYPES=BaseCalls 

Asserts the provided gzip file's (e.g., BAM) last block is well-formed; RC 100 otherwise

Manipulates interval lists. This tool offers multiple interval list file manipulation capabilities include sorting, merging, subtracting, padding, customizing, and other set-theoretic operations. If given one or more inputs, the default operation is to merge and sort them. Other options e.g. interval subtraction are controlled by the arguments. The tool lists intervals with respect to a reference sequence.

Both interval_list and VCF files are accepted as input. The interval_list file format is relatively simple and reflects the SAM alignment format to a degree. A SAM style header must be present in the file that lists the sequence records against which the intervals are described. After the header, the file then contains records, one per line in text format with the following values tab-separated:

     -Sequence name (SN) 
     -Start position (1-based)** 
     -End position (1-based, end inclusive) 
     -Strand (either + or -) 
     -Interval name (ideally unique names for intervals)

Usage example:

java -jar picard.jar IntervalListTools \
      I=input.interval_list \
      SI=input_2.interval_list \
      O=new.interval_list

Lifts over an interval list from one reference build to another. This tool adjusts the coordinates in an interval list derived from one reference to match a new reference, based on a chain file that describes the correspondence between the two references. It is based on the UCSC liftOver tool (see: http://genome.ucsc.edu/cgi-bin/hgLiftOver) and uses a UCSC chain file to guide its operation. It accepts both Picard interval_list files or VCF files as interval inputs.

Usage example:

java -jar picard.jar LiftOverIntervalList \
      I=input.interval_list \
      O=output.interval_list \
      SD=reference_sequence.dict \
      CHAIN=build.chain

Lifts over a VCF file from one reference build to another. This tool adjusts the coordinates of variants within a VCF file to match a new reference. The output file will be sorted and indexed using the target reference build. To be clear, REFERENCE_SEQUENCE should be the target reference build. The tool is based on the UCSC liftOver tool (see: http://genome.ucsc.edu/cgi-bin/hgLiftOver) and uses a UCSC chain file to guide its operation.

Note that records may be rejected because they cannot be lifted over or because of sequence incompatibilities between the source and target reference genomes. Rejected records will be emitted with filters to the REJECT file, using the source genome coordinates.

Usage example:

java -jar picard.jar LiftoverVcf \
     I=input.vcf \
     O=lifted_over.vcf \
     CHAIN=b37tohg19.chain \
     REJECT=rejected_variants.vcf \
     R=reference_sequence.fasta

Reads a VCF/VCF.gz/BCF and removes all genotype information from it while retaining all site level information, including annotations based on genotypes (e.g. AN, AF). Output an be any support variant format including .vcf, .vcf.gz or .bcf.

Identifies duplicate reads.

This tool locates and tags duplicate reads in a BAM or SAM file, where duplicate reads are defined as originating from a single fragment of DNA. Duplicates can arise during sample preparation e.g. library construction using PCR. See also EstimateLibraryComplexity for additional notes on PCR duplication artifacts. Duplicate reads can also result from a single amplification cluster, incorrectly detected as multiple clusters by the optical sensor of the sequencing instrument. These duplication artifacts are referred to as optical duplicates.

The MarkDuplicates tool works by comparing sequences in the 5 prime positions of both reads and read-pairs in a SAM/BAM file. An BARCODE_TAG option is available to facilitate duplicate marking using molecular barcodes. After duplicate reads are collected, the tool differentiates the primary and duplicate reads using an algorithm that ranks reads by the sums of their base-quality scores (default method).

The tool's main output is a new SAM or BAM file, in which duplicates have been identified in the SAM flags field for each read. Duplicates are marked with the hexadecimal value of 0x0400, which corresponds to a decimal value of 1024. If you are not familiar with this type of annotation, please see the following blog post for additional information.

Although the bitwise flag annotation indicates whether a read was marked as a duplicate, it does not identify the type of duplicate. To do this, a new tag called the duplicate type (DT) tag was recently added as an optional output in the 'optional field' section of a SAM/BAM file. Invoking the TAGGING_POLICY option, you can instruct the program to mark all the duplicates (All), only the optical duplicates (OpticalOnly), or no duplicates (DontTag). The records within the output of a SAM/BAM file will have values for the 'DT' tag (depending on the invoked TAGGING_POLICY), as either library/PCR-generated duplicates (LB), or sequencing-platform artifact duplicates (SQ). This tool uses the READ_NAME_REGEX and the OPTICAL_DUPLICATE_PIXEL_DISTANCE options as the primary methods to identify and differentiate duplicate types. Set READ_NAME_REGEX to null to skip optical duplicate detection, e.g. for RNA-seq or other data where duplicate sets are extremely large and estimating library complexity is not an aim. Note that without optical duplicate counts, library size estimation will be inaccurate.

MarkDuplicates also produces a metrics file indicating the numbers of duplicates for both single- and paired-end reads.

The program can take either coordinate-sorted or query-sorted inputs, however the behavior is slightly different. When the input is coordinate-sorted, unmapped mates of mapped records and supplementary/secondary alignments are not marked as duplicates. However, when the input is query-sorted (actually query-grouped), then unmapped mates and secondary/supplementary reads are not excluded from the duplication test and can be marked as duplicate reads.

If desired, duplicates can be removed using the REMOVE_DUPLICATE and REMOVE_SEQUENCING_DUPLICATES options.

Usage example:

java -jar picard.jar MarkDuplicates \
      I=input.bam \
      O=marked_duplicates.bam \
      M=marked_dup_metrics.txt

Identifies duplicate reads, accounting for mate CIGAR. This tool locates and tags duplicate reads (both PCR and optical) in a BAM or SAM file, where duplicate reads are defined as originating from the same original fragment of DNA, taking into account the CIGAR string of read mates.

It is intended as an improvement upon the original MarkDuplicates algorithm, from which it differs in several ways, includingdifferences in how it breaks ties. It may be the most effective duplicate marking program available, as it handles all cases including clipped and gapped alignments and locates duplicate molecules using mate cigar information. However, please note that it is not yet used in the Broad's production pipeline, so use it at your own risk.

Note also that this tool will not work with alignments that have large gaps or deletions, such as those from RNA-seq data. This is due to the need to buffer small genomic windows to ensure integrity of the duplicate marking, while large skips (ex. skipping introns) in the alignment records would force making that window very large, thus exhausting memory.

Note: Metrics labeled as percentages are actually expressed as fractions!

Usage example:

java -jar picard.jar MarkDuplicatesWithMateCigar \
      I=input.bam \
      O=mark_dups_w_mate_cig.bam \
      M=mark_dups_w_mate_cig_metrics.txt

Collect mean quality by cycle.This tool generates a data table and chart of mean quality by cycle from a BAM file. It is intended to be used on a single lane or a read group's worth of data, but can be applied to merged BAMs if needed.

This metric gives an overall snapshot of sequencing machine performance. For most types of sequencing data, the output is expected to show a slight reduction in overall base quality scores towards the end of each read. Spikes in quality within reads are not expected and may indicate that technical problems occurred during sequencing.

Note: Metrics labeled as percentages are actually expressed as fractions!

Usage example:

java -jar picard.jar MeanQualityByCycle \
      I=input.bam \
      O=mean_qual_by_cycle.txt \
      CHART=mean_qual_by_cycle.pdf

Merge alignment data from a SAM or BAM with data in an unmapped BAM file. This tool produces a new SAM or BAM file that includes all aligned and unaligned reads and also carries forward additional read attributes from the unmapped BAM (attributes that are otherwise lost in the process of alignment). The purpose of this tool is to use information from the unmapped BAM to fix up aligner output. The resulting file will be valid for use by other Picard tools. For simple BAM file merges, use MergeSamFiles. Note that MergeBamAlignment expects to find a sequence dictionary in the same directory as REFERENCE_SEQUENCE and expects it to have the same base name as the reference FASTA except with the extension ".dict". If the output sort order is not coordinate, then reads that are clipped due to adapters or overlapping will not contain the NM, MD, or UQ tags.

Usage example:

java -jar picard.jar MergeBamAlignment \
       ALIGNED=aligned.bam \ 
       UNMAPPED=unmapped.bam \ 
       O=merge_alignments.bam \
       R=reference_sequence.fasta

Merges multiple SAM and/or BAM files into a single file. This tool is used for combining SAM and/or BAM files from different runs or read groups, similarly to the "merge" function of Samtools (http://www.htslib.org/doc/samtools.html).

Note that to prevent errors in downstream processing, it is critical to identify/label read groups appropriately. If different samples contain identical read group IDs, this tool will avoid collisions by modifying the read group IDs to be unique. For more information about read groups, see the GATK Dictionary entry.

Usage example:

java -jar picard.jar MergeSamFiles \
      I=input_1.bam \
      I=input_2.bam \
      O=merged_files.bam

Merges multiple VCF or BCF files into one VCF file. Input files must be sorted by their contigs and, within contigs, by start position. The input files must have the same sample and contig lists. An index file is created and a sequence dictionary is required by default.

Normalizes lines of sequence in a FASTA file to be of the same length.This tool takes any FASTA-formatted file and reformats the sequence to ensure that all of the sequence record lines are of the same length (with the exception of the last line). Although the default setting is 100 bases per line, a custom line_length can be specified by the user. In addition, record names can be truncated at the first instance of a whitespace character to ensure downstream compatibility.

Usage example:

java -jar picard.jar NormalizeFasta \
      I=input_sequence.fasta \
      O=normalized_sequence.fasta

Class to downsample a BAM file while respecting that we should either get rid of both ends of a pair or neither end of the pair. In addition, this program uses the read-name and extracts the position within the tile whence the read came from. The downsampling is based on this position. Results with the exact same input will produce the same results. Note 1: This is technology and read-name dependent. If your read-names do not have coordinate information, or if your BAM contains reads from multiple technologies (flowcell versions, sequencing machines) this will not work properly. This has been designed with Illumina MiSeq/HiSeq in mind. Note 2: The downsampling is not random. It is deterministically dependent on the position of the read within its tile. Note 3: Downsampling twice with this program is not supported. Note 4: You should call MarkDuplicates after downsampling. Finally, the code has been designed to simulate sequencing less as accurately as possible, not for getting an exact downsample fraction. In particular, since the reads may be distributed non-evenly within the lanes/tiles, the resulting downsampling percentage will not be accurately determined by the input argument FRACTION.

Subsets intervals from a reference sequence to a new FASTA file.This tool takes a list of intervals, reads the corresponding subsquences from a reference FASTA file and writes them to a new FASTA file as separate records. Note that the reference FASTA file must be accompanied by an index file and the interval list must be provided in Picard list format. The names provided for the intervals will be used to name the corresponding records in the output file.

Usage example:

java -jar picard.jar ExtractSequences \
      INTERVAL_LIST=regions_of_interest.interval_list \
      R=reference.fasta \
      O=extracted_IL_sequences.fasta

Chart the distribution of quality scores.

This tool is used for determining the overall 'quality' for a library in a given run. To that effect, it outputs a chart and tables indicating the range of quality scores and the total numbers of bases corresponding to those scores. Options include plotting the distribution of all of the reads, only the aligned reads, or reads that have passed the Illumina Chastity filter thresholds as described here.

Note on base quality score options

Note: Metrics labeled as percentages are actually expressed as fractions!

Usage Example:

java -jar picard.jar QualityScoreDistribution \
      I=input.bam \
      O=qual_score_dist.txt \
      CHART=qual_score_dist.pdf

Renames a sample within a VCF or BCF. This tool enables the user to rename a sample in either a VCF or BCF file. It is intended to change the name of a sample in a VCF prior to merging with VCF files in which one or more samples have similar names. Note that the input VCF file must be single-sample VCF and that the NEW_SAMPLE_NAME is required.

Usage example:

java -jar picard.jar RenameSampleInVcf \
      I=input.vcf \
      O=renamed.vcf \
      NEW_SAMPLE_NAME=sample123

Not to be confused with SortSam which sorts a SAM or BAM file with a valid sequence dictionary, ReorderSam reorders reads in a SAM/BAM file to match the contig ordering in a provided reference file, as determined by exact name matching of contigs. Reads mapped to contigs absent in the new reference are dropped. Runs substantially faster if the input is an indexed BAM file.

Replaces the SAMFileHeader in a SAM or BAM file. This tool makes it possible to replace the header of a SAM or BAM file with the header of anotherfile, or a header block that has been edited manually (in a stub SAM file). The sort order (@SO) of the two input files must be the same.

Note that validation is minimal, so it is up to the user to ensure that all the elements referred to in the SAMRecords are present in the new header.

Usage example:

java -jar picard.jar ReplaceSamHeader \
      I=input_1.bam \
      HEADER=input_2.bam \
      O=bam_with_new_head.bam

Reverts SAM or BAM files to a previous state. This tool removes or restores certain properties of the SAM records, including alignment information, which can be used to produce an unmapped BAM (uBAM) from a previously aligned BAM. It is also capable of restoring the original quality scores of a BAM file that has already undergone base quality score recalibration (BQSR) if theoriginal qualities were retained.

Example with single output:

java -jar picard.jar RevertSam \
     I=input.bam \
     O=reverted.bam

Example outputting by read group with output map:

java -jar picard.jar RevertSam \
     I=input.bam \
     OUTPUT_BY_READGROUP=true \
     OUTPUT_MAP=reverted_bam_paths.tsv

Example outputting by read group without output map:

java -jar picard.jar RevertSam \
     I=input.bam \
     OUTPUT_BY_READGROUP=true \
     O=/write/reverted/read/group/bams/in/this/dir

Note: If the program fails due to a SAM validation error, consider setting the VALIDATION_STRINGENCY option to LENIENT or SILENT if the failures are expected to be obviated by the reversion process (e.g. invalid alignment information will be obviated when the REMOVE_ALIGNMENT_INFORMATION option is used).

Reverts the original base qualities and adds the mate cigar tag to read-group BAMs.

Convert a BAM file to a SAM file, or SAM to BAM. Input and output formats are determined by file extension.

Converts a SAM or BAM file to FASTQ. This tool extracts read sequences and base quality scores from the input SAM/BAM file and outputs them in FASTQ format. This can be used by way of a pipe to run BWA MEM on unmapped BAM (uBAM) files efficiently.

Usage example:

java -jar picard.jar SamToFastq \
     I=input.bam \
     FASTQ=output.fastq

Writes an interval list based on splitting a reference by Ns. This tool identifies positions in a reference where the bases are 'no-calls' and writes out an interval-list using the resulting coordinates. This can be used to create an interval list for whole genome sequence (WGS) for e.g. scatter-gather purposes, as an alternative to using fixed-length intervals. The number of contiguous nocalls that can be tolerated before creating a break is adjustable from the command line.

Usage example:

java -jar picard.jar ScatterIntervalsByNs \
      R=reference_sequence.fasta \
      OT=BOTH \
      O=output.interval_list

Fixes the NM, MD, and UQ tags in a SAM file. This tool takes in a SAM or BAM file (sorted by coordinate) and calculates the NM, MD, and UQ tags by comparing with the reference.
This may be needed when MergeBamAlignment was run with SORT_ORDER different from 'coordinate' and thus could not fix these tags then.

Usage example:

java -jar picard.jar SetNmMDAndUqTags \
      I=sorted.bam \
      O=fixed.bam \

Sorts a SAM or BAM file. This tool sorts the input SAM or BAM file by coordinate, queryname (QNAME), or some other property of the SAM record. The SortOrder of a SAM/BAM file is found in the SAM file header tag @HD in the field labeled SO.

For a coordinate sorted SAM/BAM file, read alignments are sorted first by the reference sequence name (RNAME) field using the reference sequence dictionary (@SQ tag). Alignments within these subgroups are secondarily sorted using the left-most mapping position of the read (POS). Subsequent to this sorting scheme, alignments are listed arbitrarily.

Usage example:

java -jar picard.jar SortSam \
      I=input.bam \
      O=sorted.bam \
      SORT_ORDER=coordinate

Sorts one or more VCF files. This tool sorts the records in VCF files according to the order of the contigs in the header/sequence dictionary and then by coordinate. It can accept an external sequence dictionary. If no external dictionary is supplied, the VCF file headers of multiple inputs must have the same sequence dictionaries.

If running on multiple inputs (originating from e.g. some scatter-gather runs), the input files must contain the same sample names in the same column order.

Usage example:

java -jar picard.jar SortVcf \
      I=vcf_1.vcf \
      I=vcf_2.vcf \
      O=sorted.vcf

Takes a SAM or BAM file and separates all the reads into one SAM or BAM file per library name. Reads that do not have a read group specified or whose read group does not have a library name are written to a file called 'unknown.' The format (SAM or BAM) of the output files matches that of the input file.

Identifies duplicate reads using information from read positions and UMIs.

This tool locates and tags duplicate reads in a BAM or SAM file, where duplicate reads are defined as originating from a single fragment of DNA. It is based on the MarkDuplicatesWithMateCigar tool, with added logic to leverage Unique Molecular Identifier (UMI) information.

In addition to assuming that all members of a duplicate set must have the same start and end position, it imposes thatthey must also have sufficiently similar UMIs. In this context, 'sufficiently similar' is parameterized by the command line argument MAX_EDIT_DISTANCE_TO_JOIN, which sets the edit distance between UMIs that will be considered to be part of the same original molecule. This logic allows for sequencing errors in UMIs.

This tool is NOT intended to be used on data without UMIs; for marking duplicates in non-UMI data, see MarkDuplicates or MarkDuplicatesWithMateCigar. Mixed data (where some reads have UMIs and others do not) is not supported.

Takes a VCF and a second file that contains a sequence dictionary and updates the VCF with the new sequence dictionary.

Converts VCF to BCF or BCF to VCF. This tool converts files between the plain-text VCF format and its binary compressed equivalent, BCF. Input and output formats are determined by file extensions specified in the file names. For best results, it is recommended to ensure that an index file is present and set the REQUIRE_INDEX option to true.

Usage example:

java -jar picard.jar VcfFormatConverter \
      I=input.vcf \
      O=output.bcf \
      REQUIRE_INDEX=true

Reads a SAM or BAM file and rewrites it with new adapter-trimming tags.

This tool clears any existing adapter-trimming tags (XT:i:) in the optional tag region of a SAM file. The SAM/BAM file must be sorted by query name.

Outputs a metrics file histogram showing counts of bases_clipped per read.

Usage example:

java -jar picard.jar MarkIlluminaAdapters \
 INPUT=input.sam \
METRICS=metrics.txt 

Splits SNPs and INDELs into separate files. This tool reads in a VCF or BCF file and writes out the SNPs and INDELs it contains to separate files. The headers of the two output files will be identical and index files will be created for both outputs. If records other than SNPs or INDELs are present, set the STRICT option to "false", otherwise the tool will raise an exception and quit.

Usage example:

java -jar picard.jar SplitVcfs \
      I=input.vcf \
      SNP_OUTPUT=snp.vcf \
      INDEL_OUTPUT=indel.vcf \
      STRICT=false

Validates a SAM or BAM file.

This tool reports on the validity of a SAM or BAM file relative to the SAM format specification. This is useful for troubleshooting errors encountered with other tools that may be caused by improper formatting, faulty alignments, incorrect flag values, etc.

By default, the tool runs in VERBOSE mode and will exit after finding 100 errors and output them to the console (stdout). Therefore, it is often more practical to run this tool initially using the MODE=SUMMARY option. This mode outputs a summary table listing the numbers of all 'errors' and 'warnings'.

When fixing errors in your file, it is often useful to prioritize the severe validation errors and ignore the errors/warnings of lesser concern. This can be done using the IGNORE and/or IGNORE_WARNINGS arguments. For helpful suggestions on error prioritization, please follow this link to obtain additional documentation on ValidateSamFile.

After identifying and fixing your 'warnings/errors', we recommend that you rerun this tool to validate your SAM/BAM file prior to proceeding with your downstream analysis. This will verify that all problems in your file have been addressed.

Usage example:

java -jar picard.jar ValidateSamFile \
      I=input.bam \
      MODE=SUMMARY

To obtain a complete list with descriptions of both 'ERROR' and 'WARNING' messages, please see our additional documentation for this tool.

Prints a SAM or BAM file to the screen.

Converts a VCF or BCF file to a Picard Interval List.