NeoPrecis

NeoPrecis is an computational framework designed to advance personalized cancer immunotherapy by assessing neoantigen immunogenicity.

Overview

The immune system plays a crucial role in combating tumors by recognizing tumor-specific antigens. Among these, neoantigens—derived from somatic mutations—represent a key category due to their tumor-specific nature and high immunogenic potential. However, identifying immunogenic neoantigens and evaluating individual neoantigen landscape remain significant challenges.

NeoPrecis addresses this challenge through two key functionalities:

1. Neoantigen Immunogenicity Prediction: Enables the identification of immunogenic neoantigens for designing cancer vaccines.
2. Neoantigen Landscape Construction: Facilitates the prediction of immune checkpoint inhibitor response by mapping the overall neoantigen profile.

Setup

External Tools

Please install the following external tools:

• NetMHCpan-4.1: Predicts peptide binding to MHC-I molecules.
• NetMHCIIpan-4.3: Predicts peptide binding to MHC-II molecules.
• bam-readcount: Calculates base-level allele frequencies from BAM files.

Reference Files

Please download the following reference files:

• Ensembl CDS and cDNA reference sequences (FASTA)
  • Ensembl FASTA files are available at: https://ftp.ensembl.org/pub/
  • Ensure the Ensembl version matches the VEP version used. For example, if using GRCh38 v113:
    • cDNA https://ftp.ensembl.org/pub/release-113/fasta/homo_sapiens/cdna/Homo_sapiens.GRCh38.cdna.all.fa.gz
    • CDS https://ftp.ensembl.org/pub/release-113/fasta/homo_sapiens/cds/Homo_sapiens.GRCh38.cds.all.fa.gz
• The genome reference file used for RNA-seq alignment with STAR.

Required Packages

To install the necessary dependencies, choose one of the following methods. Installation should take no more than 10 minutes.

• Python Required Packages: Install the packages listed in setup/requirements.txt using pip.

  pip3 install -r setup/requirements.txt

• Conda Environment: Create a Conda environment using the file setup/env.yml

  conda env create -f setup/env.yml
  conda activate neoprecis

Prediction of Immunogenic Neoantigens

Input Preparation

To predict immunogenic neoantigens, the following inputs are required:

• Somatic Mutations
  • A VEP-annotated VCF file (e.g. examples/case.vep.vcf)
  • Ensure the following VEP options are enabled: --symbol, --hgvs, --canonical
  • Record the VEP version used, as it is required for subsequent analyses
• MHC Alleles
  • An HLA-HD final result file (e.g. examples/case.hlahd.txt), or an allele list: one allele per line without the HLA- prefix (e.g. A*02:01), one line for a homozygous gene
  • Alleles have two or more fields; see MHC Allele Names
  • It is recommended to use the default IMGT-HLA version provided by HLA-HD to ensure compatibility with MHC-binding predictors. Updated IMGT-HLA versions may include rare alleles that are not supported by all predictors.
• RNA Expression (Optional)
  • A STAR-aligned BAM file (examples/caseAligned.sortedByCoord.out.bam) and an RSEM result file (examples/case.genes.results)
  • These files are used to calculate RNA expression levels and RNA allele frequencies, providing additional insights for neoantigen prioritization

MHC Allele Names

Each allele is predicted under the name the binding predictor lists for it. For example, the HLA-HD call HLA-A*02:01:14Q is predicted as HLA-A*02:01, and HLA-A*30:14L as HLA-A*30:14L.

1. The allele is cut to two fields, the level netMHCpan and netMHCIIpan name alleles at, and the expression letter of its full name is kept: A*02:01:14Q gives A*02:01 and Q.
2. The predictor's own allele list is searched for these names, in order: data/allelenames for netMHCpan, data/allelelist.txt for netMHCIIpan.

