MHCXGraph.core.residue_tracking¶

class MHCXGraph.core.residue_tracking.ResidueTracker(watch_residues: Iterable[tuple[int, str, int, str]] | None = None, *, out_dir: str = 'residue_tracking', max_examples_per_event: int = 25, keep_event_log: bool = True)[source]¶

Bases: object

Watches specific residues across the pipeline.

Design goals:

provenance rich (ctx includes step/chunk/comp/frame)
bounded memory (stores only when watched residue appears)
easy export to JSON

Typical use:

tracker = ResidueTracker(watch_residues={ (0,”A”,42,””), (1,”B”,15,””) }, out_dir=”tracking”) … tracker.triads_built(ctx, token, triads_absolute) tracker.combos_built(ctx, token, combos) tracker.frame_accepted(ctx, edges_residues, edges_indices) … tracker.dump_json()

combos_built(ctx: TrackCtx, token: Any, combos: Sequence[tuple[tuple[Any, ...], ...]]) → None[source]¶

component_selected(ctx: TrackCtx, *, component_nodes: Sequence[Any], component_edges: Sequence[Any] | None = None) → None[source]¶

component_skipped(ctx: TrackCtx, *, reason: str, component_size: int) → None[source]¶

dump_json(filename: str = 'residue_tracking_report.json') → str[source]¶

Writes a single JSON with:

summary
events_by_residue (only watched residues)

Returns output path.

frame_accepted(ctx: TrackCtx, *, edges_residues: Sequence[Any], edges_indices: Sequence[Any] | None = None) → None[source]¶

resolve_from_pdb_dfs(pdb_dfs: Sequence[Any], stage: str = 'resolve') → None[source]¶: You call this already in association_product. Here we just record that resolution happened. If you want mapping from (chain,resseq,icode)->resname etc, you can extend this later.

triad_filtered(ctx: TrackCtx, reason: str, *, triad_abs: tuple[Any, ...] | None = None, token: Any = None) → None[source]¶

triads_built(ctx: TrackCtx, token: Any, triads_absolute: Sequence[tuple[Any, ...]]) → None[source]¶

Bases: object

chunk_id: int | None = None¶

comp_id: int | None = None¶

frame_id: int | None = None¶

protein_i: int | None = None¶

run_id: str¶

stage: str¶

step_id: int | None = None¶

MHCXGraph.core.residue_tracking.combo_residues(combo: tuple[tuple[Any, ...], ...]) → list[list[str]][source]¶: combo = tuple(per_protein_triad_absolute) Each triad absolute begins with 3 residue labels. Returns list per protein: [[u,c,w],[u,c,w],…]

MHCXGraph.core.residue_tracking.parse_node_label(node: str) → tuple[str, str, int, str][source]¶: Parse “CHAIN:RES:NUM” -> (chain, resname, resseq_int, icode_str) Accepts “42”, “42A”, “-1”, “-1B”.

MHCXGraph.core.residue_tracking.residue_key(protein_i: int, chain: str, resseq: int, icode: str = '') → tuple[int, str, int, str][source]¶: Canonical watched key. We do NOT include resname, because in PDBs you can get weird naming and you usually care about position.

MHCXGraph.core.residue_tracking.triad_residues_from_absolute(triad_absolute: tuple[Any, ...]) → list[str][source]¶: triad_absolute = (*triad_abs, *full_describer_absolute) triad_abs = [u, center, w] (strings “A:TYR:42”)

Classes¶

`ResidueTracker`([watch_residues, out_dir, ...])	Watches specific residues across the pipeline.
`TrackCtx`(run_id, stage[, protein_i, ...])

Functions¶

`combo_residues`(combo)	combo = tuple(per_protein_triad_absolute) Each triad absolute begins with 3 residue labels.
`parse_node_label`(node)	Parse "CHAIN:RES:NUM" -> (chain, resname, resseq_int, icode_str) Accepts "42", "42A", "-1", "-1B".
`residue_key`(protein_i, chain, resseq[, icode])	Canonical watched key.
`triad_residues_from_absolute`(triad_absolute)	triad_absolute = (triad_abs, full_describer_absolute) triad_abs = [u, center, w] (strings "A:TYR:42")