A machine-learning package for navigating combinatorial protein fitness landscapes. This repository accompanies our work "Machine Learning-Assisted Directed Evolution Navigates a Combinatorial Epistatic Fitness Landscape with Minimal Screening Burden".

• MLDE
  • Table of Contents
• MLDE Concept
• Installation
  • Installation Validation
    • Basic Tests
    • Pytest Validation
• General Use
  • Generating Encodings with GenerateEncodings.py
    • Inputs for GenerateEncodings.py
    • Examples for GenerateEncodings.py
    • Outputs for GenerateEncodings.py
  • Making Predictions with ExecuteMlde.py
    • Inputs for ExecuteMlde.py
      • TrainingData.csv
      • Custom Encodings
      • MldeParameters.csv
    • Examples for ExecuteMlde.py
    • Outputs for ExecuteMlde.py
• Program Details
  • Inbuilt Models
• Dependencies
  • OS
  • Hardware
  • Software
• Citing this Repository

MLDE attempts to learn a function that maps protein sequence to protein fitness for a combinatorial design space. The procedure begins by experimentally measuring the fitness values of a small subsample from a combinatorial library. These labeled variants are then used to train an ensemble of 22 models with varied architectures (see Inbuilt Models). Trained models are next ranked by validation error, and the predictions of the N-best models are averaged to predict fitness values for the unsampled (“unlabeled”) variants. Unlabeled variants are ranked according to predicted fitness and returned. More detailed information on programmatic implementation is given below.

1. For encoding generation, MLDE relies on the module tape-neurips2019, which accompanies the work by Rao et al. Evaluating Protein Transfer Learning with TAPE. To include tape-neurips2019 as a submodule, the MLDE repository must be cloned with the "--recurse-submodules" flag as below. MLDE may not work correctly (or at all) if tape-neurips2019 is not included as a submodule.

git clone --recurse-submodules https://github.com/fhalab/MLDE.git

2. The repository will be downloaded with the mlde.yml anaconda environment template in the top-level directory. It is highly recommended that MLDE be run from within the "mlde" conda environment. Note that this environment assumes you have pre-installed CUDA and have a CUDA-capable GPU on your system. If you would rather work in a separate environment, dependencies for MLDE can be found here. To build the mlde conda environment, run

cd ./MLDE
conda env create -f mlde.yml

3. Whatever environment you are working in, the next step is to complete installation of tape-neurips2019: Activate your desired conda environment, then navigate to the tape-neurips2019 submodule and install tape-neurips2019 dependencies (substitute "mlde" for whatever environment you will be working in):

conda activate mlde
cd ./Support/tape-neurips2019
pip install -e .

4. Still within the tape-neurips2019 submodule, download the model weights needed for generating learned embeddings by by running

./download_pretrained_models.sh

Basic functionality of MLDE can be tested by running GenerateEncodings.py and ExecuteMlde.py with provided example data. Test command line calls are given below. To run GenerateEncodings.py:

conda activate mlde
python GenerateEncodings.py transformer GB1_T2Q --fasta 
  ./Validation/BasicTestData/2GI9.fasta --positions V39 D40 --batches 1

To run ExecuteMlde.py:

conda activate mlde
python ExecuteMlde.py ./Validation/BasicTestData/InputValidationData.csv 
  ./Validation/BasicTestData/GB1_T2Q_georgiev_Normalized.npy 
  ./Validation/BasicTestData/GB1_T2Q_ComboToIndex.pkl 
  --model_params ./Validation/BasicTestData/TestMldeParams.csv 
  --hyperopt

MLDE has been thoroughly tested using pytest. These tests can be repeated as follows: activate the mlde conda environment, navigate to the top-level MLDE directory, and run pytest as below

conda activate mlde
cd ~/GitRepos/MLDE
PYTHONPATH=\$pathToRepoLocation/MLDE/ pytest

The cd command should be modified for wherever your copy of MLDE is saved. The PYTHONPATH argument should also be modified as appropriate based on the location of MLDE on your computer. Running the pytest tests will take multiple hours, so it is recommended to run them overnight.

MLDE works in two stages: Encoding generation and prediction. The encoding generation stage takes a parent protein sequence and generates all encodings for a given combinatorial library. The prediction stage uses the encodings from the first stage in combination with fitness data for a small set of combinations to make predictions on the fitness of the full combinatorial space. The MLDE package can generate all encodings presented in our accompanying paper; however, users can also pass in their own encodings (e.g. from a custom encoder) to the prediction stage scripts.

Encodings for MLDE are generated with the GenerateEncodings.py script. The combinatorial space can be encoded using one-hot, Georgiev, or learned embeddings. Learned embeddings can be generated from any of the completely unsupervised pre-trained models found in tape-neurips2019.

There are a number of required and optional arguments that can be passed to GenerateEncodings.py, each of which are detailed in the table below

The below example is a command line call for generating Georgiev encodings for a 4-site combinatorial space (160000 total variants). This command could also be used for generating onehot encodings. Note that, because georgiev and onehot encodings are context-independent, no fasta file is needed. Indeed, the encodings generated from the below call could be applied to any 4-site combinatorial space.

python GenerateEncodings.py georgiev example_protein --n_combined 4 

The below example is a command line call for generating transformer embeddings for the 4-site GB1 combinatorial library discussed in our work. Note that this command could be used for generating any of the learned embeddings (with appropriate substitution of the encoding argument). Because embeddings are context-aware, these encodings should not be used for another protein.

python GenerateEncodings.py transformer GB1_T2Q 
  --fasta .Validation/BasicTestData/2GI9.fasta
  --positions V39 D40 G41 V54 --batches 4

The input fasta file looks as below:

>GB1_T2Q
MQYKLILNGKTLKGETTTEAVDAATAEKVFKQYANDNGVDGEWTYDDATKTFTVTE

Every run of GenerateEncodings.py produces a time-stamped folder containing all results. The time-stamp format is "YYYYMMDD-HHMMSS" (Y = year, M = month, D = day, H = 24-hour, M = minute, S = second). The time-stamped folder contains subfolders "Encodings" and "Fastas".

The "Encodings" folder will contain the below files ("$NAME" is from the name argument of GenerateEncodings.py; "$ENCODING" is from the encoding argument):

Note that when encoding is "onehot", only unnormalized embeddings will be returned.

The "Fastas" directory is only populated when one of the learned embeddings is generated. It contains fasta files with all sequences used to generated embeddings, split into batches as appropriate.

MLDE predictions are made using the ExecuteMlde.py script. Inputs to this script include the encodings for all possible members of the combinatorial space, experimentally determined sequence-function data for a small number of combinations (for use as training data), and a dictionary linking all possible members of the combinatorial space to their associated encoding.

This csv file contains the sequence-function data for the protein of interest. An example csv file can be found in MLDE/Validation/BasicTestData/InputValidationData.csv. The top few rows of this file are demonstrated below:

The two column headers must always be present and always have the same name. Sequence is input as the combination identity, which is the amino acid present at each position in order. For instance, a combination of A14, C23, Y60, and W91 would be written as "ACYW".

While not strictly required, it is recommended to normalize fitness in some manner. Common normalization factors would be the fitness of the parent protein or the maximum fitness in the training data.

Any encoding can be passed into ExecuteMlde.py so long as it meets the dimensionality requirements. Specifically, the array must take the shape $20^C x C x L$, where $C$ is the number of amino acid positions combined and $L$ is the number of latent dimensions per amino acid for the encoding. The program will throw an exception if a non-3D encoding is passed in as the encoding_data argument.

Note that for all but the convolutional neural networks, the last 2 dimensions of the input space will be flattened before processing. In other words, convolutional networks are trained on 2D encodings and all other models on 1D encodings.

This file details what models are included in an MLDE run and how many hyperparameter optimization rounds will be executed for each model. By default, the file found at MLDE/Support/Params/MldeParameters.csv is used, though users can pass in their own versions; the default file can be used as a template for custom parameter files, but should never be changed itself. The contents of the MldeParameters.csv file are copied below:

The column names should not be changed. Rows should never be deleted from this file. Changing the "Include" column contents to 'FALSE' will stop a model from being included in the ensemble trained for MLDE. The "NHyperopt" column contents can be changed to alter how many hyperparameter optimization rounds are performed when the hyperopt flag is thrown. Note that Keras-based models can take a long time for hyperparameter optimization, hence why only 10 rounds are performed by default.

The below is an example run of ExecuteMlde.py using information output by GenerateEncodings.py as its inputs. Note that all optional arguments are used here for demonstration purposes; they don't all need to be used in practice.

python ExecuteMlde.py ./FitnessInfo.csv ./GB1_T2Q_georgiev_Normalized.npy ./GB1_T2Q_ComboToIndex.pkl --model_params ./MyCustomModelParams.csv --output ~/Documents/MyMldeRun --n_averaged 5 --n_cv 10 --hyperopt

Every run of ExecuteMlde.py produces a time-stamped folder containing all results. The time-stamp format is "YYYYMMDD-HHMMSS" (Y = year, M = month, D = day, H = 24-hour, M = minute, S = second). The time-stamped folder contains the files "PredictedFitness.csv", "LossSummaries.csv", "CompoundPreds.npy", "IndividualPreds.npy", and "PredictionStandardDeviation.npy". If hyperparameter optimization is performed, an additional file called "HyperoptInfo.csv" will also be generated. The contents of each file are detailed below:

The MLDE algorithm takes as input all encodings corresponding to the combinations of amino acids found in the training data along with their measured fitness values. During the training stage, these sampled combinations are used to train a version of all inbuilt models using K-fold cross validation and the default model parameters; mean validation error from the K-fold cross validation is recorded. Against using K-fold validation, in the next stage, H rounds of Bayesian hyperparameter optimization using the hyperopt Python package are optionally performed. Hyperparameters which minimize mean validation error are recorded. Post hyperparameter optimization, models are retrained using their optimal hyperparameters and mean validation error is recorded.

For making predictions, the top-N model architectures (those with the lowest cross-validation error after hyperparameter optimization) are first identified. For each of the top-N model architectures, predictions are made on the unsampled combinations by averaging the predictions of the K models trained during cross validation. The predictions made by each of the N models are then averaged to return a single final prediction of the unsampled values. In total, this means that K x N models are averaged to generate a single prediction for MLDE (K from each of the top-N model architectures).

Currently, the prediction stage of MLDE can only be run using its inbuilt models, though it could potentially be expanded to allow custom designation of models in the future. All models are either written in/derived from Keras, XGBoost, and scikit-learn. The models are detailed in the supporting information section of the paper accompanying this repository.

MLDE was developed and vetted (using pytest) on a system running Ubuntu 18.04. In its current state it should run on any UNIX OS, but has not been tested on (nor can be expected to run) on Windows OS.

MLDE can be run on any standard setup (laptop or desktop) that has both CPU and GPU support. The lstm and unirep models can require up to 8 GB GPU RAM for encoding generation, while the others are fairly tame and should fit on most GPUs; encodings were generated with NVIDIA RTX2070 and TitanV GPUs during development of this software.

MLDE requires the dependencies given below. The submodule tape-neurips submodule has its own dependencies that will be installed during its setup.

• python=3.7.3
• numpy=1.16.4
• pandas=0.25.3
• tqdm=4.32.1
• biopython=1.74
• hyperopt=0.2.2
• scipy=1.3.0
• scikit-learn=0.21.2
• tensorflow-gpu=1.13.1
• keras=2.2.5
• xgboost=0.90
• nltk=3.4.4
• psutil

Specific versions used during the development of MLDE are listed here. MLDE is validated to be stable using these versions, though there should be some leeway if users use different versions. If running in a new environment, it is strongly recommended to perform the pytest validation first.

Please cite our work "Machine Learning-Assisted Directed Evolution Navigates a Combinatorial Epistatic Fitness Landscape with Minimal Screening Burden" when referencing this repository.