Launch with Your Own X-ray Data

Setting up ROCKET with your own datasets -- X-ray crystallography

In this tutorial, we walk you through how to refine a prediction to your own X-ray dataset with ROCKET.

We use the PDB ID 1LJ5 system as an example.

Note: We require users to precompute their MSA files (a3mor sto format required) from servers or a database beforehand. To use OpenFold, follow the sequence database download instructions (It requires ~TB space!). The --precomputed_alignment_dir (default: alignments/) is expected at the moment and all your alignment files in that folder will be used – we are working on integrating a sequence server into the pipeline.

🛰️ First things first – gather your data

The ROCKET preprocessing script expects input files organized as follows:

<working_directory>/
├── {file_id}_fasta/
│   └── {file_id}.fasta       # FASTA file containing the chain to refine
│                             # Header should be "> {file_id}"
│
├── {file_id}_data/
│   ├── *.mtz                 # For X-ray data
│   └── <optional files>/     # e.g., predicted or docked models
│
├── alignments/               # (default: --precomputed_alignment_dir)
│   └── {file_id}
|       └──*.a3m / *.hhr      # MSA files for the input sequence  

Run ROCKET Preprocessing

Once you have data organized in this way, you are ready to run rk.preprocess . For example:

rk.preprocess \
  --file_id 1lj5 \
  --method xray \
  --output_dir ./1lj5_processed \
  --precomputed_alignment_dir alignments/ \
  --xray_data_label FP,SIGFP \
  --max_recycling_iters 20 \
  --use_deepspeed_evoformer_attention

Note: If you are unsure about the --xray_data_label, you could run a quick investigation of your mtz file by:

rs.mtzdump {file_id}_data/xxx.mtz

Edit YAML File

rk.preprocess will automatically generate two yaml files under --output_dir for the following rk.refinerun, users are expected to review and edit those yaml files directly.

If you want to generate another set of default config files:

rk.config --mode both --datamode xray --working-dir 1lj5_processed --file-id 1lj5

The --mode both flag in the command above will set up ROCKET to run its default "aggressive" phase1 and finetuning phase2. You can optionally modify the saved config files if you want to test a specific condition for model building.

Iteratively Refine Predictions

Run the phase1 config file you generated/edited above e.g.

rk.refine 1lj5_processed/ROCKET_config_phase1.yaml

This should get you going with the refinement!

The standard protocol is to run a default phase1 and follow this up with the lower learning rate default phase2 e.g.

rk.refine 1lj5_processed/ROCKET_config_phase2.yaml

phase2 requires an existing phase1 folder to start from. If you would like to experiment with only a lower learning rate from the start, you could edit the config_phase1.yaml accordingly.

Finalize geometry and B-factors

We recommend a brief standard run of refinement (phenix.refine used in the paper) to refine B-factors and polish the geometry of the models that come straight out of ROCKET .

A note from us

We hope to make ROCKET as useful and general as we can – please let us know if you run into issues setting up your own refinements and we'll see how we can help!

Create an issue in our repo