oracular (1) samtools-split.1.gz

NAME

       samtools-split - splits a file by read group.

SYNOPSIS

       samtools split [options] merged.sam|merged.bam|merged.cram

DESCRIPTION

       Splits  a  file  by  read group, or a specified tag, producing one or more output files matching a common
       prefix (by default based on the input filename).

       Unless the -d option is used, the file will be split according to the @RG  tags  listed  in  the  header.
       Records  without  an RG tag or with an RG tag undefined in the header will cause the program to exit with
       an error unless the -u option is used.

       RG values defined in the header but with no records will produce an output file only containing a header.

       If the -d TAG option is used, the file will be split on the value in the  given  aux  tag.   Only  string
       (type  Z) and integer (type i in SAM, plus equivalents in BAM/CRAM) tags are currently supported.  Unless
       the -u option is used, the program will exit with an error if it finds a record without the given tag.

       Note that attempting to split on a tag with high cardinality may result in the creation of a large number
       of output files.  To prevent this, the -M option can be used to set a limit on the number of splits made.

       Using  -d  RG  behaves  in a similar way to the default (without -d), opening an output file for each @RG
       line in the header.  However, unlike the default, new output files will be opened for any RG  tags  found
       in the alignment records irrespective of if they have a matching header @RG line.

       The  -u  option may be used to specify the output filename for any records with a missing or unrecognised
       tag.  This option will always write out a file even if there are no records.

       Output format defaults to BAM.  For SAM or CRAM then either set the format with --output-fmt or use -f to
       set the file extension e.g.  -f %*_%#.sam.

OPTIONS

       -u FILE1      Put reads with no tag or an unrecognised tag into FILE1

       -h FILE2      Use  the  header  from  FILE2  when  writing  the file given in the -u option.  This header
                     completely replaces the one from the input file.  It must be compatible with the input file
                     header,  which means it must have the same number of references listed in the @SQ lines and
                     the references must be in the same order and have the same lengths.

       -f STRING     Output filename format string (see below) ["%*_%#.%."]

       -d TAG        Split reads by TAG value into distinct files. Only the TAG key must be  supplied  with  the
                     option.  The  value  of  the  TAG  has  to  be  a  string (i.e.  key:Z:value) or an integer
                     (key:i:value).

                     Using this option changes the default filename format string to  "%*_%!.%.",  so  that  tag
                     values appear in the output file names.  This can be overridden by using the -f option.

       -p NUMBER     Pad  numeric values in %# and %! format expansions to this many digits using leading zeros.
                     For %!, only integer tag values will be padded.  String tag values will be left  unchanged,
                     even if the value only includes digits.

       -M,--max-split NUM
                     Limit  the  number  of  files created by the -d option to NUM (default 100).  This prevents
                     accidents where trying to split on a tag with high cardinality could result in the creation
                     of a very large number of output files.  Once the file limit is reached, any tag values not
                     already seen will be treated as unmatched and the program will exit with  an  error  unless
                     the -u option is in use.

                     If  desired,  the  limit  can  be  removed  using -M -1, although in practice the number of
                     outputs will still be restricted by system limits on the number of files that can  be  open
                     at once.

                     If  splitting  by  read  group,  and  the read group count in the header is higher than the
                     requested limit then the limit will be raised to match.

       -v            Verbose output

       --no-PG       Do not add a @PG line to the header of the output file.

       Format string expansions:

                         %%   %
                         %*   basename
                         %#   index (of @RG in the header, or count of TAG values seen so far)
                         %!   @RG ID or TAG value
                         %.   output format filename extension

       -@, --threads INT
              Number of input/output compression threads to use in addition to main thread [0].

AUTHOR

       Written by Martin Pollard from the Sanger Institute.

SEE ALSO

       samtools(1), samtools-addreplacerg(1)

       Samtools website: <http://www.htslib.org/>