Expression letter	Names searched, in order	Example
none	the two-field name	A*02:01 as HLA-A*02:01
Q, L, S, C or A	without the letter, then with it	DQA1*01:07Q as DQA10107, in pairs such as HLA-DQA10107-DQB10602; A*30:14L as HLA-A*30:14L, which netMHCpan lists only with its L
N: a null allele, which makes no protein	only with the N	A*01:01:01:02N is searched only as HLA-A*01:01N, which netMHCpan does not list, so it gets no predictions; it is never predicted as A*01:01

Intermediate files name each allele by its two fields, and a null allele keeps its N: A*30:14L appears as A*30:14.

An allele the predictor lists under none of its names, such as B*07:359, gets no predictions: like a locus not typed, it presents no neoantigen and is left out of PHBR.

Usage

To run the script, first prepare a config.conf file to define the paths to external tools and reference files. An example configuration file can be found at config.conf. Then, execute the command as follows:

bash neoagfinder.sh \
  -c config.conf \
  -m examples/case.vep.vcf \
  -a examples/case.hlahd.txt \
  -o examples

Description of arguments:

• -c: Configuration file
• -m: VEP-annotated VCF file
• -a: Input file listing MHC alleles
• -r (optional): STAR-aligned RNA-seq BAM file
• -g (optional): RSEM result file of gene expression
• -t (optional): Sample identifier used to specify the tumor sample in the VCF file. If not provided, the script will default to capturing a name containing the substring "tumor".
• -o: Output folder

(Execution should take no more than 10 minutes)

Interpretation

The output folder contains a main output file, ${outdir}/${basename}.neoantigen.csv (e.g. examples/case.neoantigen.csv), along with intermediate files generated during the analysis. This main output file includes the following columns:

• Coordinates: Genomic coordinates of the mutation
• Annotations: Fields annotated by VEP
• Immunogenicity-related metrics

  Metric	Description
  DNA_AF	DNA allele frequency
  RNA_AF	RNA allele frequency
  RNA_DEPTH	RNA read coverage
  RNA_EXP	RNA expression level (in TPM)
  RNA_EXP_QRT	RNA expression level quartile (1 = minimal, 4 = maximal)
  Robustness-{MHC}	Number of alleles presenting the neoantigen
  PHBR-{MHC}	Patient harmonic-mean best rank for evaluating MHC-binding affinity (range: 0–100; lower values indicate stronger binding)
  Agretopicity-{MHC}	Log-scale binding score ratio between mutated and wild-type peptides (>0 indicates stronger binding of the mutated peptide)
  NP-Immuno-{MHC}	Immunogenicity prediction focusing on T-cell recognition
  NP-Integrated-{MHC}	Immunogenicity prediction considering antigen abundance, MHC presentation, and T-cell recognition (only applied if RNA is available)

Notes

• {MHC} in the column names refers to the MHC class type, either I or II. Metrics are calculated separately for MHC class I and class II alleles.
• A class has no columns when there is nothing to predict for it: no allele of that class that netMHCpan or netMHCIIpan lists, or no mutated peptide. If no mutation passes the filters, or a binding prediction fails, the script stops and writes no main output file.
• NP-Immuno is trained on TCR-pMHC binding data from IEDB and VDJdb, as well as T-cell activation assay data from CEDAR.
• NP-Integrated is a logistic regression model incorporating five features–DNA_AF, RNA_AF, RNA_EXP_QTL, PHBR, and NP-Immuno–trained on the NCI GI cancer cohort.

Construction of Neoantigen Landscape

Input Preparation

To construct the neoantigen landscape, the following inputs are required:

• Neoantigen Predictions: Perform neoantigen immunogenicity predictions using the provided pipeline
• Tumor Clonality Analysis
  • Provide a cluster TSV file (examples/cluster.tsv) and a loci TSV file (examples/loci.tsv) generated by PyClone
  • An example script for running PyClone is available at neoprecis/run_pyclone (to be updated)
  • To accelerate the process, the --max_clusters parameter can be set to 100

Usage

