Indexing options

-x, --preset STR

Preset [lr]. It fixes the seeding of the index and is written into it. Available STR are lr (-k21 -s9), lr:hq (-k21 -s5), splice and splice:hq (-k15 -s10), the experimental asm5, asm10 and asm20 (-k21 -s9), and the experimental ava-ont (-k17 -s9) and ava-hifi (-k21 -s5). See Preset options.

-k INT

Syncmer k-mer length [21], no larger than 23. Every preset maps an index of any such k; Nanopore direct RNA maps on a -k14 splice index. A k-mer that is its own reverse complement, possible at an even value only, is never a seed.

-s INT

Closed-syncmer s-mer size, 1 to k [9]. A closed syncmer is a k-mer whose minimal s-mer sits at one of its two ends; the seed density is about 2/(k-s+1). A preset's s larger than k is taken as k.

-I NUM

Load at most NUM target bases into RAM for indexing [no split]. If there are more than NUM bases in ref.fa, flashalign needs to read reads.fq multiple times to map it against each batch of target sequences. This would create a multi-part index. NUM may be ending with k/K/m/M/g/G. NB: mapping quality is incorrect given a multi-part index.

--idx-no-seq

Don't store target sequences in the index. It saves disk space and memory but the index generated with this option will not work with -a or -c: it serves plain PAF output only, so SAM output, --cs, --MD and the splice presets refuse it. This option is not listed on the help screen.

-t INT

Number of threads [all].

--quiet

Suppress non-error logging, including the version, command line and resource usage printed at the end of the run.

--help

Print the index help message to stdout and exit.

Placement options

-g NUM

Stop alignment elongation if there are no seeds within NUM-bp [5000]. It bounds how far base alignment extends toward a read end, and under a DNA preset two pieces of a read join into one record only across gaps of at most NUM. Under a DNA preset chaining links anchors across at most the larger of it and -r's second value, so values under that band leave the chain unchanged. Under a splice preset it bounds base alignment and is also the maximum query gap of the fine chain; there -G bounds introns. Untyped, lr and lr:hq use 5000, the assembly presets 10000 and the splice presets 2000. NUM may be ending with k/K/m/M/g/G.

-r NUM1[,NUM2]

Bandwidth for base alignment, and for gap filling and chaining [500,20000]. Under a DNA preset, NUM1 is used for alignment extension toward the read ends and for inverted middles, and NUM2 for closing gaps between anchors, both only when base-level alignment runs (-c, SAM). NUM2 is also the band of the dense chain over the whole read, one for each contig and strand of the read's candidates: each candidate contributes every anchor of its window, which widens by at most the band, and the chain links anchors within the band across at most the band, or -g where that is larger, whatever the read length. So NUM2 acts on placement, and so also on plain PAF output. ava-ont and ava-hifi refuse -r; their chains band at 20000. A single value sets NUM1 only. Each value may be ending with k/K/m/M/g/G, and NUM1 may not exceed NUM2. Under a splice preset NUM1 is the diagonal band of the fine chain and NUM2 only bounds NUM1; neither bands base alignment there, and -G sets both [200000,200000].

-m INT

Discard alignments with chaining score <INT [40; 100 on ava-ont, ava-hifi]. Chaining score equals the approximate number of matching bases minus a concave gap penalty. With a CIGAR the test counts the alignment's matching bases; in plain PAF output it reads the chain score. A rival chain scoring under INT is weighed as scoring INT in the mapping quality; an inverted middle is aligned only when both its spans reach INT; and base alignment trims a bad read end until 2*INT matching bases. At least 1. The long form is --min-chain-score. DNA presets only.

-p FLOAT

Minimal secondary-to-primary score ratio to output secondary mappings [0.8]. Under a splice preset it retains a rival: a retained rival is aligned, is what md and XA report, and is a record of its own under --secondary=yes. Under a DNA preset it decides which chains attached to an owner are kept as secondary alignments, aligned beside it with a CIGAR and written from their chains without one: those whose chain scores at least FLOAT times the owner's, or within 2k of it.

-N INT

Retain at most INT secondary alignments [5]. Under a DNA preset both lanes keep up to INT per read whether or not they are printed; with a CIGAR they are aligned and the best of them prices the mapping quality, and without one each is written from its whole chain. Under lr and lr:hq, a secondary alignment ends where its alignment first splits, at a Z-drop or at a gap too large to align. No secondary alignment is kept past INT. -N0 is --secondary=no.

--rival-min-diff INT

