scramble(1)

🦋 NAME 🦋

okay so bestie, gather round — this is scramble, from the Staden io_lib manual, section 1 (aka the "run this in your shell" section, iykyk). It converts between the SAM, BAM and CRAM file formats. That's the whole job. That's the girlboss assignment. 💅

---

✨ 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 it can work on named files. Two moods, both iconic. 🫶

When it's operating as a pipe, the input type defaults to SAM or BAM, so you need the -I cram option to indicate that the input is in CRAM format — otherwise it'll guess and honestly bestie, guessing is not the vibe. The output defaults to BAM, but you can adjust that with the -O format option. And when you give it filenames, the file type is automatically chosen based on the filename suffix. No cap, it just knows. 🔥

---

💖 OPTIONS 💖

• -I format — Selects the input format, where format is one of sam, bam or cram. Use this when reading via a pipe so you avoid input bytes being consumed when it's trying to detect whether the input is in SAM or BAM format. (Bytes getting eaten mid-detection is not the serve, so just tell it.) 🙈
• -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. Reading does not care, she is unbothered. ✨
• -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. Adds bzip2 to the list of compression codes potentially used during CRAM creation.
• -Z — CRAM encoding only. Adds 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. She's slow to get ready but she arrives cute. 😭
• -m — CRAM decoding only. Generates MD:Z: and NM:I: auxiliary fields based on the reference-based compression.
• -M — CRAM encoding only. Forcibly packs sequences from multiple references into the same slice. Normally CRAM will start a new slice when changing from one reference to another, but it 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). No index, no shortcut, sorry bestie. 💀
• -r ref.fa — CRAM encoding only. Use this to specify the reference fasta file. Note that if the input SAM or BAM file has 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 sequences 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. Embeds snippets of the reference sequence in every slice. This means the files can be decoded without needing to specify the reference fasta file. Self-sufficient queen. 👑
• -E — CRAM encoding only. Embeds 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. Omits reference based compression and instead stores details of every base verbatim. Just raw honesty.
• -B — Experimental, encoding only. When storing quality values, bins into 8 discrete values (plus 0), as typically used by modern Illumina instruments. (Note that the bins may not be precisely the same ranges.) She's experimental, be gentle. 🧚
• -! — 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.

bestie, for real, -! is an emergency-room option. Only when you're rescuing corrupted data. Not a casual Tuesday move.

• -q — Do not append @PG header lines with the scramble program name and arguments. Shy girl behaviour, respect.
• -X mode — Encodes CRAM using a set of predefined parameters defined by mode. These 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. zoom zoom 🦋
  • 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 — Discards 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 — Discards 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.

not me repeating it but fr fr: -d and -D are mutually exclusive. Pick a lane. 💅

---

🎀 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

okay bestie, that second one is experimental and not for production. The original says so, and I'm just the messenger. 🙈

---

💜 AUTHOR 💜

James Bonfield, Wellcome Trust Sanger Institute — the actual icon, the blueprint, the moment. 👑

---

and that's the whole page, bestie! This one's from the Staden io_lib manual, dated December 6 2022, and it's page scramble(1). Go convert something and slay. 🦋💖✨