TadpoleMulti

Script: tadpolemulti.sh Package: assemble Class: TadpoleMulti.java

TadpoleMulti assembles at one kmer length, then processes an ordered list of K values. Each phase fuses eligible shorter-K tip overlaps and bridges remaining gaps, using the count table for that K.

Overview

TadpoleMulti is a wrapper around Tadpole that performs multi-K assembly. The workflow executes in ordered stages:

  1. Initial Assembly: Constructs contigs at the assembly K (assemblek; by default the first value in k)
  2. Ordered Fusion and Bridging: For each K in the phase list, fuses eligible shorter-K tip overlaps (fusek) and bridges unbranched gaps (bridgek). By default the list is processed in the order given (korder=input).

Fusion merges contig ends that overlap exactly by a reciprocal tip overlap. Bridging follows unbranched walks in the count graph between contig ends that are not yet connected. Both are subject to the depth filters described below. Typical assemblies use 3-4 kmer values (e.g., k=140,75,31).

Basic Usage

tadpolemulti.sh in=reads.fq out=assembly.fa k=140,75,31

Required parameters:

Kmer Selection Guidelines

  • First kmer should be long (e.g., 140) to capture rare kmers representing true sequence. With the default assemblek=auto, the first value of k is the assembly K.
  • Intermediate kmers bridge and extend (e.g., 75) with increased sensitivity
  • Final short kmer provides maximum sensitivity (e.g., 31) for closing gaps
  • With korder=input (default), phases run in list order. korder=legacy sorts the unique values into descending order and runs all fusions before all bridges.
  • Fusion K values (fusek) must be shorter than assemblek. Bridge K values (bridgek) may be longer, shorter, or equal to it.
  • When k is given with korder=input, every value in fusek and bridgek must also appear in k
  • TadpoleMulti.java enforces no odd-only or maximum-K rule

Memory and Threading

TadpoleMulti automatically allocates memory based on available resources (default: 14GB). To specify custom memory allocation: 

tadpolemulti.sh in=reads.fq out=assembly.fa k=140,75,31 -Xmx32g

Threading is controlled via the t= parameter (passed through to Tadpole). Default uses available processors.

Parameters

TadpoleMulti supports a core set of multi-K scheduling and bridging parameters, plus all standard Tadpole parameters, which are copied into each Tadpole table that TadpoleMulti builds.

Multi-kmer Parameters

k=<comma-delimited list>
Ordered comma-delimited kmer lengths. Required unless assemblek= is given. Example: k=140,75,31. Values must be positive integers separated by commas with no spaces. With korder=input (default), list order is kept and repeated values request repeated phases (e.g., k=96,124,64,32,96). The first value assembles unless assemblek= is set; the first occurrence of the assembly K in the list is consumed by assembly.
korder=input
input (default) preserves the order of the k list and runs each phase in turn. legacy sorts the unique values into descending order and runs all fusions before all bridges, using the old longest-K defaults.
assemblek=auto
Initial assembly K. auto uses the first value in k. An explicit value overrides the k shorthand. If the value appears in k, its first occurrence is consumed by assembly; if it is absent, assembly runs before the list.
fusek=auto (alias joink=)
Exact reciprocal tip-overlap K values. All must be below assemblek. auto uses every shorter value in k. Set to none to disable fusion.
bridgek=auto
Read-supported unbranched-walk K values. These may be above, below, or equal to assemblek. auto uses every value in k under korder=input. The assembly-K table is bridged only when bridgek is set explicitly and includes assemblek. Set to none to disable bridging.
graphk=auto
Final graph K for simplification, graph output, or path extraction. auto uses the last listed K; a matching final table is reused. A different graphk loads another table. Legacy mode defaults to assemblek. Final graph processing runs when graph operations, graph classification, final low-depth diagnostics, graphmergecoverageratio>0, or sweeplen>0 are active. sweeplen defaults to 500, so final graph processing runs by default. With sweeplen=0 and no other graph option, graphk causes an error.
crosskmaxdepthratio=3
Reject a bridging merge if the path between two contig ends has coverage depth exceeding this multiple of the greater flank coverage. Lower values (e.g., 1.5) create more conservative bridges, higher values (e.g., 5) allow more bridges. Set to 0 to disable depth-based filtering and accept all bridges.
crosskpasses=10
Maximum number of direct-merge passes after each fuse or bridge phase. Passes stop early when a pass merges nothing. Each pass may enable new bridges through simpler paths. Increase for more thorough bridging (slower runtime), decrease for speed.
crosskmaxlen=500
Maximum unbranched bridge distance searched from an eligible contig end. Cycles and branches end the search earlier. This parameter is parsed by Tadpole.
fusenet=null
Optional fusion-join network. Disabled by default. Supply the path to networks/tadpole_fusion.bbnet for the bundled dense model. Requires fusencutoff.
fusencutoff=
Required with fusenet and must be finite and in [0,1]. The bundled model was tested at 0.667098 on simulated bacterial reads with minprob=0 minprobmain=f.
fusecoverageratio=0
Maximum higher/lower whole-contig mean-depth ratio for exact overlap fusion, including final graph-K fusions. Not applied to gap bridges. 0 disables; otherwise the value must be finite and at least 1. When enabled, zero-depth ends are rejected. Uses stored contig depths, not an additional evidence table. The shell usage text gives 1.75 as the example value.
graphmergecoverageratio=0
Same ratio check applied to ordinary direct merges in the final graph. Requests final graph processing and reuses a matching last table. Does not filter the initial assembly, cross-K fusion or bridging, indirect bubble removal, or path extraction. 0 disables; otherwise the value must be finite and at least 1. Zero-depth ends are rejected. Both guards work without a neural network; 1.75 was tested with the bundled network. They can reject correct joins across genuine depth changes.
showstats=t
(boolean) Generate assembly statistics (N50, L50, gap count, etc.) on completion. Requires output to be a FASTA file.
out=<file>
Output FASTA filename. Required. All contigs from the final kmer iteration will be written here. Short-name aliases: out1, oute, oute1

