MHCXGraph

A Python package for detecting potential T cell receptor cross-reactivity based on peptide–MHC structures.

MHCXGraph leverages graph-based approaches to identify conserved exposed regions across multiple pMHC structures. It supports multiple execution modes and offers fully adjustable parameters, enabling flexible configuration to suit diverse user needs. For result analysis, the package provides an interactive dashboard that facilitates data exploration through graph visualizations and projections onto 3D structures

See also:

• Documentation
• GitHub repository

Installation

From PyPI (stable): To install the latest release on PyPI, run:

pip install MHCXGraph

From source (development):

git clone https://github.com/cnpem/MHCXGraph.git
pip install -e MHCXGraph

Quick Start

MHCXGraph is configured via a JSON manifest file. Download and extract the examples package:

Linux / macOS

wget https://github.com/cnpem/MHCXGraph/releases/download/0.1.2/examples.tar.gz
tar -xzf examples.tar.gz

Windows (PowerShell)

Invoke-WebRequest -Uri https://github.com/cnpem/MHCXGraph/releases/download/0.1.2/examples.zip -OutFile examples.zip
Expand-Archive examples.zip

Or download directly: Linux/macOS (.tar.gz) · Windows (.zip)

The example manifest is at examples/manifests/manifest-minimal.json. To run it:

MHCXGraph run examples/manifests/manifest-minimal.json

A basic manifest has the following structure:

{
  "settings": {
    "run_name": "my-run",
    "run_mode": "multiple",
    "output_path": "path/to/output/",
    "edge_threshold": 8.5,
    "node_granularity": "all_atoms",
    "triad_rsa": false,
    "rsa_filter": 0.1,
    "global_distance_diff_threshold":2.0,
    "local_distance_diff_threshold":1.0,
    "distance_bin_width": 2,
  },
  "inputs": [
    {
      "path": "path/to/input",
      "extensions": [".pdb", ".cif"],
      "selectors": [{ "name": "MHC1" }]
    }
  ],
  "selectors": {
    "MHC1": {
      "chains": ["C"],
      "structures": {},
      "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": {
      "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]
      }
    },
    "general": {
	    "chains" : ["C"],
	    "structures" : ["helix"],
	    "residues" : {}
    }
  }
}

[!WARNING] Input structures in this example have been pre-processed with MHCXGraph renumber. This step must be executed before graph analysis whenever residue selectors targeting TCR-contacting positions are used.

Key Configuration Parameters¹

¹ A complete description of all parameters can be found in the documentation

² RSA token parameters are only active when triad_rsa: true.

Selectors

Selectors define which residues and chains are included as graph nodes. They can be specified by chain ID, residue index, or secondary structure type (helix, etc.), and referenced by name in the inputs block.

Citation

Santos Simões, C. D. M., Riveros Maidana, R. L. B., de Assis, S. C., Guerra, J. V. S., & Ribeiro-Filho, H. V. (2026). MHCXGraph: A Graph-Based approach to detecting T cell receptor cross-reactivity. https://doi.org/10.64898/2026.04.07.717034

License

The software is licensed under the terms of the GNU Affero General Public License 3 (AGPL3) and is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.