Package: pypef
This repository contains the source files and supplementary information for the PyPEF framework, which is described inNiklas E. Siedhoff1,§, Alexander-Maurice Illig1,§, Ulrich Schwaneberg1,2, Mehdi D. Davari3,*,PyPEF – An Integrated Framework for Data-Driven Protein Engineering,J. Chem. Inf. Model.2021, 61, 3463-3476https://doi.org/10.1021/acs.jcim.1c00099as well as additional framework features described in the preprintAlexander-Maurice Illig1,§, Niklas E. Siedhoff1,§, Ulrich Schwaneberg1,2, Mehdi D. Davari3,*,A hybrid model combining evolutionary probability and machine learning leverages data-driven protein engineering,To be publishedPreprint available at bioRxiv:https://doi.org/10.1101/2022.06.07.495081.1Institute of Biotechnology, RWTH Aachen University, Worringer Weg 3, 52074 Aachen, Germany2DWI-Leibniz Institute for Interactive Materials, Forckenbeckstraße 50, 52074 Aachen, Germany3Department of Bioorganic Chemistry, Leibniz Institute of Plant Biochemistry, Weinberg 3, 06120 Halle, Germany*Corresponding author§Equal contributionTable of ContentsPyPEF: Pythonic Protein Engineering FrameworkQuick InstallationRequirementsRunning ExamplesTutorialEncoding Technique OptionsModeling TechniquesPure Machine Learning (ML)-based ModelingHybrid Modeling Using the MERGE MethodModel Hyperparameter Grids for TrainingSetting Up the Scripts YourselfPreprocessing for DCA-based Sequence EncodingUnsupervised/zero-shot predictionAPI Usage for Sequence EncodingPyPEF: Pythonic Protein Engineering Frameworka framework written in Python 3 for performing sequence-based machine learning-assisted protein engineering to predict a protein's fitness from its sequence using different forms of sequence encoding:One-hot encodingAmino acid descriptor sets (taken from AAindex database) encodingDirect coupling analysis (amino acid coevolution based on multiple sequence alignments) encodingWritten by Niklas Siedhoff and Alexander-Maurice Illig.Protein engineering by rational or random approaches generates data that can aid the construction of self-learned sequence-function landscapes to predict beneficial variants by using probabilistic methods that can screen the unexplored sequence space with uncertaintyin silico. Such predictive methods can be applied for increasing the success/effectivity of an engineering campaign while partly offering the prospect to reveal (higher-order) epistatic effects. Here we present an engineering framework termed PyPEF for assisting the supervised training and testing of regression models for predicting beneficial combinations of (identified) amino acid substitutions using machine learning algorithms from theScikit-learnpackage. As training input, the developed framework requires the variant sequences and the corresponding screening results (fitness labels) of the identified variants as CSV (or FASTA-Like (FASL) datasets following a self-defined convention). Using linear or nonlinear regression methods (partial least squares (PLS), Ridge, Lasso, Elastic net, support vector machines (SVR), random forest (RF), and multilayer perceptron (MLP)-based regression), PyPEF trains on the given learning data while optimizing model hyperparameters (default: five-fold cross-validation) and can compute model performances on left-out test data. As sequences are encoded using amino acid descriptor sets taken from theAAindex database, finding the best index-dependent encoding for a specific test set can be seen as a hyperparameter search on the test set. In addition, one-hot anddirect coupling analysis-based feature generation are implemented as sequence encoding techniques, which often outperform AAindex-based encoding techniques. Finally, the selected or best identified encoding technique and regression model can be used to perform directed evolution walksin silico(seeChurch-lab implementationor thereimplementation) or to predict natural diverse or recombinant variant sequences that subsequently are to be designed and validated in the wet-lab.For detailed information, please refer to the above-mentioned publications and related Supporting Information.The workflow procedure is explained in theJupyter notebook(.ipynb) protocol (see
Tutorial section below).Quick InstallationA quick installation of the PyPEF command line framework using PyPI for Linux and Windows forPython 3.10can be performed with:pip install -U pypefAfter successful installation, PyPEF should work by callingpypefin the shell:pypef --helpThe detailed routine for setting up a new virtual environment with Anaconda, installing the necessary Python packages for that environment, and running the Jupyter notebook tutorial can be found below in the Tutorial section.
A quick file setup and run test can be performed running files inscripts/Setupcontaining a Batch script for Windows and a Bash script for Linux (the latter requires conda, i.e. Miniconda3 or Anaconda3, already being installed).RequirementsPython >=3.9numpyscipypandasscikit-learntensorflowray[default]matplotlibtqdmbiopythonschemadocoptadjustTextIf errors occur with third-party packages, you can check the required Python version dependencies (if available); also, as a rule of thumb, it is often helpful to use the second most recent Python version instead of the latest, since development for the latest version is often ongoing:Running ExamplesPrinting the help function:pypef --helpCreating sets for model learning and testing:pypef mklsts -w WT_SEQUENCE.FASTA -i VARIANT-FITNESS_DATA.CSVTraining and testing a model (encoding technique = {aaidx,onehot,dca}, regression model = {pls,ridge,lasso,elasticnet,svr,rf,mlp}):pypef ml -e aaidx -l LEARNING_SET.FASL -t TEST_SET.FASL --regressor plsShow the model performance(s) (reads and prints the created Model_Results.txt file):pypef ml --showLoad a trained model, predict fitness of test sequences using that model, and plot the measured versus the predicted fitness values:pypef ml -e aaidx -m MODEL -t TEST_SET.FASL-m MODELis the saved model Pickle file name, for-e aaidxthis will be the AAindex to use for encoding, e.g.-m ARGP820101, for-e onehotit will be-m ONEHOTMODELand for-e dcait will be-m DCAMODEL.Load a trained model and use it for predicting the fitness of sequences of a prediction set (with unknown corresponding fitness):pypef ml -e aaidx -m MODEL -p PREDICTION_SET.FASTASystematic creation of prediction sets – double, triple, or quadruple substituted variant recombinations of already identified amino acid substitutions (--drecomb,--trecomb,--qarecomb,--qirecomb) or naturally diverse combinations of all 20 canonical amino acids at the identified positions (--ddiverse,--tdiverse,--qdiverse):pypef mkps -w WT_SEQUENCE.FASTA -i VARIANT-FITNESS_DATA.CSV --drecombSystematic prediction of the created (re)combination prediction sets:pypef ml -e aaidx -m MODEL --pmult --drecombAn alternative way of prediction and variant identification is thein silicodirected evolutionusing theMetropolis-Hastingsalgorithm:pypef directevo ml -e -m MODEL -w WT_SEQUENCE.FASTA --usecsv -i VARIANT-FITNESS_DATA.CSV --ywt WT_FITNESSEncoding a variant-fitness CSV file and writing it to a new CSV file (for the different encodings, also specify the AAindex name with the-moption next to-e aaidx):pypef encode -i VARIANT-FITNESS_DATA.CSV -w WT_SEQUENCE.FASTA -e aaidxUsing the created variant-encoded sequence-fitness CSV file for a simulated "lowN" engineering task:pypef ml low_n -i VARIANT-FITNESS-ENCODING_DATA.CSV --regressor plsUsing the created variant-encoded sequence-fitness CSV file for a simulated "mutation extrapolation" task (requires higher/deeply-substituted variants):pypef ml extrapolation -i VARIANT-FITNESS-ENCODING_DATA.CSV --regressor plsThe use of the hybrid model (pypef hybrid) - instead of a pure ML model (pypef ml) as described in the steps above - is quite similar in terms of commands, but does not require the definition of the-e/--encodingand the--regressorflags, since it depends only on the DCA-based encoding technique and (so far) only uses Ridge regression for modeling. However, DCA-based encoding of sequences always requires a parameter file as input, which comes from the preprocessing of a query-specific multiple sequence alignment (MSA) and results in the parameter file generated byplmc. E.g. for training a model on a learning set and testing it on a test set, the command for hybrid modeling is:pypef hybrid -l LEARNING_SET.FASL -t TEST_SET.FASL --params PLMC_FILE.paramsAlso, it is now possible to infer DCA model parameters usingGREMLIN'sTensorFlow implementationand a generated MSA in FASTA or A2M format:pypef param_inference --msa MSA.fasta -w WT_SEQUENCE.FASTA --opt_iter 250For getting coupling information and highly evolved amino acids:pypef save_msa_info --msa MSA.fasta -w WT_SEQUENCE.FASTA --opt_iter 250Using saved GREMLIN model for testing:pypef hybrid -l LEARNING_SET.FASL -t TEST_SET.FASL --params GREMLINSample files for testing PyPEF routines are provided in the workflow directory, which are also used when running the notebook tutorial. PyPEF's package dependencies are linkedhere.
Further, for designing your own API based on the PyPEF workflow, modules can be adapted from thesource code.As standard input files, PyPEF requires the target protein wild-type sequence inFASTAformat and variant-fitness data inCSVformat to split the collected variant-fitness data in learning and test sets that resemble the aligned FASTA format and additionally contain lines indicating the fitness of each corresponding variant (seeANEH sample files,avGFP sample files, andMERGE SSM & DMS files).TutorialBefore starting running the tutorial, it is a good idea to set up a new Python environment using Anaconda,https://www.anaconda.com/, e.g. usingAnaconda(Anaconda3-2023.03-1-Linux-x86_64.sh installer download) orMiniconda.
Change to the download directory and run the installation, e.g. in Linux:bash Anaconda3-2023.03-1-Linux-x86_64.shAfter accepting all steps, the conda setup should also be written to your~/.bashrcfile, so that you can call anaconda typingconda.
Next, to download this repository click Code > Download ZIP and unzip the zipped file, e.g. withunzip PyPEF-main.zip, or just clone this repository using your bash shell to your local machinegit clone https://github.com/niklases/PyPEF.
To set up a new environment with conda you can either create the conda environment from the provided YAML file inside the PyPEF directory (cd PyPEForcd PyPEF-maindependent on the downloaded file name and chose YAML file for your operating system):conda env create --file linux_env.ymlor you can create a new environment yourself. You just need to specify the name of the environment and the Python version, e.g.:conda create --name pypef python=3.10To activate the environment you can define:conda activate pypefAfter activating the environment you can install required packages after changing the directory to the PyPEF directory (cd PyPEForcd PyPEF-main) and install required packages with pip if you did not use the YAML file for creating the environment (if using conda, packages will be installed in anaconda3/envs/pypef/lib/python3.10/site-packages):python3 -m pip install -r requirements.txtNote that the packageRaywhich we use for parallelizing sequence encoding and model validation of AAindices on the test set, is in beta status forWindows.Now, after installing required packages, you should be able to directly run pypef in the command-line interface.To run the tutorial after installing required packages either from the conda YAML environment file, the TEXT requirement file, or after installing packages using the pip version of PyPEF, open a Jupyter notebook. If you have installed Anaconda, Jupyter notebook and other commonly used packages for scientific computing and data science should be already installed in Python. If not, you can also install Jupyter viapython3 -m pip install ipython jupyter. To use the pypef environment as a specified kernel inside the Jupyter notebook, you need to installipykerneland set the kernel name:python3 -m pip install ipykernel jupyter
python3 -m ipykernel install --user --name=pypefNow change the directory to ./scripts/CLI (cd scripts/CLI) and run the .ipynb file (after downloading the files it might be necessary to make the script executable first:chmod +x Workflow_PyPEF.ipynb):jupyter-notebookCopy the notebook URL in your internet browser and select the Workflow_PyPEF.ipynb file to open it. Now you can select the pypef Python environment at the top notebook menu: Kernel > Change kernel > pypef (otherwise you would use your default Python version as environment, i.e. you would have to install the required packages for this interpreter as well; for this case the installation of the prerequisite packages can also be done within the notebook in provided code fields).Encoding Technique OptionsAAindex: Sequence encoding based on AAindex descriptor sets; e.g. using AAindexhttps://www.genome.jp/entry/aaindex:ARGP820101for encoding and without subsequent fast Fourier transform (FFT) of the encoded sequence:sequence 'MKLLF' --> [1.18, 1.15,	1.53,	1.53,	2.02]and with FFT of the encoded sequence:sequence 'MKLLF' --> [0.0000,	1.0000,	0.1435,	0.3010]OneHot: Occurence of a specific amino acid at a specific residue position indicated as a 1 and elso as a 0:sequence 'MKLLF' -->[ 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0,0, 0, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0 ]DCA: Direct coupling analysis of multiple sequence alignments to extract evolutionary query-specific features. DCA-based features will be generated from the local and coupling terms of the parameter file (paramfile) output byplmcfor each target variant sequence. This encoding technique generally outperforms the other encoding techniques described here, but depends on finding and aligning a minimum set of evolutionarily related/homologous sequences - which is not possible for every target sequence. Preprocessing steps for generating the paramfile based on a target sequence are described in thehybrid model repository. Unlike the other encoding techniques presented, this evolution-based encoding technique is system-specific rather than amino acid-specific, i.e. it does not treat each amino acid the same, but according to its evolutionary position- and coupling-specific history. The DCA-based encoding technique is further also provided for constructing a pure ML model:sequence 'MKLLF' --> [2.3445, 1.3294, 1.6245, 0.8901, 3.2317]  , whilesequence 'MKLKF' --> [2.3472, 1.3601, 1.5431, 1.3749, 3.0186]  .Modeling TechniquesPure Machine Learning (ML)-based ModelingServeral linear and non-linear modeling options are available by default to construct supervised regression models based on the generated sequence features, i.e. encoded sequences.
Regression models are trained, i.e. model hyperparameters are optimized, byk- fold (by default, fivefold) cross-validation on training samples. Here, the model aims to map the encoded variant sequences that are the features (X) for predicting the corresponding fitness labels (y) such thatf(X)-->y– while cross-validation and/or using a model implementing a penalty will be necessary for better model generalization behavior.
Following regression options fromScikit-learnare implemented (for optimized hyperparameters, see Model Hyperparameters section below):Partial Least Squares Regression (linear model)Lasso Regression (fit with Least Angle Regression, L1-penalty regularized linear model)Ridge Regression (L2-penalty regularized linear model)ElasticNet Regression (combined L1- and L2-penalty regularized linear model)Support Vector Machines Regression (nonlinear model)Random Forest Regression (nonlinear ensemble model)Multilayer-Perceptron Regression ("Deep" learning with a single hidden layer, nonlinear model)Hybrid Modeling Using the MERGE MethodOptimization of the two model contributions to the final hybrid model using thedifferential evolutionalgorithm (see thehybrid model preprintand the corresponding repository of the method termedMERGE); only based on DCA-derived features (therefore no definition of the flag-e,--encodingnecessary for hybrid modeling):DCA-based statistical prediction of the evolutionary energy, i.e., probability, of a variant relative to the wild type (seeEVmutation;EVmutation repository/EVcouplings repository).ML-based supervised training with Ridge regression on training subsets of DCA-encoded sequences and the corresponding fitness values (similar to the pure ML approach using the DCA-based encoding technique in combination with Ridge regression)Model Hyperparameter Grids for TrainingThe following model hyperparameter ranges are tested during (k-fold) cross-validation for optimized model generalization:Regression modelHyperparameter gridPLSN_components= {1, 2, 3, ..., 9}Ridgeregularization param. = {1.000E-06, 1.322E-06, 1.748E-06, ..., 1.000E06}(numpy.logspace(-6, 6, 100))LassoLarsregularization param. = {1.000E-06, 1.322E-06, 1.748E-06, ..., 1.000E06}(numpy.logspace(-6, 6, 100))ElasticNetregularization param. = {1.000E-06, 1.322E-06, 1.748E-06, ..., 1.000E06}(numpy.logspace(-6, 6, 100))SVRregularization param. = {2^0, 2^2, 2^4, 2^6, 2^8, 2^10, 2^12},kernel coefficient = {1E−01, 1E−02, 1E−03, 1E−04, 1E−05}RFN_trees = {100, 250, 500, 1000},max. features = {all features, sqrt(all features), log2(all features)}MLPsingle hidden layer size = {1, 2, ..., 12},solver = {ADAM, L-BFGS},initial learning rate = {0.001, 0.01, 0.1}Setting Up the Scripts YourselfPyPEF was developed to be run from a command-line interface whilepython3 ./pypef/main.py(when using the downloaded version of this repository and setting thePYTHONPATH) is equal topypefwhen installed with pip.
Downloading/cloning the repository files (manually or withwget/git clone):wget https://github.com/niklases/PyPEF/archive/main.zipUnzipping the zipped file (manually or e.g. withunzip):unzip main.zipSetting thePYTHONPATH(so that no import errors occur stating that the packagepypefand thus dependent absolute imports are unknown):Windows (example path, PowerShell)$env:PYTHONPATH="C:\Users\name\path\to\PyPEF-main"Linux (example path)export PYTHONPATH="${PYTHONPATH}:/home/name/path/to/PyPEF-main"Installing the requirements:Windows (PowerShell)python -m pip install -r requirements.txtLinuxpython3 -m pip install -r requirements.txtRunning the main script (from PyPEF-main directory):Windows (PowerShell)python .\pypef\main.pyLinuxpython3 ./pypef/main.pyPreprocessing for DCA-based Sequence EncodingDownloading sequence database (e.g. UniRef100):wget https://ftp.uniprot.org/pub/databases/uniprot/uniref/uniref100/uniref100.fasta.gzExtracting sequence database:gunzip uniref100.fasta.gzAfterinstalling jackhmmer as part of the HMMER package, construct an MSA for your target sequence provided in FASTA format (and for example set--incTto half the sequence length (0.5L) and the number of used CPUs for computing):jackhmmer --incT 199 --cpu 16 --noali -A ANEH_jhmmer.sto Sequence_WT_ANEH.fasta /path/to/uniref100.fastaConvert the created MSA fromStockholm(.sto) format toA2Mformat:pypef sto2a2m --sto ANEH_jhmmer.stoNow you can follow approaches 5.1 (using GREMLIN; implemented in TensorFlow) or 5.2 (using plmc; extern parameter generation in C).5.1. Running GREMLIN on the generated MSA (in FASTA or A2M format):pypef param_inference --msa ANEH_jhmmer.a2m -w WT_SEQUENCE.FASTA --opt_iter 250The pickled GREMLIN file can then be used for encoding new/test sequences:pypef ml -e dca -l LS.fasl -t TS.fasl --regressor pls --params GREMLINOr for hybrid modeling:pypef hybrid -l LS.fasl -t TS.fasl --params GREMLIN5.2 Afterinstalling plmc, generate the evolutionary coupling file, which is used for encoding sequences. For example, set-leto the value output bysto2a2m:plmc -o ANEH_72.6.params -le 72.6 -m 100 -g -f WT_ANEH ANEH_jhmmer.a2mThe output parameter (.params) file can be used for encoding sequences with the DCA-based encoding technique (-e dca) by providing it to PyPEF; e.g. for pure ML modeling:pypef ml -e dca -l LS.fasl -t TS.fasl --regressor pls --params ANEH_72.6.paramsOr for hybrid modeling:pypef hybrid -l LS.fasl -t TS.fasl --params ANEH_72.6.paramsUnsupervised/zero-shot predictionSeveral developed methods allow unsupervised prediction of a proteins fitness based on its sequence (and/or structure).
These methods have the advantage that no initial knowledge about a proteins fitness is required for prediction, while a correlation of the predicted score and a protein's natural fitness is assumed.
DCA itself is a statistical/unsupervised method based on MSA information that outperforms simpler MSA-based methods (such as (un)coupled raw MSA sequence frequencies or BLOSUM scores), e.g., seescripts/GREMLIN_numba/using_gremlin_functionalities.ipynb.
To make zero-shot predictions using PyPEF (plmc-DCA or GREMLIN-DCA) just do not provide a training set (no-lflag, only a-tor-pflag) for hybrid modeling, e.g., for the avGFP data, trypypef param_inference --msa uref100_avgfp_jhmmer_119.a2m
pypef hybrid -t TS.fasl --params GREMLIN
pypef hybrid -p PS.fasta --params GREMLINusing the GREMLIN parameters, or,pypef param_inference --params uref100_avgfp_jhmmer_119_plmc_42.6.params
pypef hybrid -t TS.fasl --params PLMC
pypef hybrid -p PS.fasta --params PLMCusing the plmc parameters.Other well-performing zero-shot prediction methods with available source code are:ESM-1v/ESM-2 (https://github.com/facebookresearch/esm)DeepSequence (https://github.com/debbiemarkslab/DeepSequence)EVcouplings (plmc-DCA,https://github.com/debbiemarkslab/EVcouplings)EVE (https://github.com/OATML/EVE)Tranception (https://github.com/OATML-Markslab/Tranception)This list is by no means complete, see ProteinGymrepositoryandwebsitefor a more detailed overview of available methods and achieved performances (as well as for getting many benchmark data sets).API Usage for Sequence EncodingFor script-based encoding of sequences using PyPEF and the available AAindex-, OneHot- or DCA-based techniques, the classes and corresponding functions can be imported, i.e.OneHotEncoding,AAIndexEncoding,GREMLIN(DCA),PLMC(DCA), andDCAHybridModel. In addition, implemented functions for CV-based tuning of regression models can be used to train and validate models, eventually deriving them to obtain performances on retained data for testing. An exemplary script and a Jupyter notebook for CV-based (low-N) tuning of models and using them for testing is provided atscripts/Encoding_low_N/api_encoding_train_test.pyandscripts/Encoding_low_N/api_encoding_train_test.ipynb, respectively.