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.

Examples

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 Will output a BAM/SAM file per read group.

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 Will output a BAM file per read group. Output format can be overridden with the OUTPUT_BY_READGROUP_FILE_FORMAT option. 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).

Category Read Data Manipulation

---

Overview

Reverts a SAM file by optionally restoring original quality scores and by removing all alignment information.

This tool removes or restores certain properties of the SAM records, including alignment information. It 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 the original qualities were retained during the calibration (in the OQ tag).

Usage Examples

Output to a single file

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

Output by read group into multiple files with sample map

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

Output by read group with no output map

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

This will output a BAM (Can be overridden with OUTPUT_BY_READGROUP_FILE_FORMAT option.)
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).

RevertSam (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
--INPUT  -I	null	The input SAM/BAM file to revert the state of.
--OUTPUT  -O	null	The output SAM/BAM file to create, or an output directory if OUTPUT_BY_READGROUP is true.
--OUTPUT_MAP  -OM	null	Tab separated file with two columns, READ_GROUP_ID and OUTPUT, providing file mapping only used if OUTPUT_BY_READGROUP is true.
Optional Tool Arguments
--arguments_file	[]	read one or more arguments files and add them to the command line
--ATTRIBUTE_TO_CLEAR	[NM, UQ, PG, MD, MQ, SA, MC, AS]	When removing alignment information, the set of optional tags to remove.
--help  -h	false	display the help message
--KEEP_FIRST_DUPLICATE	false	If SANITIZE=true keep the first record when we find more than one record with the same name for R1/R2/unpaired reads respectively. For paired end reads, keeps only the first R1 and R2 found respectively, and discards all unpaired reads. Duplicates do not refer to the duplicate flag in the FLAG field, but instead reads with the same name.
--LIBRARY_NAME  -LIB	null	The library name to use in the reverted output file. This will override the existing sample alias in the file and is used only if all the read groups in the input file have the same library name.
--MAX_DISCARD_FRACTION	0.01	If SANITIZE=true and higher than MAX_DISCARD_FRACTION reads are discarded due to sanitization thenthe program will exit with an Exception instead of exiting cleanly. Output BAM will still be valid.
--OUTPUT_BY_READGROUP  -OBR	false	When true, outputs each read group in a separate file.
--OUTPUT_BY_READGROUP_FILE_FORMAT  -OBRFF	dynamic	When using OUTPUT_BY_READGROUP, the output file format can be set to a certain format.
--REMOVE_ALIGNMENT_INFORMATION	true	Remove all alignment information from the file.
--REMOVE_DUPLICATE_INFORMATION	true	Remove duplicate read flags from all reads. Note that if this is false and REMOVE_ALIGNMENT_INFORMATION==true, the output may have the unusual but sometimes desirable trait of having unmapped reads that are marked as duplicates.
--RESTORE_ORIGINAL_QUALITIES  -OQ	true	True to restore original qualities from the OQ field to the QUAL field if available.
--SAMPLE_ALIAS  -ALIAS	null	The sample alias to use in the reverted output file. This will override the existing sample alias in the file and is used only if all the read groups in the input file have the same sample alias.
--SANITIZE	false	WARNING: This option is potentially destructive. If enabled will discard reads in order to produce a consistent output BAM. Reads discarded include (but are not limited to) paired reads with missing mates, duplicated records, records with mismatches in length of bases and qualities. This option can only be enabled if the output sort order is queryname and will always cause sorting to occur.
--SORT_ORDER  -SO	queryname	The sort order to create the reverted output file with.
--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]  []

---

--ATTRIBUTE_TO_CLEAR / NA

When removing alignment information, the set of optional tags to remove.

List[String]  [NM, UQ, PG, MD, MQ, SA, MC, AS]

---

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

---

--INPUT / -I

The input SAM/BAM file to revert the state of.

R File  null

---

--KEEP_FIRST_DUPLICATE / NA

If SANITIZE=true keep the first record when we find more than one record with the same name for R1/R2/unpaired reads respectively. For paired end reads, keeps only the first R1 and R2 found respectively, and discards all unpaired reads. Duplicates do not refer to the duplicate flag in the FLAG field, but instead reads with the same name.

boolean  false

---

--LIBRARY_NAME / -LIB

The library name to use in the reverted output file. This will override the existing sample alias in the file and is used only if all the read groups in the input file have the same library name.

String  null

---

--MAX_DISCARD_FRACTION / NA

If SANITIZE=true and higher than MAX_DISCARD_FRACTION reads are discarded due to sanitization thenthe program will exit with an Exception instead of exiting cleanly. Output BAM will still be valid.

double  0.01  [ [ -∞  ∞ ] ]

---

--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  [ [ -∞  ∞ ] ]

---

--OUTPUT / -O

The output SAM/BAM file to create, or an output directory if OUTPUT_BY_READGROUP is true.

Exclusion: This argument cannot be used at the same time as OUTPUT_MAP, OM.

R File  null

---

--OUTPUT_BY_READGROUP / -OBR

When true, outputs each read group in a separate file.

boolean  false

---

--OUTPUT_BY_READGROUP_FILE_FORMAT / -OBRFF

When using OUTPUT_BY_READGROUP, the output file format can be set to a certain format.

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

sam

bam

cram

dynamic

FileType  dynamic

---

--OUTPUT_MAP / -OM

Tab separated file with two columns, READ_GROUP_ID and OUTPUT, providing file mapping only used if OUTPUT_BY_READGROUP is true.

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

R File  null

---

--QUIET / NA

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

Boolean  false

---

--REFERENCE_SEQUENCE / -R

Reference sequence file.

File  null

---

--REMOVE_ALIGNMENT_INFORMATION / NA

Remove all alignment information from the file.

boolean  true

---

--REMOVE_DUPLICATE_INFORMATION / NA

Remove duplicate read flags from all reads. Note that if this is false and REMOVE_ALIGNMENT_INFORMATION==true, the output may have the unusual but sometimes desirable trait of having unmapped reads that are marked as duplicates.

boolean  true

---

--RESTORE_ORIGINAL_QUALITIES / -OQ

True to restore original qualities from the OQ field to the QUAL field if available.

boolean  true

---

--SAMPLE_ALIAS / -ALIAS

The sample alias to use in the reverted output file. This will override the existing sample alias in the file and is used only if all the read groups in the input file have the same sample alias.

String  null

---

--SANITIZE / NA

WARNING: This option is potentially destructive. If enabled will discard reads in order to produce a consistent output BAM. Reads discarded include (but are not limited to) paired reads with missing mates, duplicated records, records with mismatches in length of bases and qualities. This option can only be enabled if the output sort order is queryname and will always cause sorting to occur.

boolean  false

---

--showHidden / -showHidden

display hidden arguments

boolean  false

---

--SORT_ORDER / -SO

The sort order to create the reverted output file with.

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

unsorted

queryname

coordinate

duplicate

unknown

SortOrder  queryname

---

--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.0.0 built at Sat, 23 Nov 2019 17:12:18 -0500.