MixTCRcross Usage Guide

Overview

Cross-Reactivity Prediction Tool

MixTCRcross predicts a cross-reactivity propensity between epitopes (i.e., peptide + MHC). The main output is a score between 0 (lowest risk of cross-reactivity) and 3 (highest risk of cross-reactivity).

For interpretability, we also provide a categorical output:

• High → very likely cross-reactivity
• Medium → quite likely cross-reactivity
• Low → unlikely to cross-react

The product is provided free of charge, and, therefore, on an "as is" basis, without warranty of any kind.

FOR-PROFIT USERS: If you plan to use MixTCRcross or any data provided with the script in any for-profit application, you are required to obtain a separate license. To do so, please contact Nadette Bulgin ([email protected]) at the Ludwig Institute for Cancer Research Ltd.

If you use MixTCRcross in a publication, please cite: Liu et al. BioRxiv (2025)

For scientific questions, please contact David Gfeller ([email protected])

Copyright (2025)

Prerequisites

Make sure you have R ≥ 4.0 installed.

You also need a working installation of MixMHCpred (https://github.com/GfellerLab/MixMHCpred) if you want to automatically predict binding affinities between peptides and MHCs.

To run MixMHCpred, these Python modules are required (installed automatically if missing):

• numpy
• pandas
• scipy
• logomaker
• matplotlib

Installation

if (!requireNamespace("remotes")) install.packages("remotes")
remotes::install_github("GfellerLab/MixTCRcross")

Function Usage

library(MixTCRcross)
MixTCRcross(
  p1,
  p2,
  MHC1,
  MHC2,
  affinity1 = NULL,
  affinity2 = NULL,
  path_to_MixMHCpred = NULL,
  parallelize_parameter = 1
)

Arguments

• p1: The reference peptide.

• MHC1: The MHC class I molecule that p1 binds to. Only one MHC is allowed.

• affinity1: Binding affinity (%rank) of p1 and MHC1 predicted by MixMHCpred or other predictors.

• p2: one peptide or a list of peptides that user would like to check for cross-reactivity with p1.

• MHC2: The MHC class I molecule that p2 binds to.
  • If MHC2 is not given, MHC1 will be used as MHC2.
  • If affinity2 is given, and all p2 peptides bind to the same MHC class I molecule, user can give one MHC, otherwise the length of MHC2 should be the same as p2.
  • If affinity2 is not provided and path_to_MixMHCpred is provided, user is allowed to input several MHC alleles, and the best allele predicted by MixMHCpred will be used.

• affinity2: Binding affinity (%rank) of p2 and MHC2 predicted by MixMHCpred or other predictors.

• path_to_MixMHCpred: Path to MixMHCpred executable. Default = NULL. Required if you want the tool to calculate the affinity automatically. Usually ends like /your/path/MixMHCpred-master.

• parallelize_parameter: Number of CPU cores to use for parallelization. Default = 1. Users are encouraged to change this number when they run a large scale of peptides (more than 1 million).

Important Notes

Users can check https://github.com/GfellerLab/MixMHCpred for more information about MixMHCpred in case they want to know more about this tool.

MixTCRcross support only 9 mer peptides, any longer or shorter peptides used as p1 or p2 would cause an error.

Examples

An example with provided data:

library(MixTCRcross)
data(test_data)
MixTCRcross(p1 = "EVDPIGHLY", 
            MHC1 = "A0101",
            affinity1 = 0.002823, 
            p2 = test_data$p2, 
            MHC2 = test_data$MHC2, 
            affinity2 = test_data$affinity2)

Predicting the cross-reactivity between p1 "LLWNGPMAV" binding to MHC1 "HLA-A0201" (binding affinity1 = 0.071385) to p2 "ALWNGPMAV" binding to MHC2 "HLA-A0201" (binding affinity2 = 0.026310) :

library(MixTCRcross)
MixTCRcross(p1 = "LLWNGPMAV",
            MHC1 = "HLA-A0201", 
            affinity1 = 0.071385, 
            p2 = "ALWNGPMAV", 
            MHC2 = "A0201", 
            affinity2 = 0.026310)

Predicting the cross-reactivity between p1 "LLWNGPMAV" binding to MHC1 "HLA-A0201" to a list of p2 binding to MHC2 "HLA-A0201" without knowing the binding affinity:

# user set the python environment to allow MixMHCpred to run

# If you have the MixMHCpred python environment
reticulate::use_virtualenv("path/to/mixmhcpred_env") 

# If you have the python with all MixMHCpred dependencies
Sys.setenv(PATH = paste(
      "your/path/to/env/bin",
      Sys.getenv("PATH"),
      sep = .Platform$path.sep)) 
      
data(test_9mer_seq)
results_test <- MixTCRcross(p1 = "LLWNGPMAV", 
                            MHC1 = "HLA-A0201", 
                            p2 = test_9mer_seq, 
                            MHC2 = "HLA-A0201", 
                            path_to_MixMHCpred = "/path/to/MixMHCpred-master", 
                            parallelize_parameter = 2) 

Predicting the cross-reactivity between p1 "LLWNGPMAV" binding to MHC1 "HLA-A0201" (binding affinity1 = 0.071385) to a list of p2 binding to MHC2 "HLA-A0201" knowing the binding affinity from the output of MixMHCpred:

data(output_MixMHCpred)
results_test <- MixTCRcross(p1 = "LLWNGPMAV", 
                            MHC1 = "HLA-A0201", 
                            affinity1 = 0.071385, 
                            p2 = output_MixMHCpred$Peptide, 
                            MHC2 = output_MixMHCpred$BestAllele, 
                            affinity2 = output_MixMHCpred$X.Rank_bestAllele, 
                            parallelize_parameter = 2) 

Support

For issues, questions, or contributions, please refer to the project's GitHub repository or contact the maintainer at [[email protected]].