Settings profiles: bwa drop-in vs recommended

bwa-mem3’s defaults track bwa-mem / bwa-mem2 behavior — it is a faster drop-in for an existing bwa-mem2 pipeline. Some defaults the bwa lineage inherited are, however, more conservative than necessary. This page defines two profiles:

• a drop-in profile that keeps the bwa-mem/bwa-mem2 defaults, for migrations and parity checks;
• a recommended profile that deviates from those defaults where we have benchmarked the change to be near-neutral on accuracy and clearly faster.

The defaults ship as the drop-in profile. The recommended profile is opt-in — you turn it on with explicit flags — so upgrading bwa-mem3 never silently changes your alignments.

Which profile?

bwa-mem3 is already, by design, not byte-identical to bwa-mem2 even at default settings (additive SAM tags, per-architecture SIMD score2/MAPQ convergence, deterministic tie-breaks, a few extra supplementary alignments) — it is 99.94%–99.9996% concordant on primary records (panel-twist to WES). See Equivalence with bwa-mem2. “Drop-in” therefore means as close to bwa-mem2 as bwa-mem3 gets; the recommended profile is a further, documented deviation.

Drop-in profile (default)

bwa-mem3 mem -t <N> ref.fa R1.fq R2.fq > out.sam

No extra flags. Use this when you are:

• reproducing or validating against bwa-mem / bwa-mem2 output, or
• migrating an existing bwa-mem2 pipeline and want to change one variable (the aligner binary) at a time before tuning anything else.

Recommended profile

bwa-mem3 mem -t <N> -m 10 -y 0 ref.fa R1.fq R2.fq > out.sam

Use this for new pipelines, or once a drop-in migration is validated and you want bwa-mem3’s best speed/accuracy trade-off. Current recommended deviations:

This table will grow as we benchmark additional tunings; each entry is gated on the same “measurably faster, near-neutral accuracy” bar.

For a bisulfite (--meth) pipeline the recommended invocation is therefore:

bwa-mem3 mem -t <N> --meth -m 10 -s 0 -y 0 ref.fa R1.fq R2.fq > out.sam

Mate-rescue depth: -m 10

-m caps how many near-best candidate loci per read get a mate-rescue Smith–Waterman pass. bwa-mem and bwa-mem2 both default to 50; we measured the marginal value of that depth directly — end-to-end and at the read level against simulated golden truth.

The depth beyond ~10 is a measured wash. Mate rescue earns its keep on the first few candidates, but candidates 11–50 only ever engage on reads with many near-best loci — repetitive and cross-contig placements — and on truth data deep rescue places about as many of those reads correctly as it mis-places. Lowering -m 50 → 10 changes which low-confidence reads win, but the net true-recall cost is ≈ 0.003–0.004% (≈200 reads in 5.4 M), on both methylation and non-methylation data, and the accuracy-vs-depth curve is flat (no depth between 10 and 50 is meaningfully better). Disabling rescue entirely (-S, or -m 0) is a real regression — so rescue matters, just not 50-deep.

In exchange you get a real speed-up, largest exactly where deep rescue binds (high-depth amplicon/panel and repetitive regions):

Aggregate samtools flagstat impact is a uniform, directional sub-0.2 pp reduction in mapped%/proper-pair% (≤0.02 pp on WGS/WES; ≤0.12–0.19 pp on amplicon/meth), entirely in the low-MAPQ deep-rescue tail: the mapped count only ever decreases (it never newly maps a previously-unmapped read), and the handful of reads whose placement does change net to ≈0 recall against golden truth.

One caveat: this golden-truth metric scores a single best placement per read, so it does not capture downstream tools that aggregate over repeats — depth-based CNV, SV/mobile-element calling in repetitive regions, or repeat-region methylation. If your pipeline relies on which repeat copy is reported (rather than just the confident, MAPQ-high tier), validate -m 10 against your own analysis rather than assuming neutrality.

Numbers are from bwa-mem3-bench on 5 M-read real datasets plus a multi-contig holodeck golden-truth ablation; consult the bench for methodology and current figures.

Third-round seeding: -y 0

bwa-mem seeds in up to three rounds: (1) SMEMs, (2) reseeding long SMEMs (-r), and (3) an occurrence-bounded “seed strategy” round (-y) that, for every read position, grows an exact match until it occurs fewer than -y (default 20) times in the genome and emits it. Round 3 is a repeat-region safety net. -y 0 disables it entirely.

