taf-minimap2

TAFFISH wrapper for minimap2, a fast and versatile nucleotide sequence aligner for long reads, short reads, spliced RNA-seq reads, assembly-to-assembly alignment, and all-vs-all read overlap.

This repository packages upstream minimap2 2.31 as a TAFFISH tool app. The container builds the official v2.31 source release in Debian 12, installs the upstream minimap2 executable, and includes paftools.js with the k8 JavaScript shell used by upstream helper workflows.

Package

name: minimap2
command: taf-minimap2
version: 2.31-r1
kind: tool
image: ghcr.io/taffish/minimap2:2.31-r1
upstream release: v2.31
runtime version: 2.31-r1302

Installation

Install from the public TAFFISH Hub index:

taf update
taf install minimap2

Install the exact release:

taf install minimap2 2.31-r1

For local testing before the app is published to the public index:

taf install --from .

Usage

Show TAFFISH app help:

taf-minimap2 --help

Show upstream minimap2 help:

taf-minimap2 -- --help
taf-minimap2 minimap2 --help

Run minimap2 through command mode:

taf-minimap2 minimap2 -x map-ont reference.fa reads.fq > aln.paf
taf-minimap2 minimap2 -a -x map-hifi reference.fa reads.fq > aln.sam
taf-minimap2 minimap2 -a -x sr reference.fa read1.fq read2.fq > aln.sam

Because minimap2 is the default upstream command, option-leading minimap2 calls can also be written in the short form:

taf-minimap2 -x map-ont reference.fa reads.fq > aln.paf
taf-minimap2 -a -x splice reference.fa cdna_reads.fa > splice.sam

Build and reuse a minimap2 index:

taf-minimap2 minimap2 -x map-ont -d reference.map-ont.mmi reference.fa
taf-minimap2 minimap2 -a reference.map-ont.mmi reads.fq > aln.sam

Use assembly-to-reference alignment with CIGAR and cs tags:

taf-minimap2 minimap2 -cx asm5 --cs reference.fa assembly.fa > asm.paf

Use the official PAF helper script:

taf-minimap2 paftools.js stat asm.paf > asm.stats.txt
taf-minimap2 paftools.js view asm.paf > asm.view.txt
taf-minimap2 paftools.js gff2bed annotation.gff3 > annotation.bed
taf-minimap2 paftools.js sim2bed simulated.txt > simulated.bed
taf-minimap2 paftools.js badread2fa reference.fa.fai badread.fq > reads.fa

paftools.js is executable directly because the image includes k8 in PATH. You may also run it explicitly:

taf-minimap2 k8 /usr/local/bin/paftools.js version

Container

The container image is built from docker/Dockerfile. It starts from debian:12-slim, downloads the upstream minimap2-2.31.tar.bz2 release source archive, verifies its SHA256 digest, builds minimap2 with GCC, GNU Make, pthreads, libm, and zlib development headers, and installs the compiled binary into /usr/local/bin.

The image includes:

minimap2
paftools.js
k8

Runtime dependencies are intentionally small:

bash
gzip
libgcc-s1
libstdc++6
zlib1g

The upstream man page and documentation are installed under:

/usr/local/share/man/man1/minimap2.1
/usr/local/share/doc/minimap2/

This app intentionally does not bundle the Python binding mappy, Python, Cython, samtools, bgzip/tabix, variant normalizers, visualization tools, or large reference data. Minimap2 outputs PAF by default and SAM with -a; BAM, CRAM, indexing, sorting, compression beyond ordinary gzip streams, and VCF post-processing should be handled by dedicated TAFFISH tools or flows.

The image is built and validated for:

linux/amd64
linux/arm64

Minimap2 requires SSE2 on x86 CPUs or NEON on ARM CPUs. The Dockerfile uses the upstream x86 build path on linux/amd64 and the upstream arm_neon=1 aarch64=1 build path on linux/arm64.

Upstream 2.31 Notes

Upstream 2.31 reports runtime version 2.31-r1302. Compared with 2.30, it fixes long-standing minimap2 bugs around supplementary/secondary alignment flags and rare Smith-Waterman out-of-bound access in inversion alignment. Upstream notes that these bug fixes can occasionally change alignments relative to the previous version.

paftools.js adds sim2bed for converting simulated-read metadata to BED and badread2fa for formatting Badread-simulated reads. The upstream Python binding mappy also changed in 2.31, but this focused TAFFISH image still does not bundle Python or mappy.

Smoke Coverage

The TAFFISH metadata declares Docker smoke checks that verify:

exist: minimap2
exist: paftools.js, k8, gzip, bash
test:  minimap2 reports runtime version 2.31-r1302
test:  minimap2 help is available and lists presets such as map-ont
test:  paftools.js reports runtime version 2.31-r1302 and command summary
test:  paftools.js exposes the new sim2bed and badread2fa commands
test:  minimap2 and k8 link against zlib in the Debian runtime
test:  minimap2 can align a tiny read and emit SAM
test:  minimap2 can emit PAF with CIGAR/cs tags and paftools.js can read it
test:  minimap2 can build a tiny .mmi index and map gzip-compressed input

During TAFFISH Hub indexing, each smoke test is independent and verifies that the published image exposes the expected command surface, reports the pinned upstream version, and can run minimal local alignment and PAF-helper workflows.

Upstream

• Project: minimap2
• Homepage and manual: https://lh3.github.io/minimap2/
• Source: https://github.com/lh3/minimap2
• Releases: https://github.com/lh3/minimap2/releases
• Release: https://github.com/lh3/minimap2/releases/tag/v2.31
• Source archive: https://github.com/lh3/minimap2/releases/download/v2.31/minimap2-2.31.tar.bz2
• Source SHA256: c1351de6319c123369c2f4f37ba0ccf18c7ace47e2b1c0a35e30056b4a3bd9c9
• Upstream license: MIT
• Primary citation: Li 2018, doi:10.1093/bioinformatics/bty191, PMID:29750242
• Accuracy update citation: Li 2021, doi:10.1093/bioinformatics/btab705, PMID:34623391

Maintainer Notes

Useful checks before publishing:

taf check
hubctl/target/hubctl check --app-root repos/apps/bio/tools/minimap2 --no-write
taf publish --build --release --dry-run
docker build -t ghcr.io/taffish/minimap2:2.31-r1 -f docker/Dockerfile .
docker build --platform linux/amd64 -t ghcr.io/taffish/minimap2:2.31-r1-amd64-test -f docker/Dockerfile .
docker build --platform linux/arm64 -t ghcr.io/taffish/minimap2:2.31-r1-arm64-test -f docker/Dockerfile .
docker run --rm ghcr.io/taffish/minimap2:2.31-r1 minimap2 --version
docker run --rm ghcr.io/taffish/minimap2:2.31-r1 paftools.js version

The Dockerfile includes build-time checks for source checksum, version reporting, upstream help, paftools.js, new 2.31 helper command visibility, zlib linkage, SAM output, PAF output, .mmi indexing, and gzip input.

The repository wrapper files are licensed under Apache-2.0. Upstream minimap2 is distributed under the MIT license, and third-party runtime components are distributed under their own upstream licenses.