TARS: Transcript Alignment for RNA Splicing (AUS-418)

[shiv-hartwig]

TARS (Transcript Alignment for RNA Splicing) is a new tool giving STAR-like splice-aware RNA alignments using bwa-mem2.

How it works

1. SpliceFastaBuilder (offline, once per ensembl release) builds synthetic per-transcript contigs (concatenated exon sequences) plus a sidecar TSV mapping each contig back to gene / transcript / exon spans.
2. RNA reads are aligned with bwa-mem2 against the genome FASTA with those transcript contigs appended.
3. SpliceLiftBack rewrites the transcript-contig alignments back to genomic coordinates (introns become N CIGAR ops; XA / SA / mate fields made genomic), producing an ordinary genomic RNA BAM ready for downstream tools.

Highlights

• Consumes bwa's name-grouped output in a single streaming pass (no input sort, no fragment cache); decompression is offloaded to the bam tool's threads so workers stay fed. Writes a coord-sorted + indexed BAM.
• A ref-vs-tx discriminator picks the right primary when a read maps both to the genome and a transcript contig (spliced vs intron-retained / paralog).
• Optional refinement passes recover junctions bwa fragments or mis-trims: rescue-via-supp, terminal micro-junction collapse, softclip tail-extend, junction canonicalize. All boundary re-scoring shares one bwa-mem affine model (BwaMemScore).
• Excluded regions (-rna_unmap_regions: rRNA / 7SL / acrocentric / multi-map zones) are handled post-lift on genomic coords REDUX-style: a primary lifting in is unmapped (kept, not dropped), a supplementary is dropped and its entry stripped from the primary's SA. Post-lift because a tx-contig read's input coords are chrN_tx and some excluded zones (acrocentric arms) are themselves in the transcriptome, so contamination only becomes visible once lifted.
• Logging: INFO stays scannable (lifecycle + headline counts + producer backlog/throughput); per-worker progress at DEBUG; per-read decision tracing (discriminator / rescue / collapse / extend / canonicalize / unmap) at TRACE.
• Per-record debug TSVs gated behind -write_liftback_tsv (off by default; whole-sample they run to 100s of GB).

Docs

• tars/README.md: following hmftools pattern
• tars/policy.md: the precise decision policy: every tunable constant (with where/why/gotcha), the ref-vs-tx decision tree, the modify-read passes, and rule precedence.

[shiv-hartwig]

Superseded by #839. The branch was renamed to AUS418-tars-star-replacement for AUS-418; GitHub cannot move an open PR's head branch, so review continues on #839. This PR is kept as the earlier review record.