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 it is also the maximum gap of chaining, whose reach is never below the chain's band and grows with the read length, so values under the band leave that chain unchanged. The band is -b's first value for the dense chains and its second for the screening chain. 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 uses 5000 for base alignment and 20000 for chaining, lr:hq 10000 for both, the assembly presets 10000 and 20000, and the splice presets 2000 for both; a typed NUM sets both. NUM may be ending with k/K/m/M/g/G.

-r NUM1[,NUM2]

Bandwidth for base alignment and gap filling [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); neither bands chaining, which -b sets. 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].

-b NUM1[,NUM2]

Chaining bandwidth [20000,20000; 100000,20000 on asm5, asm10, asm20]. NUM1 bands each candidate's dense chain over the whole read and NUM2 its bounded screening chain: a chain keeps only the anchors whose diagonal lies within the band of the candidate's, and long reads chain with a reach that grows with their length. It acts on placement, so also on plain PAF output. A single value sets both. Each value may end with k/K/m/M/g/G. The long form is --chain-band. DNA presets only; ava-ont and ava-hifi, which do not partition the read, refuse it.

-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 alternative loci enter the ownership selection, which chains attached to an owner are aligned beside it and kept as secondary alignments, and which rival a piece of a split read is weighed against in the mapping quality: one whose chain scores at least FLOAT times the primary's, or within 2k of it.

-N INT

Retain at most INT secondary alignments [1; splice presets 5]. Under a DNA preset the base-level lane realizes and keeps up to INT rivals per read whether or not they are printed; one prices the mapping quality. -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]. The splice presets use 2.

--max-vote-occ INT

Ignore a seed whose reference occurrence is above INT when voting, and under a DNA preset when chaining too; 0 turns occurrence filtering off [200]. Unset, the cap is the larger of 200 and the occurrence of the top 1.81e-4 fraction of the most frequent seeds in the index, at most 500 under lr:hq, and the DNA chaining gates take the same cap. The splice presets keep the fixed 200. 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. DNA presets only.

--dw INT

Width in reference bases of the diagonal bin a seed votes into, greater than 0 [64]. lr:hq and splice:hq use 48. Under a DNA preset the width otherwise grows with the read length; a value given here fixes it and turns that growth off.

--dw-slope-den INT

Denominator of the term that grows the vote bin with read length: the width is the read length divided by INT, held between the base width and the cap [128]. lr:hq, ava-ont and ava-hifi use 64, and 0 drops the term. DNA presets only.

--dw-max INT

Largest width that growth may reach, greater than 0 [2048]. While the growth is on it may not be below the width --dw sets. DNA presets only.

--vote-seeds INT

Seeds per strand that vote [128; 4096 on asm5, asm10, asm20; 256 on ava-ont]: the read is cut into INT 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 INT-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. Neither --min-support nor --max-cands scales with INT; a vote peak needs --min-support votes (3 on the DNA presets), so an INT below that places few reads or none. The Python field is Config.max_query_seeds. DNA presets only; the splice presets take --vote-spacing.

--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 partition nothing. 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.

--tiles INT

Query tiles the read is cut into for placement, 2 to 4096 [128; 2048 on asm5, asm10, asm20]. The exact query partition gives each tile one candidate or none, and an owned block needs two tiles with seed support. Under the default --tile-score, 2 tiles place no read: a two-tile block scores 8 - 12 = -4, below the -2 of leaving both tiles unowned. The --tile-score terms are per tile, so their weight against each other and against the read's length moves with INT. A candidate starts with the tiles in which a voting seed supports it, so with fewer voting seeds than tiles (--vote-seeds) most tiles start unsupported and candidates are hard to admit; keep --vote-seeds at least INT. Above 2048 tiles, candidates are admitted by comparing their supports on 2048 tiles. The partition's work grows with INT. DNA presets only.

--tile-score hit=INT,block=INT,null=INT,miss=INT

Objective of the exact query partition, which decides for each of the read's query tiles (--tiles) which candidate owns it [hit=4,block=12,null=1,miss=0]. Under a DNA preset the partition picks the candidates chained over the whole read, and the anchors of those chains then decide which chain owns each part of the read. hit rewards an owned tile the seeds support and is at least 1; block is charged each time an ownership block opens, null per valid tile left unowned, and miss per owned tile without seed support, each at least 0. Any subset of the keys may be given, and a repeated key keeps its last value. 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 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 a DNA preset writes no secondary alignment. 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).

-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 loads neither the reference nor the reads, so flashalign align -x lr:hq --show-config is a complete invocation; of a .faix target it reads the header alone.

--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 [3]. 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.