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.bamExample 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/dirThis 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 |
The input SAM/BAM file to revert the state of. | ||
--OUTPUT -O |
The output SAM/BAM file to create, or an output directory if OUTPUT_BY_READGROUP is true. | ||
--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. | ||
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 |
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_HARDCLIPS -RHC |
true | When true, restores reads and qualities of records with hard-clips containing XB and XQ tags. | |
--RESTORE_ORIGINAL_QUALITIES -OQ |
true | True to restore original qualities from the OQ field to the QUAL field if available. | |
--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. | ||
--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 an index when writing VCF or coordinate sorted BAM output. | |
--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 |
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
read one or more arguments files and add them to the command line
List[File] []
--ATTRIBUTE_TO_CLEAR
When removing alignment information, the set of optional tags to remove.
List[String] [NM, UQ, PG, MD, MQ, SA, MC, AS]
--COMPRESSION_LEVEL
Compression level for all compressed files created (e.g. BAM and VCF).
int 5 [ [ -∞ ∞ ] ]
--CREATE_INDEX
Whether to create an index when writing VCF or coordinate sorted BAM output.
Boolean false
--CREATE_MD5_FILE
Whether to create an MD5 digest for any BAM or FASTQ files created.
boolean false
--GA4GH_CLIENT_SECRETS
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
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
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
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
.
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
- Generate SAM files.
- bam
- Generate BAM files.
- cram
- Generate CRAM files.
- dynamic
- Generate files based on the extention of INPUT.
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
Whether to suppress job-summary info on System.err.
Boolean false
--REFERENCE_SEQUENCE / -R
Reference sequence file.
File null
--REMOVE_ALIGNMENT_INFORMATION
Remove all alignment information from the file.
boolean true
--REMOVE_DUPLICATE_INFORMATION
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_HARDCLIPS / -RHC
When true, restores reads and qualities of records with hard-clips containing XB and XQ tags.
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
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
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
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
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
display the version number for this tool
boolean false
GATK version 4.2.4.0-SNAPSHOT built at Thu, 16 Dec 2021 11:57:48 -0800.
0 comments
Please sign in to leave a comment.