Skip to content

Add Bwa mem3 - #8222

Open
joachimwolff wants to merge 2 commits into
galaxyproject:mainfrom
joachimwolff:bwa-mem3
Open

Add Bwa mem3#8222
joachimwolff wants to merge 2 commits into
galaxyproject:mainfrom
joachimwolff:bwa-mem3

Conversation

@joachimwolff

Copy link
Copy Markdown
Contributor

Wrapper and data manger for bwa_mem3 forked from bwa_mem2: https://github.com/fg-labs/bwa-mem3

FOR CONTRIBUTOR:

  • I have read the CONTRIBUTING.md document and this tool is appropriate for the tools-iuc repo.
  • Use of AI
    • The contribution is mostly AI generated
    • The contribution has been assisted by AI
  • License permits unrestricted use (educational + commercial)
  • This PR adds a new tool or tool collection
  • This PR updates an existing tool or tool collection
  • This PR does something else (explain below)

There are two labels that allow to ignore specific (false positive) tool linter errors:

  • skip-version-check: Use it if only a subset of the tools has been updated in a suite.
  • skip-url-check: Use it if github CI sees 403 errors, but the URLs work.

To request a review once your PR is ready, comment "please review" on the PR. This will
automatically apply the ready-for-review label if the PR is not a draft, all review
threads are resolved, and all CI checks have passed.

joachimwolff and others added 2 commits July 26, 2026 13:04
BWA-MEM3 (fg-labs/bwa-mem3) is a short-read aligner derived from BWA-MEM2
with correctness fixes, performance improvements, methylation-aware
alignment and a multi-tier SIMD runtime. On non-methylation data at
default settings it reproduces BWA-MEM/BWA-MEM2 alignments while running
faster.

The wrapper is modeled on the existing tools-iuc bwa_mem2 wrapper and
adapted to the bwa-mem3 0.6.0 CLI:

- single / paired / paired-collection / interleaved fastq input
- history FASTA reference (index built transparently) or cached
  bwa_mem3_indexes data table
- read-group support via the shared read_group_macros
- Simple Illumina mode and a Full options mode (algorithmic, scoring,
  input/output)
- a dedicated BWA-MEM3 performance-options section exposing the new
  speed heuristics (--fast, --smem-dedup, --skip-contained-ext,
  --adaptive-band, --max-extend-chains), each documenting whether it is
  byte-identical to BWA-MEM2 output
- BAM output with coordinate / name / input sort via samtools

The bwa-mem3 -x preset modes and -e (present in bwa-mem2) are omitted
because bwa-mem3 0.6.0 does not provide them.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Companion data manager for the BWA-MEM3 mapper: builds a BWA-MEM3
reference index with `bwa-mem3 index` and registers it in the
bwa_mem3_indexes tool data table, so admins can provide built-in
(cached) indexes selectable in the wrapper's "Use a built-in genome
index" mode.

Modeled on data_manager_bwa_mem2_index_builder; targets bwa-mem3 0.6.0.
The index consists of the .amb, .ann, .bwt.2bit.64 and .pac files
(bwa-mem3 does not emit the .0123 unpacked reference by default).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@bgruening

Copy link
Copy Markdown
Member

So you know how this relates to https://github.com/lh3/minibwa ?

@joachimwolff

Copy link
Copy Markdown
Contributor Author

As far as I understand bwa-mem3 is just cleaning up the source code of bwa-mem2 and improves it here and there, while minibwa seems to be a complete exchange of the basis algorithms.
The bwa-mem3 changes have partially be proposed also to bwa-mem2, but because they include ARM / Apple Silicon optimisations, the maintainers of bwa-mem2 cannot accept it because he/she is an Intel employee: bwa-mem2/bwa-mem2#288 (comment)

@bgruening

Copy link
Copy Markdown
Member

I understand that minibwa is the successor of bwa-mem and also faster then bwa-mem2. Should we move users to minibwa and skip bwa-mem3? I would not mind a new tool, but if we need a new DM and new indices,.we are wasting a lot of storage and compute that defeated the greener- IT thing of this tool.

@joachimwolff

Copy link
Copy Markdown
Contributor Author

I run some benchmarks, and it strongly suggests we shall move on with minibwa.

Index build (mm39)

Threads bwa-mem3 wall bwa-mem3 RSS minibwa wall minibwa RSS
1 430.1 s 47.0 GB 272.8 s 49.1 GB
4 173.9 s 47.0 GB 176.0 s 49.1 GB
8 141.6 s 47.0 GB 164.2 s 49.1 GB
16 139.9 s 47.0 GB 164.2 s 49.1 GB
32 164.3 s 47.0 GB 194.6 s 49.1 GB

Mapping (1,000,000 PE150 pairs)

Threads bwa-mem3 wall bwa-mem3 RSS minibwa wall minibwa RSS
4 1839.4 s [2] 12.0 GB 181.2 s 8.5 GB
8 900.6 s 14.6 GB 91.6 s 8.6 GB
16 424.3 s 19.7 GB 48.8 s 8.6 GB
32 352.6 s 27.7 GB 39.0 s 8.6 GB
Metric bwa-mem3 minibwa
mapped 100.00% 100.00%
correctly placed (all reads) 95.67% 95.44%
reads kept at MAPQ >= 30 92.84% 92.69%
reads kept at MAPQ >= 60 89.54% 86.99%
error rate, MAPQ >= 0 (all mapped) 4.335% 4.559%
error rate, MAPQ >= 10 0.061% 0.129%
error rate, MAPQ >= 20 0.018% 0.021%
error rate, MAPQ >= 30 0.005% 0.010%
error rate, MAPQ >= 60 0.000% 0.000%

@bgruening

Copy link
Copy Markdown
Member

Wtf this is a hell lot faster,.cool. Should we close this PR here.

@joachimwolff

Copy link
Copy Markdown
Contributor Author

Before we close it, let me validate with real data and not just the 1 Mio toy data set, and see if any influence on downstream results is there or not.

@joachimwolff

Copy link
Copy Markdown
Contributor Author

On a 9 GB fastq.gz file, single-end, the result is not that clear, but still advantage for minibwa.

Tool Input File Threads Elapsed Time (mm:ss) User Time (s) System Time (s) CPU Usage (%) Peak Memory / Max RSS
minibwa DMSO_R1.fastq.gz 8 19:53.66 9,647.65 48.60 812% 8.56 GB (8,978 MB)
bwa-mem3 DMSO_R1.fastq.gz 8 22:51.03 10,365.92 775.88 812% 13.70 GB (13,700 MB)
minibwa DMSO_R1.fastq.gz 16 10:47.63 10,467.80 23.80 1619% 10.21 GB (10,702 MB)
bwa-mem3 DMSO_R1.fastq.gz 16 12:44.21 12,160.20 238.61 1622% 17.90 GB (17,904 MB)
minibwa DMSO_R1.fastq.gz 32 12:36.01 16,020.45* 32.55* 2123%* 11.20 GB (11,742 MB)
bwa-mem3 DMSO_R1.fastq.gz 32 10:13.38 18,952.19 143.42 3113% 23.56 GB (23,562 MB)

@bgruening

Copy link
Copy Markdown
Member

And the memory usage is also nice. Means we can run more in parallel on most boxes. Cool thanks for doing the benchmarks. ping @wm75 he might be interested in this as well.

@joachimwolff joachimwolff mentioned this pull request Jul 27, 2026
8 tasks
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Status: Triage/Discuss

Development

Successfully merging this pull request may close these issues.

2 participants