Examples¶

This directory contains a curated set of examples for validating and exploring the main functionalities of MHCXGraph. Each example is driven by a JSON manifest file that defines the input structures, execution mode, selectors, and output path.

Directory structure¶

examples/
├── EXAMPLES.rst
├── input
│   ├── pre-renumbered
│   └── renumbered
├── manifests
│   ├── manifest-minimal.json
│   ├── manifest-multiple.json
│   ├── manifest-pairwise.json
│   └── manifest-screening.json
└── results

Overview¶

The core workflow of MHCXGraph is:

run  →  (optional) heatmap

Two main usage paths are available, depending on whether the analysis should be restricted to functionally relevant hotspot residues:

Path	When to use
A: `run` → `heatmap`	General structural comparison without residue filtering.
B: `renumber` → `run` (with selectors) → `heatmap`	Analysis restricted to MHC hotspot residues. This requires IMGT-standardized numbering.

The renumber and heatmap commands are accessory modules. The renumber step is only required when using the predefined MHC1 or MHC2 selectors, as described in Using hotspot residue selectors.

Core processing¶

The run command is the main execution module of MHCXGraph. It is driven by a manifest file that defines the inputs, execution mode, and structural selectors. For a detailed description of the manifest structure and available configuration fields, see Execution configuration (Manifest).

Warning

Input PDB files should not contain additional macromolecules, such as TCRs or antibodies, interacting with the MHC in a way that alters the exposure of surface residues. Their presence may affect relative solvent accessibility (RSA) calculations and graph connectivity, leading to inaccurate comparison results.

Pairwise mode¶

The pairwise mode performs an all-against-all comparison across the input dataset. Its main purpose is to quantify structural similarity between every possible pair of MHC structures.

MHCXGraph run manifests/manifest-pairwise.json

Multiple mode¶

The multiple mode performs a simultaneous comparison of a group of structures in a single run. It is useful for identifying structural features shared across all inputs.

MHCXGraph run manifests/manifest-multiple.json

Screening mode¶

The screening mode is optimized for one-against-many comparisons. It compares a reference structure against a directory of target structures in order to identify structural cross-reactive candidates.

MHCXGraph run manifests/manifest-screening.json

Visualization with heatmap¶

After a pairwise run, MHCXGraph can generate a similarity heatmap with hierarchical clustering. The similarity metric is a coverage-based index defined as the fraction of unique nodes in association graph frames relative to the total number of nodes in both input graphs.

MHCXGraph heatmap \
  -i results/pairwise/PAIRWISE/ \
  -o results/pairwise/ \
  -n similarity_heatmap.png

Flag	Description
`-i`	Input directory, corresponding to the `PAIRWISE/` folder generated by a pairwise run.
`-o`	Output directory for the heatmap image.
`-n`	Output file name.

Note

This module requires the output of a completed pairwise run. Execute MHCXGraph run with a pairwise manifest before using MHCXGraph heatmap.

Output files¶

In addition to the .png figure, the heatmap module generates several data files that are useful for downstream analysis:

distance_matrix.csv Numerical representation of dissimilarity between every pair of proteins.
component_count_matrix.csv Number of connected components shared between each pair of proteins.
unique_nodes_graph_*.csv Detailed lists of residues involved in the shared nodes for each pairwise comparison.

Using hotspot residue selectors¶

By default, MHCXGraph processes the full structure. If you want to restrict the analysis to functionally relevant residues, such as those lining the peptide-binding groove or participating in TCR contact, you can use the predefined MHC1 or MHC2 selectors in the manifest.

When using these selectors, you must first run renumber. The residue indices in MHC1 and MHC2 follow the IMGT domain numbering scheme, so applying them to structures with non-standardized numbering may produce incorrect or incomplete results.

Step 1, standardize numbering¶

MHCXGraph renumber \
  -i examples/input/pre-renumbered/ \
  -o examples/input/renumbered/ \
  -c mhci \
  --suffix _renumbered

Flag	Description
`-i`	Input directory containing the original structure files.
`-o`	Output directory for the renumbered files.
`-c`	Chain convention. Use `mhci` for MHC class I and `mhcii` for MHC class II.
`--suffix`	Suffix appended to each output file name.

Step 2, configure selectors in the manifest¶

Two predefined hotspot residue sets are available.

`MHC1`¶

Residues from MHC class I involved in peptide presentation and TCR recognition. This selector covers positions along the α1 and α2 helices and the floor of the peptide-binding groove, using IMGT numbering for chain A.

"MHC1": {
  "chains": ["C"],
  "residues": {
    "A": [18, 19, 42, 43, 44, 54, 55, 56, 58, 59, 61, 62, 63, 64, 65, 66,
          68, 69, 70, 71, 72, 73, 75, 76, 79, 80, 83, 84, 89, 108, 109,
          142, 143, 145, 146, 147, 148, 149, 150, 151, 152, 153, 154, 155,
          156, 157, 158, 159, 161, 162, 163, 165, 166, 167, 169, 170, 171]
  }
}

`MHC2`¶

Residues from MHC class II located at the peptide-binding interface, distributed across the α chain (chain A) and β chain (chain B).

"MHC2": {
  "chains": ["C"],
  "residues": {
    "A": [37, 51, 52, 53, 55, 56, 58, 59, 60, 62, 63, 65, 66, 67, 69],
    "B": [56, 57, 59, 60, 61, 62, 63, 65, 66, 67, 68, 69, 70, 71, 72,
          73, 74, 77, 78, 81]
  }
}