Combine cis SNVs into MNVs without losing transcript or phase interpretations

Open
  • Is something wrong?
#368 1 comment 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
45/100
Issue type
Feature
Clarity
Mostly clear
Activity status
Quiet
Tech stack
python
Domain
bioinformatics

Research direction

Start with docs/transforms.md and the varcode.transforms module docstring, then read the transform shape from #367 and the phase-resolver infrastructure in #269. Review #364 for conventions around reducing variants, provenance, and metadata. Done means the listed cis, trans, phase-unknown, codon-boundary, and three-SNV cases are covered, with clean composition after pair_breakends.

Written by the indexing model from the issue text.

Description

enhancement

Current status (2026-10-26; Varcode 10.20.2)

Phase-aware/haplotype annotation already models combined coding consequences, but the cardinality-reducing combine_cis_snvs collection transform is still only a planned entry in the transforms module. Keep the request open for that optional normalization/provenance operation; it is not required merely to obtain a combined haplotype consequence.

Corrections to the older draft plan

  • Codon membership must be relative to the annotated CDS start on each transcript, not transcript.spliced_offset(position) // 3, which includes the 5′ UTR.
  • A shared PS label alone does not establish that alternate alleles are in cis; use the resolver's allele/sample-aware phase result, preserving unknown or contradictory evidence.
  • A codon can cross an exon junction. A contiguous genomic MNV must not absorb the intervening intron just because the edited bases share a spliced codon.
  • Do not pick the lexically first transcript when transcripts imply incompatible grouping choices. Preserve the ambiguity or decline the reduction.

Remaining acceptance

Retain all source variants and metadata provenance; require an explicit sample/phase scope and reference-validated gap bases; preserve unchanged behavior for trans/unknown phase, same-position alternatives and incompatible transcript interpretations. Test both strands, nonzero UTR lengths, codon boundaries, split codons, differing transcript CDS frames, multi-sample phase conflicts and idempotence. Demonstrate consequence equivalence against the current haplotype path for every eligible combination.

The original proposed shape is retained below; the older comment's algorithm is a draft, not the current implementation or an accepted shortcut around these constraints.

Original request

Follow-up from #364 / #367 (the varcode.transforms module shape). One of four planned transforms enumerated in docs/transforms.md and the module docstring.

Scope

Reduce two or more adjacent SNVs that share a phase set (or are otherwise determined cis) into a single MNV. Removes the need for HaplotypeEffect/PhaseAmbiguousEffect wrapping in the common case where two SNVs sit in the same codon on the same haplotype and can be classified as one combined codon substitution.

Signature:

def combine_cis_snvs(vc, phase_resolver) -> VariantCollection:
    """Combine adjacent in-codon SNVs sharing a phase set into MNVs.

    Cardinality: reduces.
    """

Contract (per transforms module conventions)

  • Cardinality: reduces.
  • Provenance: combined MNV carries source_variants=(snv1, snv2, ...).
  • Metadata behavior: GT must agree across all source SNVs (raises on mismatch — same rule as pair_breakends); other FORMAT fields taken from the lex-earlier source.

Pairing rule

Two SNVs are combined when all of:

  1. Both share a phase set (the phase_resolver answers in_cis(a, b) is True), OR both are homozygous-alt for the same sample at distinct positions within a single codon.
  2. They sit within a transcript codon window (3 bp at the same codon position).
  3. They're on the same contig.

Tests

  • Two SNVs at codon positions 1+2 of the same codon, in cis -> single MNV; effect prediction emits one Substitution instead of two adjacent ones.
  • Two SNVs in cis but spanning a codon boundary -> not combined (out of codon window).
  • Two SNVs in trans -> not combined.
  • Phase unknown -> not combined; existing PhaseAmbiguousEffect path still handles them.
  • Three SNVs in cis within one codon -> one MNV with source_variants=(a, b, c).

Composition

Should compose cleanly after pair_breakends (separate scopes; both reduce; both idempotent).

See also

  • #364 — BND mate pairing (the first transform).
  • #367 — varcode.transforms module shape PR.
  • #269 — phase resolver infrastructure.
Dominant language
Python
Stars
88
Forks
28
Avg merge
3h 17m
Merged PRs (30d)
52

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from openvax/varcode

All issues in openvax/varcode

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.