peptcrnet 1.1.1

A Deep Learning Framework for TCR-Peptide Recognition Prediction

PepTCR-Net: Deep Learning for TCR-Peptide Recognition Prediction

PepTCR-Net predicts T-cell receptor (TCR) recognition of peptide antigens using deep learning with uncertainty quantification.

Quick Start

pip install -U peptcrnet
peptcrnet-download-models
peptcrnet-demo

For notebooks: pip install peptcrnet[notebooks]

Requirements: Python 3.8–3.12 (not 3.13).

Installation

From PyPI (recommended)

pip install -U peptcrnet
peptcrnet-download-models   # downloads ~283 MB from Zenodo to ~/.peptcrnet/

From source

git clone https://github.com/mlizhangx/Pep-TCRNet.git
cd Pep-TCRNet
pip install -e ".[notebooks]"
peptcrnet-download-models

Pretrained model checkpoints (required for prediction)

Checkpoints are not included in the pip package. Download them once from Zenodo:

• Checkpoints (v2): https://doi.org/10.5281/zenodo.14194846
• Training CSV data (v1): https://doi.org/10.5281/zenodo.14194728
• Paper: https://doi.org/10.1093/bib/bbaf351

Automatic (recommended):

peptcrnet-download-models

Manual:

curl -LO "https://zenodo.org/records/14194846/files/peptcrnet-pretrained-checkpoints-v1.zip?download=1"
unzip peptcrnet-pretrained-checkpoints-v1.zip -d ~/.peptcrnet/

Files are cached under ~/.peptcrnet/checkpoints/ and ~/.peptcrnet/datasets/atchley.txt.

If a previous download failed, delete the bad file first:

rm -f ~/.peptcrnet/peptcrnet-pretrained-checkpoints-v1.zip
rm -rf ~/.peptcrnet/checkpoints ~/.peptcrnet/datasets

Basic Usage

One-line prediction

from peptcrnet import quick_predict

results = quick_predict(
    tcr_sequences=["CASSLAPGATNEKLFF", "CASSLKPSYNEQFF"],
    mhc_alleles=["HLA-A*02:01", "HLA-A*02:01"],
    v_genes=["TRBV19", "TRBV7-9"],
    j_genes=["TRBJ1-4", "TRBJ2-3"],
    scenario=16,
)
print(results)

Predict from CSV

from peptcrnet import predict_from_file

results = predict_from_file("my_data.csv", scenario=16)
results.to_csv("predictions.csv", index=False)

See USAGE_EXAMPLES.md and documentation for more.

Training pipeline (advanced)

from peptcrnet import PepTCRNetPipeline

pipeline = PepTCRNetPipeline(data_path="your_data.csv")
pipeline.load_data()
pipeline.split_data(test_size=0.2, val_size=0.1)
pipeline.prepare_features(feature_types=["sequences", "categorical"])
history = pipeline.train(epochs=100, batch_size=128)

Data Format

Input CSV for predict_from_file and the predictor API:

Column	Required	Description	Example
CDR3	Yes	TCR CDR3β sequence	CASSRGQGNEQFF
MHC	Scenario-dependent	HLA allele (single column)	HLA-A*02:01
V	Scenario-dependent	V gene segment	TRBV7-2
J	Scenario-dependent	J gene segment	TRBJ2-1
Peptide	Optional	True peptide (evaluation only)	GILGFVFTL

Note: The prediction API uses a single MHC column. Some training notebooks split HLA into HLA-A, HLA-B, HLA-C; merge to MHC for prediction or use the Zenodo CSV format.

Default scenario 16 uses ED + HLA + VJ features — provide CDR3, MHC, V, and J.

Demo notebook (source install)

pip install peptcrnet[notebooks]
jupyter notebook DEMO_Complete_Pipeline.ipynb

Citation

@article{le2025peptcrnet,
  title={PepTCR-Net: prediction of multi-class antigen peptides by T-cell receptor sequences with deep learning},
  author={Le, Phi and Ung, Leah and Yang, Hai and Huang, Anwen and He, Tao and Bruno, Peter and Oh, David Y and Keenan, Bridget P and Zhang, Li},
  journal={Briefings in Bioinformatics},
  volume={26},
  number={4},
  pages={bbaf351},
  year={2025},
  doi={10.1093/bib/bbaf351}
}

License

MIT — see LICENSE.

Contact

• GitHub Issues
• [e-mail]