minibwa/minibwa.1 at Apache2 · nh13/minibwa

Repository navigation

.TH minibwa 1 "15 June 2026" "minibwa-0.1 (r363)" "Bioinformatics tools"
minibwa - short/long-read alignment against a reference genome
.SH SYNOPSIS
* Indexing a genome with the libsais algorithm (OpenMP required for multi-threading):
minibwa index
.IR nThreads ]
.RI [ idxPrefix ]
* Indexing a genome in low memory with the BWT-SW algorithm:
minibwa index
.RI [ idxPrefix ]
* Aligning short paired-end reads to an indexed genome and outputting SAM:
minibwa map
.IR nThreads ]
.I idxPrefix
.I read1.fq.gz
.I read2.fq.gz
.I output.sam
* Indexing and aligning bisulfite sequencing reads:
minibwa index
.IR nThreads ]
.RI [ idxPrefix ]
minibwa map
.IR nThreads ]
.I idxPrefix
.I read1.fq.gz
.I read2.fq.gz
.I output.sam
.SH DESCRIPTION
Minibwa aligns short reads against a reference genome. It is the successor of
bwa-mem with a different algorithm. Minibwa is over three times as fast as the
original bwa-mem and twice as fast as bwa-mem2 at comparable accuracy. While
minibwa works with accurate long reads, minimap2 is more robust under high
error rate.
Minibwa is a hybrid of bwa-mem and minimap2: it indexes the genome with
Burrow-Wheeler Transform (BWT), finds variable-length seeds like bwa-mem, and
performs chaining and SIMD-based nucleotide alignment with the minimap2
algorithm. Minibwa speeds up bwa-mem2 further with additional prefetch for
seeding, new heuristics to skip unnecessary mate rescue and reduced effort in
highly repetitive regions where reads would often be wrongly mapped due to
structural changes anyway.
.SH THE INDEX COMMAND
.SS Summary
.B minibwa index
.IR nThreads ]
.RB [ --meth ]
.RI [ idxPrefix ]
Index a genome in the FASTA format. Generate
.IR idxPrefix .l2b
for the genome sequence and
.IR idxPrefix .mbw
for the FM-index. Minibwa uses the libsais algorithm for BWT construction by
default. This algorithm is fast but requires
bytes where
is the length of the genome. Use

