###############
# PRIME is a PRedictor of class I IMmunogenic Epitopes. It combines predictions of binding to MHC-I molecules and propensity for TCR recognition.
#
# PRIME2.1 can be used freely by academic groups for non-commercial purposes (see license).
# 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 PRIME (version 2.1) 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 (nbulgin@lcr.org) at the Ludwig Institute for Cancer Research Ltd.
#
# If you use PRIME in a publication, please cite:
# Gfeller et al. Improved predictions of antigen presentation and TCR recognition with MixMHCpred2.2 and PRIME2.0 reveal potent SARS-CoV-2 CD8+ T-cell epitopes , Cell Systems (2023).
#
# For scientific questions, please contact David Gfeller (David.Gfeller@unil.ch)
#
# Copyright (2024) David Gfeller
###############


########################
NEW FEATURES OF VERSION 2.1
########################

- Expanded training set of MHC-I alleles from human and other species

############
INSTALLATION
############

For Mac and Linux:

1) Download the PRIME2.1.zip file and move it to a directory
of your choice, where you have writing permissions.

2) Unzip the PRIME2.1.zip package.

3) To run it from anywhere on your computer, add the PRIME2.1 directory to your path.

4) PRIME requires MixMHCpred v3.0 or above to be installed on your computer (https://github.com/GfellerLab/MixMHCpred) and be in your PATH (if not in your PATH, you can use the '-mix PATH_OF_MIXMHCPRED_EXEC' command line option).

6) To test your installation, make sure you are in the PRIME2.1 directory and run the command (should not take more than a few seconds):

   ./PRIME -i test/test.txt -o test/out.txt -a A0101,A2501,B0801,B1801

Apart from specific paths, the output file test/out.txt should be the same as test/out_compare.txt

For Mac:

Depending on your security setup, you may have to manually allow PRIME executable to run (Systems Preferences -> Security & Privacy -> General)

For Linux:

After step 3), you also need to compile the PRIME.cc code. Go to
PRIME2.1/lib and compile with your favorite C++ compiler
(e.g. g++ -O3 PRIME.cc -o PRIME.x)

For Windows:

We provide a precompiled version of the C++ code. Should you have issues with it, try to recompile it on a Windows machine with the command: g++ -O3 -static PRIME.cc -o PRIME.exe

########
RUNNING
########

Command:
PRIME -i input_file -o output_dir -a allele1,allele2

-i input_file:
File listing all the peptides. Ideally a text file, but fasta files
are supported and lines starting with ">" are skipped. Do NOT use filenames with special characters like '*' (e.g., "HLA-A*02:01.txt").
All peptides should be of length 8 to 14. Depending on your memory, you may have issues if the number of peptides is too large (e.g., > 1'000'000).

-a allele:
List of HLA-I alleles. Use the simple nomenclature like A0101.
A01:01, HLA-A01:01 or HLA-A*01:01 are also supported, but not
recommended. If you want to make predictions with multiple
alleles, list the different alleles separated by a single comma ","
(e.g. -a A0101,A2501,B0801,B1801).

-o output_file:
The name of the output file. Do NOT use filenames with special characters like '*' or '\' (e.g., "HLA-A*02:01.txt").

Optional parameters:

-mix: Give the full path of MixMHCpred executable (required if MixMHCpred is not in your PATH). Version 3.0 of MixMHCpred or above is required.

########
Output
########

Output file:
Column 1: Peptide sequence
Column 2: Lowest %Rank for PRIME score across the different alleles
Column 3: PRIME Score corresponding to allele with the lowest %Rank
Column 4: Predicted binding score (i.e., MixMHCpred %Rank)
Column 5: Best allele (based on the lowest PRIME %Rank).
Additional columns: %Rank, scores and MixMHCpred %Rank for each allele.

The %Rank indicates the fraction of random peptides from the human proteome (length 8 to 14) that would have a score higher or equal to the peptide given in input. The %Rank should be used to rank peptides for experimental validation.