cryoSPHERE minimal reproducible dataset

About cryoSPHERE:

This dataset is a minimal reproducible example for cryoSPHERE published at ICLR 2025, see github:

https://github.com/Gabriel-Ducrocq/cryoSPHERE

and the project page:

https://gabriel-ducrocq.github.io/cryosphere.github.io/

and the paper:

https://arxiv.org/pdf/2407.01574

How to reproduce the results:

These results have been obtained running cryoSPHERE as explained on github, with the paramters described in parameters_two_segmentation.yaml, and taking the 1000th epoch to perform the analysis step.

To reproduce the results, you can start with the particles.star, particles.mrcs, base_structure_minimal_reproducible.pdb, parameters_two_segmentation.yaml and images.yaml. From that, you can follow the steps 1 and 1 bis: obtain a consensus reconstruction with the tool of your choice, fit base_structure_minimal_reproducible.pdb in that reconstruction and center it, following the steps described on github.

Alternatively, you can skip the steps 1 and 1 bis and run cryoSPHERE directly on the base_structure_minimal_reproducible_centered.pdb structure (step 2 on github).

The configuration files you need to run cryoSPHERE are parameters_two_segmentation.yaml and images.yaml. They are in setup_files.zip.

How has the dataset been generated:

We sampled 10000 structures from a molecular dynamics simulation, see appendix B.2 of the paper. You can find the structures in ground_truth_structures.zip.

We then sampled 2 poses per structure, uniformly distributed on the set of poses. We posed the structures and projected them according to our image formation model, see equation (1) and (2) in our paper. Finally, we added Gaussian noise to the picture to get a SNR of 0.1.

This procedure results in 20000 images, aranged in the same order as the structures in ground_truth_structures.zip: the first two images correspond to the first structure, images 3 and 4 to structure 2, images 5 and 6 to structure 3 and so on...

Plots:

After running cryoSPHERE and up to 1000 epochs, we predicted 10000 structures (one structure every two pictures, so we actually get one predicted structure per one ground truth structure). We then computed the distance between domain 1 (residues 321-503 of chain A) and domain 2 (residues 321-503 of chain B) for each ground truth and predicted structure. We plot two things, available in the plots.zip:

scatter_plot.png is a scatter plot of the predicted vs true distances (Å) where we see that the points are along the diagonal, showing that cryoSPHERE recovers the right conformation for a given image.

histogram.png is two histograms, one of the true distances and the other one of the predicted distances. We see that they match.

To reproduce these results, you can use the compute_distances.py script to compute all the distances of a set of images, within the cryoSPHERE environment you created when installing it:

python compute_distances.py --path path/to/folder/structures/ --chain_information

where --chain_information indicates that the chain numbers have been kept in the pdb files. If --no-chain_information, the opposite is assumed.

And --path is set to the path of the folder containing the structures. This command will output a .npy file containing the distances in the same order as the numbering of the structures, in the structure folder.

Once you have the distances, you can create the plots using:

python plotting.py --true_distances /path/to/true_distances.npy --predicted_distances /path/to/predicted_distances.npy ---output_path /path/to/output/folder/

where --true_distances is the path to the npy file containing the true distances

where --predicted_distances is the path to the npy file containing the predicted distances

where --output_path is the path to the folder where the plot will be saved.

The outputs of this command are one histogram and one scatter plot, like the ones in plots.zip

How is this dataset organized:

There are 5 files:

• particles.mrcs is the mrcs file containing the particles.
• setup_files.zip contains multiple files:
  • particles.star is the star file containing the poses and ctf for each particle.
  • base_structure_minimal_reproducible.pdb is the base structure obtained via AlphaFold.
  • base_structure_minimal_reproducible_centered.pdb is the same as base_structure_minimal_reproducible.pdb but centered, following the steps explained on github. 
  • back_projection.mrc is the volume obtained using a consensus reconstruction method (here the backprojection algorithm available with cryoDRGN).
  • back_projection_centered.mrc is the same volume as back_projection.mrc but centered following the setps explained on github.
  • base_structure_minimal_reproducible_centered_mrc.mrc is the volume obtained from base_structure_minimal_reproducible_centered.pdb as explained on github.
  • parameters_two_segmentation.yaml is the configuration file used to run cryoSPHERE.
  • images.yaml is the configuration file with the informations about the images in particles.mrcs
• cryosphere_results.zip contains the results produce by cryosphere at training epoch 1000:
  • pc0, folder containing:
    • pca.png, picture of the first two axes of the PCA decomposition of the latent space, with their explained variance and 20 points corresponding to the traversal of the first axis.
    • 20 structures, named structure_z_x.pdb where x goes from 0 to 19 corresponding to the traversal points of pca.png. The file structure_z_0.pdb corresponds to the point with the lowest value of the PCA axis 1 and the value of x corresponds to increasing values of the PCA axis 1.
  • pc1, is the same as the folder pc0, but for PC 2.
  • pc2, is the same as the folder pc0, but for PC 3.
  • predicted_structures, folder containing the predicted structure for each image (20000 in total, in the same order as the images).
  • z.npy the 20000 latent variable, one for each image, in the same order at the images in the particles.star file.
• ground_truth_structures.zip contains the 10000 structures used to generate the dataset, in the same order as the images. It also contains a file called true_distances.npy containing the distances of the ground truth structures, see above.
• plots.zip, containing the plots of the results:
  • One histogram, see above.
  • One scatter plot, see above.
  • compute_distances.py to compute the distances of the structures output by cryoSPHERE, see above.
  • plotting.py to recreate the histogram and scatter plot, see above.