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

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
protected static class	FilterSamReads.Filter

Field Summary

Fields

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

Fields inherited from class picard.cmdline.CommandLineProgram

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

Constructor Summary

Constructors

Constructor and Description
FilterSamReads()

Method Summary

Modifier and Type	Method and Description
protected java.lang.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

getCommandLine, getCommandLineParser, getCommandLineParser, getDefaultHeaders, getFaqLink, getMetricsFile, 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 Detail

INPUT

@Argument(doc="The SAM or BAM file that will be filtered.",
          shortName="I")
public java.io.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 or BAM file, when using FILTER=includeReadList or FILTER=excludeReadList.",
          optional=true,
          shortName="RLF")
public java.io.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 java.io.File INTERVAL_LIST

TAG

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

TAG_VALUE

@Argument(doc="The tag value(s) to filter by",
          optional=true,
          shortName="TV")
public java.util.List<java.lang.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 or BAM file for resulting reads.",
          shortName="O")
public java.io.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 java.io.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 Detail

FilterSamReads

public FilterSamReads()

Method Detail

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 java.lang.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.