mosdepth

Algorithm

mosdepth calculates depth by creating an array for each chromosome. For every read start encountered, it increments the value at that position; for every stop, it decrements it. The depth at any position is the cumulative sum of all preceding array positions.

Key characteristics:

• Accuracy: It avoids double-counting overlapping mate-pairs and tracks every aligned part of every read using CIGAR operations.
• Performance: It is generally faster than samtools depth because it avoids the per-base pileup machinery. It is highly efficient for window-based or BED-based regional queries.
• Memory Usage: It uses more memory than samtools. Memory consumption is approximately 32-bits * longest chromosome length (e.g., ~1GB for Chromosome 1).

Speed

mosdepth is optimized for speed, especially in window mode. For a 30X genome, window mode with 3 threads can report mean depth in under 9 minutes.

Threading

Threads passed to mosdepth are decompression threads. Performance scaling typically plateaus after approximately 4 threads; adding more threads beyond this point provides diminishing returns.

If you require per-base depth but want to avoid the slow write speeds of standard BED files, use the --d4 flag. The D4 format is significantly faster to write and more useful for certain downstream applications.

mosdepth --d4 <prefix> <BAM-or-CRAM>

The file {prefix}.mosdepth.global.dist.txt contains a cumulative distribution of coverage for each chromosome and the whole genome. This is useful for Quality Control (QC).

Each row contains:

1. Chromosome (or "total")
2. Coverage level
3. Proportion of bases covered at that level

You can use the provided Python script to visualize these distributions:

python scripts/plot-dist.py *.global.dist.txt

This generates a dist.html file with plots for the genome and individual chromosomes.

You can install mosdepth using several methods:

• Bioconda: The recommended method for bioinformatics environments.
• Homebrew: brew install brewsci/bio/mosdepth
• Docker: Pull the official container from Quay.
• Manual: Download the static binary from the GitHub releases page. Static binaries have no dependencies.

Note for manual builds: If building from source, you require htslib version 1.4 or later. If you encounter libhts.so errors, set your LD_LIBRARY_PATH to the directory containing the library.

docker run -v /hostpath/:/opt/mount quay.io/biocontainers/mosdepth:0.2.4--he527e40_0 mosdepth -n --fast-mode -t 4 --by 1000 /opt/mount/sample /opt/mount/$bam

You can create a BED file of 'callable' regions by using the --quantize flag. This merges adjacent bases that fall into the same coverage bins. You can control the labels in the 4th column of the output BED file by setting the following environment variables:

• MOSDEPTH_Q0: Label for depth 0.
• MOSDEPTH_Q1: Label for depth 1 to $N_1$.
• MOSDEPTH_Q2: Label for depth $N_1+1$ to $N_2$.

Example: To label 0 as NO_COVERAGE, 1-4 as LOW_COVERAGE, 5-149 as CALLABLE, and 150+ as HIGH_COVERAGE:

export MOSDEPTH_Q0=NO_COVERAGE
export MOSDEPTH_Q1=LOW_COVERAGE
export MOSDEPTH_Q2=CALLABLE
export MOSDEPTH_Q3=HIGH_COVERAGE
mosdepth -n --quantize 0:1:5:150: $sample.quantized $sample.wgs.bam

By default, mosdepth uses the coverage range (e.g., 0:1, 1:4) as the label for the 4th column in the output. You can replace these numeric labels with custom text by setting environment variables following the pattern MOSDEPTH_Q<BIN_INDEX>=<LABEL>.

Note that the bin index corresponds to the order of the boundaries provided to --quantize.

export MOSDEPTH_Q0=NO_COVERAGE
export MOSDEPTH_Q1=LOW_COVERAGE
export MOSDEPTH_Q2=CALLABLE
export MOSDEPTH_Q3=HIGH_COVERAGE

For Whole Genome Sequencing (WGS), it is often more efficient to use windowed depth rather than per-base depth. Using -n (no per-base) and --fast-mode provides the best performance.

mosdepth -n --fast-mode --by 500 sample.wgs $sample.wgs.cram

The --thresholds flag allows you to report how many bases in each --by region meet specific coverage thresholds. This is highly efficient even with many thresholds.

Example: To see how many bases in each exon are covered at least 1x, 10x, 20x, and 30x:

mosdepth --by exons.bed --thresholds 1,10,20,30 $prefix $bam

This produces a .thresholds.bed.gz file where each threshold is a new column.

To calculate the mean coverage for specific regions defined in a BED file (e.g., an exome capture kit), use the --by flag. If the input BED file has 4 or more columns, the 4th column (name) is preserved in the output.

mosdepth --by capture.bed sample-output sample.exome.bam

The --quantize flag allows you to split coverage into specific bins and merge adjacent regions that fall into the same bin. This significantly reduces output file size compared to per-base reporting.

Bins are defined by an arbitrary number of numeric boundaries. For example, --quantize 0:1:4:100:200: creates bins where the upper endpoint is non-inclusive: 0:1, 1:4, 4:100, 100:200, and 200:infinity.

This feature is useful for outputting regions of low, high, or "callable" coverage, similar to GATK's CallableLoci tool.

The basic syntax for mosdepth is:

mosdepth [options] <prefix> <BAM-or-CRAM>

Arguments

• <prefix>: The prefix for all output files (e.g., .per-base.bed.gz, .summary.txt, .regions.bed.gz).
• <BAM-or-CRAM>: The alignment file to process.

Common Options

• -t, --threads <threads>: Number of BAM decompression threads (default: 0).
• -c, --chrom <chrom>: Restrict calculation to a specific chromosome.
• -b, --by <bed|window>: Provide a BED file for specific regions or an integer for window sizes.
• -n, --no-per-base: Skip per-base depth output. This significantly speeds up execution; use this if you only need windowed, quantized, or thresholded data.
• -f, --fasta <fasta>: Required for CRAM files.
• -x, --fast-mode: Recommended for most use cases. Disables internal CIGAR operation checks and mate overlap corrections for a substantial speed boost.