It is net-useless-to-harmful, even in the repeats it was built for. We swept -y 0 (and the more-aggressive -y 0 -r 10, see below) against the stock default across four golden-truth regimes (holodeck, read-name truth) and on real WES + WGS:

The tiny easy/indel deltas are ≤0.016 in absolute F1; on the divergent and repeat-enriched regimes — where round 3 is supposed to earn its keep — removing it makes F1 better. Mechanism: its low-occurrence (<20-hit) seeds add spurious near-tied repeat candidates that slightly degrade placement; dropping them lets the correct unique anchor win. (The regime sweep was on standard, non---meth reads; -y 0 is a generic seeding change and is recommended for --meth on the same basis, but was not separately F1-measured there.)

On real data the confident core is untouched. On 20 M real WES+WGS reads, zero confidently and uniquely mapped reads (MAPQ ≥ 60, NM ≤ 1, no soft-clip) became unmapped under -y 0, and 3–4 per 10 M lost any alignment score. Every regression lands on the already-low-confidence tail (base MAPQ ≈ 0, heavily soft-clipped or high-NM), and round 3 was so often producing worse primaries that removing it improves a large share of as many reads as it perturbs (on WES, 3,194 reads improve vs 3,784 that worsen).

In exchange, alignment CPU drops ~11–30 % single-thread, larger on data with more repeat content (WGS > WES). The win is confirmed cross-architecture (Graviton4/Linux: realistic +29.9 %, HG002 WGS +19.8 %, matching macOS) — it cuts cold-memory seeding work, not arithmetic, so it ports.

More aggressive (clean-data only): also drop round 2 with -y 0 -r 10. That roughly halves alignment CPU (~50–63 %), but round 2 is genuine split-read/divergence sensitivity — it costs −0.074 F1 on divergent data (the -y 0 -r 10 column above, concentrated in the repeat/multimapper bin). Use -y 0 -r 10 only on known-clean, low-divergence libraries; -y 0 alone is the broadly-safe recommendation.

Pass-2 re-seeding under --meth: -s 0

-s controls bwa-mem’s Pass-2 “re-seeding” — after the first seeding pass, long super-maximal exact matches whose occurrence count is ≤ -s are re-seeded from their midpoint to recover shorter, more frequent matches that a long seed would otherwise swallow. Under --meth, reads are projected into a 3-letter alphabet (C→T and G→A), which collapses sequence complexity: in that space Pass-2 mostly mines low-complexity sub-seeds that inflate the candidate set without changing placement. Setting -s 0 disables Pass-2 entirely (an exact seed’s interval size is always ≥ 1, so the re-seed gate never fires). This is methylation-specific — in the full 4-letter alphabet Pass-2 still earns its keep, so the recommendation is scoped to --meth.

Placement is a measured wash, even where re-seeding should matter most. We aligned ~33 M holodeck em-seq golden-truth reads with -s 0 vs the -s 10 default across two references — single-contig chr22 and a deliberately hard multi-contig build (chr19–22 + their ALT scaffolds + decoys + HLA, 2,977 contigs) that stresses cross-contig multi-mapping. In both regimes the net true-recall difference is within noise:

The direction (a sub-0.003% loss concentrated in the low-MAPQ cross-contig tail) mirrors -m 10’s, and -s 0 is not the same as disabling all seeding — it only removes the redundant second pass.

The one caveat is mapping-quality calibration. Removing Pass-2 shrinks the candidate set, so MAPQ trends upward (≈95% of changed reads). On easy references this is benign re-distribution; in the hard multi-contig regime the dominant high-confidence bin (MAPQ 50–60, ~84% of reads) stays identically calibrated (0.020% mis-placement either way), but the small mid-MAPQ bins (~3% of reads) are modestly to ~2× more error-prone at a given reported MAPQ under -s 0. This is negligible for methylation quantification but worth knowing for callers that hard-filter on MAPQ in repetitive regions.

In exchange, seeding is ~20% cheaper. On chr22 (single thread, best-of-5): alignment user-CPU −19.7% (12.96 s vs 16.14 s) and peak RSS −6.5%, with the gain largest on high-depth and repetitive inputs where the redundant Pass-2 candidate set is largest.

A selective fallback — skip Pass-2 globally but re-seed only low-confidence reads — was evaluated and does not help: in the multi-contig regime it would re-seed ~13% of reads yet recovers about as many placements as it sacrifices (net within noise), so there is no cheap middle ground.

