samtools-cram-size(1)

📦
version 1.24 · 7 versions
, in epel 10, nixpkgs unstable

💅 samtools cram-size 💅

Okay bestie, listen — this is samtools-cram-size, one of the little samtools helpers, and it's here to spill the tea on exactly what's living inside your CRAM file. Like a full body scan but for data blocks. Iconic.

✨ SYNOPSIS ✨

samtools cram-size [-ve] [-o file] in.bam

🌸 DESCRIPTION 🌸

So what it does is: it makes a summary of all the CRAM block Content ID numbers and the Data Series that are chilling inside them. And if you want the whole story — like, per-container-level detail of how each data series is encoded — you can pass -e or --encodings and it'll give you that too. Obsessed.

Now here's the messy part 😭 CRAM is allowed to mix multiple Data Series into a single block. And when that happens, there's literally no way to tell what proportion of the block each Data Series is eating. Not a vibe, but that's the spec.

CRAM also lets different encodings and block Content ID assignments happen per container, which — honestly? Highly unusual. Red flag energy, but legal. Meanwhile, Htslib will always assign the same Data Series to a block with a consistent Content ID, though the CRAM Encoding itself may change.

Every CRAM block has a compression method, and ngl these are not guaranteed to be consistent between successive blocks that share the same Content ID. Htslib is out here learning which compression methods actually work, so a single Content ID can end up with multiple compression methods attached to it. Each method gets listed per line with a single character code — but if you want the size breakdown per method and a chattier description, use -v. 💅

The compression codecs used in CRAM can have a whole variety of parameters — think compression levels, inbuilt transformations, choices of entropy encoding. This tool makes an attempt to distinguish between those different method parameterisations.

So here are the compression methods with their short and long (verbose) names, in all their glory 👑

🎀 The method table 🎀

  • g / gzip — Gzip
  • _ / gzip-min — Gzip -1
  • G / gzip-max — Gzip -9
  • b / bzip2 — Bzip2
  • b / bzip2-1 to bzip2-8 — Explicit bzip2 compression levels
  • B / bzip2-9 — Bzip2 -9
  • l / lzma — LZMA
  • r / r4x8-o0 — rANS 4x8 Order-0
  • R / r4x8-o1 — rANS 4x8 Order-1
  • 0 / r4x16-o0
  • 0 / r4x16-o0R — rANS 4x16 Order-0 with RLE
  • 0 / r4x16-o0P — rANS 4x16 Order-0 with PACK
  • 0 / r4x16-o0PR — rANS 4x16 Order-0 with PACK and RLE
  • 1 / r4x16-o1
  • 1 / r4x16-o1R — rANS 4x16 Order-1 with RLE
  • 1 / r4x16-o1P — rANS 4x16 Order-1 with PACK
  • 1 / r4x16-o1PR — rANS 4x16 Order-1 with PACK and RLE
  • 4 / r32x16-o0
  • 4 / r32x16-o0R — rANS 32x16 Order-0 with RLE
  • 4 / r32x16-o0P — rANS 32x16 Order-0 with PACK
  • 4 / r32x16-o0PR — rANS 32x16 Order-0 with PACK and RLE
  • 5 / r32x16-o1
  • 5 / r32x16-o1R — rANS 32x16 Order-1 with RLE
  • 5 / r32x16-o1P — rANS 32x16 Order-1 with PACK
  • 5 / r32x16-o1PR — rANS 32x16 Order-1 with PACK and RLE
  • 8 / rNx16-xo0 — rANS Nx16 STRIPED mode
  • 2 / rNx16-cat — rANS Nx16 CAT mode
  • a / arith-o0
  • a / arith-o0R — Arithmetic coding Order-0 with RLE
  • a / arith-o0P — Arithmetic coding Order-0 with PACK
  • a / arith-o0PR — Arithmetic coding Order-0 with PACK and RLE
  • A / arith-o1
  • A / arith-o1R — Arithmetic coding Order-1 with RLE
  • A / arith-o1P — Arithmetic coding Order-1 with PACK
  • A / arith-o1PR — Arithmetic coding Order-1 with PACK and RLE
  • a / arith-xo0 — Arithmetic coding STRIPED mode
  • a / arith-cat — Arithmetic coding CAT mode
  • f / fqzcomp — FQZComp quality codec
  • n / tok3-rans — Name tokeniser with rANS encoding
  • n / tok3-arith — Name tokeniser with Arithmetic encoding

