samtools-coverage(1)

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

✨ samtools-coverage 💅

okay so bestie, welcome to samtools-coverage, straight out of the samtools manual, section 1 🎀. This is the tool that tells you how covered your genome actually is, and then draws you a whole little ASCII vibe check about it. Obsessed.

🌸 SYNOPSIS 🌸

samtools coverage [options] [in1.sam|in1.bam|in1.cram
[in2.sam|in2.bam|in2.cram] [...]]

🦋 DESCRIPTION 🦋

So what does it do? It computes the coverage at each position or region, then hits you with either an ASCII-art histogram or a nice tabulated text table. Your choice, main character.

Coverage is defined as the percentage of positions within each bin with at least one base aligned against it. That's the whole definition, no cap 💖

The tabulated form uses these headings, and yes you need to know all of them:

  • rname — Reference name / chromosome
  • startpos — Start position
  • endpos — End position (or sequence length)
  • numreads — Number reads aligned to the region (after filtering)
  • covbases — Number of covered bases with depth >= 1
  • coverage — Percentage of covered bases [0..100]
  • meandepth — Mean depth of coverage
  • meanbaseq — Mean baseQ in covered region
  • meanmapq — Mean mapQ of selected reads

✨ OPTIONS ✨

💜 Input options:

  • -b, --bam-list FILE — List of input BAM files, one file per line [null]
  • -l, --min-read-len INT — Ignore reads shorter than INT base pairs [0]
  • -q, --min-MQ INT — Minimum mapping quality for an alignment to be used [0]
  • -Q, --min-BQ INT — Minimum base quality for a base to be considered [0]
  • --rf, --incl-flags STR|INT — Required flags: skip reads with mask bits unset [null]
  • --ff, --excl-flags STR|INT — Filter flags: skip reads with mask bits set [UNMAP,SECONDARY,QCFAIL,DUP]
  • -d, --depth INT — Maximum allowed coverage depth [1000000]. If 0, depth is set to the maximum integer value, effectively removing any depth limit 🫶
  • --min-depth INT — Minimum coverage depth, below which a position is ignored [1]

🎀 Output options:

  • -m, --histogram — Show histogram instead of tabular output.
  • -D, --plot-depth — As above but displays the depth of coverage instead of the percent of coverage. This option can be used to visualize copy number variations in the terminal 👑
  • -A, --ascii — Show only ASCII characters in histogram using colon and fullstop for full and half height characters.
  • -o, --output FILE — Write output to FILE [stdout].
  • -H, --no-header — Don't print a header in tabular mode.
  • -w, --n-bins INT — Number of bins in histogram. [terminal width - 40]
  • -r, --region REG — Show specified region. Format: chr:start-end.
  • -h, --help — Shows command help.

🔥 EXAMPLES 🔥

tabular mode, one specific region 🧚

Running coverage in tabular mode, on a specific region, with tabs shown as spaces for clarity in this man page:

samtools coverage -r chr1:1M-12M input.bam

#rname  startpos  endpos    numreads  covbases  coverage  meandepth  meanbaseq  meanmapq
chr1    1000000   12000000  528695    1069995   9.72723   3.50281    34.4       55.8

histogram mode, it's giving art 🌈

An example of the histogram output is below, with ASCII block characters replaced by # for rendering in this man page.

samtools coverage -A -w 32 -r chr1:1M-12M input.bam

chr1 (249.25Mbp)
>  24.19% | .                              | Number of reads: 528695
>  21.50% |::                              |     (132000 filtered)
>  18.81% |::                              | Covered bases:   1.07Mbp
>  16.12% |::                           :  | Percent covered: 9.727%
>  13.44% |::  :  .       ::            : :| Mean coverage:   3.5x
>  10.75% |:: ::  :       ::          : : :| Mean baseQ:      34.4
>   8.06% |:::::  :       ::        : : : :| Mean mapQ:       55.8
>   5.37% |::::: ::      :::      : ::::: :|
>   2.69% |::::: :::     :::  ::: :::::::::| Histo bin width: 343.8Kbp
>   0.00% |:::::::::::. :::::::::::::::::::| Histo max bin:   26.873%
        1.00M     4.44M     7.87M       12.00M

plot-depth mode, copy number variation era 💀

samtools coverage  -m -r 'chr1:24500000-25600000' --plot-depth -w 32 -A input.bam

chr1 (249.25Mbp)
>    38.8 |            .:::::::            | Number of reads: 283218
>    34.5 |            ::::::::            |     (3327 filtered)
>    30.2 |           :::::::::.           | Covered bases:   1.10Mbp
>    25.9 |.:::::.:.::::::::::::::::::::::.| Percent covered: 99.83%
>    21.6 |::::::::::::::::::::::::::::::::| Mean coverage:   33.2x
>    17.2 |::::::::::::::::::::::::::::::::| Mean baseQ:      37.2
>    12.9 |::::::::::::::::::::::::::::::::| Mean mapQ:       59.3
>     8.6 |::::::::::::::::::::::::::::::::|
>     4.3 |::::::::::::::::::::::::::::::::| Histo bin width: 34.5Kbp
>     0.0 |::::::::::::::::::::::::::::::::| Histo max cov:   43.117
        24.50M    24.84M    25.19M      25.60M

🫶 AUTHOR 🫶

Written by Florian P Breitwieser. king behavior honestly 👑

⭐ SEE ALSO ⭐

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

and that's the whole page bestie, go forth and cover some genomes 💖

okay bye ily, this was samtools-1.24 from 9 July 2026, page samtools-coverage(1) — see u in the group chat 🎀✨🦋

📦 where this page comes from