
Introduction
============
What is PRESCOTT?
-----------------

PRESCOTT (PRESCOTT: Population awaRe Epistatic and StruCtural mOdel of muTational effecTs) is a package predicting mutational effects in a protein based
on population, evolutionary and structural information. It is made up of
two main programs: escott and prescott.

ESCOTT can calculate effects of single point mutations and multiple
point mutations. On the other hand, PRESCOTT incorporates population
frequencies into ESCOTT predictions. Therefore, you need to run ESCOTT
first to have predictions of mutational effects. We recommend using
PRESCOTT package via our web site or our docker image due to its
dependencies.

Input Data Requirements
-----------------------

Input Data Requirements for escott
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

escott requires two files:

* a multiple sequence alignment (MSA) file in fasta format (mandatory):

  * your query protein must be the first sequence in the fasta file. In addition, the query sequence should not contain any gaps. 


* a structure file in PDB format (optional but highly recommended).

One of the fastest ways to obtain both input MSA and a PDB file is to
run colabfold:
https://colab.research.google.com/github/sokrypton/ColabFold/blob/main/AlphaFold2.ipynb

Please note that the MSA file produced by colabfold (a3m file) can
contain gaps in the query sequence. You have to remove them before using
it in PRESCOTT. You can remove the gaps with programs that have a GUI,
such as ugene (http://ugene.net/) or jalview (https://www.jalview.org/).

For testing purpose, you can find some example input files for BLAT
protein in data/ folder of this repository. 

Input Data Requirements for prescott
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

prescott requires three files:

* output file of escott (the file ending with …normPredCombi.txt) 
* a fasta file containing only your query sequence 
* gnomad csv file containing to be downloaded from https://gnomad.broadinstitute.org/ for your protein.

Usage
-----

You can find example bash scripts for escott and prescott in examples
folder of this repository.

Below, you will find examples of the most basic usage. Consult to the
documentation for further details.

Running escott program
~~~~~~~~~~~~~~~~~~~~~~~~~~

Let’s assume that our input MSA is inputAli.fasta and input.pdb is our
structure file in PDB format.

Run the program by issuing the following command in a bash terminal:

.. code:: bash

   escott inputAli.fasta --pdbfile input.pdb 

A quick help can be accessed by typing

.. code:: bash

   escott --help

By default, ESCOTT will predict the effect of all possible single
mutations at all positions in the query sequence. Alternatively, a set
of single or multiple mutations can be given with the option -m. Each
line of the file should contain a mutation (e.g. D136R) or combination
of mutations separated by colons and ordered according to their
positions in the sequence (e.g. D136R,V271A).

Running prescott program with gnomAD frequency data
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

A quick help can be accessed by typing

.. code:: bash

   prescott --help

Run the program by issuing the following command in a bash terminal:

.. code:: bash

   prescott -e ../data/MLH1_normPred_evolCombi.txt -g ../data/gnomAD_v4.1.0_MLH1_HUMAN_ENSG00000076242.csv -s ../data/MLH1.fasta


GnomAD v4.1.0 is the most comprehensive, publicly available human population dataset as far as we are aware of. 
The most important output is prescott-scores.csv file, which produces entire single point mutational landscape for the protein. 

In addition, there is a file called prescott-scores-details.csv. The file contains all information about the points modulated by population 
information coming from gnomad file and non-modulated variants. Here are a few lines from the example 

.. code:: bash

   mutant,ESCOTT,protein,log10frequency,labels,position,PRESCOTT
   M1V,0.27,MLH1_normPred_evolCombi,999.0,,1,0.27
   M1W,0.36,MLH1_normPred_evolCombi,999.0,,1,0.36
   M1Y,0.36,MLH1_normPred_evolCombi,999.0,,1,0.36
   S2A,0.06,MLH1_normPred_evolCombi,-5.55059765214601,,2,0.06

There are seven fields in that file: mutant,ESCOTT,protein,log10frequency,labels,position,PRESCOTT. 
Let's explain each field separately.

1. mutant: M1V
2. ESCOTT: A floating point ESCOTT score of the variant (0.27). 
3. protein: This is a string derived from your input file name (MLH1_normPred_evolCombi). 
4. log10frequency: If you gnomad file constains frequency information for this variant, you will have a value such as -5.55059765214601. When your gnomad file does not contain any frequency information for that variant, you will see 999.0 in that field. 
5. labels: If your gnomad file constains 'Pathogenic', 'Pathogenic/Likely pathogenic' or 'Likely pathogenic' ClinVar labels, your labels field will be 1. If your gnomad file constains 'Benign', 'Benign/Likely benign' or 'Likely benign' ClinVar labels, your labels field will be 0. If there is not any Clinvar label, the field will remain empty. 
6. position: An integer value clearly indicating amino acid position in your protein. 
7. PRESCOTT: A floating point PRESCOTT score of the variant (0.27). 


Finally, if you have both pathogenic and benign labels in the gnomad file, there will be a 'clinvar-vs-position.png' file showing how these labeled 
variants are affected by population information. 

Please note that the example input files of MLH1 protein for prescott acalculations are in the data directory of this repository.


Running prescott program with older versions of GnomAD data
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If you would like to use GnomAD v4.0.0 data in prescott, you should specify GnomAD version with '--gnomadversion' parameter as follows:

.. code:: bash

   prescott -e ../data/MLH1_normPred_evolCombi.txt -g ../data/gnomAD_v4.0.0_MLH1_HUMAN_ENSG00000076242.csv -s ../data/MLH1.fasta --gnomadversion 40

However, if you would like to use GnomAD v2.1.1, you should specify the version with '--gnomadversion' parameter as below:

.. code:: bash

   prescott -e ../data/MLH1_normPred_evolCombi.txt -g ../data/gnomAD_v2.1.1_MLH1_HUMAN_ENSG00000076242.csv -s ../data/MLH1.fasta --gnomadversion 2


Running prescott program with custom frequency data
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
What if you have your own frequencies for a set of missense mutations that you or another researcher measured?
prescott module can do calculations with custom frequency files as well. The first step is to prepare a plain text file with ".txt" extension. 
Note: Saving the custom frequency file with .txt extension is very important to distinguish it from gnomad .csv extension. 

You must have two columns separated by a space character for each missense mutation in a custom frequency file. The first column is the missense mutation and the second 
column is the frequency (number of observations divided by total number of samples). A few example lines for the format of the custom frequency file is given below:

.. code:: bash

   S2A 2.5607342137e-06
   S2L 6.1954797779e-06
   S2W 6.840647125218045e-07
   F3L 1.5903965494e-06
   F3S 1.2003274493e-06
   F3L 1.67277954004e-05

We provide an sample custom frequency file for MLH1 in the data folder of this repository. You can download that file to your computer with the following Linux/Unix command:

.. code:: bash

   wget http://gitlab.lcqb.upmc.fr/tekpinar/PRESCOTT/raw/master/data/custom-frequency-file.txt

If you have already downloaded the repository, go to the examples directory and run the following command to use the custom frequency file:

.. code:: bash

   prescott -e ../data/MLH1_normPred_evolCombi.txt -g ../data/custom-frequency-file.txt -s ../data/MLH1.fasta



Installation
------------

PRESCOTT is implemented in Python 3 and R. It has been tested only on
Linux. Since PRESCOTT has many dependencies, we recommend using our web
site or our docker image. If you are a determined user, you can find the
steps required to install it from the source in the following link (or
in the docs folder of this repository):

Citation
--------

Tekpinar, M., David, L., Henry, T., & Carbone, A. (2024). PRESCOTT: a population aware, epistatic 
and structural model accurately predicts missense effect. medRxiv. doi:10.1101/2024.02.03.24302219

https://www.medrxiv.org/content/10.1101/2024.02.03.24302219v1 


.. |License: GPLv3| image:: https://img.shields.io/badge/license-GPLv3-blue
   :target: https://www.gnu.org/licenses/gpl-3.0.html