Absolute chain-score band that retains a rival beside -p [30]. Splice presets only.

--min-support INT

Minimal number of seeds on a vote peak [3].

--max-vote-occ INT

Ignore a seed whose reference occurrence is above INT when voting, under a DNA preset when chaining too, and under a splice preset in every later step that reads seeds; 0 turns occurrence filtering off [200]. Unset, the cap is the larger of 200 and the occurrence of the top 1.81e-4 fraction (1.62e-3 under splice and splice:hq) of the most frequent seeds in the index, at most 500 under lr:hq, and the DNA chaining gates take the same cap. Under a DNA preset a vote tile whose seeds are all above the cap still votes with its rarest seed of at most 4095 occurrences (lr) or 1024 (lr:hq), and chaining keeps that seed.

--vote-ratio FLOAT

Keep every vote peak whose vote is at least FLOAT of the best peak's [0.25; 0 on ava-ont, ava-hifi]. 0 keeps the top four peaks by count instead. DNA presets only.

--max-chain-occ INT

Drop a seed whose genome-wide reference occurrence is above INT from the pool handed to chaining; 0 disables the gate [200]. Unset, the gate is the voting cap (--max-vote-occ). A seed an empty vote tile kept passes the gate. Only this gate bounds the seeds chaining receives: with 0, repeats can cost several times the CPU and memory. The same value removes, before voting, every seed whose k-mer occurs in the read itself more than INT times and in more than the fraction of the read's seeds that --q-occ-frac sets, as minimap2 does (not under ava-ont and ava-hifi); 0 removes none. DNA presets only.

--q-occ-frac FLOAT

Before voting, drop every seed whose k-mer occurs in the read more times than the occurrence cap and in more than FLOAT of the read's seeds, as minimap2's option of the same name does [0.01]; 0 turns this filter off. The cap is the chaining cap (--max-chain-occ) under lr, lr:hq, asm5, asm10 and asm20, and the voting cap (--max-vote-occ) under splice and splice:hq. Not under ava-ont and ava-hifi.

-e INT

In each run of the read's seeds whose occurrence is above the occurrence cap, between two seeds at or under it or a read end, keep the rarest seeds anyway, one per INT bases of the run and at most 128, except a seed that occurs more than 4095 times, as minimap2's option of the same name does; 0 turns this off [0; 500 under splice and splice:hq]. Every stage that applies the cap takes the kept seeds. Under the DNA presets it is off unless given, and unmeasured.

-v NUM1[,NUM2]

Seeds per strand that vote, and query tiles per read [128,128]. The read is cut into NUM1 equal tiles and each tile votes with one of its seeds; 0 votes with every seed. Above 128, the preset keeps the seeds the 128-tile cut picks and adds seeds of the NUM1-tile cut, each the farthest from those kept, until it holds as many as that cut picks; a rescued seed that would exceed the strand's budget of rescued occurrences is skipped, so the count can stop short. The exact refinement of the vote peaks uses the seeds of both cuts. NUM2 is the number of equal query tiles on which a candidate's seed support over the read is counted for its admission to the catalogue, 1 to 4096, of which admission by --vote-ratio compares at most 2048; under lr:hq the blocks of a split read are also measured in these tiles when their mapping-quality rivals are chosen. A single value sets NUM1 only. Neither --min-support nor --max-cands scales with NUM1; a vote peak needs --min-support votes, so a NUM1 below that places few reads or none. The Python field for NUM1 is Config.max_query_seeds. DNA presets only; the splice presets take --vote-spacing.

-W NUM1[,NUM2]

Width in reference bases of the diagonal bin a seed votes into, and the divisor of the read-length term that widens it [64,128]: a read of length L votes into bins of width max(NUM1, L/NUM2), at most --dw-max. A single value sets NUM1 only and keeps the preset's divisor; a NUM2 of 0 drops the term and fixes the width at NUM1. The splice presets take NUM1 alone: their width is fixed.

--dw-max INT

Largest width the read-length term of -W may reach, greater than 0 and, while that term is on, not below NUM1 [2048]. DNA presets only.

--max-cands INT

Vote peaks and placement candidates kept per strand, 1 to 64 [16]; 1 to 16383 [16383] under ava-ont and ava-hifi, which chain each contig and strand of the read once. Elsewhere, unset, it is 16 when vote peaks are admitted by their ratio to the best (--vote-ratio), where it only bounds the cost, and 4 when --vote-ratio is 0, where it selects; a value replaces whichever applies. With a CIGAR the secondary alignments come from these candidates' chains, so a wider bound can add secondaries. DNA presets only.

