Package: evodiff
EvoDiffDescriptionIn this work, we introduce a general-purpose diffusion framework, EvoDiff, that combines evolutionary-scale data with
the distinct conditioning capabilities of diffusion models for controllable protein generation in sequence space.
EvoDiff generates high-fidelity, diverse, and structurally-plausible proteins that cover natural sequence and functional
space. Critically, EvoDiff can generate proteins inaccessible to structure-based models, such as those with disordered
regions, while maintaining the ability to design scaffolds for functional structural motifs, demonstrating the
universality of our sequence-based formulation. We envision that EvoDiff will expand capabilities in protein engineering
beyond the structure-function paradigm toward programmable, sequence-first design.We evaluate our sequence and MSA models – EvoDiff-Seq and EvoDiff-MSA, respectively – across a range of generation tasks
to demonstrate their power for controllable protein design. Below, we provide documentation for running our models.EvoDiff is described in thispreprint; if you use the code from this repository or the results, please cite the preprint.Table of contentsEvodiffTable of contentsInstallationDatasetsLoading pretrained modelsAvailable modelsUnconditional generationUnconditional sequence generationUnconditional MSA generationConditional sequence generationEvolution-guided protein generation with EvoDiff-MSAGenerating intrinsically disordered regionsScaffolding functional motifsAnalysisDownloading generated sequencesInstallationTo download our code, we recommend creating a clean conda environment with pythonv3.8.5.conda create --name evodiff python=3.8.5In that new environment, install EvoDiff:pip install evodiff
pip install git+https://github.com/microsoft/evodiff.git # bleeding edge, current repo main branchYou will also need to install PyTorch (we tested our models onv2.0.1), PyTorch Geometric, and PyTorch Scatter.We provide a notebook with installation guidance that can be found inexamples/evodiff.ipynb. It also includes examples on how to generate a smaller number of sequences and MSAs using our models. We recommend following this notebook if you would like to use our models to generate proteins.Our downstream analysis scripts make use of a variety of tools we do not include in our package installation. To run the
scripts, please download the following packages in addition to EvoDiff:TM scoreOmegafoldProteinMPNNESM-IF1; see thisJupyter notebookfor setup details.PGPDR-BERTWe refer to the setup instructions outlined by the authors of those tools.DatasetsWe obtain sequences from theUniref50 dataset, which contains
approximately 42 million protein sequences.
The Multiple Sequence Alignments (MSAs) are from theOpenFold dataset,
which contains 401,381 MSAs for 140,000 unique Protein Data Bank (PDB) chains and 16,000,000 UniClust30 clusters.
The intrinsically disordered regions (IDR) data was obtained from theReverse Homology GitHub.For the scaffolding structural motifs task, we use the baselines compiled in RFDiffusion. We provide pdb and fasta files used for conditionally generating sequences in theexamples/scaffolding-pdbsfolder. We also provide
We provide pdb files used for conditionally generating MSAs in theexamples/scaffolding-msasfolder.To access the UniRef50 test sequences, use the following code:test_data = UniRefDataset('data/uniref50/', 'rtest', structure=False) # To access the test sequencesThe filenames for train and validation Openfold splits are saved indata/valid_msas.csvanddata/train_msas.csvLoading pretrained modelsTo load a model:from evodiff.pretrained import OA_DM_38M

model, collater, tokenizer, scheme = OA_DM_38M()Available evodiff models are:D3PM_BLOSUM_640M()D3PM_BLOSUM_38M()D3PM_UNIFORM_640M()D3PM_UNIFORM_38M()OA_DM_640M()OA_DM_38M()MSA_D3PM_BLOSUM_RANDSUB()MSA_D3PM_BLOSUM_MAXSUB()MSA_D3PM_UNIFORM_RANDSUB()MSA_D3PM_UNIFORM_MAXSUB()MSA_OA_DM_RANDSUB()MSA_OA_DM_MAXSUB()It is also possible to load our LRAR baseline models:LR_AR_640M()LR_AR_38M()Note: if you want to download aBLOSUMmodel, you will first need to downloaddata/blosum62-special-MSA.mat.Available modelsWe investigated two types of forward processes for diffusion over discrete data modalitiesto determine which would be most effective.
In order-agnostic autoregressive diffusionOADM, one amino acid is converted to a special mask token at each step in the forward process.
After $T=L$ steps, where $L$ is the length of the sequence, the entire sequence is masked.
We additionally designed discrete denoising diffusion probabilistic modelsD3PMfor protein sequences.
In EvoDiff-D3PM, the forward process corrupts sequences by sampling mutations according to a transition matrix, such that after $T$ steps the sequence is indistinguishable from a uniform sample over the amino acids.
In the reverse process for both, a neural network model is trained to undo the previous corruption.
The trained model can then generate new sequences starting from sequences of masked tokens or of uniformly-sampled amino acids for EvoDiff-OADM or EvoDiff-D3PM, respectively.
We trained all EvoDiff sequence models on 42M sequences from UniRef50 using a dilated convolutional neural network architecture introduced in theCARPprotein masked language model.
We trained 38M-parameter and 640M-parameter versions for each forward corruption scheme and for left-to-right autoregressive (LRAR) decoding.To explicitly leverage evolutionary information, we designed and trained EvoDiff MSA models using theMSA Transformerarchitecture on theOpenFolddataset}.
To do so, we subsampled MSAs to a length of 512 residues per sequence and a depth of 64 sequences, either by randomly sampling the sequences ("Random") or by greedily maximizing for sequence diversity ("Max"). Within each subsampling strategy, we then trained EvoDiff MSA models with the OADM and D3PM corruption schemes.Unconditional sequence generationUnconditional generation with EvoDiff-SeqEvoDiff can generate new sequences starting from sequences of masked tokens or of uniformly-sampled amino acids. All available models
can be used to unconditionally generate new sequences, without needing to download the training datasets.To unconditionally generate 100 sequences from EvoDiff-Seq, run the following script:python evodiff/generate.py --model-type oa_dm_38M --num-seqs 100The default model type isoa_dm_640M, other evodiff models available are:oa_dm_38Md3pm_blosum_38Md3pm_blosum_640Md3pm_uniform_38Md3pm_uniform_640MOur LRAR baseline models are also available:lr_ar_38Mlr_ar_640MAn example of unconditionally generating a sequence of a specified length can be found inthis notebook.To evaluate the generated sequences, we implement our self-consistency Omegafold ESM-IF pipeline, as shown inanalysis/self_consistency_analysis.py.
To use this evaluation script, you must have the dependencies listed under theInstallationsection installed.Unconditional generation with EvoDiff-MSATo explicitly leverage evolutionary information, we design and train EvoDiff-MSA models using the MSA Transformer architecture
on the OpenFold dataset. To do so, we subsample MSAs to a length of 512 residues per sequence and a depth of 64 sequences,
either by randomly sampling the sequences (“Random”) or by greedily maximizing for sequence diversity (“Max”).It is possible to unconditionally generate an entire MSA, using the following script:python evodiff/generate-msa.py --model-type msa_oa_dm_maxsub --batch-size 1 --n-sequences 64 --n-sequences 256 --subsampling MaxHammingThe default model type ismsa_oa_dm_maxsub, which is EvoDiff-MSA-OADM trained on Max subsampled sequences, and the other available
evodiff models are:EvoDiff-MSA OADM trained on random subsampled sequences:msa_oa_dm_randsubEvoDiff-MSA D3PM-BLOSUM trained on Max subsampled sequences:msa_d3pm_blosum_maxsubEvoDiff-MSA D3PM-BLOSUM trained on random subsampled sequences:msa_d3pm_blosum_randsubEvoDiff-MSA D3PM-Uniform trained on Max subsampled sequences:msa_d3pm_uniform_maxsubEvoDiff-MSA D3PM-Uniform trained on random subsampled sequences:msa_d3pm_uniform_randsubYou can also specify a desired number of sequences per MSA, sequence length, batch size, and more.Conditional sequence generationEvoDiff’s OADM diffusion framework induces a natural method for conditional sequence generation by fixing some subsequences and
predicting the remainder. Because the model is trained to generate proteins with an arbitrary decoding order, this is easily
accomplished by simply masking and decoding the desired portions. We apply EvoDiff’s power for controllable protein design
across three scenarios: conditioning on evolutionary information encoded in MSAs, inpainting functional domains, and scaffolding
structural motifs.Evolution-guided protein generation with EvoDiff-MSAFirst, we test the ability of EvoDiff-MSA (msa_oa_dm_maxsub) to generate new query sequences conditioned on the remainder of an MSA,
thus generating new members of a protein family without needing to train family-specific generative models.To generate a new query sequence, given an alignment, use the following with the--start-msaflag. This starts conditional
generation by sampling from a validation MSA. To run this script you must have the Openfold dataset and splits downloaded.python evodiff/generate-msa.py --model-type msa_oa_dm_maxsub --batch-size 1 --n-sequences 64 --n-sequences 256 --subsampling MaxHamming --start-msaIf you want to generate on a custom MSA, it is possible to retrofit existing code.Additionally, the code is capable of generating an alignment given a query sequence, use the following--start-queryflag.
This starts with the query and generates the alignment.python evodiff/generate-msa.py --model-type msa_oa_dm_maxsub --batch-size 1 --n-sequences 64 --n-sequences 256 --subsampling MaxHamming --start-queryNOTE: you can only specify one of the above flags at a time. You cannot specify both (--start-query&--start-msa) together.
Please look atgenerate.pyfor more information.Generating intrinsically disordered regionsBecause EvoDiff generates directly in sequence space, we hypothesized that it could natively generate intrinsically disordered regions
(IDRs). IDRs are regions within a protein sequence that lack secondary or tertiary structure, and they carry out important and diverse
functional roles in the cell directly facilitated by their lack of structure. Despite their prevalence and critical roles in function
and disease, IDRs do not fit neatly in the structure-function paradigm and remain outside the capabilities of structure-based protein
design methods.We used inpainting with EvoDiff-Seq and EvoDiff-MSA to intentionally generate disordered regions conditioned on their surrounding
structured regions, and then used DR-BERT to predict disorder scores for each residue in the generated and natural sequences. Note: to
generate with our scripts here, you must have the IDR dataset downloaded. Different pre-processing steps may apply to other datasets.To run our code and generate IDRs from EvoDiff-Seq, run the following:python generate/conditional_generation_msa.py --model-type msa_oa_ar_maxsub --cond-task idr --num-seqs 1or equivalently, from EvoDiff-MSA:python generate/conditional_generation_msa.py --model-type msa_oa_ar_maxsub --cond-task idr --query-only --max-seq-len 150 --num-seqs 1Which will sample IDRs from the IDR dataset, and generate new ones.Scaffolding functional motifsGiven that the fixed functional motif includes the residue identities for the motif, we show that a sequence-only model
can be used for a motif scaffolding task. We used EvoDiff to generate scaffolds for a set of 17 motif-scaffolding problems
by fixing the functional motif, supplying only the motif's amino-acid sequence as conditioning information, and then decoding
the remainder of the sequence.For the scaffolding structural motifs task, we provide pdb and fasta files used for conditionally generating sequences in theexamples/scaffolding-pdbsfolder. We also provide
We provide a3m files used for conditionally generating MSAs in theexamples/scaffolding-msasfolder. Please view the PDB codes available and select an appropriate code. In this example, we use PDB code 1prw with domains 16-35 (FSLFDKDGDGTITTKELGTV) and 52-71 (INEVDADGNGTIDFPEFLTM).
An example of generating 1 MSA scaffold of a structural motif can be found inthis notebook.To generate from EvoDiff-Seq:python generate/conditional_generation.py --model-type oa_dm_640M --cond-task scaffold --pdb 1prw --start-idxs 15 --end-idxs 34 --start-idxs 51 --end-idxs 70 --num-seqs 100 --scaffold-min 50 --scaffold-max 100The--start-idxsand--end-idxsindicate the start & end indices for the motif being scaffolded. If defining multiple motifs, you can supply the start and end index motifs as new arguments, such as in the example we provide above.Equivalent code for generating a new scaffold sequence from an EvoDiff-MSA:python generate/conditional_generation_msa.py --model-type msa_oa_dm_maxsub --cond-task scaffold --pdb 1prw --start-idxs 15 --end-idxs 34 --start-idxs 51 --end-idxs 70 --num-seqs 1 --query-onlyTo generate a custom scaffold for a given motif, one simply needs to supply the PDB ID, and the residue indices of the motif. The code will download the PDB for you.
In some cases PDB files downloaded from rcsb will be incomplete, or contain additional residues. We have implemented code to circumvent PDB-reading issues, but we recommend care when
generating files for this task.Analysis of generationsTo analyze the quality of the generations, we look at:amino acid KL divergence (aa_reconstruction_parity_plot)secondary structure KL divergence (evodiff/analysis/calc_kl_ss.py)model perplexity for sequences (evodiff/analysis/sequence_perp.py)model perplexity for MSAs (evodiff/analysis/msa_perp.py)Fréchet inception distance (evodiff/analysis/calc_fid.py)Hamming distance (evodiff/analysis/calc_nearestseq_hamming.py)RMSD score (analysis/rmsd_analysis.py)We also compute the self-consistency perplexity to evaluate the foldability of generated sequences. To do so, we make use of various tools:TM scoreOmegafoldProteinMPNNESM-IF1; see thisJupyter notebookfor setup details.PGPDR-BERTWe refer to the setup instructions outlined by the authors of those tools.Our analysis scripts for iterating over these tools are in theevodiff/analysis/downstream_bash_scriptsfolder. Once we run the scripts in this folder, we analyze the results inself_consistency_analysis.py.Downloading generated sequencesWe provide all generated sequences on theEvoDiff Zenodo.To download our unconditional generated sequences fromunconditional_generations.csvfile:curl -O https://zenodo.org/record/8332830/files/unconditional_generations.csv?download=1To extract all unconditionally generated sequences created using the EvoDiff-seqoa_dm_640Mmodel, run the following code:import pandas as pd
df = pd.read_csv('unconditional_generations.csv', index_col = 0)
subset = df.loc[df['model'] == 'evodiff_oa_dm_640M']The CSV files containing generated data are organized as follows:Unconditional generations from sequence based models:unconditional_generations.csvsequence: generated sequencemin hamming dist: minimum Hamming distance between generated sequence and all training sequencesseq len: length of generated sequencemodel: model type used for generations, models:evodiff_oa_dm_38M,evodiff_oa_dm_640M,evodiff_d3pm_uniform_38M,evodiff_d3pm_uniform_640M,evodiff_d3pm_blosum_38M,evodiff_d3pm_blosum_640M,carp_38M,carp_640M,lr_ar_38Mlr_ar_38M,lr_ar_640M,esm_1b, oresm_2Sequence predictions for unconditional structure generation baselines:esmif_predictions_unconditional_structure_generations.csvsequence: predicted protein sequence from protein structure (using ESM-IF1 model)seq len: length of generated sequencemodel: 'foldingdiff' or 'rfdiffusion'Sequence generation via evolutionary alignments:msa_evolution_conditional_generations.csvsequence: generated query sequencesseq len: length of generated sequencemodel: model type used for generations:evodiff_msa_oa_dm_maxsub,evodiff_msa_oa_dm_randsub,esm_msa_1b, orpottsGenerated IDRs:idr_conditional_generations.csvsequence: subsampled sequence that contains IDRseq len: length of generated sequencegen_idrs: the generated IDR sequenceoriginal_idrs: the original IDR sequencestart_idxs: indices corresponding to start of IDR in sequenceend_idxs: indices corresponding to end of IDR in sequence (inclusive)model: model type used for generationsevodiff_seq_oa_dm_640Morevodiff_msa_oa_dm_maxsubSuccessfully generated scaffoldsmsa_scaffold.csv(EvoDiff-MSA generations) orseq_scaffold.csv(Evodiff-Seq generations)pdb: pdb code corresponding to scaffold taskseqs: generated scaffold and motifstart_idxs: indices corresponding to start of motifend_idxs: indices corresponding to end of motifseq len: length of generated sequencescores: average predicted local distance difference test (pLDDT) of sequencermsd: motifRMSD between predicted motif coordinates and crystal motif coordinatesmodel: model type used for generationsContributingThis project welcomes contributions and suggestions.  Most contributions require you to agree to a
Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us
the rights to use your contribution. For details, visithttps://cla.opensource.microsoft.com.When you submit a pull request, a CLA bot will automatically determine whether you need to provide
a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions
provided by the bot. You will only need to do this once across all repos using our CLA.This project has adopted theMicrosoft Open Source Code of Conduct.
For more information see theCode of Conduct FAQor
contactopencode@microsoft.comwith any additional questions or comments.TrademarksThis project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft
trademarks or logos are subject to and must followMicrosoft's Trademark & Brand Guidelines.
Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship.
Any use of third party trademarks or logos is subject to those third-party's policies.