bash neoagland.sh \
  -i examples/case.neoantigen.csv \
  -c examples/case.cluster.tsv \
  -l examples/case.loci.tsv \
  -o examples/case.landscape.csv

Description of arguments:

• -i: Neoantigen prediction file
• -c: Cluster file generated by PyClone
• -l: Loci file generated by PyClone
• -o: Output path

(Execution should take no more than 10 minutes)

Interpretation

The output file provides tumor-centric scores, aggregated from mutation-centric scores based on immunogenicity predictions.

Each row represents a specific metric:

Metric	Description
TMB	Tumor mutation burden (non-synonymous mutations)
TNB	Tumor neoantigen burden (PHBR-I ≤ 2)
NPB	NeoPrecis burden (product of NP-Immuno-I and NP-Immuno-II ≥ 0.16)
NP-LandscapeSum	Sum of NP-Immuno scores across all neoantigens
NP-LandscapeCCF	Weighted sum of NP-Immuno scores across all neoantigens, adjusted by the cancer cell fraction (CCF) of mutations
NP-LandscapeClone	Aggregated NP-Immuno scores across all neoantigens based on mutation clusters

Each column represents a score scale:

Scale	Description
value	Raw metric value
percentile_melanoma	normalized percentile within the melanoma cohort (n=277)
percentile_NSCLC	normalized percentile within the NSCLC cohort (n=248)

Notes

• Normalized percentile (between 0 to 1) within the melanoma and NSCLC cohorts are provided to contextualize the metric values and enhance interpretability.

Analyses for the Manuscript

The analyses for the manuscript are detailed in the manuscript directory. Please refer to its contents for reproducing the results presented in our manuscript.

Reference

• netMHCpan-4.1: Reynisson, B., Alvarez, B., Paul, S., Peters, B. & Nielsen, M. NetMHCpan-4.1 and NetMHCIIpan-4.0: improved predictions of MHC antigen presentation by concurrent motif deconvolution and integration of MS MHC eluted ligand data. Nucleic Acids Res. 48, 449–454 (2020).
• NetMHCIIpan-4.3: Nilsson, J. B. et al. Accurate prediction of HLA class II antigen presentation across all loci using tailored data acquisition and refined machine learning. Sci. Adv. 9, eadj6367 (2023).
• bam-readcount: Khanna, A. et al. Bam-readcount - rapid generation of basepair-resolution sequence metrics. J. Open Source Softw. 7, 3722 (2022).
• PyClone: Roth, A. et al. PyClone: statistical inference of clonal population structure in cancer. Nat. Methods 11, 396–398 (2014).
• NCI cohort: Parkhurst, M. R. et al. Unique Neoantigens Arise from Somatic Mutations in Patients with Gastrointestinal Cancers. Cancer Discov. 9, 1022–1035 (2019).
• IEDB: Vita, R. et al. The Immune Epitope Database (IEDB): 2018 update. Nucleic Acids Res. 47, D339–D343 (2019).
• VDJdb: Goncharov, M. et al. VDJdb in the pandemic era: a compendium of T cell receptors specific for SARS-CoV-2. Nat. Methods 19, 1017–1019 (2022).
• CEDAR: Koşaloğlu-Yalçın, Z. et al. The Cancer Epitope Database and Analysis Resource (CEDAR). Nucleic Acids Res. 51, D845–D852 (2023).

Please refer to the NeoPrecis manuscript for the complete list of references

Citation

@article{lee2025neoprecis,
  title={NeoPrecis: Enhancing Immunotherapy Response Prediction through Integration of Qualified Immunogenicity and Clonality-Aware Neoantigen Landscapes},
  author={Lee, Ko-Han and Sears, Timothy J. and Zanetti, Maurizio and Carter, Hannah},
  year={2025},
  month={jul},
  journal={bioRxiv},
  doi={10.1101/2025.07.23.666355},
  url={https://doi.org/10.1101/2025.07.23.666355},
  note={Preprint}
}