TadpoleMulti

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

TadpoleMulti performs descending-kmer assembly followed by conservative bridging of graph-disconnected contig ends. It assembles initially at a long kmer length to get a robust contig scaffold, then iteratively bridges gaps at progressively shorter kmers, allowing disconnected contigs to be merged when appropriate.

Overview

TadpoleMulti is a wrapper around Tadpole that performs sophisticated multi-kmer assembly. The workflow executes in two distinct phases:

  1. Long-kmer Assembly: Constructs initial contigs at the longest specified kmer length, providing a robust structural scaffold
  2. Progressive Bridging: Sequentially applies shorter kmer lengths to bridge disconnected contigs, using careful heuristics to avoid spurious merges

This approach produces higher-quality assemblies by leveraging the sensitivity of shorter kmers to resolve gaps while maintaining the specificity of longer kmers in the structural phase. Optimal assemblies typically use 3-4 kmer values in descending order (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
  • Intermediate kmers bridge and extend (e.g., 75) with increased sensitivity
  • Final short kmer provides maximum sensitivity (e.g., 31) for closing gaps
  • Kmer lengths must be strictly descending (no equal or increasing values)
  • All values must be odd (e.g., use 75 not 76)
  • Maximum recommended is k=127 (kmer must fit in 64-bit encoding)

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 bridging parameters specific to multi-kmer operation, plus all standard Tadpole parameters which are applied to the initial long-kmer assembly phase.

Multi-kmer Parameters

k=<comma-delimited list>
Strictly descending comma-delimited kmer lengths. Required. Example: k=140,75,31. Kmer values must be positive integers in strictly descending order, each separated by comma with no spaces. All kmers must be odd.
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 at each shorter kmer length. Bridges are progressively discovered and applied; each pass may enable new bridges through simpler paths. Increase for more thorough bridging (slower runtime), decrease for speed.
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)

The following parameters are passed through to Tadpole at every kmer phase (the initial long-kmer assembly and each shorter-kmer bridging pass) and control general assembly behavior. Refer to the Tadpole documentation for full details:

pop=
Bubble popping mode. TadpoleMulti forces pop=f during the shorter-kmer bridging phases; the initial long-kmer phase uses Tadpole's default popping behavior.
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.

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) removes small alternative paths. 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 descending 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

Assembly Phase 1: Long-kmer Scaffold

TadpoleMulti constructs an initial contig set at the longest specified kmer length. This phase uses standard Tadpole assembly with bubble-popping disabled (pop=f) to preserve all structural variants. The resulting "scaffold" contigs represent high-confidence sequence regions.

Assembly Phase 2-N: Progressive Bridging

For each remaining kmer value (in descending order):

  1. Load kmers at the current length
  2. Apply kmers to the contig graph (marking potential bridge paths between disconnected ends)
  3. Enable cross-kmer direct merging in BubblePopper
  4. Execute up to N passes of bubble popping, where each pass:
    • Identifies paths that bridge contig ends
    • Checks depth ratios: rejects if path depth > crosskmaxdepthratio × max(flank coverage)
    • Merges qualifying contigs into single sequences
    • Potentially enables new bridge opportunities for the next pass
  5. Clear kmer tables and continue to next shorter kmer

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.

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 descending comma-delimited k values"

Cause: The k parameter must be a comma-separated list with no spaces (e.g., k=140,75,31, not k=140, 75, 31). Kmer values must be strictly descending.

Error: "Kmer lengths must be positive and strictly descending"

Cause: One or more kmer values are equal to or greater than the previous value. Ensure each kmer is smaller than the one before it.

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: