Provided by: staden-io-lib-utils_1.14.15-1_amd64 
NAME
scramble - Converts between the SAM, BAM and CRAM file formats.
SYNOPSIS
scramble [options] [input_file [output_file]]
DESCRIPTION
scramble converts between various next-gen sequencing alignment file formats, including
SAM, BAM and CRAM. It can either act as a pipe reading stdin and writing to stdout, or on
named files.
When operating as a pipe the input type defaults to SAM or BAM, requiring the -I cram
option to indicate input is in CRAM format is appropriate. The output defaults to BAM, but
can be adjusted by using the -O format option. When given filenames the file type is
automatically chosen based on the filename suffix.
OPTIONS
-I format
Selects the input format, where format is one of sam, bam or cram. Use this when
reading via a pipe to avoid input bytes being consumed when attempting to detect if
the input is in SAM or BAM format.
-O format
Selects the output format, where format is one of sam, bam or cram.
-1 to -9
Sets the compression level from 1 (low compression, fast) to 9 (high compression,
slow) when writing in BAM or CRAM format. This is only used during writing.
-0 or -u
Writes uncompressed data. In BAM this still uses BGZF containers, but with no
internal compression. In CRAM it stores blocks in RAW format instead. The option
has no effect on SAM output.
-j CRAM encoding only. Add bzip2 to the list of compression codes potentially used
during CRAM creation.
-Z CRAM encoding only. Add lzma to the list of compression codes potentially used
during CRAM creation. Given the slow compression speed of lzma, this may only be
used where it gives a significant advantage over zlib or bzip2, but with higher
compression levels (-7) this weighting is ignored as LZMA decompression speed is
acceptable, albeit still slower than zlib.
-m CRAM decoding only. Generate MD:Z: and NM:I: auxiliary fields based on the
reference-based compression.
-M CRAM encoding only. Forcibly pack sequences from multiple references into the same
slice. Normally CRAM will start a new slice when changing from one reference to
another, but will still automatically switch to multi-reference slices if the
number of sequences per slice becomes too small.
-R range
Currently for CRAM input only, but SAM/BAM support is pending. This indicates a
reference sequence name and optionally a start and end location within that
reference, using the syntax ref_name or ref_name:start-end. For efficient operation
the CRAM file needs a .crai format index (built using the cram_index program).
-r ref.fa
CRAM encoding only. Use this to specify the reference fasta file. Note that if
the input SAM or BAM file a file: or local file system based URI specified in the
@SQ headers then this option may not be necessary.
-s number
CRAM encoding only. Specifies the number of sequecnes per slice. Defaults to
10000.
-S number
CRAM encoding only. Specifies the number of slices per container. Defaults to 1.
-t BAM and CRAM only. Specifies the number of compression or decompression threads,
adaptively shared between both encoding and decoding. Defaults to 1 (no
threading).
-V version_string
CRAM encoding only. Sets the CRAM file format version. Supported values are "2.0",
"2.1" and "3.0".
-e CRAM encoding only. Embed snippets of the reference sequence in every slice. This
means the files can be decoded without needing to specify the reference fasta file.
-E CRAM encoding only. Embed snippets of the consensus sequence in every slice. This
operates as per the -e option, but the consensus is generated from the aligned
data. This does not therefore require a reference to be known during encode
(although it is still a mandatory part of the specification that the SQ SAM headers
have an M5 field). It also means the files can be decoded without needing to
specify the reference fasta file.
-x CRAM encoding only. Omit reference based compression and instead store details of
every base verbatim.
-B Experimental, encoding only. When storing quality values, bin into 8 discrete
values (plus 0), as typically used by modern Illumina instruments. (Note that the
bins may not be precisely the same ranges.)
-! CRAM v3.0 and above decoding only. Do not check CRCs. This option should only be
used when attempting to recover from a data corruption.
-q Do not append @PG header lines with the scramble program name and arguments.
-X mode
Encode CRAM using a set of predefined parameters defined by mode. This are one of
fast, normal / default, small or archive.
fast (param: -1 -s 1000)
Lightweight compression for speed and small slice size for quick fine-
grained random access.
normal (param: none)
Default mode. This is the same as not specifying -X. For version 3.1
onwards this enables the name tokeniser ("-T").
small (param v3.0: -j -s 25000, param v3.1 or v4: -Tf -s 25000)
Optimise for smaller files, with larger slices.
archive (param v3.0: -j -s 100000, param v3.1 or v4: -Tfa -s 100000)
Optimised for smallest files, intended for data archival. This uses a large
slice size and will have poorer random access. At level 7 onwards this also
enables lzma compression if compiled in ("-Z").
-d tag-list
Discard all auxiliary tags except those listed in tag-list. The list is comma
separated and contains the two letter tag codes specified as-is or with simplified
regular expressions. Character classes such as "[A-W]" are permitted, but not with
the negation code "^". Also "." is a synonym for any legal tag character. Hence
"[A-Z][A-Z0-9]" represents all tag types belonging to the official namespace.
The option may be specified more than once, but it cannot be mixed with -D.
-D tag-list
Discard auxiliary tags listed in tag-list, keeping everything else. The list is
comma separated and contains only the two letter tag codes. As with -d tag-list
can be specified using a simplified regular expression. This means -D .. removes
all auxiliary tags.
The option may be specified more than once, but it cannot be mixed with -d.
EXAMPLES
To convert a BAM file from stdin to CRAM on stdout, using reference MT.fa.
some_command | scramble -I bam -O cram -r MT.fa | some_command
The default CRAM output format is version 3.0. The command below enables the experimental
newer compression codecs (NB: do not use this in production) using the "small" profile,
while also removing all tag types reserved for local/private use. (Also consider -d [A-
Z][A-Z0-9] instead of the -D arguments.)
scramble -V 3.1 -X small -D [a-zXYZ]. -D.[a-z] in.cram out.cram
AUTHOR
James Bonfield, Wellcome Trust Sanger Institute
December 6 2022 scramble(1)