Tracking: remaining ROADMAP.md items (Phases 14, 16, 17) #298

Tracks the items still open in ROADMAP.md as of abf2ab7, with what was measured against STAR 2.7.11b. Thematic background lives in #143, development status in #163.

Phase 14, STARsolo

• 14.7 CB/UB/GX/GN SAM tags + CB_samTagOut: feat(solo): STARsolo per-read SAM tags, CB_samTagOut and paired-end barcode reads (Phase 14.7) #226 (rebased on main; CB/UB are now filled as records leave the bounded-memory sort from feat(io): bound coordinate-sort memory with an external merge #214, with a test through a spilled sort)

Phase 17, features

The four "planned" sub-phases are already on main. Checked against STAR on 20k yeast pairs:

The remaining differences come from alignment parity (Phase 16 below).

• Roadmap text updated: docs(roadmap): mark 17.2-17.6 and 17.B done #296
• @HD VN:1.4 like STAR (was 1.6): fix(sam): STAR's header text, from @HD VN:1.4 to the @CO command line #297

Phase 16, algorithm parity

Items listed in the roadmap:

• .18919121 "SA construction diff": no longer reproducible. Genome, SA and SAindex built by rustar are byte-identical to STAR's on R64-1-1, with and without the GTF.
• .6302610 PE false positive: no longer reproducible.
• SE CIGAR insertion placement: see theme 1 below.
• PE AS diffs: covered by the themes below.

Measured on the first 200k pairs of ERR12389696, STAR index with GTF (sjdbOverhang 149), default parameters. "Diff" counts mates whose primary differs and that are not multi-mapper ties (same NH, same AS, same loci set).

Remaining themes on top of #295 (one PR each, if a STAR-faithful fix exists):

• 1. Insertion placement in repeats (same AS, I at a different read position), ~15 mates: root cause was the seed search, fix(seed): padding sorts above every base in the SA binary search #300 (padding compared on the wrong side in the SA binary search; on main it fixes 77 mates and the mates only rustar maps go from 68 to 12)
• 2. Short-range alignments STAR finds with a higher AS (short exon at a read end), ~20 mates: fix(align): STAR's seed-overlap order, insertion with overlapping seeds, sjdb overhang per side #302 (seed overlap in rStart order, negative genome gap as insertion, sjdb overhang per side; stacked on fix(align): never stitch same-diagonal seeds; port STAR's PE junction consistency walk #301)
• 3. Long-range splices with alignIntronMax 0 (window formation), both directions, ~20 mates: fix(align): STAR's window formation and per-window dedup for long splices #304 (no 589 kb pair cap when alignMatesGapMax is 0, flanks stop at chromosome ends, STAR's per-window dedup; stacked on fix(align): STAR's seed-overlap order, insertion with overlapping seeds, sjdb overhang per side #302). Fixes ROADMAP reads .13842 and .15864.
• 4. Chromosome X 120.7-121.3 kb (gene with several short annotated introns), ~25 mates: fix(align): never stitch same-diagonal seeds; port STAR's PE junction consistency walk #301 (same-diagonal seeds are never stitched, STAR's PE junction-consistency walk; 70 mates fixed on top of fix(align): stitch annotated junctions like STAR; drop covered PE sub-alignments #295)
• 5. Pairs only one tool maps (34 only rustar, 15 only STAR): fix(seed): treat N-flagged SAindex prefixes as non-tight, as STAR's iSA1noN #303 (N-flagged SAindex prefixes are not tight bounds). Remaining: .84534 (STAR finds 16 loci, uT:3), .114807-like mate-start cases.

PRs will be linked here as they open.

Measurement note

The first numbers above counted a mate as matching when chromosome, position and CIGAR matched, even if NH differed. Counting NH too (2026-10-09), each PR was re-checked mate by mate against its base:

Found while reviewing the work above