✨ OPTIONS ✨

  • -o FILE — sends the size information into FILE instead of wherever it was going. 🫶
  • -v — verbose mode, babes. Shows one whole line per combination of Content ID and compression method. That's the detail you came for.
  • -e, --encodings — okay so CRAM uses an Encoding, which is the whole description of how the data gets serialised into a data block. Important: this is distinct from the CRAM compression method, which is applied to the block after encoding. The encoding methods are stored per CRAM Container.

This option lists the CRAM record encoding map and tag encoding map. It shows you the data series, the associated CRAM encoding method — things like HUFFMAN, BETA or EXTERNAL — and any parameters tied to that encoding.

Heads up bestie: the output can be large 😭 because this is information per container, not one tidy set of summary statistics dumped at the end of processing.

🌈 EXAMPLES 🌈

  1. The basic summary of block Content ID sizes for a CRAM file:
$ samtools cram-size in.cram
#   Content_ID  Uncomp.size    Comp.size   Ratio Method  Data_series
BLOCK     CORE            0            0 100.00% .
BLOCK       11    394734019     51023626  12.93% g       RN
BLOCK       12   1504781763     99158495   6.59% R       QS
BLOCK       13       330065        84195  25.51% _r.g    IN
BLOCK       14     26625602      6803930  25.55% Rrg     SC
...
  1. Same file as above, but with verbose mode on. Here's where you actually see the distinct compression methods that have been used per block Content ID 👀
$ samtools cram-size -v in.cram
#   Content_ID  Uncomp.size    Comp.size   Ratio Method      Data_series
BLOCK     CORE            0            0 100.00% raw
BLOCK       11    394734019     51023626  12.93% gzip        RN
BLOCK       12   1504781763     99158495   6.59% r4x8-o1     QS
BLOCK       13       275033        64343  23.39% gzip-min    IN
BLOCK       13        43327        15412  35.57% r4x8-o0     IN
BLOCK       13         2452         2452 100.00% raw         IN
BLOCK       13         9253         1988  21.49% gzip        IN
BLOCK       14     23106404      5903351  25.55% r4x8-o1     SC
BLOCK       14      1951616       513722  26.32% r4x8-o0     SC
BLOCK       14      1567582       386857  24.68% gzip        SC
...
  1. Listing encoding methods per CRAM Data Series. The two-letter series are the standard CRAM Data Series, and the three-letter ones are the optional auxiliary tags with the tag name and type combined together. iykyk 💅
$ samtools cram-size -e in.cram
Container encodings
    RN      BYTE_ARRAY_STOP(stop=0,id=11)
    QS      EXTERNAL(id=12)
    IN      BYTE_ARRAY_STOP(stop=0,id=13)
    SC      BYTE_ARRAY_STOP(stop=0,id=14)
    BB      BYTE_ARRAY_LEN(len_codec={EXTERNAL(id=42)}, \
                           val_codec={EXTERNAL(id=37)}
    ...
    XAZ     BYTE_ARRAY_STOP(stop=9,id=5783898)
    MDZ     BYTE_ARRAY_STOP(stop=9,id=5063770)
    ASC     BYTE_ARRAY_LEN(len_codec={HUFFMAN(codes={1},lengths={0})}, \
                           val_codec={EXTERNAL(id=4281155)}
    ...

👑 AUTHOR 👑

Written by James Bonfield from the Sanger Institute. Absolute legend, no cap. 🫶

🦋 SEE ALSO 🦋

and that's the whole page bestie!! ✨ this lil masterpiece is from samtools-1.24, dated 9 July 2026 — go forth and inspect those CRAM blocks, you gorgeous data gremlin 💖🎀🦋

📦 where this page comes from