Alignment options

Under a DNA preset, -A, -B, -O, -E, -z and --score-N set the scoring of the gap fills between anchors, and that row is checked: -O and -E positive, E1>E2 and O1+E1<O2+E2 unless the two pieces are equal, (O1+E1)+(O2+E2) at most 127, --score-N below -B, -A and -B within [1,127] and --end-bonus at least -1; a row that fails exits 1. The read-end extensions use the preset's own row, which also scores every alignment, so AS, -S and --end-bonus are in its units: for lr -A2 -B4 -O4,24 -E2,1 -z400,200 --score-N 1, for lr:hq -A1 -B4 -O6,26 -E2,1 -z400,200 --score-N 1. Under asm5, asm10 and asm20, as under the splice presets, the gap fills and the read-end extensions use one row, and these options set it. The defaults below are those of lr.

-A INT

Matching score [4].

-B INT

Mismatching penalty [8]. Use a larger value for lower divergence.

-O INT[,INT]

Gap open penalty [8,48]. If the second INT is not specified, it is set to the first.

-E INT[,INT]

Gap extension penalty [4,1]. A gap of length k costs min{O1+k*E1,O2+k*E2}. If the second INT is not specified, it is set to the first.

-z INT1[,INT2]

Truncate an alignment if the running alignment score drops too quickly along the diagonal of the DP matrix (diagonal X-drop, or Z-drop) [800,200]. Under a DNA preset, a drop above INT2 tests the dropped region for a small inversion, aligning the reverse complement of the query there; under lr:hq, only where the read's own seeds of the other strand chain inside that region. If INT2 is not specified, it is set to INT1; it may not exceed INT1.

-S INT

Minimal peak DP alignment score to output [80]. Under a splice preset it is also the floor of a supplementary piece, which needs 3 anchors and 40 matching bases besides; the primary is exempt. Under a DNA preset an alignment also needs at least -m (40) matching bases; a value of 0 or less turns off the score test, not the base count. Plain PAF output, which has no DP, is not filtered by this score; under a DNA preset it prints no record whose chaining score is below -m. The long form is --min-dp-score.

--score-N INT

Penalty of a mismatch involving ambiguous bases [2].

--end-bonus INT

Score bonus when alignment extends to the end of the query sequence [-1].

Splice options

--min-intron INT

Minimal reference gap that chaining accepts as an intron [20]; a shorter gap is left to base alignment as a deletion. It does not decide the `N' CIGAR operator: base alignment writes a gap as `N' once the second gap penalty makes the long gap cheaper (see -O and -E). Splice presets only.

-G NUM

Maximum gap on the reference (effective with a splice preset), that is the maximum intron length [200k]. It also sets both values of -r, as in minimap2; when both -G and -r are given, the later one decides them. NUM may be ending with k/K/m/M/g/G. The long form is --max-intron-len. Splice presets only.

-u CHAR

How to find canonical splicing sites GT-AG - f: transcript strand; b: both strands; r: reverse strand; n: no attempt to match GT-AG [b]. Under n no ts tag is stamped. Use f for reads already on the transcript strand, such as direct RNA and Iso-Seq. Splice presets only.

--junc-bed FILE

Junctions to prefer during base alignment []. FILE can be gene annotations in the BED12 format (aka 12-column BED), or intron positions in 6-column BED with the strand column required. BED12 file can be converted from GTF/GFF3 with `paftools.js gff2bed anno.gtf'. Splice presets only.

--junc-bonus INT

Score bonus for a splice donor or acceptor found in annotation [9]. Effective with --junc-bed. INT ranges from 0 to 127. Splice presets only.

--vote-spacing INT

One vote seed per INT query bases [8; splice:hq 16]: a read of length L votes with max(128, ceil(L/INT)) seeds per strand, one per equal tile, so a read of at most 128 times INT bases votes with 128 seeds as before; 0 keeps the fixed 128. The vote serves plain PAF and base-level output alike. The Python field is Config.vote_seed_spacing. Splice presets only.

Input/output options

-o, --output FILE

Output alignments to FILE [stdout].

-c

Generate CIGAR. In PAF, the CIGAR is written to the `cg' custom tag. PAF without -c is placement-only: it runs no base-level dynamic programming, so its coordinates and its AS:i differ from those of a base-level alignment. -c, --cs and --MD turn base-level alignment on in PAF; SAM output always has it.

--cs[=short|long]

