Package picard.sam

# Class FilterSamReads

java.lang.Object
picard.cmdline.CommandLineProgram
picard.sam.FilterSamReads

@DocumentedFeature public class FilterSamReads extends CommandLineProgram

### 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 invalid input: '<'<EOF> 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" invalid input: '&'invalid input: '&' ce.length() > 2;
     }

     accept(record);
     EOF

     java -jar picard.jar FilterSamReads \
           I=input.bam \
           O=output.bam \
           JAVASCRIPT_FILE=script.js \
           FILTER=includeJavascript

## Nested Class Summary

Nested Classes
Modifier and Type
Class
Description
`protected static enum`
`FilterSamReads.Filter`

## Field Summary

Fields
Modifier and Type
Field
Description
`FilterSamReads.Filter`
`FILTER`
`File`
`INPUT`
`File`
`INTERVAL_LIST`
`File`
`JAVASCRIPT_FILE`
`File`
`OUTPUT`
`File`
`READ_LIST_FILE`
`htsjdk.samtools.SAMFileHeader.SortOrder`
`SORT_ORDER`
`String`
`TAG`
`List<String>`
`TAG_VALUE`
`boolean`
`WRITE_READS_FILES`

### Fields inherited from class picard.cmdline.CommandLineProgram

`COMPRESSION_LEVEL, CREATE_INDEX, CREATE_MD5_FILE, MAX_ALLOWABLE_ONE_LINE_SUMMARY_LENGTH, MAX_RECORDS_IN_RAM, QUIET, REFERENCE_SEQUENCE, referenceSequence, specialArgumentsCollection, SYNTAX_TRANSITION_URL, TMP_DIR, USE_JDK_DEFLATER, USE_JDK_INFLATER, VALIDATION_STRINGENCY, VERBOSITY`

## Constructor Summary

Constructors
Constructor
Description
`FilterSamReads()`

## Method Summary

Modifier and Type
Method
Description
`protected String[]`
`customCommandLineValidation()`
Put any custom command-line validation in an override of this method.
`protected int`
`doWork()`
Do the work after command line has been parsed.

### Methods inherited from class picard.cmdline.CommandLineProgram

`checkRInstallation, getCommandLine, getCommandLineParser, getCommandLineParserForArgs, getDefaultHeaders, getFaqLink, getMetricsFile, getPGRecord, getStandardUsagePreamble, getStandardUsagePreamble, getVersion, hasWebDocumentation, instanceMain, instanceMainWithExit, makeReferenceArgumentCollection, parseArgs, requiresReference, setDefaultHeaders, useLegacyParser`

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

## Field Details

### INPUT

@Argument(doc="The SAM/BAM/CRAM file that will be filtered.", shortName="I") public File INPUT

### FILTER

@Argument(doc="Which filter to use.") public FilterSamReads.Filter FILTER

### READ_LIST_FILE

@Argument(doc="File containing reads that will be included in or excluded from the OUTPUT SAM/BAM/CRAM file, when using FILTER=includeReadList or FILTER=excludeReadList.", optional=true, shortName="RLF") public File READ_LIST_FILE

### INTERVAL_LIST

@Argument(doc="Interval List File containing intervals that will be included in the OUTPUT when using FILTER=includePairedIntervals", optional=true, shortName="IL") public File INTERVAL_LIST

### TAG

@Argument(doc="The tag to select from input SAM/BAM", optional=true, shortName="T") public String TAG

### TAG_VALUE

@Argument(doc="The tag value(s) to filter by", optional=true, shortName="TV") public List<String> TAG_VALUE

### SORT_ORDER

@Argument(doc="SortOrder of the OUTPUT file, otherwise use the SortOrder of the INPUT file.", optional=true, shortName="SO") public htsjdk.samtools.SAMFileHeader.SortOrder SORT_ORDER

### OUTPUT

@Argument(doc="SAM/BAM/CRAM file for resulting reads.", shortName="O") public File OUTPUT

### JAVASCRIPT_FILE

@Argument(shortName="JS", doc="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: \n \'record\' a SamRecord ( https://samtools.github.io/htsjdk/javadoc/htsjdk/htsjdk/samtools/SAMRecord.html ) and \n \'header\' a SAMFileHeader ( https://samtools.github.io/htsjdk/javadoc/htsjdk/htsjdk/samtools/SAMFileHeader.html ).\n all the public members of SamRecord and SAMFileHeader are accessible. A record is accepted if the last value of the script evaluates to true.", optional=true) public File JAVASCRIPT_FILE

### WRITE_READS_FILES

@Argument(doc="Create <OUTPUT>.reads file containing names of reads from INPUT and OUTPUT (for debugging purposes.)", optional=true) public boolean WRITE_READS_FILES

## Constructor Details

### FilterSamReads

public FilterSamReads()

## Method Details

### doWork

protected int doWork()
Description copied from class: `CommandLineProgram`
Do the work after command line has been parsed. RuntimeException may be thrown by this method, and are reported appropriately.

Specified by:
  `doWork` in class `CommandLineProgram`
Returns:
  program exit status.

### customCommandLineValidation

protected String[] customCommandLineValidation()
Description copied from class: `CommandLineProgram`
Put any custom command-line validation in an override of this method. clp is initialized at this point and can be used to print usage and access argv. Any options set by command-line parser can be validated.

Overrides:
  `customCommandLineValidation` in class `CommandLineProgram`
Returns:
  null if command line is valid. If command line is invalid, returns an array of error message to be written to the appropriate place.