Port STAR's WithinBAM output (supersedes #282); PE nM is the pair's

CHANGELOG.md

@@ -65,6 +65,30 @@ Sections commonly used: Features, Bug fixes, Other changes.
 
 ### Bug fixes
 
+- **`--chimOutType WithinBAM` ported from STAR** (`chimericBAMoutput`,
+  `alignBAM`). The chimera now replaces the read's normal alignment, as in
+  STAR: one segment as a normal record and the other as a supplementary
+  (`0x800`), hard-clipped on the junction side unless `SoftClip`, with `SA`
+  tags built from the other record's final CIGAR. The representative segment
+  is chosen as STAR chooses it; paired segments covering both mates are
+  written as pairs, and mates on either side of the junction as two normal
+  records. Records carry STAR's flags, MAPQ, mate fields, qualities and
+  `NH`/`HI`/`AS`/`nM`/`NM`. Previously the normal alignment was kept and two
+  incomplete records were appended, so no chimeric read matched STAR's
+  output; on yeast 10k every chimeric read now does, apart from known ties.
+  As in STAR, such reads are not counted as mapped in `Log.final.out` and
+  feed neither `SJ.out.tab` nor gene counts.
+  - `WithinBAM` requires `--outSAMtype BAM` and adds `NM` to the output
+    attributes, as STAR does.
+  - `--chimOutType` accepts up to three values (e.g. `Junctions WithinBAM
+    HardClip`) and rejects unknown ones. `SeparateSAMold` is refused rather
+    than silently ignored; it is not implemented.
+
+- **Paired-end `nM` is the pair's mismatch count on both mates**, as STAR
+  writes it (`trOut.nMM`, like `AS`). We wrote each mate's own count, which
+  differed from STAR on 42% of yeast PE pairs; no comparison script checked
+  tags.
+
 - **`--quantMode TranscriptomeSAM` no longer aborts on reads soft-clipped at
   both ends of a single match block** (e.g. `1S97M2S`). With the default
   `--quantTranscriptomeSAMoutput BanSingleEnd_BanIndels_ExtendSoftclip`, the

docs/src/content/docs/guides/chimeric.md

@@ -5,7 +5,7 @@ description: Detect reads spanning two distant genomic locations — fusion cand
 
 A chimeric alignment is a read whose two halves map to different genomic locations — different chromosomes, the same chromosome with an unrealistically large gap, or the same chromosome but on opposite strands. These are the candidate evidence for gene fusions, large-scale structural variants, and circular RNA back-splicing.
 
-rustar-aligner implements STAR's chimeric detection pipeline with four tiers, all of which run automatically when chimeric detection is enabled.
+rustar-aligner uses STAR's two chimeric detectors, ported as written; which one runs depends on `--chimMultimapNmax`.
 
 ## Enabling chimeric detection
 
