Package picard.sam

## Class AddOrReplaceReadGroups

- java.lang.Object
- - picard.cmdline.CommandLineProgram
  - - picard.sam.AddOrReplaceReadGroups

-     @DocumentedFeature
      public class AddOrReplaceReadGroups
      extends CommandLineProgram

  Assigns all the reads in a file to a single new read-group.

  ### Summary

  Many tools (Picard and GATK for example) require or assume the presence of at least one `RG` tag, defining a "read-group" to which each read can be assigned (as specified in the `RG` tag in the SAM record). This tool enables the user to assign all the reads in the `INPUT` to a single new read-group. For more information about read-groups, see the GATK Dictionary entry.
  This tool accepts as INPUT BAM and SAM files or URLs from the Global Alliance for Genomics and Health (GA4GH).

  ### Usage example:

       java -jar picard.jar AddOrReplaceReadGroups \
             I=input.bam \
             O=output.bam \
             RGID=4 \
             RGLB=lib1 \
             RGPL=illumina \
             RGPU=unit1 \
             RGSM=20

  ### Caveats

  The value of the tags must adhere (according to the SAM-spec) with the regex

      "^[ -~]+$"

  (one or more characters from the ASCII range 32 through 126). In particular `<Space>` is the only non-printing character allowed.
  The program enables only the wholesale assignment of all the reads in the `INPUT` to a single read-group. If your file already has reads assigned to multiple read-groups, the original `RG` value will be lost.

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `String` | `INPUT` |
    `File` | `OUTPUT` |
    `static String` | `READGROUP_ID_REGEX` |
    `String` | `RGCN` |
    `String` | `RGDS` |
    `htsjdk.samtools.util.Iso8601Date` | `RGDT` |
    `String` | `RGFO` |
    `String` | `RGID` |
    `String` | `RGKS` |
    `String` | `RGLB` |
    `String` | `RGPG` |
    `Integer` | `RGPI` |
    `String` | `RGPL` |
    `String` | `RGPM` |
    `String` | `RGPU` |
    `String` | `RGSM` |
    `htsjdk.samtools.SAMFileHeader.SortOrder` | `SORT_ORDER` |

    - ### 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
    --- | ---
    `AddOrReplaceReadGroups()` |

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

    - #### READGROUP_ID_REGEX

          public static final String READGROUP_ID_REGEX

      See Also:
        Constant Field Values

    - #### INPUT

          @Argument(shortName="I",
                    doc="Input file (BAM or SAM or a GA4GH url).")
          public String INPUT

    - #### OUTPUT

          @Argument(shortName="O",
                    doc="Output file (BAM or SAM).")
          public File OUTPUT

    - #### SORT_ORDER

          @Argument(shortName="SO",
                    optional=true,
                    doc="Optional sort order to output in. If not supplied OUTPUT is in the same order as INPUT.")
          public htsjdk.samtools.SAMFileHeader.SortOrder SORT_ORDER

    - #### RGID

          @Argument(shortName="ID",
                    doc="Read-Group ID")
          public String RGID

    - #### RGLB

          @Argument(shortName="LB",
                    doc="Read-Group library")
          public String RGLB

    - #### RGPL

          @Argument(shortName="PL",
                    doc="Read-Group platform (e.g. illumina, solid)")
          public String RGPL

    - #### RGPU

          @Argument(shortName="PU",
                    doc="Read-Group platform unit (eg. run barcode)")
          public String RGPU

    - #### RGSM

          @Argument(shortName="SM",
                    doc="Read-Group sample name")
          public String RGSM

    - #### RGCN

          @Argument(shortName="CN",
                    doc="Read-Group sequencing center name",
                    optional=true)
          public String RGCN

    - #### RGDS

          @Argument(shortName="DS",
                    doc="Read-Group description",
                    optional=true)
          public String RGDS

    - #### RGDT

          @Argument(shortName="DT",
                    doc="Read-Group run date",
                    optional=true)
          public htsjdk.samtools.util.Iso8601Date RGDT

    - #### RGKS

          @Argument(shortName="KS",
                    doc="Read-Group key sequence",
                    optional=true)
          public String RGKS

    - #### RGFO

          @Argument(shortName="FO",
                    doc="Read-Group flow order",
                    optional=true)
          public String RGFO

    - #### RGPI

          @Argument(shortName="PI",
                    doc="Read-Group predicted insert size",
                    optional=true)
          public Integer RGPI

    - #### RGPG

          @Argument(shortName="PG",
                    doc="Read-Group program group",
                    optional=true)
          public String RGPG

    - #### RGPM

          @Argument(shortName="PM",
                    doc="Read-Group platform model",
                    optional=true)
          public String RGPM

  - ### Constructor Detail

    - #### AddOrReplaceReadGroups

          public AddOrReplaceReadGroups()

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