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 <<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" && 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 class` | `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, GA4GH_CLIENT_SECRETS, MAX_RECORDS_IN_RAM, QUIET, REFERENCE_SEQUENCE, referenceSequence, specialArgumentsCollection, TMP_DIR, USE_JDK_DEFLATER, USE_JDK_INFLATER, VALIDATION_STRINGENCY, VERBOSITY`

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `FilterSamReads()` |

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    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

      `getCommandLine, 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 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=includeReadList.",
                    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.