mopdepth

An LLM-assisted port of mosdepth to Crystal for BAM/CRAM depth calculation. LLMs were used to translate and adapt the original implementation. It provides per-base depth, region statistics, coverage distributions, quantization, and threshold counts.

Installation

Building from source requires Crystal, Shards, HTSlib, and Make.

git clone https://github.com/kojix2/mopdepth
cd mopdepth
make
bin/mopdepth --help

make builds an optimized release binary at bin/mopdepth. Use make debug for a development build. D4 output is included through d4.cr, with no Rust or native D4 dependency.

Usage

Input must be an indexed BAM or CRAM file. For CRAM, supply the reference FASTA with -f or REF_PATH.

bin/mopdepth [options] <prefix> <BAM-or-CRAM>

# Per-base depth and summary statistics
bin/mopdepth output sample.bam

# BED regions or 1 kb windows, without per-base output
bin/mopdepth -n -b regions.bed regions sample.bam
bin/mopdepth -n -b 1000 windows sample.bam

# CRAM input or D4 output
bin/mopdepth -f reference.fa cram sample.cram
bin/mopdepth --d4 depth sample.bam

Use bin/mopdepth --help for the full option list.

The default mode uses CIGAR operations to calculate depth. Fast mode and fragment mode are mutually exclusive. Fragment mode examines the complete chromosome even with --chrom, so fragments spanning the selected range are included.

Regions

BED input may be plain text, gzip, or BGZF. Coordinates must be zero-based, half-open, non-empty, and within the named reference. Unknown references are reported and ignored. Overlapping intervals are counted independently.

With -n -b regions.bed, chromosomes absent from the BED are skipped unless -q or -T is also requested. Skipped chromosomes do not contribute to summaries, distributions, or total. For processed chromosomes, total and the global distribution cover the entire chromosome or selected --chrom range; total_region and the region distribution cover the BED intervals.

Tag filtering

To keep PCR/library duplicates while excluding optical duplicates:

bin/mopdepth -F 772 --exclude-tag DT:SQ output sample.bam

The default FLAG mask excludes all duplicate-flagged records, so changing -F is necessary for this use. Tag conditions are combined with OR and apply to individual records in every mode. Matching is exact and case-sensitive; missing or non-string tags do not match. Tag names must match [A-Za-z][A-Za-z0-9]. Values may contain colons, spaces, or be empty (XX:); quote shell arguments containing spaces. Commas separate conditions.

Output

<label> is mopdepth by default and mosdepth with -M.

BED outputs are BGZF-compressed and receive CSI indexes after successful completion. D4 output receives an embedded secondary frame index.

The summary columns are chrom, length, bases, mean, min, and max. length is the number of bases summarized; bases is the sum of their depths.

Histogram-based statistics have fixed limits:

These limits leave per-base depth, threshold counts, quantization, and summary mean and maximum depth unchanged.

Library API

require "mopdepth"

options = Mopdepth::Options.new(minimum_mapping_quality: 20)
control = Mopdepth::Control.new { |progress| STDERR.puts progress }

Mopdepth::Reader.open("sample.bam", threads: 4) do |reader|
  reader.each_coverage(options: options, control: control) do |coverage|
    puts "#{coverage.region.chromosome}: #{coverage.values.size} bases"
  end
end

Reader provides coverage, coverage_into, and each_coverage. Coordinates are zero-based and half-open. coverage_into reuses a caller-owned Array(Int32); results contain one depth per base. Use one reader per concurrent worker. The block form closes the reader automatically.

Options supports Mode::Standard, Mode::Fast, and Mode::Fragment. Tag exclusions use exclude_tags: [Mopdepth::TagFilter.new("DT", "SQ")]; FLAG filtering is set separately through exclude_flags. Pass control: for progress callbacks and cooperative cancellation; another fiber or thread can call control.cancel. For CRAM, pass reference: "reference.fa" to Reader.open.

mosdepth compatibility

Coverage, filtering, NoData, thresholds, quantization, and window distributions follow mosdepth conventions. Compatibility checks compare decoded output and indexed query results.

Mopdepth uses the true intersection when removing overlap from contained read pairs, includes the final reference base in quantization, and applies --chrom ranges to calculation and output. These intentionally differ from mosdepth 0.3.x edge cases. Region means use integer depth sums before formatting.

Development

make test
make test-d4
make lint
make format-check

License

MIT