openvax / topiary / 24363658924

90%

push

github

AntigenFragment abstraction — v5.2.0 (#120)

* Add AntigenFragment abstraction — v5.2.0

Core abstraction for antigens from any origin (somatic variants,
structural variants, ERVs, CTAs, viral proteins, allergens,
autoantigens, synthetic constructs), unified through one prediction
pipeline.  Designed to be reusable by vaxrank for vaccine-window
selection, not just epitope scoring.

New module topiary/antigen.py:
- AntigenFragment dataclass (frozen, eq=False).  Free-form
  `source_type` tag (recommended vocabulary documented but not
  enforced); `target_intervals: list[tuple[int,int]] | None` for
  disjoint regions (tandem-duplication breakpoints, ERV non-self
  regions, etc.); `reference_sequence` + `germline_sequence` with
  germline-precedence `effective_baseline`.  Identity by
  `fragment_id`: human-readable prefix + SHA-1 hash (8 hex).
  Convenience constructors `from_variant` (handles in-frame vs
  frameshift target semantics) and `from_junction` (fusion / splice
  / cryptic-exon variants).  Stdlib-only serialization
  `to_dict`/`from_dict`/`to_json`/`from_json`; compact `__str__`.

New module topiary/io_antigen.py:
- `read_antigens` / `write_antigens` / `iter_antigens` TSV IO.
  JSON-encoded columns for `target_intervals` and `annotations`.
  Unknown columns rejected to catch typos; use annotations dict for
  tool-specific extensions.

TopiaryPredictor.predict_from_antigens(fragments):
- Scans each fragment's sequence, propagates fragment-level fields
  (source_type, variant, effect, effect_type, gene, gene_id,
  transcript_id, gene_expression, transcript_expression, plus every
  annotation key) onto prediction rows.
- Threads `fragment_id` through so downstream code (vaxrank) can
  group peptides back to their source.
- Emits `overlaps_target` (bool / NaN) computed from each peptide's
  position vs. the fragment's target_intervals.
- Backwards-compat `contains_mutant_residues` for source types
  prefixed with `variant`.
- `wt_peptide` + `wt_pep... (continued)

240 of 247 new or added lines in 5 files covered. (97.17%)

2983 of 3390 relevant lines covered (87.99%)

2.64 hits per line