Selective alignment parameter tuning

selective-alignment-parameter-tuning

Summary

Adjust chain-pruning thresholds and seed-representation strategies in selective-alignment mode to optimize mapping rate and quantification accuracy for RNA-seq transcript abundance estimation. This skill is essential when comparing implementations (C++ vs. Rust salmon) or when default chain-pruning settings leave reads unmapped that alternative thresholds would recover.

When to use

Apply this skill when you observe discrepancies in mapping rate or per-transcript quantification between two salmon implementations, or when the default chain-pruning thresholds (orphanChainSubThresh, postMergeChainSubThresh) are leaving a substantial fraction of reads unmapped (e.g., >1% difference in mapping rate). Use it to systematically isolate whether differences are due to k-mer lookup bugs (pufferfish orientation), threshold defaults, or seed representation granularity.

When NOT to use

• Input reads are from a different organism or library type than the baseline — comparison requires the same dataset and index.
• You are comparing salmon 2.0 (Rust) against C++ salmon 1.12.0 without controlling for the pufferfish SSHash streaming orientation bug — apply the pufferfish fix (commit 5dce7f4) first.
• The observed mapping-rate or quantification discrepancy is <0.01% — further parameter tuning is unlikely to be statistically meaningful and may introduce artifacts.

Inputs

• FASTQ reads (single-end or paired-end)
• salmon reference index (built from transcriptome FASTA on byte-identical basis)
• chain-pruning parameter values (orphanChainSubThresh, postMergeChainSubThresh, preMergeChainSubThresh)
• seed representation strategy (default unitig-constrained, sparse fixed-k, reference-extended, true unitig MEM)

Outputs

• quant.sf file (per-transcript NumReads, EffectiveLength, TPM)
• mapping rate (percentage of reads mapped)
• per-read mapping agreement summary (percentage of fully unmapped reads on which both tools agree)
• Pearson correlation coefficients (NumReads and EffectiveLength between baseline and variant)
• unmapped_names.txt (fully unmapped read identifiers for cross-comparison)

How to apply

First, establish a baseline by running selective-alignment quantification with default parameters (salmon quant -l <libType> with default chain thresholds) on a byte-identical reference index and recording per-transcript NumReads, TPM, and mapping rate. Next, identify the source of discrepancies: check if a k-mer lookup orientation bug exists (by comparing against minimap2 full Smith-Waterman), then test alternative chain-pruning thresholds by running salmon quant with modified orphanChainSubThresh and postMergeChainSubThresh values. For seed representation variants, re-run the mapper with sparse fixed-k anchors, reference-extended MEMs, or unitig-constrained uni-MEMs. Calculate Pearson correlation coefficients (NumReads and EffectiveLength) between each variant and the baseline; correlations ≥0.99999995 indicate the variant does not explain observed gaps. Finally, validate that mapping rate changes are within ≤0.01% tolerance and compare per-read mapping agreement (fully unmapped reads coded 'u' in mapping outputs) to confirm the source of the improvement.

Related tools

• salmon 2.0 (primary mapper and quantifier; run with varied chain-pruning thresholds and seed representations in selective-alignment mode) — https://github.com/COMBINE-lab/salmon
• salmon 1.12.0 (C++) (reference implementation for comparison; use default C++ thresholds (orphanChainSubThresh=0.95, postMergeChainSubThresh=0.9) as baseline) — https://github.com/COMBINE-lab/salmon/tree/cpp
• pufferfish (underlying k-mer lookup engine; fix streaming orientation bug (commit 5dce7f4) to ensure fair comparison between C++ and Rust)
• piscem-rs (Rust mapper backend; derives k-mer orientation correctly and was validated against C++ after pufferfish fix)
• minimap2 (full Smith-Waterman alignment for validation; use to confirm strand and locus agreement of differentially mapped reads)

Examples

salmon quant -i salmon_index -l A -1 reads_1.fastq.gz -2 reads_2.fastq.gz -p 16 -o sample_quant_baseline && salmon quant -i salmon_index -l A -1 reads_1.fastq.gz -2 reads_2.fastq.gz -p 16 --orphanChainSubThresh 0.95 --postMergeChainSubThresh 0.9 -o sample_quant_tuned

Evaluation signals

