Showing tool doc from version 4.6.2.0 | The latest version is
4.6.2.0

FilterSamReads (Picard)

Subsets reads from a SAM/BAM/CRAM file by applying one of several filters. Takes a SAM/BAM/CRAM 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/BAM/CRAM file that will be filtered.
--OUTPUT
 -O 		SAM/BAM/CRAM 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/BAM/CRAM 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.
--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/CRAM 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/CRAM 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 reads that have a value of tag TAG that is contained in the values for TAG_VALUES
excludeTagValues
Output reads that do not have a value of tag TAG that is contained in the values for TAG_VALUES

R Filter  null

--help / -h

display the help message

boolean  false

--INPUT / -I

The SAM/BAM/CRAM 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/BAM/CRAM 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/BAM/CRAM file, when using FILTER=includeReadList or FILTER=excludeReadList.

File  null

--REFERENCE_SEQUENCE / -R

Reference sequence file.

PicardHtsPath  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

Return to top

See also General Documentation | Tool Docs Index Tool Documentation Index | Support Forum

GATK version 4.6.2.0 built at Sun, 13 Apr 2025 13:21:43 -0400.