8000
to enable the BWT-SW algorithm which is slower but uses much less memory.
.SS Options
Use the old low-memory algorithm for BWT construction. Minibwa uses the libsais
algorithm by default which uses over 50 GB for a human genome.
.BI -t \ INT
Number of threads for the libsais algorithm [1]. Minibwa needs to be compiled
with OpenMP to enable this option.
Generate an index for aligning bisulfite sequencing reads. Minibwa will
additionally generate
.IR idxPrefix .meth.mbw
which combines C-to-T and G-to-A converted reference genomes.
.SH THE MAP COMMAND
.SS Summary
.B minibwa map
.IR preset ]
.IR nThreads ]
.I idxPrefix
.I read.fq.gz
.RI [ read2.fq.gz ]
Map reads to an index genome. Minibwa automatically detects
interleaved read pairs and like bwa-mem and minimap2, allowing mixed single-end
and paired-ened reads as input.
.SS Common Options
Output alignment in the PAF format (SAM by default)
.BI -t \ INT
Number of worker CPU threads [1]. Minibwa additionally uses
.RI min(2, \fIINT )
threads for I/O.
.BI -l \ NUM
In the adaptive mode, treat reads shorter than
as short reads [325]
.BI -R \ STR
SAM read group line in a format like '@RG\\tID:foo\\tSM:bar' []
.BI -b \ STR
Output a base alignment tag:
[]. Only one tag is allowed.
Map Hi-C reads. Equivalent to option
.B directional
bisulfite sequencing (BS-seq) data. Require an index built with
.BR --meth .
In this mode, an unmethylated C on read 1 is expected to be converted to T and
an unmethylated G on read 2 converted to A. Minibwa does not support
undirectional BS-seq.
.SS Mapping Options
.BI -k \ INT
Minimum seed length [19]. Like bwa-mem, minibwa uses variable-length seeds.
.BI -c \ NUM
Maximum seed occurrence [250]. Minibwa samples up to
occurrences if there are too many.
.BI -g \ NUM
Stop chain enlongation if there are no minimizers within
.BR NUM -bp
[5000]. Also used for extending from the first and last anchors during base
.BI -w \ NUM
Bandwidth for initial chaining and base alignment [500].
.BI -W \ NUM
Bandwidth for secondary chaining through long gaps [20000].
.BI -m \ INT
Minimum chaining score [25]
.BI -p \ FLOAT
Minimum secondary-to-primary score ratio [0.5]
.BI -N \ INT
Retain at most
secondary alignments [101]
.B --chain-only
Perform chaining only without base alignment
.BR --long = yes | no
Whether to use the long-read heuristic for all reads
.BR --adap = yes | no
Whether to enable the adaptive mode, which is the default behavior with the
preset. In the adaptive mode, minibwa smoothly adjusts
.BR -g / -w / -W / -N / -m / -s
based on the individual read length, using formula
.IR x1 -( x1 - x0 )*pow(2,-(max( L ,100)-100)/(2000-100)),
is the read length,
is the value for long reads that are fixed, and
is the value for short reads that can be changed on the command line. For a
read longer than
minibwa additionally enables anchor filtering and mixes the short- and
long-read formulae for calculating the mapping quality.
.BI -x \ STR
.RB [ adap ].
If unsure, use the default
which works well for both short and long reads.
For short-read alignment. It may give fragmented alignment for typical long reads.
For long-read alignment
.RB ( --pe=no
.B --long -m40 -s50 -w500 -g5k -N5
.BR -K500m ).
It may miss highly repetitive alignments for typical short reads.
For mixed short and long reads but optimized for short reads. It is equivalent to
.BR --adap=yes '.
.SS Alignment Options
.BI -A \ INT
Match score [2]
.BI -B \ INT
Mismatch penalty [8]
.B -O \fIINT1\fR[,\fIINT2\fR]
Dual gap open penalty [12,23]. If
is not specified, it is set to
.B -E \fIINT1\fR[,\fIINT2\fR]
Dual gap extension penalty [2,1]. If
is not specified, it is set to
A gap of length
.RI min( O1 + k * E1 , O2 + k * E2 ).
.SS Paired-end Options
Skip read pairing and mate rescue
.BR --rescue = \fIINT
Mate rescue for up to
candidates [10]
.BR --pe = yes | no
Whether to enable the paired-end mode. Enabled by default with the
presets. Disabled with the
.SS Input/Output Options
.BI -o \ FILE
Output file name [stdout]
Don't output unmapped reads
.BR --outn = \fIINT
Output up to
secondary alignments [0]. Primary and supplementary alignments are always outputted.
Copy FASTA/Q comments to output
In the SAM output, use soft clipping for supplementary alignments
In the SAM output, if a read has supplementary alignments, take the alignment
with the smallest query (not genomic) position as primary. This mode, combined with
is commonly used for mapping Hi-C reads.
.B -K \fINUM1\fR[,\fINUM2\fR]
.IR NUM1 - NUM2
bp of query sequences in a batch [100m,1g]. Given enough reads in the input, a
batch is at least
in size. If there are less than 40000 sequences in the batch, continue to read
until the size reaches
.B --version
Print version number
.SH OUTPUT FORMATS
Minibwa outputs the SAM format by default. Options
enables the PAF output. PAF is a TAB-delimited text format with each line
consisting of at least 12 fields as are described in the following table:
center box;
cb | cb | cb
r | c | l .
Col	Type	Description
1	string	Read name
2	int	Read length
3	int	Read start coordinate (0-based)
4	int	Read end coordinate (0-based)
5	char	`+' for forward strand; `-' for reverse
6	string	Contig name
7	int	Contig length
8	int	Contig start coordinate on the original strand
9	int	Contig end coordinate on the original strand
10	int	Number of matching bases
11	int	Number of bases in alignment
12	int	Mapping quality (0-255 with 255 for missing)
Both SAM and PAF may have addtional fields in typed
key-value format
4010
. Minibwa may output the following tags:
center box;
cb | cb | cb
r | c | l .
Tag	Type	Description
AS	i	Alignment score from dynamic programming
ms	i	Score of the maximum scoring segment
cg	Z	CIGAR (PAF only)
MD	Z	Difference string in the SAM spec
cs	Z	Difference string
.SH LIMITATIONS
Minibwa does not work with noisy long reads or spliced RNA-seq reads.
Minibwa does not support undirectional bisulfite sequencing data.
FilesExpand file tree

minibwa.1

Latest commit

History

minibwa.1

File metadata and controls