• Pearson correlation coefficient for NumReads between baseline and tuned variant ≥0.99999995 (variant does not explain observed gap) or <0.99999995 (variant introduces systematic shift requiring investigation).
• Per-read mapping agreement: count fully unmapped reads (coded 'u' in mapping outputs) that both tools agree upon; ≥99% agreement indicates chain-pruning thresholds are not the primary source of discrepancy.
• Mapping rate difference: ≤0.01% tolerance between baseline and variant indicates threshold change did not materially affect sensitivity; >0.01% difference suggests the threshold is a key parameter.
• Byte-identical index validation: confirm that both salmon implementations build indices with identical bytes (hash seeds, bit-vectors, k-mer encoding) to isolate algorithmic from implementation differences.
• Cross-check read placement using SAM/BAM writeMappings output: for reads identified as differentially mapped, verify strand orientation and transcript locus match between variants to rule out spurious placements.

Limitations

• Chain-pruning parameter tuning is implementation-specific: C++ salmon 1.11.4 uses orphanChainSubThresh=0.95 and postMergeChainSubThresh=0.9 by default, while Rust salmon 2.0 uses orphanChainSubThresh=0.0 and postMergeChainSubThresh=0.0, making direct cross-version comparison require explicit threshold matching.
• ~80% of mapping-rate differences between C++ and Rust implementations are attributable to chain-pruning defaults, not seed-representation granularity; optimizing seed representation alone will not recover the gap.
• Byte-identical index requirement limits practical applicability: indices must be rebuilt with identical FASTA cleaning (e.g., non-ACGT replacement rules, poly-A clipping ≥10 trailing As) to ensure fair comparison; pre-built indices from different sources may not be directly comparable.
• Pearson correlation metric can mask outliers: high overall correlation (r≥0.999) does not guarantee agreement on lowly-expressed transcripts; use supplementary quantile-quantile plots or per-transcript fold-change distributions to detect systematic biases.
• Seed representation variants (sparse fixed-k, reference-extended MEMs, true unitig uni-MEMs) are theoretical constructs tested only on Rust salmon; their behavior on C++ implementation is not characterized in this article.

Evidence

• [methods] On real short reads the Rust port mapped ~2% more reads than C++ salmon. That extra ~2% was not a Rust 'sensitivity choice' — it exposed a k-mer-orientation bug in pufferfish's SSHash streaming lookup: "On real short reads the Rust port mapped ~2% more reads than C++ salmon. That extra ~2% was not a Rust 'sensitivity choice' — it exposed a k-mer-orientation bug in pufferfish's SSHash streaming lookup"
• [methods] After fixing pufferfish (commit 5dce7f4, salmon pin bumped), C++ salmon maps the same reads: 83.48% → 85.55%, matching the Rust port to within 1 read: "After fixing pufferfish (commit 5dce7f4, salmon pin bumped), C++ salmon maps the same reads: 83.48% → 85.55%, matching the Rust port to within 1 read"
• [methods] ~80% (~49k): a chain-sub-optimality default difference (describable, deferred). C++ prunes low-coverage chains/orphans before alignment using orphanChainSubThresh = 0.95 and postMergeChainSubThresh = 0.9: "C++ prunes low-coverage chains/orphans before alignment using orphanChainSubThresh = 0.95 and postMergeChainSubThresh = 0.9"
• [methods] NumReads Pearson correlation is 0.99854 between C++ and Rust on byte-identical index: "On byte-identical index, NumReads Pearson correlation is 0.99854 between C++ and Rust"
• [methods] Compute Pearson correlation coefficient (r) between NumReads counts from each variant and the default baseline using correlation analysis, verifying r ≥ 0.99999995 for all variants.: "Calculate Pearson correlation coefficient (r) between NumReads counts from each variant and the default baseline using correlation analysis, verifying r ≥ 0.99999995 for all variants"
• [intro] salmon 2.0 (Rust): from-scratch Rust rewrite of salmon: "This is salmon 2.0 — a from-scratch Rust rewrite of salmon"
• [intro] It keeps the same workflow (salmon index → salmon quant → quant.sf) and the same output formats downstream tools read: "It keeps the same workflow (salmon index → salmon quant → quant.sf) and the same output formats downstream tools read"