SSMuLA

About

• Code base termed "Site Saturation Mutagenesis Landscape Analysis (SSMuLA)" for our paper titled "Evaluation of Machine Learning-Assisted Directed Evolution Across Diverse Combinatorial Landscapes"
• Data and results can be found at Zenodo

Environment

• For the overall environment SSMuLA

conda env create -f SSMuLA.yml

• Then install EVmutation from the develop branch after the environment is created
• For the ESM-IF environment

conda create -n inverse python=3.9
conda activate inverse
conda install pytorch cudatoolkit=11.3 -c pytorch
conda install pyg -c pyg -c conda-forge
conda install pip
pip install biotite
pip install git+https://github.com/facebookresearch/esm.git

or install the ESM-IF environment esmif

conda env create -f esmif.yml

• For the CoVES environment coves

conda env create -f coves.yml

• For installing Triad command line, see instructions here
• For running ESM-2 fintuning simulations, use the finetune.yml environment

conda env create -f finetune.yml

• Frozen environment can be found in envs/frozen

Datasets

• The data/ folder is organized by protein type. Each protein directory contains:

  • .fasta: FASTA file for the parent sequence
  • .pdb: PDB file for the parent structure
  • .model: EVmutation model file
  • fitness_landscape/: Folder containing CSV files for all fitness landscapes for this protein type, each listing amino acid substitutions and their corresponding fitness values from the original sources
  • scale2max/: the folder containing processed fitness csv files returned from the process_all function in the SSMuLA.fitness_process_vis module where the maximum fitness value is normalized to 1 for each landscape

• Landscapes summarized in the table below and described in detail in the paper:

Landscape	PDB ID	Sites
ParD2	6X0A	I61, L64, K80
ParD3	5CEG	D61, K64, E80
GB1	2GI9	V39, D40, G41, V54
DHFR	6XG5	A26, D27, L28
T7	1CEZ	N748, R756, Q758
TEV	1LVM	T146, D148, H167, S170
TrpB3A	8VHH	A104, E105, T106
TrpB3B		E105, T106, G107
TrpB3C		T106, G107, A108
TrpB3D		T117, A118, A119
TrpB3E		F184, G185, S186
TrpB3F		L162, I166, Y301
TrpB3G		V227, S228, Y301
TrpB3H		S228, G230, S231
TrpB3I		Y182, V183, F184
TrpB4		V183, F184, V227, S228

Preprocessing

• Run

python -m tests.test_preprocess

refer to the test file and the script documentation for further details

• Processed with fitness_process_vis
• Rename columns to be AAs, AA1, AA2, AA3, AA4, fitness, add active if not already there and add muts columns
• Scale to max (with option to scale to parent)
• Processed data saved in scale2max folder
• The landscape stats will be saved

Landscape attributes

Local optima

• Run

python -m tests.local_optima

refer to the test file and the script documentation for further details

• Calculate local optima with calc_local_optima function in SSMuLA.local_optima

Pairwise epistasis

• Run

python -m tests.pairwise_epistasis

refer to the test file and the script documentation for further details

• Calculate pairwise epistasis with calc_all_pairwise_epistasis function in SSMuLA.pairwise_epistasis
• Start from all active variants scaled to max fitness without post filtering
• Initial results will be saved under the default path results/pairwise_epistasis folder (corresponding to the active_start subfolder in the zenodo repo)
• Post processing the output with plot_pairwise_epistasis function in SSMuLA.pairwise_epistasis
• Post processed results will be saved under the default path results/pairwise_epistasis_dets folder with summary files (corresponding to the processed subfolder) and results/pairwise_epistasis_vis for each of the landscape with a master summary file across all landscapes (in the pairwise_epistasis_summary.csv)

Zero-shot

• The currrent pipeline runs EVmutation and ESM together, and then append the rest based

EVmutation

• All EVmutation predictions run with EVcouplings
• All settings remain default
• Model parameters in the .model files are downloaded and renamed

ESM

• The logits will be generated and saved in the output folder
• Run

python -m tests.test_ev_esm

