diff --git a/models/rfd3/README.md b/models/rfd3/README.md index 778d2c82..d5d02c7a 100644 --- a/models/rfd3/README.md +++ b/models/rfd3/README.md @@ -170,7 +170,7 @@ further optimization! In `models/rfd3/configs/datasets/design_base.yaml` there's the shared configs for all datasets under `global_transform_args`. The dials that control the conditioning described above go under `training_conditions`, where for example `tipatom` - a specific preset conditioning sampler which more frequently fixes few tokens with few atoms - and others can be found. -**Training with WandB:** We strongly recommend tracking your runs via wandb. To use it, simply have your WANDB_API_KEY set and use the wandb logger. For more details see [here](wandb.ai) +**Training with WandB:** We strongly recommend tracking your runs via wandb. To use it, simply have your WANDB_API_KEY set and use the wandb logger. For more details see [here](https://wandb.ai/site/) # Appendix diff --git a/models/rfd3/docs/.assets/enzyme_tutorial/RASA_ligand.png b/models/rfd3/docs/.assets/enzyme_tutorial/RASA_ligand.png new file mode 100644 index 00000000..cbf1c93e Binary files /dev/null and b/models/rfd3/docs/.assets/enzyme_tutorial/RASA_ligand.png differ diff --git a/models/rfd3/docs/.assets/enzyme_tutorial/RASA_output.png b/models/rfd3/docs/.assets/enzyme_tutorial/RASA_output.png new file mode 100644 index 00000000..aeab0769 Binary files /dev/null and b/models/rfd3/docs/.assets/enzyme_tutorial/RASA_output.png differ diff --git a/models/rfd3/docs/.assets/enzyme_tutorial/enzyme_ori_token.png b/models/rfd3/docs/.assets/enzyme_tutorial/enzyme_ori_token.png new file mode 100644 index 00000000..4ca65914 Binary files /dev/null and b/models/rfd3/docs/.assets/enzyme_tutorial/enzyme_ori_token.png differ diff --git a/models/rfd3/docs/.assets/enzyme_tutorial/example_output.png b/models/rfd3/docs/.assets/enzyme_tutorial/example_output.png new file mode 100644 index 00000000..091219b3 Binary files /dev/null and b/models/rfd3/docs/.assets/enzyme_tutorial/example_output.png differ diff --git a/models/rfd3/docs/.assets/enzyme_tutorial/example_output_fixed_ori.png b/models/rfd3/docs/.assets/enzyme_tutorial/example_output_fixed_ori.png new file mode 100644 index 00000000..bd711ddf Binary files /dev/null and b/models/rfd3/docs/.assets/enzyme_tutorial/example_output_fixed_ori.png differ diff --git a/models/rfd3/docs/.assets/enzyme_tutorial/input_structure.png b/models/rfd3/docs/.assets/enzyme_tutorial/input_structure.png new file mode 100644 index 00000000..91e36ce3 Binary files /dev/null and b/models/rfd3/docs/.assets/enzyme_tutorial/input_structure.png differ diff --git a/models/rfd3/docs/.assets/enzyme_tutorial/select_fixed_atoms.png b/models/rfd3/docs/.assets/enzyme_tutorial/select_fixed_atoms.png new file mode 100644 index 00000000..6c87a9d7 Binary files /dev/null and b/models/rfd3/docs/.assets/enzyme_tutorial/select_fixed_atoms.png differ diff --git a/models/rfd3/docs/enzyme_design_tutorial.md b/models/rfd3/docs/enzyme_design_tutorial.md new file mode 100644 index 00000000..3d6dea6d --- /dev/null +++ b/models/rfd3/docs/enzyme_design_tutorial.md @@ -0,0 +1,177 @@ +# Enzyme Design in RFdiffusion3 + +## Before We Get Started... +This tutorial does not cover installing RFD3. If you need to install this model, see the [README](https://github.com/RosettaCommons/foundry/tree/production/models/rfd3) for installation instructions. You will need to remember the path to the directory where you stored your checkpoint files, if you did not store them in the default location. + +```{note} +You will need to clone the repository to access the tutorial files. Using the `pip` commands to install the model does not automatically download the files in the repository to your system. +``` + +Make sure you have activated any environment(s) you used to install RFD3. + +RFD3 runs best on GPUs. It is suggested to follow this tutorial on an interactive GPU node if you have access to one. + +You will need the file `1euv_lig.pdb`. This is provided in [`foundry/models/rfd3/docs/enzyme_tutorial_files/`](enzyme_tutorial_files/1euv_lig.pdb). You can clone the [`foundry`](https://github.com/RosettaCommons/foundry) repository to easily access files related to this tutorial. + + + +(enzyme-learning-objectives)= +## Learning Objectives +In this tutorial, we will use RFdiffusion3 to design cysteine hydrolases, similar to what is described in [*De novo* design of All-atom Biomolecular Interactions with RFdiffusion3](https://www.biorxiv.org/content/10.1101/2025.09.18.676967v2). This will allow us to explore the constraint options useful in enzyme design tasks. + +(enzyme-setup)= +## Setup +Create a directory named `rfd3_enzyme_tutorial` and `cd` into it: +```bash +mkdir rfd3_enzyme_tutorial && cd rfd3_enzyme_tutorial +``` +This is where you will be storing the files related to this tutorial. + +If you would like to compare your outputs against those generated by the authors of this tutorial, you can find pre-generated output files in `foundry/models/rfd3/docs/enzyme_tutorial_files/outputs.zip`. + +There is also a pre-made JSON file available in `foundry/models/rfd3/docs/enzyme_tutorial_files`. We recommend following the tutorial to create this file yourself to better understand the RFD3 options that are relevant to enzyme design. + +(enzyme-creating-the-json-file)= +## Creating the JSON file +In the next few sections we will be briefly describing the settings we will be using for this example enzyme design project. If you would like more information about the options discussed here or information about the other options that are available, see the [input specification](input.md) documentation. + +1. Using your editor of choice, open a new file called `rfd3_enzyme_tutorial.json`. This is where we will be storing the options we will use to constrain our enzyme design. +1. This is a JSON file, so all of the options contained in it need to be encapsulated in curly braces ({}). Go ahead and add a pair of these to your file. +1. Like all designs you will create using RFD3, we need to start by giving our calculation a name. It should be short, but descriptive, so let's call it `cys_1euv_lig`. Add this name in quotes to your file and place a colon and another pair of curly brackets after this. Your file should now look like: + ```json + { + "cys_1euv_lig":{ + + } + } + ``` + All of the other settings discussed here will go inside the inner curly brackets. +1. Next we need to specify the structure file (PDB, CIF, etc.) that contains information about any input structures related to our calculation: + ```json + "input": "path/to/1euv_lig.pdb", + ``` +1. The identifier representing the ligand in our PDB file needs to be listed so that RFD3 knows to treat this molecule differently: + ```json + "ligand": "l:g", + ``` + ```{note} + The ligand used in this tutorial is not a real molecule. Placing a colon (:) in your ligand name ensures that it does not match a molecule in the [Chemical Component Database](https://www.wwpdb.org/data/ccd). If you are running a calculation that uses a real ligand, feel free to use its actual chemical identifier. + ``` +1. Add an option to `unindex` the residues in the input file. These residues were determined to be important for the enzymatic activity we are trying to create and design a protein around. However, we don't know where in our designed structure we want these enzymes to be, making this option incredibly useful for enzyme design: + ```json + "unindex": "A514,A531,A574,A579-581", + ``` + ```{important} + Choosing the residues to use in your enzyme design comes from knowledge of your system, literature searches, etc. The only guidance we will give on this topic is to try several combinations of the residues you think are important for your enzyme design. Too many and you might overconstrain your system, too few and you are less likely to obtain useful designs. + ``` +1. We will use the `length` option to tell RFD3 how long we want our designed proteins to be: + ```json + "length": "100-200", + ``` +1. To define where our protein should be centered, we will give RFD3 an 'ori token'. This specifies the *ori*gin (center of mass) of the designed portion of our output structure: + ```json + "ori_token": [0,1,0], + ``` + ```{figure} ./.assets/enzyme_tutorial/enzyme_ori_token.png + :width: 60% + + Image of the input structure with the ORI token in the center, visualized as a white sphere. + ``` + ```{important} + In this example the ori token is placed close to the center of our input structure. When designing your own enzyme scaffolds, this may not be the best placement depending on your design goals. See the [RFdiffusion2 paper](https://www.nature.com/articles/s41592-025-02975-x) for more information about how ORI tokens impact the results of diffusion calculations. + ``` +1. Even though we do not care where our residues end up in our final protein sequence, we want their geometries (or at least some of their atoms) to remain in the same place spatially so that their relationships to the ligand stay the same. For this we use `select_fixed_atoms`: + ```json + "select_fixed_atoms": { + "A514":"NE2,CE1,ND1,CD2,CG,CB", + "A531":"OD1,CG,OD2,CB", + "A574":"NE2,CD,OE1,CG", + "A579":"C,O,CA,N", + "A580":"SG,CB,CA,N,C,O", + "A581":"C,O,CA,N" + }, + ``` + For residue A514 (histidine), A531 (aspartic acid), and A574 (glutamine) the side chain is fixed, for residue 580 (cysteine) the entire residue is fixed, and for A579 (aspartic acid) and A581 (glycine) the backbones are fixed. The ligand is automatically held in place. + + ```{figure} ./.assets/enzyme_tutorial/select_fixed_atoms.png + :width: 60% + + Image of the starting structure where the fixed atoms have been highlighted in purple. + ``` +1. RFD3 allows for RASA conditioning to control how exposed or buried different portions of your input are relative to the designed protein. + ```json + "select_buried": { + "l:g": "O1,C8,O3,C4,C5,C23,C24,C25,C26,C27" + }, + "select_exposed": { + "l:g": "C2,C22,C19,C18,C17,C20,C16,C15,O21,O14,C13,C12" + }, + ``` + As the names of the options suggest, RFD3 will do its best to bury atoms that were passed to the `select_buried` option and expose the atoms passed to the `select_exposed` option. + + ```{figure} ./.assets/enzyme_tutorial/RASA_ligand.png + :width: 60% + + Image of the ligand where the exposed portion is colored blue and the buried portion is colored red. + ``` + + There is a third option for RASA conditioning which was not used here,`select_partially_buried`, that you might find useful for your protein design tasks. +1. Next we're also going to unfix the *sequence* for residues A579 and A581. For this design, we know where we want the backbones for the residues next to A580 (the cysteine), but their exact identity and index does not matter. This is where the option `select_unfixed_sequence` becomes useful. + ```json + "select_unfixed_sequence": "A579,A581", + ``` + ```{note} + These residues have fixed portions in the `select_fixed_atoms` setting, but the atoms chosen are **only the backbone atoms**. If you are using both of these settings in your designs it is important to not fix any of the side chain atoms to allow for the identity of the residue to actually change. + ``` +1. Save your file and close it. Your files should be similar to what is stored in `outputs.zip`. + +(enzyme-running-rfd3)= +## Running RFD3 +To actually run RFD3 you need to know: +- the directory you want the outputs to be stored in +- the path to the JSON (or YAML) file that stores the specific settings for the calculation +- the location of your checkpoint files + +Once you have these three things you can run something like this from the command line: +```bash +rfd3 design out_dir=enzyme_tutorial_outputs/0 inputs=rfd3_enzyme_tutorial.json ckpt_path=/path/to/your/checkpoint/files/rfd3_latest.ckpt +``` +Your output files will be placed in a new directory `enzyme_tutorial_outputs/0`. Your output files will be named `enzyme_tutorial_cys_1euv_lig_0_model_n.cif.gz` where `n` is the number of the design. `enzyme_tutorial` comes from the name of the JSON file and `cys_1euv_lig` comes from the name you gave your calculation in the JSON file. + +```{note} +You may see several warning messages when you run RFD3, these should not interfere with the calculation. +``` + +(enzyme-analyzing-the-outputs)= +## Analyzing the Outputs +You should end up with 8 designs, numbered 0-7, each with its own `.cif.gz` and `.json` file. If you want to adjust the number, add the configuration option `diffusion_batch_size` to your `rfd3 design` command. + +The JSON file has many details about your diffusion run, including the options in the YAML file you created. The compressed CIF file contains information about the final diffused structure that you can easily visualize with tools like PyMOL. + +Your results should look something like this: +```{figure} ./.assets/enzyme_tutorial/example_output_fixed_ori.png +:width: 60% + +Example output for the enzyme scaffold design. The input structure is in green and the output structure is light pink. The residues that had some of their atoms fixed are highlighted in purple. The ORI token is shown as a white sphere. +``` + +You'll notice: +- The fixed atoms have stayed in place, once the structures have been aligned to the ligand +- The index of the original residues has changed (easy to tell in this example because we have held their coordinates fixed, you can see the mapping in the output JSON file.) +- The structures are all the same length, which is between 100 and 200 residues long. (All designs in the same batch will have the same length. Set the batch size to 1 if you want to design proteins with all different lengths.) + +Changing the view slightly lets us see that our RASA conditioning was also followed: +```{figure} ./.assets/enzyme_tutorial/RASA_output.png +:width: 60% + +You can see that the portion of the ligand that was specified as exposed (blue) is much less buried in the designed protein than the portion of the ligand that was specified as buried (red). +``` + +## Conclusion +You have now set up an RFD3 calculation and successfully ran the inference code for an enzyme design problem. While the options discussed here are particularly useful in enzyme design projects, RFD3 has many more that you can explore by looking at (input.m). + +(enzyme-references)= +## References and Further Reading +- For more information on the different inference settings in RFD3, see [input.md](input.md) +- The calculation presented here was used to benchmark RFdiffusion2, for more information see [Atom-level enzyme active site scaffolding using RFdiffusion2](https://www.nature.com/articles/s41592-025-02975-x) +- A more thorough discussion of the settings and configuration options in RFD3 can be found [here](intro_inference_calculations.md) \ No newline at end of file diff --git a/models/rfd3/docs/enzyme_tutorial_files/1euv_lig.pdb b/models/rfd3/docs/enzyme_tutorial_files/1euv_lig.pdb new file mode 100644 index 00000000..0fa5742b --- /dev/null +++ b/models/rfd3/docs/enzyme_tutorial_files/1euv_lig.pdb @@ -0,0 +1,92 @@ +ATOM 2 N HIS A 514 3.231 1.208 -1.240 1.00 19.42 A N +ATOM 3 CA HIS A 514 1.911 1.858 -1.146 1.00 18.23 A C +ATOM 4 C HIS A 514 1.410 2.170 -2.547 1.00 16.65 A C +ATOM 5 O HIS A 514 2.223 2.219 -3.470 1.00 18.87 A O +ATOM 6 CB HIS A 514 2.084 3.200 -0.401 1.00 18.92 A C +ATOM 7 CG HIS A 514 0.793 3.885 -0.097 1.00 19.11 A C +ATOM 8 CD2 HIS A 514 0.480 5.175 -0.343 1.00 19.33 A C +ATOM 9 ND1 HIS A 514 -0.281 3.307 0.570 1.00 19.64 A N +ATOM 10 CE1 HIS A 514 -1.232 4.247 0.679 1.00 20.67 A C +ATOM 11 NE2 HIS A 514 -0.784 5.363 0.136 1.00 18.73 A N +ATOM 12 N ASP A 531 -4.991 9.875 -2.283 1.00 18.01 A N +ATOM 13 CA ASP A 531 -4.198 8.868 -1.542 1.00 17.65 A C +ATOM 14 C ASP A 531 -5.028 8.515 -0.313 1.00 17.93 A C +ATOM 15 O ASP A 531 -5.344 9.384 0.513 1.00 19.21 A O +ATOM 16 CB ASP A 531 -2.843 9.512 -1.268 1.00 18.96 A C +ATOM 17 CG ASP A 531 -1.823 8.638 -0.562 1.00 19.66 A C +ATOM 18 OD1 ASP A 531 -2.229 7.763 0.218 1.00 20.25 A O +ATOM 19 OD2 ASP A 531 -0.605 8.900 -0.780 1.00 19.95 A O1- +ATOM 20 N GLN A 574 -7.907 4.613 4.461 1.00 20.37 A N +ATOM 21 CA GLN A 574 -7.953 3.179 4.855 1.00 21.00 A C +ATOM 22 C GLN A 574 -7.671 3.054 6.344 1.00 21.03 A C +ATOM 23 O GLN A 574 -6.759 3.718 6.872 1.00 20.78 A O +ATOM 24 CB GLN A 574 -6.902 2.474 3.981 1.00 21.23 A C +ATOM 25 CG GLN A 574 -5.460 2.863 4.335 1.00 22.92 A C +ATOM 26 CD GLN A 574 -4.523 2.355 3.261 1.00 23.64 A C +ATOM 27 NE2 GLN A 574 -3.727 1.344 3.595 1.00 24.35 A N +ATOM 28 OE1 GLN A 574 -4.554 2.817 2.125 1.00 23.51 A O +ATOM 29 N ASP A 579 -4.972 -2.251 2.419 1.00 16.24 A N +ATOM 30 CA ASP A 579 -6.009 -1.965 1.401 1.00 15.40 A C +ATOM 31 C ASP A 579 -5.673 -0.876 0.414 1.00 15.59 A C +ATOM 32 O ASP A 579 -6.577 -0.537 -0.384 1.00 16.28 A O +ATOM 33 CB ASP A 579 -7.339 -1.639 2.096 1.00 16.76 A C +ATOM 34 CG ASP A 579 -8.180 -2.869 2.367 1.00 18.53 A C +ATOM 35 OD1 ASP A 579 -8.022 -3.926 1.704 1.00 18.83 A O +ATOM 36 OD2 ASP A 579 -9.038 -2.793 3.279 1.00 20.44 A O1- +ATOM 37 N CYS A 580 -4.482 -0.303 0.456 1.00 14.58 A N +ATOM 38 CA CYS A 580 -4.229 0.856 -0.451 1.00 14.75 A C +ATOM 39 C CYS A 580 -4.592 0.525 -1.890 1.00 15.30 A C +ATOM 40 O CYS A 580 -5.133 1.439 -2.570 1.00 15.92 A O +ATOM 41 CB CYS A 580 -2.811 1.409 -0.381 1.00 16.92 A C +ATOM 42 SG CYS A 580 -1.587 0.078 -0.708 1.00 15.01 A S +ATOM 43 N GLY A 581 -4.214 -0.616 -2.427 1.00 15.26 A N +ATOM 44 CA GLY A 581 -4.496 -0.901 -3.873 1.00 15.15 A C +ATOM 45 C GLY A 581 -6.031 -0.979 -4.060 1.00 12.80 A C +ATOM 46 O GLY A 581 -6.496 -0.558 -5.161 1.00 16.14 A O +TER +HETATM 47 C2 l:g B 1 0.721 0.361 2.697 1.00 0.00 B C +HETATM 48 O3 l:g B 1 -2.014 -0.494 1.873 1.00 0.00 B O +HETATM 49 C4 l:g B 1 -0.420 -1.974 0.850 1.00 0.00 B C +HETATM 50 C5 l:g B 1 0.633 -2.135 -0.222 1.00 0.00 B C +HETATM 51 C8 l:g B 1 -0.950 -0.521 0.955 1.00 0.00 B C +HETATM 52 C12 l:g B 1 1.587 -0.654 3.148 1.00 0.00 B C +HETATM 53 C13 l:g B 1 2.184 -0.571 4.411 1.00 0.00 B C +HETATM 54 O14 l:g B 1 2.997 -1.544 4.811 1.00 0.00 B O +HETATM 55 C15 l:g B 1 3.599 -1.534 5.994 1.00 0.00 B C +HETATM 56 C16 l:g B 1 3.396 -0.477 6.884 1.00 0.00 B C +HETATM 57 C17 l:g B 1 2.549 0.578 6.518 1.00 0.00 B C +HETATM 58 C18 l:g B 1 1.924 0.537 5.251 1.00 0.00 B C +HETATM 59 C19 l:g B 1 1.061 1.550 4.794 1.00 0.00 B C +HETATM 60 C20 l:g B 1 2.333 1.717 7.480 1.00 0.00 B C +HETATM 61 O21 l:g B 1 4.358 -2.487 6.314 1.00 0.00 B O +HETATM 62 C22 l:g B 1 0.472 1.457 3.531 1.00 0.00 B C +HETATM 63 C23 l:g B 1 0.259 -2.375 -1.555 1.00 0.00 B C +HETATM 64 C24 l:g B 1 1.235 -2.502 -2.549 1.00 0.00 B C +HETATM 65 C25 l:g B 1 2.589 -2.391 -2.220 1.00 0.00 B C +HETATM 66 C26 l:g B 1 2.969 -2.152 -0.897 1.00 0.00 B C +HETATM 67 C27 l:g B 1 1.997 -2.024 0.100 1.00 0.00 B C +HETATM 68 O1 l:g B 1 0.085 0.352 1.440 1.00 0.00 B O +CONECT 42 51 +CONECT 47 52 62 68 +CONECT 48 51 +CONECT 49 50 51 +CONECT 50 49 63 67 +CONECT 51 42 48 49 68 +CONECT 52 47 53 +CONECT 53 52 54 58 +CONECT 54 53 55 +CONECT 55 54 56 61 +CONECT 56 55 57 +CONECT 57 56 58 60 +CONECT 58 53 57 59 +CONECT 59 58 62 +CONECT 60 57 +CONECT 61 55 +CONECT 62 47 59 +CONECT 63 50 64 +CONECT 64 63 65 +CONECT 65 64 66 +CONECT 66 65 67 +CONECT 67 50 66 +CONECT 68 47 51 +END diff --git a/models/rfd3/docs/enzyme_tutorial_files/outputs.zip b/models/rfd3/docs/enzyme_tutorial_files/outputs.zip new file mode 100644 index 00000000..1c4aa949 Binary files /dev/null and b/models/rfd3/docs/enzyme_tutorial_files/outputs.zip differ diff --git a/models/rfd3/docs/enzyme_tutorial_files/rfd3_enzyme_tutorial.json b/models/rfd3/docs/enzyme_tutorial_files/rfd3_enzyme_tutorial.json new file mode 100644 index 00000000..e567c5dc --- /dev/null +++ b/models/rfd3/docs/enzyme_tutorial_files/rfd3_enzyme_tutorial.json @@ -0,0 +1,24 @@ +{ + "1euv": { + "input": "./1euv_lig.pdb", + "ligand": "l:g", + "unindex": "A514,A531,A574,A579-581", + "length": "100-200", + "ori_token": [0, 1, 0], + "select_fixed_atoms": { + "A514":"NE2,CE1,ND1,CD2,CG,CB", + "A531":"OD1,CG,OD2,CB", + "A574":"NE2,CD,OE1,CG", + "A579":"C,O,CA,N", + "A580":"SG,CB,CA,N,C,O", + "A581":"C,O,CA,N" + }, + "select_buried": { + "l:g": "O1,C8,O3,C4,C5,C23,C24,C25,C26,C27" + }, + "select_exposed": { + "l:g": "C2,C22,C19,C18,C17,C20,C16,C15,O21,O14,C13,C12" + }, + "select_unfixed_sequence": "A579,A581" + } +} diff --git a/models/rfd3/docs/index.rst b/models/rfd3/docs/index.rst index e07c1c54..05fdc2bc 100644 --- a/models/rfd3/docs/index.rst +++ b/models/rfd3/docs/index.rst @@ -20,6 +20,7 @@ Tutorials :maxdepth: 1 ppi_design_tutorial.md + enzyme_design_tutorial.md Examples -------- diff --git a/models/rfd3/docs/na_binder_tutorial.md b/models/rfd3/docs/na_binder_tutorial.md new file mode 100644 index 00000000..ea0c1d13 --- /dev/null +++ b/models/rfd3/docs/na_binder_tutorial.md @@ -0,0 +1,151 @@ +# Nuclei Acid Binder Design in RFdiffusion3 + +## Before We Get Started... +This tutorial does not cover installing RFD3. Before continuing, you should make sure that RFdiffusion3 (RFD3) is installed and runnable on your system. + +See the [README](https://github.com/RosettaCommons/foundry/tree/production/models/rfd3) for installation instructions. You will need to remember the path to the directory where you stored your checkpoint files. + +```{note} +The instructions below assume that you have installed RFD3 via the pip commands. +You may need to slightly modify how you run the calculations based on your setup. +``` + +Make sure you have activated any environment(s) you used to install RFD3. + +RFD3 runs best on GPUs. It is suggested to follow this tutorial on an interactive GPU node if you have access to one. + +You will need the file `2r5z.pdb`. This is provided in [`foundry/models/rfd3/docs/input_pdbs`](./input_pdbs/2r5z.pdb). You can clone the [`foundry`](https://github.com/RosettaCommons/foundry) repository to easily access files related to this tutorial. + +Lastly, we will be visualizing the outputs of the calculations presented in the tutorial using [PyMOL](https://pymol.org/). The visualization steps are completely optional, but if you would like to follow along you will need to have PyMOL installed. + +(na-learning-objectives)= +## Learning Objectives +In this tutorial, we will design a DNA-protein complex to explore the settings available in RFD3 that are useful for nucleic acid binder design. +(na-setup)= +## Setup +Create a directory named `rfd3_na_tutorial` and `cd` into it: +```bash +mkdir rfd3_na_tutorial && cd rfd3_na_tutorial +``` +This is where you will be storing the files related to this tutorial. + +If you would like to compare your outputs against those generated by the authors of this tutorial, you can find pre-generated output files in `foundry/models/rfd3/docs/na_tutorial_files`. +The 'basic' zip file contains outputs that did not use the setting discussed in the [Hydrogen Bond Conditioning](#hydrogen-bond-conditioning) section. The 'hbond' zip file has the outputs resulting from using hydrogen bond conditioning. + +There is also a pre-made JSON file available in `foundry/models/rfd3/docs/na_tutorial_files`. We recommend following the tutorial to create this file yourself to better understand the RFD3 options that are relevant to nucleic acid binder design. + +(na-creating-the-yaml-file)= +## Creating the JSON file +In this tutorial, we will be briefly describing each of the settings we will be using for this example. + +1. Using your editor of choice, open a new file called `rfd3_na_tutorial.json`. This is where we will be storing the options we will use to constrain our enzyme design. +1. This is a JSON file, so all of the options contained in it need to be encapsulated in curly braces ({}). Go ahead and add a pair of these to your file. +1. Like all designs you will create using RFD3, we need to start by giving our calculation a name. It should be short, but descriptive, so let's call it `dsDNA_complex`. Add this name in quotes to your file and place a colon and another pair of curly brackets after this. Your file should now look like: + ```json + { + "dsDNA_complex":{ + + } + } + ``` +1. Next we need to specify the structure file (PDB, CIF, etc.) that contains information about any input structures related to our calculation: + ```json + "input": "path/to/2r5z.pdb", + ``` +1. To define the portions of our final structure that will be defined vs. taken from our input structure file, we will use the `contig` option: + ```json + "contig": "C5-18,/0,D24-37,/0,40-50,A146-154,80-90", + ``` + Let's break down what's going on here a bit further: + - `C5-18`: Our final design will start with residues C5-C18 from our input PDB + - `/0`: This indicates a chain break, the C5-18 residues will not be connected to anything coming next in our `contig` string. + - `D24-27`: After the chain break we have residues D24-37 from the input structure file. + - `/0,40-50`: After another chain break RFD3 will design a segment with 40-50 residues. + - `A146-154`: residues A146-154 from the input structure will be connected to the C-terminus of the designed residues + - `80-90`: RFD3 will design 80-90 residues connected to the C-terminus of A154 from the input structure +1. Since there are two portions of the designed structure with random lengths, it is useful to specify the overall `length` of our design: + ```json + "length": "147-167", + ``` + Our design can be at most 177 residues long. This specification will ensure that the lengths of each of our designed structures are short enough to have our final structure have a length of 167 residues, or shorter. +1. For the purposes of this design, we happen to know that residues B251-B255 are important to include in our design, but it does not matter where they end up in our final structure. This is referred to as an 'unindexed motif' in the documentation. To include them, we will add the `undindex` option: + + ```json + "unindex": "/0,/0,B251-B255", + ``` + Here we have two chain breaks before our unindexed motif to correspond to the contig string, these residues will go in the third chain of the output structure. +1. Next, just because we specified that we wanted portions of our input structure to be part of our output structure does not mean that the atoms belonging to these residues will stay in the same place. Here, we want portions of our DNA strands to be stationary (the middle sections) while the portions towards either end of the double helix can relax: + + ```json + "select_fixed_atoms": { + "C9-14":"ALL", + "D28-33":"ALL", + "C5-8,C15-18": "", + "D24-27,D34-37": "" + }, + ``` +1. To define where the center of mass of our designed structure should go, we will use an ORI (origin) token: + + ```json + "ori_token":[25,35,20], + ``` + ```{important} + In this example the ori token is placed close to the center of our input structure. When designing your own enzyme scaffolds, you should try many ORI token placements. See the [RFdiffusion2 paper](https://www.nature.com/articles/s41592-025-02975-x) for more information about how ORI tokens impact the results of diffusion calculations. + ``` +1. Last, but not least, we want our design to have minimal loops. We will use the `is_non_loopy` option for this. As of the creation of this tutorial, there are no other parameters to control the secondary structure of the designs from RFD3. +```json +"is_non_loopy": true +``` +1. Save your file and close it. If you run the file now, your files should be similar to what is stored in `basic.zip`. + +(hydrogen-bond-conditioning)= +### Hydrogen Bond Conditioning +The steps in this section are optional, skip to [Running RFD3](#na-running-rfd3). If you would like to include them, reopen your JSON file and append to what you added in the previous section. +```{important} +Using hydrogen bond conditioning with RFdiffusion3 requires having HBPLUS installed. See the [RFdiffusion3 README](https://github.com/RosettaCommons/foundry/tree/production/models/rfd3) for more information. + +``` +Hydrogen bond conditioning can be useful in the design of nucleic acid binders. Here we will apply it to some backbone and base atoms for a few of the DNA bases: +```json +"select_hbond_acceptor": {"C16":"N7,O6", "D31-32":"N7", "D28-30":"OP1,OP2,O3',O5'"}, +"select_hbond_donor": {"D31-32":"N6"} +``` + +(na-running-rfd3)= +## Running RFD3 +To actually run RFD3 you need to know: +- the directory you want the outputs to be stored in +- the path to the JSON (or YAML) file that stores the specific settings for the calculation +- the location of your checkpoint files + +Once you have these three things you can run something like this from the command line: +```bash +rfd3 design out_dir=na_tutorial_outputs/0 inputs=rfd3_na_tutorial.json ckpt_path=/path/to/your/checkpoint/files/rfd3_latest.ckpt +``` + +Your output files will be placed in a new directory `na_tutorial_outputs/0`. Your output files will be named `na_tutorial_dsDNA_complex_0_model_n.cif.gz` where `n` is the number of the design. `enzyme_tutorial` comes from the name of the JSON file and `cys_1euv_lig` comes from the name you gave your calculation in the JSON file. + +```{note} +You may see several warning messages when you run RFD3, these should not interfere with the calculation. +``` + +(na-analyzing-the-outputs)= +## Analyzing the Outputs +You should end up with 8 designs, numbered 0-7, each with its own `.cif.gz` and `.json` file. If you want to adjust the number, add the configuration option `diffusion_batch_size` to your `rfd3 design` command. + +The JSON file has many details about your diffusion run, including the options in the JSON file you created. The compressed CIF file contains information about the final diffused structure that you can easily visualize with tools like PyMOL. + +Your results should look something like this: + + +You should notice that the location of the designed portions of your output structure are centered around the location of the ORI token as expected. You can also align the 2R5Z structure with any of the outputs to see that the atoms selected in `select_fixed_atoms` have stayed in the same physical locations. + +Checking that our unindexed motif is present in our designs is a bit more difficult, but the information we need is provided in the JSON file that is created with each design. If you open one of these JSON files, the first piece of information you see is a `diffused_index_map` that connects the residues from the input to residues in the output design. You should see that residues B251-B255 have been mapped to residues in your output structure. + +If you added the additional hydrogen bonding constraints then you can visualize the hydrogen bonding interactions with PyMOL. In one of the structures, go to (A)ctions -> find -> polar contacts -> within selection to see the polar interactions within the structure. + +(na-references-and-further-reading)= +## References and Further Reading +- For more information on the different inference settings in RFD3, see [input.md](input.md) +- +- A more thorough discussion of the settings and configuration options in RFD3 can be found [here](intro_inference_calculations.md) \ No newline at end of file diff --git a/models/rfd3/docs/na_tutorial_files/rfd3_na_tutorial.json b/models/rfd3/docs/na_tutorial_files/rfd3_na_tutorial.json new file mode 100644 index 00000000..f2a88cf8 --- /dev/null +++ b/models/rfd3/docs/na_tutorial_files/rfd3_na_tutorial.json @@ -0,0 +1,18 @@ +{ + "dsDNA_complex": { + "input": "./input_pdbs/2r5z.pdb", + "contig": "C5-18,/0,D24-37,/0,40-50,A146-154,80-90", + "length": "147-167", + "unindex": "/0,/0,B251-B255", + "select_fixed_atoms": { + "C9-14":"ALL", + "D28-33":"ALL", + "C5-8,C15-18": "", + "D24-27,D34-37": "" + }, + "ori_token":[25,35,20], + "select_hbond_acceptor": {"C16":"N7,O6", "D31-32":"N7", "D28-30":"OP1,OP2,O3',O5'"}, + "select_hbond_donor": {"D31-32":"N6"}, + "is_non_loopy": true + } +} \ No newline at end of file diff --git a/models/rfd3/docs/ppi_design_tutorial.md b/models/rfd3/docs/ppi_design_tutorial.md index ead64e60..3165e545 100644 --- a/models/rfd3/docs/ppi_design_tutorial.md +++ b/models/rfd3/docs/ppi_design_tutorial.md @@ -1,7 +1,7 @@ # Protein-Protein Interface Design in RFdiffusion3 ## Before We Get Started... -This tutorial does not cover installing RFD3, before continuing you should make sure that RFdiffusion3 (RFD3) is installed and able to be run on your system. +This tutorial does not cover installing RFD3. Before continuing, you should make sure that RFdiffusion3 (RFD3) is installed and runnable on your system. See the [README](https://github.com/RosettaCommons/foundry/tree/production/models/rfd3) for installation instructions. You will need to remember the path to the directory where you stored your checkpoint files. @@ -10,19 +10,19 @@ The instructions below assume that you have installed RFD3 via the pip commands. You may need to slightly modify how you run the calculations based on your setup. ``` -Make sure you have activated any environments you used to install RFD3. +Make sure you have activated any environment(s) you used to install RFD3. -RFD3 runs best on GPUs. It is suggested to follow this tutorial on an interactive GPU node, if you have access to one. +RFD3 runs best on GPUs. It is suggested to follow this tutorial on an interactive GPU node if you have access to one. You will need the file `4zxb_cropped.pdb`. This is provided in [`foundry/models/rfd3/docs/input_pdbs`](input_pdbs/4zxb_cropped.pdb). You can clone the [`foundry`](https://github.com/RosettaCommons/foundry) repository to easily access files related to this tutorial. Lastly, we will be visualizing the outputs of the calculations presented in the tutorial using [PyMOL](https://pymol.org/). The visualization steps are completely optional, but if you would like to follow along you will need to have PyMOL installed. -(learning-objectives)= +(ppi-learning-objectives)= ## Learning Objectives In this tutorial, we will design a binder for the human insulin receptor to explore the settings available in RFD3 that are useful in protein-protein interface (PPI) design. -(setup)= +(ppi-setup)= ## Setup Create a directory named `rfd3_ppi_tutorial` and `cd` into it: ```bash @@ -30,16 +30,16 @@ mkdir rfd3_ppi_tutorial && cd rfd3_ppi_tutorial ``` This is where you will be storing the files related to this tutorial. -If you would like to compare your outputs against those generated by the authors of this tutorial, you can find pre-generated output files in `foundry/models/rfd3/docs/ppi_tutorial_files` +If you would like to compare your outputs against those generated by the authors of this tutorial, you can find pre-generated output files in `foundry/models/rfd3/docs/ppi_tutorial_files`. The 'basic' zip file contains outputs that did not use the setting discussed in [Other Useful Settings](#other-useful-settings) section. The 'fixed' zip file has the outputs resulting from using the `select_fixed_atoms` option. -There is also an already made YAML file available in `foundry/models/rfd3/docs/ppi_tutorial_files`. We recommend following the tutorial to create this file yourself to better understand the RFD3 options that are relevant to PPI design. +There is also a pre-made YAML file available in `foundry/models/rfd3/docs/ppi_tutorial_files`. We recommend following the tutorial to create this file yourself to better understand the RFD3 options that are relevant to PPI design. -(creating-the-yaml-file)= +(ppi-creating-the-yaml-file)= ## Creating the YAML file In this tutorial, we will be briefly describing each of the settings we will be using for this example binder design project. -1. Using your editor of choice, open a new file called `rfd3_ppi_tutorial.yaml`. This is where we will be storing all of the settings that tell RFD3 the type of designs we would like to make. +1. Using your editor of choice, open a new file called `ppi_tutorial.yaml`. This is where we will be storing all of the settings that tell RFD3 the type of designs we would like to make. 1. Our calculation needs a name. For this tutorial, we will only be including one example calculation, but your YAML file could have several. A name allows you (and RFD3) to differentiate them. Since we are designing binders for the human insulin receptor, let's just call it `insulinr`: ```yaml insulinr: @@ -47,13 +47,13 @@ In this tutorial, we will be briefly describing each of the settings we will be Everything that comes after this should be indented to show that it's part of this `insulinr` calculation. You will want to use spaces, not the tab character. If a tab character (`\t `) is found in the file, RFD3 will crash. 1. Tell RFD3 where to find your input file: ```yaml - input: /path/to/rfd3_ppi_tutorial/4zxb_cropped.pdb + input: /path/to/4zxb_cropped.pdb ``` This file was directly cropped from the 4zxb structure that can be found in the [RSCB PDB library](https://www.rcsb.org/). *If you visualize the cropped structure against the full one from the RSCB library, they may not appear to be exactly the same structure. However, if you align the two you will get an RMSD of 0.0.* 1. The `contig` string is the main way you can tell RFD3 what portions of your input structure you want defined and what portions you want preserved from your input structure. ```yaml @@ -62,7 +62,7 @@ In this tutorial, we will be briefly describing each of the settings we will be The different sections of the `contig` string are separated by commas. Here's what each section is telling RFD3: - `40-120` specifies that we want RFD3 to design a new peptide chain that is between 40 and 120 residues long - `/0` is how a chain break is specified in RFD3. - - `E6-155` is the portion of the input structure that we are keeping in our final output. The letter corresponds to the chain label in the input PDB and the starting and ending residue are included in the final structure. If you do not include the chain label, then RFD3 would just design a peptide chain between 6 and 155 residues in length. + - `E6-155` is the portion of the input structure that we are keeping in our final output. The letter corresponds to the chain label in the input PDB and the starting and ending residues are included in the final structure. If you do not include the chain label, then RFD3 would just design a peptide chain between 6 and 155 residues in length. 1. We can also specify the overall number of residues in our final structure: ```yaml length: 190-270 @@ -82,7 +82,7 @@ In this tutorial, we will be briefly describing each of the settings we will be The hotspot residues along with the specific target atoms circled in yellow. ``` -1. Next we need to add information about our ORI token, this token specifies where we want the center of mass of our designed protein to be. Unless you know where you want to place the ORI token for your specific design needs, it is often easiest to have RFD3 infer the ORI placement based on the chosen `hotspots`: +1. Next we need to add information about our ORI token. This token specifies where we want the center of mass of our designed protein to be. Unless you know where you want to place the ORI token for your specific design needs, it is often easiest to have RFD3 infer the ORI placement based on the chosen `hotspots`: ```yaml infer_ori_strategy: hotspots ``` @@ -91,10 +91,12 @@ In this tutorial, we will be briefly describing each of the settings we will be ```yaml is_non_loopy: true ``` -1. Save you file and close it. +1. Save your file and close it. If you run the file now, your files should be similar to what is stored in `basic.zip`. + +(ppi-other-useful-settings)= +### Other Useful Settings +This section provides other settings that are useful for protein-protein binder design tasks, but you may or may not need depending on your specific project. -(other-useful-settings)= -### Other useful settings 1. There is a setting for allowing structural flexibility while keeping the sequence fixed in the input structure, for example: ```yaml select_fixed_atoms: @@ -104,7 +106,9 @@ In this tutorial, we will be briefly describing each of the settings we will be ``` Here, an empty list indicates that all atoms are flexible, `BKBN` keeps the backbone atoms fixed while allowing side chain atoms to move, and for the last residue, specific atoms are fixed in place while allowing the others to move. Feel free to try adding this to your YAML file and see how your outputs change. -(running-rfd3)= + Including this setting will give you structures similar to what is in `fixed.zip`. + +(ppi-running-rfd3)= ## Running RFD3 To actually run RFD3 you need to know: - the directory you want the outputs to be stored in @@ -115,17 +119,17 @@ Once you have these three things you can run something like this from the comman ```bash rfd3 design out_dir=ppi_tutorial_outputs/0 inputs=ppi_tutorial.yaml ckpt_path=/path/to/your/checkpoint/files/rfd3_latest.ckpt inference_sampler.step_scale=3 inference_sampler.gamma_0=0.2 ``` -Your output files will be placed in a new directory `ppi_tutorial_outputs/0`. If you run the tutorial again, change the `0` to another number to not overwrite your outputs. Your output files will be named `ppi_tutorial_insulinr_0_model_n.cif.gz` where `n` is the number of the design. `ppi_tutorial` comes from the name of the YAML file and `insulinr` comes from the name you gave your calculation in the YAML file. +Your output files will be placed in a new directory `ppi_tutorial_outputs/0`. Your output files will be named `ppi_tutorial_insulinr_0_model_n.cif.gz` where `n` is the number of the design. `ppi_tutorial` comes from the name of the YAML file and `insulinr` comes from the name you gave your calculation in the YAML file. ```{note} You may see several warning messages when you run RFD3, these should not interfere with the calculation. ``` -(analyzing-the-outputs)= +(ppi-analyzing-the-outputs)= ## Analyzing the Outputs You should end up with 8 designs, numbered 0-7, each with its own `.cif.gz` and `.json` file. If you want to adjust the number, add the configuration option `diffusion_batch_size` to your `rfd3 design` command. -The JSON file has many details about your diffusion run, including the options in the YAML file you created. The compressed CIF file that you can easily visualize with tools like PyMOL. +The JSON file has many details about your diffusion run, including the options in the YAML file you created. The compressed CIF file contains information about the final diffused structure that you can easily visualize with tools like PyMOL. Your results should look something like this: ```{figure} .assets/ppi_tutorial/example_output_w_hotspots.png @@ -138,10 +142,10 @@ You'll notice that the binders are always on the side of the input structure clo The lengths of the designed binders are all also between 40 and 120 amino acids long. However, you'll also notice that they are all the same length! This is because RFD3 runs batched inference calculations. All of the calculations in a single 'batch' will have the same randomly sampled length, while designs from other batches will have different lengths. If you want to change the number of batches, you will want to add the setting `n_batches` to your `run rfd3` command. -(references-and-further-reading)= +(ppi-references-and-further-reading)= ## References and Further Reading - For more information on the different inference settings in RFD3, see [input.md](input.md) -- For more information on the example used here, see [*De novo design of protein structure and function with RFdiffusion*](https://www.nature.com/articles/s41586-023-06415-8#Sec12) by Joeseph L. Watson, et. al. +- For more information on the example used here, see [*De novo design of protein structure and function with RFdiffusion*](https://www.nature.com/articles/s41586-023-06415-8#Sec12) by Joseph L. Watson, et al. - A more thorough discussion of the settings and configuration options in RFD3 can be found [here](intro_inference_calculations.md)