RNA-seq read mapping parameter tuning
Summary
Systematically adjust chain-pruning thresholds and selective-alignment parameters in transcript mappers to resolve discrepancies in mapping rate between implementations and recover reads left unmapped by suboptimal defaults. This skill is essential when a reference implementation (e.g., C++ salmon 1.12.0) and a port (e.g., Rust salmon 2.0) show unexplained mapping-rate gaps on identical inputs.
When to use
When comparing two implementations of the same RNA-seq mapping algorithm on identical reference indices and read sets, if per-read mapping agreement is <99.8% or the overall mapping rate differs by >0.02%, investigate whether chain-pruning defaults (orphanChainSubThresh, postMergeChainSubThresh, preMergeChainSubThresh) or alignment-score thresholds are causing the divergence. Use this skill to isolate which parameter(s) account for the gap and whether tuning them recovers the missing mapped reads.
When NOT to use
- Do not use this skill when comparing two independent algorithms on different indices or under different library-type assumptions; parameter tuning will not resolve algorithmic differences.
- Do not apply this skill if the reference implementation uses bias-correction, poly-A clipping, or decoy sequences that the port does not; first harmonize preprocessing before tuning mapping parameters.
- Do not use this skill as a substitute for fixing upstream bugs (e.g., k-mer-orientation errors in k-mer lookup); it is appropriate only for resolving gaps due to parameter defaults, not correctness bugs.
Inputs
- Byte-identical reference transcriptome index (built with identical k-mer length, deterministic N-replacement)
- Paired-end RNA-seq reads in FASTQ format (or equivalent; test on well-characterized, publicly available datasets)
- Configuration files or parameter sets for both implementations being compared
Outputs
- Mapping statistics (total mapped reads, mapping rate percentage) for each parameter configuration
- Per-read mapping agreement matrix (% reads mapped by both, by one only, by neither)
- NumReads Pearson correlation coefficient between implementations
- Classification of boundary-case reads (strong/weak/unaligned) from full-alignment re-ranking
- Quantified attribution of mapping gap to specific parameter(s)
How to apply
First, quantify the magnitude and asymmetry of the mapping gap on a byte-identical reference index using a well-characterized dataset (e.g., GEUVADIS ERR188044, 36.35M 76 bp paired-end reads). Run both implementations with selective alignment enabled and identical flags (no bias correction, deterministic k-mer replacement) and measure per-read mapping agreement, NumReads correlation, and counts of reads mapped by only one implementation. Next, systematically adjust chain-pruning parameters: C++ salmon 1.12.0 uses orphanChainSubThresh=0.95 and postMergeChainSubThresh=0.9 as defaults; rerun the Rust port with these same values and re-measure mapping counts and per-read agreement. If tuning reduces the disagreement from ~63k to <20k reads and brings mapping rate within 0.02% of the reference, the gap is attributable to pruning-threshold defaults. For residual discrepancies, use full Smith-Waterman re-alignment (e.g., minimap2) on boundary-case reads to classify them as strong/weak/unaligned and determine whether the remaining gap stems from alignment-score thresholds, k-mer-orientation bugs, or other systematic biases.
Related tools
- salmon (Primary transcript-mapping and quantification engine; tuning applies to both salmon 2.0 (Rust) and salmon 1.12.0 (C++) when invoked with selective alignment (-l A) and chain-pruning flags (--orphanChainSubThresh, --postMergeChainSubThresh).) — https://github.com/COMBINE-lab/salmon
- minimap2 (Full Smith-Waterman aligner used to re-rank boundary-case reads and classify them as strong/weak/unaligned in order to diagnose source of residual mapping disagreement.)
- piscem-rs (Underlying selective-alignment and k-mer-lookup library for salmon 2.0 Rust port; parameter tuning is applied via salmon CLI flags that configure piscem-rs behavior.) — https://github.com/COMBINE-lab/salmon
- pufferfish (K-mer index and lookup library used by salmon; bugs in pufferfish k-mer-orientation (e.g., commit 5dce7f4) can cause spurious mapping gaps that must be distinguished from parameter-tuning issues.)
Examples
salmon quant -i salmon_index -l A -1 reads_R1.fastq.gz -2 reads_R2.fastq.gz --orphanChainSubThresh 0.95 --postMergeChainSubThresh 0.9 -p 16 -o quant_tuned
Evaluation signals
- Mapping rate of tuned implementation must be within 0.02% of reference (e.g., 92.011% ± 0.02% for C++ salmon 1.12.0 on ERR188044).
- Per-read mapping agreement must reach ≥99.8% after tuning (measured as % of reads on which both implementations agree, mapped or unmapped).
- Residual per-read disagreement (reads mapped by Rust only + reads mapped by C++ only) must drop from initial gap (~63k reads on ERR188044) to <20k reads after tuning.
- NumReads Pearson correlation between implementations must be ≥0.99854 after parameter adjustment.
- Full Smith-Waterman re-alignment (minimap2) of remaining boundary-case reads should show symmetric disagreement (not skewed toward one implementation) and classify >90% of remaining reads as 'weak' rather than 'strong', confirming they are ambiguous rather than false negatives.
Limitations
- Parameter tuning assumes both implementations use identical preprocessing (poly-A clipping ≥10 trailing As, deterministic N-replacement) and identical reference indices; if upstream steps differ, tuning will not resolve the gap.
- Chain-pruning parameters are implementation-specific and may not be directly transferable; the exact thresholds (orphanChainSubThresh=0.95, postMergeChainSubThresh=0.9) were validated only for salmon C++ 1.12.0 vs. Rust 2.0 on ERR188044.
- Tuning maps only ~80% of the observed gap; the remaining ~20% may stem from k-mer-orientation bugs, alignment-score thresholds, or floating-point rounding differences that require deeper debugging.
- The skill does not address single-cell (alevin) mapping; those parameters are now managed by alevin-fry, not salmon 2.0.
- Validation requires a well-characterized, publicly available dataset (e.g., GEUVADIS) with known ground-truth or consensus mapping profiles; results on other datasets may differ.
Evidence
- [other] Does applying C++ salmon 1.12.0's chain score thresholds (orphanChainSubThresh=0.95, postMergeChainSubThresh=0.9) to the Rust salmon port on ERR188044 reduce the mapping count gap and confirm that
80% of the discrepancy is attributable to the orphan/post-merge pruning default difference?: "C++ salmon uses orphanChainSubThresh=0.95 and postMergeChainSubThresh=0.9 for chain pruning before alignment, accounting for approximately 80% (49k reads) of the observed mapping count gap between"
- [other] Workflow and metrics described in task card: "Rust mapping rate must be ≥92.03% (within 0.02% of C++ 1.12.0); residual per-read disagreement (Rust-only + C++-only) must drop from 62,966 to <20,000 reads; per-read mapping agreement ≥99.8%."
- [methods] Methods section describing pufferfish k-mer-orientation fix: "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] Methods section describing per-read agreement metric: "per-read mapping agreement | 99.83%"
- [methods] Methods section describing boundary-case re-alignment: "minimap2 (full SW) on these reads gives near-identical quality profiles in both directions"
- [readme] README introduction emphasizing breaking changes and index rebuild requirement: "The most important one: the index format changed, so you must rebuild your index."
1---2name: rna-seq-read-mapping-parameter-tuning3description: Use when when comparing two implementations of the same RNA-seq mapping algorithm on identical reference indices and read sets, if per-read mapping agreement is <99.8% or the overall mapping rate differs by >0.4license: CC-BY-4.05---67# RNA-seq read mapping parameter tuning89## Summary1011Systematically adjust chain-pruning thresholds and selective-alignment parameters in transcript mappers to resolve discrepancies in mapping rate between implementations and recover reads left unmapped by suboptimal defaults. This skill is essential when a reference implementation (e.g., C++ salmon 1.12.0) and a port (e.g., Rust salmon 2.0) show unexplained mapping-rate gaps on identical inputs.1213## When to use1415When comparing two implementations of the same RNA-seq mapping algorithm on identical reference indices and read sets, if per-read mapping agreement is <99.8% or the overall mapping rate differs by >0.02%, investigate whether chain-pruning defaults (orphanChainSubThresh, postMergeChainSubThresh, preMergeChainSubThresh) or alignment-score thresholds are causing the divergence. Use this skill to isolate which parameter(s) account for the gap and whether tuning them recovers the missing mapped reads.1617## When NOT to use1819- Do not use this skill when comparing two independent algorithms on different indices or under different library-type assumptions; parameter tuning will not resolve algorithmic differences.20- Do not apply this skill if the reference implementation uses bias-correction, poly-A clipping, or decoy sequences that the port does not; first harmonize preprocessing before tuning mapping parameters.21- Do not use this skill as a substitute for fixing upstream bugs (e.g., k-mer-orientation errors in k-mer lookup); it is appropriate only for resolving gaps due to parameter defaults, not correctness bugs.2223## Inputs2425- Byte-identical reference transcriptome index (built with identical k-mer length, deterministic N-replacement)26- Paired-end RNA-seq reads in FASTQ format (or equivalent; test on well-characterized, publicly available datasets)27- Configuration files or parameter sets for both implementations being compared2829## Outputs3031- Mapping statistics (total mapped reads, mapping rate percentage) for each parameter configuration32- Per-read mapping agreement matrix (% reads mapped by both, by one only, by neither)33- NumReads Pearson correlation coefficient between implementations34- Classification of boundary-case reads (strong/weak/unaligned) from full-alignment re-ranking35- Quantified attribution of mapping gap to specific parameter(s)3637## How to apply3839First, quantify the magnitude and asymmetry of the mapping gap on a byte-identical reference index using a well-characterized dataset (e.g., GEUVADIS ERR188044, 36.35M 76 bp paired-end reads). Run both implementations with selective alignment enabled and identical flags (no bias correction, deterministic k-mer replacement) and measure per-read mapping agreement, NumReads correlation, and counts of reads mapped by only one implementation. Next, systematically adjust chain-pruning parameters: C++ salmon 1.12.0 uses orphanChainSubThresh=0.95 and postMergeChainSubThresh=0.9 as defaults; rerun the Rust port with these same values and re-measure mapping counts and per-read agreement. If tuning reduces the disagreement from ~63k to <20k reads and brings mapping rate within 0.02% of the reference, the gap is attributable to pruning-threshold defaults. For residual discrepancies, use full Smith-Waterman re-alignment (e.g., minimap2) on boundary-case reads to classify them as strong/weak/unaligned and determine whether the remaining gap stems from alignment-score thresholds, k-mer-orientation bugs, or other systematic biases.4041## Related tools4243- **salmon** (Primary transcript-mapping and quantification engine; tuning applies to both salmon 2.0 (Rust) and salmon 1.12.0 (C++) when invoked with selective alignment (-l A) and chain-pruning flags (--orphanChainSubThresh, --postMergeChainSubThresh).) — https://github.com/COMBINE-lab/salmon44- **minimap2** (Full Smith-Waterman aligner used to re-rank boundary-case reads and classify them as strong/weak/unaligned in order to diagnose source of residual mapping disagreement.)45- **piscem-rs** (Underlying selective-alignment and k-mer-lookup library for salmon 2.0 Rust port; parameter tuning is applied via salmon CLI flags that configure piscem-rs behavior.) — https://github.com/COMBINE-lab/salmon46- **pufferfish** (K-mer index and lookup library used by salmon; bugs in pufferfish k-mer-orientation (e.g., commit 5dce7f4) can cause spurious mapping gaps that must be distinguished from parameter-tuning issues.)4748## Examples4950```51salmon quant -i salmon_index -l A -1 reads_R1.fastq.gz -2 reads_R2.fastq.gz --orphanChainSubThresh 0.95 --postMergeChainSubThresh 0.9 -p 16 -o quant_tuned52```5354## Evaluation signals5556- Mapping rate of tuned implementation must be within 0.02% of reference (e.g., 92.011% ± 0.02% for C++ salmon 1.12.0 on ERR188044).57- Per-read mapping agreement must reach ≥99.8% after tuning (measured as % of reads on which both implementations agree, mapped or unmapped).58- Residual per-read disagreement (reads mapped by Rust only + reads mapped by C++ only) must drop from initial gap (~63k reads on ERR188044) to <20k reads after tuning.59- NumReads Pearson correlation between implementations must be ≥0.99854 after parameter adjustment.60- Full Smith-Waterman re-alignment (minimap2) of remaining boundary-case reads should show symmetric disagreement (not skewed toward one implementation) and classify >90% of remaining reads as 'weak' rather than 'strong', confirming they are ambiguous rather than false negatives.6162## Limitations6364- Parameter tuning assumes both implementations use identical preprocessing (poly-A clipping ≥10 trailing As, deterministic N-replacement) and identical reference indices; if upstream steps differ, tuning will not resolve the gap.65- Chain-pruning parameters are implementation-specific and may not be directly transferable; the exact thresholds (orphanChainSubThresh=0.95, postMergeChainSubThresh=0.9) were validated only for salmon C++ 1.12.0 vs. Rust 2.0 on ERR188044.66- Tuning maps only ~80% of the observed gap; the remaining ~20% may stem from k-mer-orientation bugs, alignment-score thresholds, or floating-point rounding differences that require deeper debugging.67- The skill does not address single-cell (alevin) mapping; those parameters are now managed by alevin-fry, not salmon 2.0.68- Validation requires a well-characterized, publicly available dataset (e.g., GEUVADIS) with known ground-truth or consensus mapping profiles; results on other datasets may differ.6970## Evidence7172- [other] Does applying C++ salmon 1.12.0's chain score thresholds (orphanChainSubThresh=0.95, postMergeChainSubThresh=0.9) to the Rust salmon port on ERR188044 reduce the mapping count gap and confirm that ~80% of the discrepancy is attributable to the orphan/post-merge pruning default difference?: "C++ salmon uses orphanChainSubThresh=0.95 and postMergeChainSubThresh=0.9 for chain pruning before alignment, accounting for approximately 80% (~49k reads) of the observed mapping count gap between"73- [other] Workflow and metrics described in task card: "Rust mapping rate must be ≥92.03% (within 0.02% of C++ 1.12.0); residual per-read disagreement (Rust-only + C++-only) must drop from 62,966 to <20,000 reads; per-read mapping agreement ≥99.8%."74- [methods] Methods section describing pufferfish k-mer-orientation fix: "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"75- [methods] Methods section describing per-read agreement metric: "per-read mapping agreement | 99.83%"76- [methods] Methods section describing boundary-case re-alignment: "minimap2 (full SW) on these reads gives near-identical quality profiles in both directions"77- [readme] README introduction emphasizing breaking changes and index rebuild requirement: "The most important one: **the index format changed, so you must rebuild your index.**"
