Package: vespa-effect
Table of Contents[[TOC]]VESPA --VariantEffectScorePrediction withoutAlignmentsVESPAis a simple, yet powerful Single Amino Acid Variant (SAV) effect predictor based on embeddings of the Protein Language ModelProtT5.The single-sequence-based SAV effect prediction is set up in a multistage pipeline that includes (1) generatingProtT5embeddings, (2) extracting per-residue conservation predictions, (3) (optionally) extracting per-variant log-odds ratios, and (4) predicting the effect of all possible amino acid substitutions. Step (4) can be completed by either usingVESPAwith (2) and (3) as input, or by using the computationally more efficient method VESPA-light (VESPAl) with only step (2) as input for a small drop in prediction performance.The specifics ofVESPAandVESPAlcan be found in our paper,Embeddings from protein language models predict conservation and variant effects(Marquet et al., 2021). The performance ofVESPAwhen evaluated against SOTA methods can be seen below.Precomputed VESPA and VESPAl predictionsPrecomputedVESPAandVESPAlpredictions are currently available for 39DMS experimentshere:Supplementary file 3 of (Marquet et al., 2021). Furthermore,VESPAlpredictions are available for thehuman proteome(downloaded 22/01/17), and for thefly (drosophila melanogaster) proteome(downloaded 22/03/01).UsageThe preferred method to installVESPAis via pip:pipinstallvespa-effectInput FilesRequired: A singleFASTAfile containing all your wildtype sequences (note: this file can contain any number of sequences).Optional: If you are only interested in a subset of possible mutations (specific mutations), you can add-m mutations.txtto the code line inQuickstart(note: per default all mutations are considered). Clickhereto head to the file format explanation ofmutations.txt.QuickstartFor simplicity of this guide, we will assume a folder containing all data: f.e., theFASTAfile is placed atdata/sequences.fastaand the (optional)mutations.txtatdata/mutations.txt.After installing the repository, you can run the following:vespadata/sequences.fasta--prott5_weights_cachedata/cacheBy default, this runsVESPAlfor all possible mutations. It will generate a new foldervespa_run_directoryin your current working directory. Within this folder you will find two files containing input features (embeddings, conservation prediction) and anoutputfolder with .csv files containingVESPAlpredictions for each sequence with all possible mutations. More details can be found underoutput.WARNINGCreating embeddings requires a powerful GPU (we recommend at least 12GB of VRAM). The same applies to runningVESPA. For more details, seeStep 1 on generating embeddingsandStep 3 on extracting log-odds ratios.Optional:If you already have precomputed embeddings available, you can use those instead of generating new ones by adding--use_existing_embeddingsfollowed by the file location. Then runningVESPAlwill not require a GPU.If you have a GPU available you can generateVESPApredictions by adding--vespato the code line above. After runningVESPAyou will find another file in your foldervespa_run_directorycontaining log-odds ratios as additional input.--prott5_weights_cachefollowed by a folder path specifies the location of a caching folder (or preloaded ProtT5 weigths). Instead of downloading the weights for every run ofVESPAand/orVESPAl, the weights will be downloaded into this folder or just reused if already present.In case you want to output a single [.h5 file](#.h5 files) in addition to the default .csv files with predictions, add--h5_outputfollowed by the output file location. If you are only interested in an .h5 file, add--no_csv.Below you can find information on how to run each step ofVESPAandVESPAlindividually.
Running the vespa script will automatically the substeps below for you (with the optional specifications you of your choice). Use the substeps if you are interested in a particular intermediate result.The substeps of VESPA and VESPAlThe following steps can be run individually and for any number of sequences contained in aFASTAfile.Step 1: Extracting ProtT5 embeddingsTo runVESPAand/orVESPAlto obtain SAV predictions, you will need theProtT5embeddings of your sequences. If you have a GPU, you can use the included embedding script on your own machine to generate your protein embeddings:vespa_embdata/sequences.fasta-odata/embeddings.h5--prott5_weights_cachedata/cacheAs you can see, you need to specify an output file location (-o), and theFASTAfile location of your input sequences.Optional:--prott5_weights_cachespecifies a caching directory to storeProtT5weights. If not present, the line above will download the weights to your current working directory for every run ofVESPAand/orVESPAl.Step 2: Conservation PredictionVESPAandVESPAltake per-residue conservation predictions as input. To generate them, run the following (in theVESPAfolder):vespa_conspreddata/embeddings.h5-odata/conspred.h5The input for our conservation predictor are theProtT5embeddings. In your output file (-o), you will find 9-state conservation probabilities (per-residue) needed as input for the models. For more details on the conservation prediction please see the paper mentioned above.Optional: In case you are interested in generating a file that contains the predicted conservation classes instead of the assigned class probabilities, add--output_classesabove.Step 3: Log-odds ratio of masked marginal probabilitiesThis step requires a GPU! The two modelsVESPAandVESPAldiffer in their predictive performance but also in the required input. If you are only interested in runningVESPAl, you can skip this step.To generate the log-odds ratios of masked marginal probabilities required forVESPA, run (in theVESPAfolder):vespa_logoddsdata/sequences.fasta-odata/logodds.h5Optional:To run the log-odds script including the mutations file, add-m data/mutations.txtto the code line above.Per default the command above generates the.h5filerequired for the subsequent steps. We provide two options to output a human readable version of the log-odds scores by adding--single_csv data/single_logodds.csvor--csv_dir data/csv_dir/at the end of the code line above. The first option generates a single csv file with all sequences and SAVs. For large sets, we recommend to use the second option, which outputs multiple csv files separated by sequence ID of the givenFASTAfile. The format of the .csv files is describedbelow.Step 4: RunVESPAand/orVESPAlNow you have all the data required to runVESPAand/orVESPAl. Per default, thevespascript will predict SAV effects forVESPAlonly. To explicitly enableVESPAadd--vespa(which will run both models), and to disableVESPAladd--no-vespal. To generate predictions, execute the following code (in theVESPAfolder):Both(if you computed the conservation prediction and the log-odds):vespa_run--vespadata/conspred_probs.h5data/sequences.fasta--T5_inputdata/logodds.h5--outputpredictions/Only VESPA(if you computed the conservation prediction and the log-odds):vespa_run--vespa--no-vespaldata/conspred_probs.h5data/sequences.fasta-T5_inputdata/logodds.h5--outputpredictions/Only VESPAl(if you only computed the conservation prediction):vespa_rundata/conspred_probs.h5data/sequences.fasta--outputpredictions/Optional: In case you want to output a single [.h5 file](#.h5 files) in addition to the default .csv files with predictions, add--h5_outputfollowed by the output location. If you are only interested in an .h5 file, add--no_csvand drop--output predictions/. More details can be found underoutput.Note:The format of the results file is described below atVESPA and VESPAl output.Additional InformationExtracting raw reconstruction probabilitiesYou might be interested in extracting the raw reconstruction probabilities for each mutation position fromProtT5. These raw reconstruction probabilities are used to calculate the log-odds ratio and is explained in more detail in the corresponding publication.
To do so, use:vespa_logodds-r--reconstruction_outputdata/reconstruction_probasdata/sequences.fasta-odata/logodds.h5Optional: Add a mutations file.The generated datasets in the.h5filecontain probability vectors that determine the reconstruction probabilities for all amino acids sorted according to theMUTATION_ORDERinconfig.py. If a particular mutation was not computed (i.e., the position was not present in themutation.txt) it contains -1.File SpecificationsThis section describes relevant file formats forVESPAandVESPAl:Mutations fileA simple text file with a protein ID and one mutation per-line (i.e., mutations separated by \n for newline).
Every mutation should be specified by<PROTEIN_ID>_<SAV-String>separated by an underscore. The default<SAV-String>has the following format<fromAA><0-basedSequencePosition><toAA>.The sequence ID needs to be equivalent to the one in the sequenceFASTAfile.
The SAV string has the format:<Original Amino Acid><Position><Replacement Amino Acid>Example:ENSP00000355206_I0L
ENSP00000355206_I0V
ENSP00000355206_I0L
ENSP00000355206_I0K
ENSP00000355206_I0TOptional:In case you have a file with 1-based mutations, add the flag--one_based_mutations..h5filesMultiple scripts generate.h5files. These files follow thehdf5-standardand can be processed in python using the libraryh5py. Generally, the files are segmented into datasets that can be accessed using the protein accession in theFASTAfile. The datasets are explained in more detail in the respectiveoutput sections.Conservation outputThe conservation prediction will output an .h5 file with the predicted 9-state conservation probabilities. For each ID of theFASTAfile, the respective dataset contains a matrix of size 9xL, with L being the length of the protein sequence, and 9 being the predicted conservation class (index 0 = very variable; index 8 = very conserved).Additionally, you can extract a file with per-residue conservation class predictions for each sequence directly.Log-odds ratio outputThe default output is an .h5 file that contains one Lx20 matrix per sequence. -1 means no log-odds ratio was computed for the respective mutation.When running--single_csv data/single_logodds.csv, the log-odds ratio output file contains all mutations (or the mutations determined by the mutations file) as<PROTEIN_ID>_<SAV-String>, followed by a;and the log-odds ratio for a particular mutation per line.Example:B3VI55_LIPSTSTABLE_A438Q;0.053829677402973175
B3VI55_LIPSTSTABLE_A438N;0.061238136142492294
B3VI55_LIPSTSTABLE_A438Y;0.012603843584656715
B3VI55_LIPSTSTABLE_A438M;0.012212143279612064
B3VI55_LIPSTSTABLE_A438H;0.0241163931787014
B3VI55_LIPSTSTABLE_A438W;0.004520446062088013In case the predictions are written into a directory, e.g. by specifying--csv_dirinStep 3, the script will create one file per sequence, named by sequence ID (note: the ID will be normalized, i.e, each special character will be replaced by_).
The file will contain one<Mutation-String>;scoreper-line.Example file calledB3VI55_LIPSTSTABLE:A438Q;0.053829677402973175
A438N;0.061238136142492294
A438Y;0.012603843584656715
A438M;0.012212143279612064
A438H;0.0241163931787014
A438W;0.004520446062088013VESPA and VESPAl outputThe default output ofVESPAand/orVESPAlwill generate one .csv (with semicolon separator) file per protein in the output folder ofvespa_run_directory. If you specified an output directory with--output, you will find the .csv (with semicolon separator) files there.
To circumvent naming issues due to long sequence ID's, the csv files will be numbered by sequence occurrence in theFASTAfile. A lookup filemap.jsonwill be created in the output directory containing a dictionary mapping from number to sequence ID.Examplemap.json:{"0":"B3VI55_LIPSTSTABLE","1":"BF520_ENV","2":"BG_STRSQ","3":"BG505_ENV","4":"HG_FLU","5":"MTH3_HAEAESTABILIZED"}The individual files will contain rows with the mutations (format:<fromAA><0-basedSequencePosition><toAA>) along with the respective predictions ofVESPAand/orVESPAl.Example0.csv:Mutant;VESPAl;VESPA
M0A;0.4457732174287125;0.3520255108578212
M0L;0.3191178420567241;0.2717188481387661
M0G;0.5355136080284415;0.4110670843315182
M0V;0.3594337197937546;0.2971971641898669
M0S;0.4457732174287125;0.35202555423053
M0R;0.4457732174287125;0.35202621644931126If you chose to generate an .h5 output, the ID's will be the originalFASTAID's. The file contains one 20xL-shaped matrix per sequence-ID. L is the length of the respective protein length, and 20 is the possible number of amino acid variants (including self). The order of amino acids is determined byMUTANT_ORDERinpredict/config.py(ALGVSREDTIPKFQNYMHWC). Empty fields that were not calculated/specified (f.e., wildtype substitutions) contain a -1.Development RoadmapWrite comprehensive testsPublish pypi packageInstall from github releaseContributing guidelinesInstallation from current Github ReleaseWARNING Experimental: To install the current release from github you can use:python-mpipinstallhttps://github.com/Rostlab/VESPA/releases/download/v0.9.0-beta/vespa-0.9.0b0.tar.gzCiteIf you want to credit us, feel free to citeMarquet, C., Heinzinger, M., Olenyi, T. et al. Embeddings from protein language models predict conservation and variant effects. Hum Genet (2021).https://doi.org/10.1007/s00439-021-02411-y@article{Marquet2021,doi={10.1007/s00439-021-02411-y},url={https://doi.org/10.1007/s00439-021-02411-y},year={2021},month=dec,publisher={Springer Science and Business Media {LLC}},author={C{\'{e}}line Marquet and Michael Heinzinger and Tobias Olenyi and Christian Dallago and Kyra Erckert and Michael Bernhofer and Dmitrii Nechaev and Burkhard Rost},title={Embeddings from protein language models predict conservation and variant effects},journal={Human Genetics}}