refer to the test file and the script documentation for further details

Hamming distance

• Directly calculated from n_mut
• For Hamming ditsance testing, run

python -m tests.hamming_distance

to deploy run_hd_avg_fit and run_hd_avg_metric from SSMuLA.calc_hd refer to the test file and the script documentation for further details

ESM-IF

• Run

python -m tests.test_esmif

refer to the test file and the script documentation for further details

• Generate the input fasta files with get_all_mutfasta from SSMuLA.zs_data to be used in ESM-IF
• Set up the environment for ESM-IF to

conda create -n inverse python=3.9
conda activate inverse
conda install pytorch cudatoolkit=11.3 -c pytorch
conda install pyg -c pyg -c conda-forge
conda install pip
pip install biotite
pip install git+https://github.com/facebookresearch/esm.git

or use

• With in the esmif folder within the new environment, run

./esmif.sh

• ESM-IF results will be saved in the same directory as the esmif.sh script

CoVES

• Follow the instructions in the CoVES
• Prepare input data in the coves_data folder
• Run run_all_coves from SSMuLA.run_coves to get all scores
• Append scores with append_all_coves_scores from SSMuLA.run_coves

Triad

• Prep mutation file in .mut format such as A_1A+A_2A+A_3A+A_4A with TriadGenMutFile class in SSMuLA.triad_prepost
• Run

python -m tests.test_triad_pre

refer to the test file and the script documentation for further details

• With triad-2.1.3 local command line
• Prepare structure with 2prep_structures.sh
• Run 3getfixed.sh
• Parse results with ParseTriadResults class in SSMuLA.triad_prepost

Combine all zs

• Run

python -m tests.test_zs

refer to the test file and the script documentation for further details

Simulations

DE

• Run de_simulations and visualise with plot_de_simulations
• Run

python -m tests.test_de

and

python -m tests.test_de_vis

refer to the test file and the script documentation for further details

MLDE and ftMLDE

• Use MLDE_lite environment
• For using learned ESM embeddings, first run gen_all_learned_emb from SSMuLA.gen_learned_emb, else skip this step
• Run

python -m tests.test_gen_learned_emb

• Run run_all_mlde_parallelized from SSMuLA.mlde_lite to run simulations
• Run

python -m tests.test_mlde

• Important options including:
  • n_mut_cutoffs: list of integers for Hamming distance cutoff options where [0] means none and [2] for Hamming distance of two for ensemble
  • zs_predictors: list of strings for zero-shot predictors, i.e. ["none", "Triad", "ev", "esm"] where none means not focused training and thus default MLDE runs; the list can be extended for non-Hamming distance ensemble, including ["Triad-esmif", "Triad-ev", "Triad-esm", "two-best"]
  • ft_lib_fracs: list of floats for fraction of libraries to use for focused training, i.e. [0.5, 0.25, 0.125]
  • encoding: list of strings for encoding options, i.e. ["one-hot"] + DEFAULT_LEARNED_EMB_COMBO
  • model_classes: list of strings for model classes, i.e. ["boosting", "ridge"]
  • n_samples: list of integers for number of training samples to use, i.e. [96, 384]
  • n_split: integer for number of splits for cross-validation, i.e. 5
  • n_replicate: integer for number of replicates for each model, i.e. 50
  • n_tops: integer for number of variants to test the prediction, i.e. [96, 384] refer to the test file and the script documentation for further details
• Run MLDESum from SSMuLA.mlde_analysis to get the summary dataframe and optional visualization

python -m tests.test_mlde_vis

ALDE and ftALDE

• See details in alde4ssmula repository
• aggregate_alde_df from SSMuLA.alde_analysis to get the summary dataframe

python -m tests.test_alde

Fine-tuning

• Run train_predict_per_protein from SSMuLA.plm_finetune for ESM-2 LoRA fine-tuning simulations

Analysis and paper figures

• All notebooks in fig_notebooks are used to reproduce figures in the paper with files downloaded from Zenodo

Contact

• Francesca-Zhoufan Li