Short-seed extension: --min-ext-len 30

--min-ext-len INT drops seeds shorter than INT bp before banded Smith–Waterman, so their extension never runs (off by default, 0 → byte-identical to baseline). Extension is ~60% of mem CPU and almost all of it is spent on short seeds — seeds ≤40 bp hold ~90% of all banded-SW cells yet are ~99% wasted, because long seeds already resolve via the ungapped fast-path. Skipping them thins the extension stage without touching seeding or chaining.

The accuracy change is confined to reads that were already low-confidence. On real HG002 1M PE WGS at --min-ext-len 30, 0.40% of reads change, and profiling every one of them against the population shows the cost lands entirely on reads that were already marginal — heavily soft-clipped partial alignments (median 95 of 150 bp clipped), high edit distance, or multi-mappers. Zero confidently, uniquely mapped reads (MAPQ ≥ 60, NM ≤ 1, no soft-clip) regress. Like -m 10, the mapped count only ever decreases (≈0.11% newly unmapped; it essentially never newly maps a previously-unmapped read), and the reads whose locus changes are repeat/paralog churn with sub-2-mismatch score deltas — about 1 in 4 of which the filter actually improves. On simulated clean Illumina and indel-rich data the change is nil-to-positive even at larger thresholds.

In exchange, alignment CPU drops ~10–20% single-thread, largest on data carrying many short seeds (real WGS sees more than idealized simulated reads). Because the speedup thins extension rather than speeding seeding — and seeding dominates the wall — the wall-clock gain is smaller than the ~90% banded-SW cell reduction would suggest.

Contraindication — very high per-base error. On degraded-chemistry or cross-species libraries (per-base error well above modern Illumina), every seed is short, so some correct alignments depend solely on short seeds and the cost rises sharply (e.g. at 2–15% simulated substitution error, F1 −0.2% at 30, growing to −1.4% at 40 and a cliff at 50). Keep --min-ext-len low or off for such data. Indels and structural variants are not a contraindication — an indel splits a read into two still-long exact segments that the fast-path handles, so indel-rich data is free.

30 is the accuracy-safe knee; 40–50 give a little more speed on known-clean data but trade accuracy as divergence rises. The CPU win is confirmed cross-architecture: on Graviton4/Linux (c8g) the same single-thread sweep gives realistic +15.8% and HG002 +20.5% (T=0→T=30), matching macOS — the filter is algorithmic, so it ports. Remaining before this graduates from “recommended for standard-error reads” to an unqualified default: a multi-thread + broader bwa-mem3-bench run (all current figures are single-thread).

Speed: drop-in and recommended

When comparing bwa-mem3 to a stock bwa-mem2 baseline, report both layers:

1. Drop-in speed-up — bwa-mem3 vs bwa-mem2 at identical settings, from its vectorized kernels, lockstep SMEM batching, libsais indexing, and mimalloc. See Performance Overview and What’s Different — Performance.
2. Recommended-profile speed-up — the additional ~11–22% alignment-CPU reduction from -m 10, on top of the drop-in gain.

A benchmark that quotes only default-vs-default settings understates the throughput available to a caller who has adopted the recommended profile; quote both so readers can pick the comparison that matches their deployment.

Situational: --supp-rep-hard-cap for SV-aware pipelines

This is not part of the recommended profile — it is a situational knob, not a free speed-up, and the default (0, off) is correct for plain alignment.

If you run structural-variant or breakpoint detection downstream (e.g. fgsv SvPileup), --supp-rep-hard-cap 20 suppresses repeat-induced spurious supplementary breakpoints — split alignments anchored in repeats whose mapping quality is overestimated — at no measured cost to real SV breakpoints. On GIAB HG002 CMRG (GRCh38, 2×250) it stripped repeat artifacts while preserving every credible real-SV breakpoint, including ones in moderately-repetitive regions.

Do not use more aggressive values: --supp-rep-hard-cap ≤ 10 began suppressing real GIAB SV breakpoints (a verified insertion at chr3:45890256 and deletion at chr18:79739776) whose supporting split reads happen to land in repetitive regions.

Caveats: this was measured on a single repeat-enriched truth set at the breakpoint level (not end-to-end SV calls), so treat 20 as a sensible starting point for SV workflows rather than a universal recommendation. It has no effect on primary-alignment MAPQ or on non-SV pipelines.

See also: Optimization checklist · Performance Overview · Equivalence with bwa-mem2 · CLI Reference — mem