• SAM tags are written in a fixed order; STAR follows the order given to --outSAMattributes (nM AS NH MD comes out NH AS nM MD): fix(sam): write optional tags in --outSAMattributes order, as STAR (and STAR's fixed unmapped / quant tag sets) #306

• --outSAMtype BAM Unsorted SortedByCoordinate (both files at once) is rejected: feat(params): accept --outSAMtype BAM Unsorted SortedByCoordinate (both BAM outputs), outStd routed per output as STAR #305 (also makes --outStd redirect only the matching output, as STAR)

• Header (fix(sam): STAR's header text, from @HD VN:1.4 to the @CO command line #297 now covers all of these): no @CO user command line: line; --outSAMheaderCommentFile lines get a second @CO prefix; the TranscriptomeSAM BAM has @HD/@PG where STAR writes only @SQ/@RG; a user @HD without VN still gets VN:1.4

• max_mappable_length updates its i1a/i1b history in the opposite order to STAR: checked, cannot change the SA range found, no change made

• feat(solo): STARsolo per-read SAM tags, CB_samTagOut and paired-end barcode reads (Phase 14.7) #226: barcode/gene tags without BAM output were dropped silently; now refused like STAR

• Unmapped records carry AS:i:0 nM:i:0; STAR writes the best transcript's values: fix(sam): unmapped records carry trBest's AS/nM, MAPQ 0 and STAR's half-mapped fields #310 (with MAPQ, uT:4 and half-mapped mate fields). With fix(align): last yeast differences; 200k pairs now match STAR mate for mate #311: all 62,966 unmapped records of the 200k pairs identical to STAR, from 0

• Fully unmapped records have MAPQ 255; STAR writes 0: fix(sam): unmapped records carry trBest's AS/nM, MAPQ 0 and STAR's half-mapped fields #310

• MC and ch attributes are not implemented (STAR's All includes both): feat(sam): MC:Z mate CIGAR and ch:A chimeric tags, --outSAMattributes All as STAR #309

• Chimeric WithinBAM records use a fixed SA NM AS set and ignore --outSAMattributes: checked with main's Port STAR's WithinBAM output (supersedes #282); PE nM is the pair's #307 + feat(sam): MC:Z mate CIGAR and ch:A chimeric tags, --outSAMattributes All as STAR #309, tags and order match STAR on every chimeric record in 7 attribute configurations

• An explicit XS in --outSAMattributes is dropped unless --outSAMstrandField intronMotif; STAR switches to intronMotif instead: fix(params): an explicit XS in --outSAMattributes turns on --outSAMstrandField intronMotif, as STAR #314 (with the parity stack, branch merge/xs-on-parity-stack: XS identical to STAR at all 332,692 common loci of the 200k pairs)

• --quantMode GeneCounts requires --sjdbGTFfile even when the index already has the annotation; STAR does not: Load the gene model from the index tables when no --sjdbGTFfile is given (GeneCounts, solo Gene/GeneFull, GX/GN) #308

• With a GTF given at mapping time, annotated non-canonical junctions are keyed on true coordinates rather than STAR's flushed ones: fix(index): insert --sjdbGTFfile junctions at mapping time exactly as genomeGenerate does (flushed keys, Gsj, SA) #312 (STAR's on-the-fly sjdb insertion; 0 mates differ on 200k pairs, _STARgenome byte-identical)

• Yeast PE reads still differing after the whole stack: all fixed by fix(align): last yeast differences; 200k pairs now match STAR mate for mate #311 (strict seed-chain bound, junction-scan early exit, pair genomic-length span; with fix(seed): padding sorts above every base in the SA binary search #300 and fix(seed): treat N-flagged SAindex prefixes as non-tight, as STAR's iSA1noN #303 merged in)

Whole stack

#295 (with its fix) + #301 + #302 + #304, on the first 200k pairs of ERR12389696 against STAR 2.7.11b, NH-aware: 350 mates fixed, 0 newly differing versus main. #300 and #303 are independent of that stack and add 86 and 9 more on main.

• With a GTF given at mapping time, TranscriptomeSAM still prefers the index tables: Use the mapping-time --sjdbGTFfile for the TranscriptomeSAM tables, in STAR's transcript order #313 (and STAR's transcript order; @sq lines identical)
• fix(sam): paired-end nM is the pair's mismatch total, as in STAR #294 superseded by main's Port STAR's WithinBAM output (supersedes #282); PE nM is the pair's #307 (PE nM = pair total)

200k yeast pairs: mate for mate

With #311 (= #295 + #301 + #302 + #304 + #300 + #303 + #311), the first 200k ERR12389696 pairs match STAR 2.7.11b on chromosome, position, CIGAR and NH for every mate, paired-end and single-end, on the index with and without the GTF. The only remaining differences are multimapper primary ties (DIVERGENCE.md §1.1). Versus main: 459 mates fixed with the GTF index, 205 without, 0 newly differing.

• Chimeric detection (yeast 20k): PE 75/78 WithinBAM records identical, 3 differ in position; SE 82/86, STAR finds 2 chimeric reads rustar misses and one multimapper differs (NH 1 + SA vs NH 2)

• TranscriptomeSAM records: fix(quant): Aligned.toTranscriptome.out.bam record for record as STAR (primary draw, pair-level soft-clip budget, MAPQ, mate order, merged CIGAR, deletions, alignment order) #315 (STAR's random primary via its mt19937 stream, pair-level soft-clip budget, merged M blocks, MAPQ from nAlignT, STAR's order): all 274,542 records of the 200k pairs identical to STAR --runThreadN 1, in order. Single-end order and BySJout draw order done on fix(quant): Aligned.toTranscriptome.out.bam record for record as STAR (primary draw, pair-level soft-clip budget, MAPQ, mate order, merged CIGAR, deletions, alignment order) #315 too.

• --outFilterType BySJout and SJ.out.tab filtering: fix(sj): outFilterType BySJout and SJ.out.tab filtering as STAR (outputSJ, two-stage held reads) #316 (genomic SAM, SJ.out.tab and transcriptome BAM identical to STAR on 200k pairs; Normal-mode SJ.out.tab now identical too)

• --twopassMode Basic: fix(twopass): --twopassMode Basic as STAR: pass-1 SJ.out.tab, sjdbInsertJunctions, pass 2 on the extended genome #317 (pass-1 junctions inserted into the genome like STAR; pass-1 and final SJ.out.tab byte-identical, 0 mates differ)