Subsets reads from a SAM or BAM file by applying one of several filters.
Takes a SAM or BAM file and subsets it by either excluding or only including certain reads such as aligned or unaligned reads, specific reads based on a list of reads names, an interval list, by Tag Values (type Z / String values only), or using a JavaScript script.
Usage example:
Filter by queryname
java -jar picard.jar FilterSamReads \
I=input.bam \
O=output.bam \
READ_LIST_FILE=read_names.txt \
FILTER=includeReadList
Filter by interval
java -jar picard.jar FilterSamReads \
I=input.bam \
O=output.bam \
INTERVAL_LIST=regions.interval_list \
FILTER=includePairedIntervals
Filter by Tag Value (type Z / String values only)
java -jar picard.jar FilterSamReads \
I=input.bam \
O=output.bam \
TAG=CR \
TAG_VALUE=TTTGTCATCTCGAGTA \
FILTER=includeTagValues
Filter reads having a soft clip on the beginning of the read larger than 2 bases with a JavaScript script
cat < script.js
/** reads having a soft clip larger than 2 bases in beginning of read*/
function accept(rec) {
if (rec.getReadUnmappedFlag()) return false;
var cigar = rec.getCigar();
if (cigar == null) return false;
var ce = cigar.getCigarElement(0);
return ce.getOperator().name() == "S" && ce.length() > 2;
}
accept(record);
EOF
java -jar picard.jar FilterSamReads \
I=input.bam \
O=output.bam \
JAVASCRIPT_FILE=script.js \
FILTER=includeJavascript
Category Read Data Manipulation
Overview
Summary
Subsets a SAM file by either selecting or excluding certain reads
Details
Subsets a SAM or BAM file by either excluding or selecting reads as specified by FILTER. Other parameters influence the behavior of the FILTER algorithm as described below.
Usage examples
Filter by queryname:
java -jar picard.jar FilterSamReads \ I=input.bam \ O=output.bam \ READ_LIST_FILE=read_names.txt \ FILTER=includeReadList
Filter by interval:
java -jar picard.jar FilterSamReads \ I=input.bam \ O=output.bam \ INTERVAL_LIST=regions.interval_list \ FILTER=includePairedIntervals
Filter reads having a (2-base or more) soft clip on the beginning of the read:
cat < script.js // reads having a soft clip larger than 2 bases in start of read function accept(rec) { if (rec.getReadUnmappedFlag()) return false; var cigar = rec.getCigar(); if (cigar == null) return false; var ce = cigar.getCigarElement(0); return ce.getOperator().name() == "S" && ce.length() > 2; } accept(record); EOF java -jar picard.jar FilterSamReads \ I=input.bam \ O=output.bam \ JAVASCRIPT_FILE=script.js \ FILTER=includeJavascript
FilterSamReads (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 | |||
--FILTER |
Which filter to use. | ||
--INPUT -I |
The SAM or BAM file that will be filtered. | ||
--OUTPUT -O |
SAM or BAM file for resulting reads. | ||
Optional Tool Arguments | |||
--arguments_file |
read one or more arguments files and add them to the command line | ||
--help -h |
false | display the help message | |
--INTERVAL_LIST -IL |
Interval List File containing intervals that will be included in the OUTPUT when using FILTER=includePairedIntervals | ||
--JAVASCRIPT_FILE -JS |
Filters the INPUT with a javascript expression using the java javascript-engine, when using FILTER=includeJavascript. The script puts the following variables in the script context: 'record' a SamRecord ( https://samtools.github.io/htsjdk/javadoc/htsjdk/htsjdk/samtools/SAMRecord.html ) and 'header' a SAMFileHeader ( https://samtools.github.io/htsjdk/javadoc/htsjdk/htsjdk/samtools/SAMFileHeader.html ). all the public members of SamRecord and SAMFileHeader are accessible. A record is accepted if the last value of the script evaluates to true. | ||
--READ_LIST_FILE -RLF |
File containing reads that will be included in or excluded from the OUTPUT SAM or BAM file, when using FILTER=includeReadList or FILTER=excludeReadList. | ||
--SORT_ORDER -SO |
SortOrder of the OUTPUT file, otherwise use the SortOrder of the INPUT file. | ||
--TAG -T |
The tag to select from input SAM/BAM | ||
--TAG_VALUE -TV |
The tag value(s) to filter by | ||
--version |
false | display the version number for this tool | |
--WRITE_READS_FILES |
false | Create .reads file containing names of reads from INPUT and OUTPUT (for debugging purposes.) | |
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] []
--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
--FILTER
Which filter to use.
The --FILTER argument is an enumerated type (Filter), which can have one of the following values:
- includeAligned
- Output aligned reads only. INPUT SAM/BAM must be in queryname SortOrder. (Note: first and second of paired reads must both be aligned to be included in OUTPUT.)
- excludeAligned
- Output Unmapped reads only. INPUT SAM/BAM must be in queryname SortOrder. (Note: first and second of pair must both be aligned to be excluded from OUTPUT.)
- includeReadList
- Output reads with names contained in READ_LIST_FILE. See READ_LIST_FILE for more detail.
- excludeReadList
- Output reads with names *not* contained in READ_LIST_FILE. See READ_LIST_FILE for more detail.
- includeJavascript
- Output reads that have been accepted by the JAVASCRIPT_FILE script, that is, reads for which the value of the script is true. See the JAVASCRIPT_FILE argument for more detail.
- includePairedIntervals
- Output reads that overlap with an interval from INTERVAL_LIST (and their mate). INPUT must be coordinate sorted.
- includeTagValues
- OUTPUT SAM/BAM will contain reads that have a value of tag TAG that is contained in the values for TAG_VALUES
- excludeTagValues
- OUTPUT SAM/BAM will contain reads that do not have a value of tag TAG that is contained in the values for TAG_VALUES
R Filter null
--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 SAM or BAM file that will be filtered.
R File null
--INTERVAL_LIST / -IL
Interval List File containing intervals that will be included in the OUTPUT when using FILTER=includePairedIntervals
File null
--JAVASCRIPT_FILE / -JS
Filters the INPUT with a javascript expression using the java javascript-engine, when using FILTER=includeJavascript. The script puts the following variables in the script context:
'record' a SamRecord ( https://samtools.github.io/htsjdk/javadoc/htsjdk/htsjdk/samtools/SAMRecord.html ) and
'header' a SAMFileHeader ( https://samtools.github.io/htsjdk/javadoc/htsjdk/htsjdk/samtools/SAMFileHeader.html ).
all the public members of SamRecord and SAMFileHeader are accessible. A record is accepted if the last value of the script evaluates to true.
File null
--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
SAM or BAM file for resulting reads.
R File null
--QUIET
Whether to suppress job-summary info on System.err.
Boolean false
--READ_LIST_FILE / -RLF
File containing reads that will be included in or excluded from the OUTPUT SAM or BAM file, when using FILTER=includeReadList or FILTER=excludeReadList.
File null
--REFERENCE_SEQUENCE / -R
Reference sequence file.
File null
--showHidden / -showHidden
display hidden arguments
boolean false
--SORT_ORDER / -SO
SortOrder of the OUTPUT file, otherwise use the SortOrder of the INPUT file.
The --SORT_ORDER argument is an enumerated type (SortOrder), which can have one of the following values:
- unsorted
- queryname
- coordinate
- duplicate
- unknown
SortOrder null
--TAG / -T
The tag to select from input SAM/BAM
String null
--TAG_VALUE / -TV
The tag value(s) to filter by
List[String] []
--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
--WRITE_READS_FILES
Create .reads file containing names of reads from INPUT and OUTPUT (for debugging purposes.)
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.