Package picard.sam

Class 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
     
    • Field Detail

      • INPUT

        @Argument(doc="The SAM or BAM file that will be filtered.",
                  shortName="I")
        public File INPUT
      • 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 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 or BAM 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 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 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.