Alternative polyA/TSS terminal-end transcript discovery + reference-consistent model assignment

[andrewprzh]

Overview

This branch adds alternative-terminal (polyA/TSS) transcript-model discovery and makes the model-side read assignment and quantification consistent with the reference-based path, building on the existing graph-based model construction.

What's new

1. PolyA / TSS terminal-site prediction

• Per-transcript read-end histograms + peak detection + shipped XGBoost peak filters, emitting SAMPLE.polyA_prediction.tsv / SAMPLE.TSS_prediction.tsv (gated by --genedb; TSS additionally by --fl_data).
• Predictions are computed per gene and reused to refine the intron-graph terminal vertices — clustering still selects the vertices, the detector only refines their positions.

2. Alternative-end (polyA/TSS) NIC discovery

• Default on with --genedb (the interim --refine_transcript_ends flag was dropped). Two mechanisms: a graph-level reclassification when a refined FL-path terminal vertex disagrees with the matched reference end, and a post-construction per-transcript pass that peak-calls a known model's own reads for confident alternative ends (relative-support gated, intron-chain/ends deduped).
• End polishing of constructed model termini toward the trained polyA/TSS peaks is always on (needs no annotation). --novel_apa (hidden, opt-in) extends alt-end creation to novel chains.
• De-novo (no --genedb): only end polishing runs — transcript models are unchanged from base behavior.
• Discovery is scored end-sensitively with a --terminal-delta gffcompare fork at three terminal tolerances (default/50/10), since the default gffcompare metric is end-agnostic for multi-exon transcripts. New alt-end-discovery CI configs + workflows and a simulation reduced-db prep script are included.

3. Read-assignment gate + model-counting refactor

• Gate: a read the reference step assigned uniquely to a known isoform stays on that isoform during model re-assignment — or is left unassigned if that isoform was not built — instead of being re-profiled onto a different/novel model. This makes model-side assignment consistent with the reference analysis. Inert without --genedb.
• Counter refactor: model quantification now flows through the same add_read_info(ReadAssignment) path as the reference counters; the redundant add_read_info_raw API is deleted throughout (including no-op stubs on the exon counters).

Validation

• Reduced-db gffcompare (mouse PacBio / ONT-R10 / ONT-R9-trunc): known transcripts preserved (recall/precision within tolerance).
• Alt-terminal discovery: on the polyA/TSS simulations, alternative-end transcripts are now recovered (master emits ~none), scored end-sensitively via the terminal-delta fork.
• Gate consistency: raises the correlation between reference-based transcript_counts and discovered-model transcript_counts on ONT (R10 corr_overlap 0.94 → 0.99, R9 0.991 → 0.996); PacBio was already near-perfect — the same known isoform is now quantified consistently by both paths.
• Unit tests added for alt-end discovery, end refinement, and per-gene flush.

🤖 Generated with Claude Code