@@ -25,14 +25,12 @@ Higher values (e.g. 20) produce fewer, more confident calls; lower values (e.g.
 
 ## What gets detected
 
-The 4-tier pipeline runs in this order, stopping as soon as a chimeric pair is found:
+Both detectors work on the read's window transcripts, the alignments stitching produced before any filtering. For paired-end reads these are whole-fragment transcripts (`mate1 | RC(mate2)`), so one side of a chimera can be a complete mate pair.
 
-1. **Tier 1 — transcript-pair search.** Searches the read's existing transcript pool for two segments that together cover most of the read but map to incompatible locations.
-2. **Tier 2 — multi-cluster.** When the seed pool produces multiple distinct alignment clusters, evaluates each pair as a candidate chimeric.
-3. **Tier 1b — soft-clip re-mapping.** Takes the soft-clipped tail of the primary alignment and re-seeds it against the genome. Recovers chimeric pairs where the original aligner only kept one half.
-4. **Tier 3 — residual outer re-seeding.** For reads where Tier 1/1b/2 has already found a chimeric pair, re-seeds the *remaining* uncovered regions of the read (before the donor / after the acceptor). Enables 3-way detection — gene fusions involving three loci, e.g. a complex rearrangement where two breakpoints are present in a single read.
+- **Default (`--chimMultimapNmax 0`):** STAR's `chimericDetectionOld`. The best linear alignment is one segment, and the detector looks for the single best partner that covers the rest of the read. A chimera is reported only if it is clearly better than the runner-up (`--chimScoreSeparation`), and at most one per read.
+- **`--chimMultimapNmax N > 0`:** STAR's `chimericDetectionMult`. Every pair of window transcripts is tried and re-scored after the junction is placed, and all chimeras within `--chimMultimapScoreRange` of the best are reported, up to `N` (more than `N` reports none). The junction file gains six columns: number of chimeras, maximum possible score, best non-chimeric score, this chimera's score, best chimeric score, and whether the mates were merged.
 
-For paired-end data, additional inter-mate detection runs: if mate 1 maps confidently to one location and mate 2 to another that's incompatible with a normal proper pair (different chromosomes, same strand, or >1 Mb gap), the pair is reported as chimeric.
+When the junction falls inside a read, its position is chosen by STAR's scan over the overlap, preferring GT/AG or CT/AC motifs; when the two mates of a pair lie on either side of it, the junction type is `-1`.
 
 ## Output formats
 
@@ -49,18 +47,21 @@ Writes a `<prefix>Chimeric.out.junction` file with one row per chimeric junction
 ### `WithinBAM`
 
 ```bash
---chimOutType WithinBAM
+--chimOutType WithinBAM [HardClip|SoftClip]
+--outSAMtype BAM Unsorted        # or SortedByCoordinate; WithinBAM needs BAM output
 ```
 
-Embeds the chimeric segments as supplementary alignment records (FLAG `0x800`) in the primary BAM, with `SA` tags linking the donor and acceptor halves. This is the format expected by tools that process chimeric BAM directly (e.g. for fusion calling on already-sorted BAMs).
+Writes the chimera into the main BAM **in place of the read's normal alignment**, as STAR does: one segment as a normal record and the other as a supplementary record (FLAG `0x800`), with `SA` tags pointing at each other. The supplementary segment is hard-clipped by default (`HardClip`) or soft-clipped (`SoftClip`). For paired-end reads a segment that covers both mates is written as a normal pair; when the mates lie on either side of the junction, both are written as normal records with no supplementary. `NM` is added to the output attributes, as STAR does. This is the input [Arriba](https://github.com/suhrig/arriba) recommends.
+
+Because these reads are written as chimeras, STAR does not count them as uniquely or multi-mapped in `Log.final.out`, and they do not contribute to `SJ.out.tab` or gene counts; rustar-aligner does the same.
 
 ### Mixed output
 
 ```bash
 --chimOutType Junctions WithinBAM
 ```
 
-Writes both the junction file and the supplementary BAM records. Useful when downstream tools have different format requirements.
+Writes both the junction file and the chimeric BAM records.
 
 ## Tuning parameters
 
@@ -87,11 +88,11 @@ The `Chimeric.out.junction` file has 14 tab-separated columns (STAR-compatible):
 | 4 | `chr_acceptorB` | Acceptor (right segment) chromosome |
 | 5 | `brkpt_acceptorB` | Acceptor breakpoint position |
 | 6 | `strand_acceptorB` | Acceptor strand |
-| 7 | `junction_type` | -1 (encompassing PE) / 0 (non-canonical) / 1 (GT/AG) / 2 (CT/AC) |
+| 7 | `junction_type` | -1 (mates on either side of the junction) / 0 (non-canonical) / 1 (GT/AG) / 2 (CT/AC) |
 | 8 | `repeat_left_lenA` | Length of repeat to the left |
 | 9 | `repeat_right_lenB` | Length of repeat to the right |
 | 10 | `read_name` | Source read name |
-| 11 | `start_alnA` | Donor start position on the read |
-| 12 | `cigar_alnA` | Donor CIGAR |
-| 13 | `start_alnB` | Acceptor start position on the read |
-| 14 | `cigar_alnB` | Acceptor CIGAR |
+| 11 | `start_alnA` | Donor segment's first aligned genomic position |
+| 12 | `cigar_alnA` | Donor CIGAR; a paired segment carries the second mate after a `p` operation (the genomic gap between mates, negative when they overlap) |
+| 13 | `start_alnB` | Acceptor segment's first aligned genomic position |
+| 14 | `cigar_alnB` | Acceptor CIGAR, same convention |

docs/src/content/docs/reference/cli-parameters.md

@@ -173,7 +173,7 @@ Run `rustar-aligner --help` for the full machine-generated listing.
 | `--chimSegmentReadGapMax` | `0` | Max read-space gap between chimeric segments. |
 | `--chimJunctionOverhangMin` | `20` | Min overhang at chimeric junction. |
 | `--chimScoreJunctionNonGTAG` | `-1` | Score penalty for non-GT/AG chimeric junctions. |
-| `--chimOutType` | `Junctions` | `Junctions`, `WithinBAM`, or both space-separated. |
+| `--chimOutType` | `Junctions` | `Junctions` and/or `WithinBAM`, optionally followed by `HardClip` (default) or `SoftClip` for the supplementary segment. `WithinBAM` requires `--outSAMtype BAM`. |
 
 ## Debug
 

docs/src/content/docs/reference/output-files.md

@@ -71,7 +71,7 @@ Written when `--chimSegmentMin > 0`. Format depends on `--chimOutType`.
 
 ### Chimeric records in the primary BAM
 
-When `--chimOutType` includes `WithinBAM`, the chimeric segments are embedded as supplementary alignment records (FLAG `0x800`) in the main BAM output, with `SA` tags linking the donor and acceptor halves. Tools like Arriba and STAR-Fusion know how to read either format.
+When `--chimOutType` includes `WithinBAM`, a chimeric read is written into the main BAM in place of its normal alignment, as STAR does: one segment as a normal record and the other as a supplementary record (FLAG `0x800`, hard-clipped unless `SoftClip`), with `SA` tags linking the two. Paired reads whose mates lie on either side of the junction are written as two normal records. See the [chimeric guide](/rustar-aligner/guides/chimeric/).
 
 ## Quantification