Tadpole Parameters (Passed Through)

Unrecognized arguments are copied into every Tadpole table that TadpoleMulti builds: the initial assembly table and each fusion or bridge table. The following parameters control general assembly behavior. Refer to the Tadpole documentation for full details:

pop=
Bubble popping mode. The initial assembly uses the value given here (or Tadpole's default if absent). TadpoleMulti forces pop=f on every fusion and bridge table.
shave=
Remove contig "whiskers" (small branches at contig ends). Default behavior depends on input data characteristics.
rinse=
Remove small branches and orphan contigs. Useful for cleaning up assembly graph before bridging.
mincountseed=
Minimum kmer count for a kmer to seed contig formation. Higher values require more coverage; lower values include rare kmers.
mincountextend=
Minimum kmer count for contig extension. Lower than mincountseed for sensitivity, higher for specificity.
t=
Number of threads to use. Default: auto-detect. Note: TadpoleMulti resets memory after each kmer iteration; threading remains consistent throughout.

Usage Examples

Basic Multi-kmer Assembly

tadpolemulti.sh in=reads.fq out=assembly.fa k=140,75,31

Assembles using a 3-level descending kmer strategy. The longest kmer (140) captures rare sequence variants. The middle kmer (75) provides bridging sensitivity. The shortest kmer (31) closes remaining gaps. This is a good starting point for most datasets.

Custom Phase Schedule

tadpolemulti.sh in=reads.fq out=assembly.fa assemblek=96 fusek=64 bridgek=128,96,64,32 graphk=96

Assembles at k=96. Phases run in this order: 96 (initial assembly, bridged because bridgek explicitly includes assemblek), 64 (tip-overlap fusion, then bridging), 128 (bridging only, longer than the assembly K), and 32 (bridging only). The final graph is built at k=96. Because the last phase is k=32, this loads a new count table.

Conservative Assembly (Avoid Spurious Bridges)

tadpolemulti.sh in=reads.fq out=assembly.fa k=140,75,31 crosskmaxdepthratio=1.5 crosskpasses=5

Stricter depth-ratio filter (1.5 vs default 3) reduces false bridges caused by uneven coverage. Fewer passes (5 vs default 10) also decreases risk of chain-reaction errors. Use when assembly quality is more important than completeness (e.g., for polishing or structural studies).

Aggressive Assembly (Maximum Bridging)

tadpolemulti.sh in=reads.fq out=assembly.fa k=140,75,31 crosskmaxdepthratio=5 crosskpasses=20 pop=t

Permissive depth-ratio (5) accepts more bridges. More passes (20) allow complex bridging chains. Bubble popping (pop=t) applies to the initial assembly only, because TadpoleMulti forces pop=f on fusion and bridge tables. Use for fragmented assemblies where connectivity matters more than precision (e.g., preliminary scaffolding).

Ultra-Long Kmer Scaffolding

tadpolemulti.sh in=reads.fq out=scaffolds.fa k=255,127,63,31 showstats=t

Four-level strategy with very long initial kmer (255). Useful for high-coverage, high-quality reads where extreme specificity is needed. Reports comprehensive statistics on completion.

How TadpoleMulti Works

Initial Assembly

TadpoleMulti constructs an initial contig set at assemblek (by default the first value in k). Bubble popping follows Tadpole's default unless pop= is given. Tadpole's contig construction is then followed by the ordered phases below.

Ordered Fusion and Bridging Phases

For each entry in the phase list (input order by default, or sorted descending under korder=legacy), TadpoleMulti:

  1. Loads a count table at that K only if the phase needs one: for bridging with at least two eligible contig endpoints, for explicit fusion evidence options, or for final graph processing. Otherwise the phase runs without a new table.
  2. If the K is in fusek, proposes exact reciprocal tip overlaps (overlap K up to assemblek-1) and merges accepted pairs with direct merges.
  3. If the K is in bridgek and at least two eligible contig endpoints exist, traverses unbranched walks at that K from eligible endpoints (up to crosskmaxlen), and merges qualifying walks in up to crosskpasses direct-merge passes.
  4. Releases the phase table and continues to the next entry.

After the last phase, final graph processing runs when it is required. It reuses the table at graphk if the last phase used that K, or loads a new one. It runs exact tip-overlap fusion at graphk when graphk is shorter than assemblek, then simplifies the graph and writes the requested output.

Depth Ratio Heuristic

The crosskmaxdepthratio parameter implements a key safety mechanism. When bridging between two contig ends (flanks) with a kmer path (center), it computes: 

bridge_valid = (center_depth <= crosskmaxdepthratio × max(left_depth, right_depth))

A ratio of 1.0 means the bridge must be as well-covered as the stronger flank (very conservative). A ratio of 3.0 (default) allows bridges 3× deeper than flanks, balancing connectivity with accuracy. A ratio of 0 disables checking.

Optional Coverage Safeguards

fusecoverageratio and graphmergecoverageratio add whole-contig depth checks. They use depths already stored on contigs and do not load an additional evidence table. fusecoverageratio applies to exact overlap fusion, including final graph-K fusions, but not to gap bridges. graphmergecoverageratio applies only to ordinary direct merges during final graph simplification. Both are disabled by default (0).

Performance and Optimization

Runtime Characteristics

Total runtime increases linearly with number of kmers and dataset size. The longest-kmer phase typically dominates (often 50-70% of total time). Subsequent shorter-kmer phases are faster but may create complex bridging patterns.

Memory Usage

TadpoleMulti automatically clears kmer tables between phases, keeping memory usage bounded by the largest single kmer table. Peak memory typically remains near the limit specified at startup (default 14GB).

Thread Scaling

Assembly performance scales nearly linearly up to 16-24 threads on typical systems. Beyond that, contention on hash tables can limit gains. Use t=16 or t=24 for most scenarios.

Kmer Count Impact

Using 3-4 kmers provides good balance. More kmers (5+) adds diminishing returns for extra runtime cost. Fewer kmers (1-2) reduces total bridging capability.

Troubleshooting

Error: "TadpoleMulti requires k=<list> or assemblek=<value>."

Cause: Neither k nor assemblek was given. Provide a comma-separated list with no spaces (e.g., k=140,75,31), or set assemblek explicitly.

Error: "k requires a positive kmer length: ..."

Cause: A value in the k list is zero or negative. Each value must be a positive integer.

Error: "fusek values must be shorter than assemblek=..."

Cause: A fusek value is equal to or greater than assemblek. Fusion requires shorter K values. To bridge at a longer K, list it in bridgek instead.

Error: "Phase K=... is absent from k; include it in the ordered k list."

Cause: With k given and korder=input, a value in fusek or bridgek is missing from the k list. Add it to k, or remove it from fusek or bridgek.

Output File Cannot Be Written

Cause: Insufficient disk space, permission issues, or invalid output path. Ensure the output directory exists and is writable.

Many "bridging" operations produce few results

Possible causes:

Relationship to Tadpole

TadpoleMulti is built on top of Tadpole and should be used instead of manual multi-pass Tadpole invocations. It automatically manages:

For single-kmer assemblies or specialized workflows, use Tadpole directly.

Support

For questions and support: