Add RNA read phasing source

CHANGELOG.md

@@ -2,6 +2,13 @@
 
 ## [Unreleased]
 
+**Added**
+- Added `RNAReadPhasingSource`, a BAM-backed `ReadPhasingSource`
+  implementation for RNA read/fragment co-occurrence. It is consumed
+  through `MolecularPhaseResolver(source)` and lives behind the optional
+  `varcode[rna]` / `pysam` dependency. `ReadPhaseResolver` remains as
+  the varcode 5.0 compatibility name.
+
 **Breaking**
 - Unified the multi-outcome machinery: `SpliceCandidate` deleted;
   `MultiOutcomeEffect.outcomes` accessor + `_with_extra_outcomes`

docs/api.md

@@ -117,10 +117,18 @@ Auto-generated from in-source docstrings via
 
 ::: varcode.MutantTranscriptSource
 
+### `varcode.MolecularPhaseResolver`
+
+::: varcode.MolecularPhaseResolver
+
 ### `varcode.ReadPhaseResolver`
 
 ::: varcode.ReadPhaseResolver
 
+### `varcode.RNAReadPhasingSource`
+
+::: varcode.RNAReadPhasingSource
+
 ### `varcode.VCFPhaseResolver`
 
 ::: varcode.VCFPhaseResolver

docs/germline.md

@@ -21,9 +21,14 @@ possibility set** — one classified effect per haplotype hypothesis
 
 - `VCFPhaseResolver(merged_phased.vcf)` — reads `PS` tags from a
   WhatsHap- or HapCUT2-phased merged VCF.
-- `ReadPhaseResolver(source)` — wraps any RNA-phasing source
+- `MolecularPhaseResolver(source)` — wraps any RNA-phasing source
   (typically an Isovar adapter shipped by `openvax/isovar`) to check
   which haplotype the somatic was observed on in RNA reads.
+  For RNA-seq BAMs without assembly, use
+  `MolecularPhaseResolver(RNAReadPhasingSource("tumor.rna.bam"))` to phase
+  by direct read/fragment co-occurrence. Raw BAM phasing does not
+  provide observed `MutantTranscript`s; assembly-backed sources can.
+  `ReadPhaseResolver` remains as the varcode 5.0 compatibility name.
 - Anything implementing `in_cis(v1, v2, transcript) -> bool | None`.
 
 Phase known → single `MutationEffect`. Phase unknown →
@@ -111,7 +116,7 @@ print("trans ->", type(eff_trans).__name__, eff_trans.short_description)
 ```
 
 In real code use `VCFPhaseResolver(merged_phased.vcf)` or
-`ReadPhaseResolver(source)` — same `phase_resolver=` slot.
+`MolecularPhaseResolver(source)` — same `phase_resolver=` slot.
 
 ## When does this matter?
 

pyproject.toml

@@ -33,6 +33,9 @@ include = ["varcode", "varcode.*"]
 "Homepage" = "https://github.com/openvax/varcode"
 "Bug Tracker" = "https://github.com/openvax/varcode/issues"
 
+[project.optional-dependencies]
+rna = ["pysam>=0.21"]
+
 [project.scripts]
 varcode-genes = "varcode.cli.genes_script:main"
 varcode = "varcode.cli.effects_script:main"

tests/test_read_phase_resolver.py

@@ -22,6 +22,7 @@
 from pyensembl import cached_release
 
 from varcode import (
+    MolecularPhaseResolver,
     MutantTranscript,
     MutantTranscriptSource,
     ReadPhaseResolver,
@@ -84,6 +85,13 @@ def test_resolver_default_phase_source_tag():
     assert resolver.phase_source == "read_phasing"
 
 
+def test_molecular_resolver_is_preferred_name():
+    resolver = MolecularPhaseResolver(StubReadPhasingSource())
+    assert resolver.phase_source == "molecular_phasing"
+    assert isinstance(ReadPhaseResolver(StubReadPhasingSource()),
+                      MolecularPhaseResolver)
+
+
 def test_in_cis_true_when_both_observed_together():
     transcript = _cftr()
     v1 = Variant("7", 117531100, "T", "A", ensembl_grch38)