Output the cs tag. If no argument is given, `short' is set [none]. Implies -c.

--MD

Output the MD tag (see the SAM spec). Implies -c.

--eqx

Output =/X CIGAR operators for sequence match/mismatch. It rewrites every CIGAR the run realizes - the SAM CIGAR, SA:Z and PAF's cg:Z - and implies nothing, so plain PAF needs -c beside it.

-Y, --soft-clip-supp

In SAM output, use soft clipping for supplementary alignments. The default is hard clipping.

-R, --rg STR

SAM read group line in a format like @RG\tID:foo\tSM:bar []. It must start with @RG and carry an ID field, and it adds RG:Z as the first tag of every SAM record.

--sam-hit-only

In SAM, don't output unmapped reads.

--paf-no-hit

In PAF, output unmapped queries; the strand and the reference name fields are set to `*', and every count to 0.

--no-header

Don't output the SAM header.

--dual=yes|no

With an overlap preset, whether an overlap is printed from each of its reads that finds it (yes) or once, from the shorter read, ties going to the read whose name sorts first (no), minimap2's --dual [no] (minimap2 prints from the read whose name sorts first). With no a read is not compared with a target read shorter than itself, or as long and earlier by name. Refused with any other preset.

--secondary=yes|no

Whether to output secondary alignments [no]. With yes, each alternative alignment of a read is written after the primary and its supplementary records: FLAG 0x100, or 0x900 on its continuation segments, tp:A:S in PAF, mapping quality 0, and `*' for SEQ and QUAL. A secondary record carries ms and its own chain's cm and s1, but no md, s2, SA or XA. Under a DNA preset with a CIGAR the secondary alignments are those of the chains aligned beside an owner that, after alignment, overlap a primary record by more than half of the shorter, at most -N per read; they are listed on the primary's XA. Without a CIGAR they are the chains kept beside an owner (-p), at most -N per read, each written from its whole chain, with no ms. The value may also be given as a separate word (--secondary yes); typed twice, the last one wins.

-y

Copy input FASTA/Q comments to output, verbatim, as the last field of every record the read produces.

-t INT

Number of threads [all-2]: mapping runs on the machine's hardware threads less the reader and the writer. An explicit value is the whole mapping budget, and decompression of compressed input borrows from it rather than adding to it: -t/8 threads, from 1 to 8, when every read input qualifies (BGZF or BAM of at least 16 MiB at any -t of 2 or more; other gzip of at least 64 MiB from -t 32) and --batch-window is above 1.

-K, --batch-bp NUM

Number of bases loaded into memory to process in a mini-batch [500M]. As with -I, a k/K/m/M/g/G suffix is accepted. Output bytes and output order do not depend on it.

--show-config

Print the fully resolved configuration to stdout and exit 0. It reads no reference base and no read, so flashalign align -x lr:hq --show-config is a complete invocation; of a .faix target it reads the header, except that with a DNA or splice preset and a single-part index it loads the index without its bases (with them under --junc-bed) and appends rows tagged [resolved]: the seed occurrence cap and its parts, and under a DNA preset the rescue window, the vote's bin width at four read lengths and the chain's band and reach.

--stats

Print a summary of the run to stderr: reads and bases, mapped reads, records written, wall time, throughput and peak memory.

--progress

Print per-batch progress to stderr.

--quiet

Suppress non-error logging, including the three lines a run ends with on stderr: the version, the command line, and the real time, CPU time and peak memory.

-a

Generate CIGAR and output alignments in the SAM format. FlashAlign outputs in PAF by default.

--batch-window INT

Number of batches in flight in the compute stage [the preset's: 1 on asm5, asm10 and asm20, 3 otherwise]. With 1, all threads finish a batch before the next one starts. Output bytes and order are identical for every value.

--io-staging MIB

Ceiling, in MiB, on the decompressed gzip input staged ahead of the reader; 0 scales it with -t [0]. A non-zero value must be at least 64. BGZF and BAM input is not affected.

Preset options

-x, --preset STR

Preset [lr]. This option applies multiple options at the same time. An explicit -x also overrides the preset recorded in a .faix target; the index keeps its own (k, s). Available STR are:

Miscellaneous options

--help

Print the help screen of the subcommand to stdout and exit 0. A subcommand invoked with no arguments prints the same screen to stderr and exits 2. The help screen lists the common options; this page lists every option.

version

Print the version number to stdout. flashalign --version and flashalign -V print the same line. Both spellings are top-level only: neither is an align or index option.