Latest revision as of 12:59, 4 January 2019

Our results

For a description of the approach, please read our (open-access) paper in Structure.

In order to further facilitate the uptake of this method by the community, we also wrote a step-by-step protocol for Nature Protocols. While this draft is under review, you can already read it on bioRxiv. The ribosome data set described in that paper and all our intermediate results are also available from the EMDB's EMPIAR data base (accession number EMPIAR-10045). New users are recommended to replicate/follow these results on their own system in order to learn the approach.

Recommended procedures

Getting organised

As in single-particle projects, also sub-tomogram averaging is organized in a single ProjectDirectory for each structure/project (also see the recommended procedures). Inside this directory it is recommended to make a Tomograms directory. Inside this directory, one should make a separate directory for each of the recorded tomograms (e.g. Tomograms/tomo0001). (Optionally, the Tomograms/ directory may contain sub-directories to group sets of tomograms, because for example they were collected on different days (e.g. Tomograms/12Mar2015/tomo0001). You are free to choose whatever names for your directories and your tomograms. We have only tested this script for IMOD tomogram reconstructions, but there is no reason why other software packages could not be used. The important thing is to save the tomogram in MRC format, and with a .mrc extension. In each of the individual tomogram directories you will need 5 files:

tomo.mrc   : the actual reconstructed tomogram
tomo.mrcs  : the aligned tilt series in MRC-stack format (e.g. save this from IMOD) 
tomo.coords: a text file with 3 columns: the X, Y and Z coordinates of each subtomogram (e.g. save this from IMOD)
tomo.order : a text file with 2 columns: the tilt angle of each image in tomo.mrcs and the accumulated dose in electron/A2 for that image.
tomo.tlt   : a text file with the final tilt angles from IMOD. If this is not provided then the extended header of the .mrcs will be read.

You are free to change the rootname of these files (in this case "tomo"), but the extensions have to be like the ones above.

Generating STAR files and a script for CTF-reconstruction

Tanmay Bharat wrote the relion_prepare_subtomograms.py script to run CTFFIND on all images of the tilt series stack. Please note that an extension of this script to include CTF-estimation from two neighbouring exposure areas is still pending. This script also generates the input particles_subtomo.star file for sub-tomogram refinement, and the STAR files that are required for the reconstruction of the 3D CTF models for each subtomogram. In addition, this script generates a shell script (called tomo_reconstruct_ctfs.sh) inside the directory for each tomogram.

Note that the relion_prepare_subtomograms.py script depends on python, IMOD, RELION and CTFFIND (version 3 or 4). The input for this script is a RELION-type STAR file with one line for each tomogram. It looks like this:

data_
loop_
_rlnMicrographName
Tomograms/tomo001/tomo.mrc
Tomograms/tomo002/tomo.mrc
Tomograms/tomo003/tomo.mrc

One way to make it would be:

relion_star_loopheader rlnMicrographName > all_tomograms.star
ls Tomograms/tomo???/*.mrc >>  all_tomograms.star

After making this STAR file, edit the header of the relion_prepare_subtomograms.py script to provide information about the experimental setup and execute it using:

python relion_prepare_subtomograms.py

Generating 3D CTF models for sub-tomogram averaging

The relion_prepare_subtomograms.py script also generates a shell script called do_all_reconstruct_ctfs.sh, which calls to each of the tomo_reconstruct_ctfs.sh in the Tomograms/ subdirectories. This script needs to be executed from the command line to perform the reconstructions for the 3D CTF models of all subtomograms from all tomograms. You may parallelise its execution as is most suited for your computer setup.

Sub-tomogram extraction

Extract sub-tomograms using RELION as you would do for 2D micrographs. Always launch the relion GUI from the ProjectDirectory. Use the all_tomograms.star file generated above as the "micrograph STAR file" on the I/O tab of the particle extraction jobtype. The "Coordinate-file suffix" on that tab should be set to ".coords". The "Extract rootname" on the I/O tab and the "Particle box size" on the extract tab should be set to the same values as used in the header of the relion_prepare_subtomograms.py script. Do not forget to fill in the parameters of pixel size and particle diameter on the General jobtype of the GUI as well!

Executing this RELION job will extract and normalize all 3D subtomograms. Note that this job will generate a STAR file called subtomo.star (assuming the "Extract rootname" was subtomo). This STAR file should NOT be used for further processing. Instead, one should use the particles_subtomo.star file that was generated as described above by the relion_prepare_subtomograms.py script.

Note that at the particle extraction step, one could also project each 3D subtomogram along the Z-direction to yield 2D particles by providing the additional argument --project3d on the Running tab. In this case, you should use a different "Extract rootname" (e.g. particles2d), and use the generated particles2d.star file for standard single-particle processing in RELION. For example, you may want to run 2D class averaging to select good particles. The following Relion 2Dto3D star.py script may be helpful in converting the STAR file with selected 2D projections back into selected 3D sub-tomograms.

Sub-tomogram averaging

You can now run 3D Auto-Refine or 3D classification jobs using your 3D subtomogram particles by using the particles_subtomo.star file as Input images STAR file on the I/O tab. From here on, everything is analogous to the single-particle cases, including all analyse results options.

@@ Line 1: / Line 1: @@
-The following was written by Tanmay Bharat.
+= Our results =
-== Getting started ==
+For a description of the approach, please read our (open-access) paper in [http://dx.doi.org/10.1016/j.str.2015.06.026 Structure].
+In order to further facilitate the uptake of this method by the community, we also wrote a step-by-step protocol for Nature Protocols. While this draft is under review, you can already read it on [http://dx.doi.org/10.1101/030544 bioRxiv]. The ribosome data set described in that paper and all our intermediate results are also available from the EMDB's EMPIAR data base (accession number [http://www.ebi.ac.uk/pdbe/emdb/empiar/entry/10045 EMPIAR-10045]). New users are recommended to replicate/follow these results on their own system in order to learn the approach.
-As in single-particle projects, also sub-tomogram averaging is organized in a single ProjectDirectory for each structure/project (also see the [[Recommended_procedures | recommended procedures]]). Inside this directory it is recommended to make a Tomograms directory. Inside this directory, one should make a separate directories for each of the recorded tomograms (e.g. Tomograms/tomo0001). (Optionally, the Tomograms directory may contain siub-directories to group sets of tomograms, becase for example they were collected on different days (e.g. Tomograms/12Mar2015/tomo0001). You are free to choose whatever names for your directories and your tomograms. We have only used IMOD for tomogram reconstruction, but there is not reason why other software packages could not be used, as long as the instructions below are
+= Recommended procedures =
-The important thing is to save the tomogram in MRC format, and with a .mrc extension. In each of the individual tomogram directories you will need 4 files:
- tomo.mrc    : the actual reconstructed tomogram
+== Getting organised ==
- tomo.coords : a ASCII text file with 3 columns: the X, Y and Z coordinates of the subtomograms (e.g. save this from IMOD)
- tomo.st     : the aligned tilt series in MRC format (e.g. save this from IMOD)
- tomo.order
-</code>
-You are free to change the rootname of these files (in this case "tomo"), but the extensions
+As in single-particle projects, also sub-tomogram averaging is organized in a single ProjectDirectory for each structure/project (also see the [[Recommended_procedures | recommended procedures]]). Inside this directory it is recommended to make a <code>Tomograms</code> directory. Inside this directory, one should make a separate directory for each of the recorded tomograms (e.g. <code>Tomograms/tomo0001</code>). (Optionally, the <code>Tomograms/</code> directory may contain sub-directories to group sets of tomograms, because for example they were collected on different days (e.g. <code>Tomograms/12Mar2015/tomo0001</code>). You are free to choose whatever names for your directories and your tomograms. We have only tested this script for IMOD tomogram reconstructions, but there is no reason why other software packages could not be used. The important thing is to save the tomogram in MRC format, and with a <code>.mrc</code> extension. In each of the individual tomogram directories you will need 5 files:
-of all these directories
-latter directories can be organized in can optionmake other subdirectories (e.g.
-Tomograms should be in .mrc format. Coordinates for the sub-tomograms should be in 3-column ASCII files with X Y Z coordinates.
-== Generating 3D CTF volumes for sub-tomogram averaging ==
+ tomo.mrc   : the actual reconstructed tomogram
+ tomo.mrcs  : the aligned tilt series in MRC-stack format (e.g. save this from IMOD)
+ tomo.coords: a text file with 3 columns: the X, Y and Z coordinates of each subtomogram (e.g. save this from IMOD)
+ tomo.order : a text file with 2 columns: the tilt angle of each image in tomo.mrcs and the accumulated dose in electron/A2 for that image.
+ tomo.tlt   : a text file with the final tilt angles from IMOD. If this is not provided then the extended header of the .mrcs will be read.
-*  First CTFFIND should be run for all images of the tilt series (that was used to generate the tomogram). The results should be written out in a text file with the syntax:
+You are free to change the rootname of these files (in this case "tomo"), but the extensions have to be like the ones above.
-<code>Tilt_angle   average_defocus_value_from_CTFFIND</code>
+== Generating STAR files and a script for CTF-reconstruction ==
-This can be done automatically using the script [[run_ctffind.py]]. Please modify the header values of the script.
+Tanmay Bharat wrote the [http://www2.mrc-lmb.cam.ac.uk/groups/scheres/relion_prepare_subtomograms relion_prepare_subtomograms.py] script to run [http://grigoriefflab.janelia.org/ctf CTFFIND] on all images of the tilt series stack. Please note that an extension of this script to include CTF-estimation from two neighbouring exposure areas is still pending. This script also generates the input <code>particles_subtomo.star</code> file for sub-tomogram refinement, and the STAR files that are required for the reconstruction of the 3D CTF models for each subtomogram. In addition, this script generates a shell script (called <code>tomo_reconstruct_ctfs.sh</code>) inside the directory for each tomogram.
-*  Now the coordinates from the text file and the average defocus values from CTFFIND will be used to calculate local CTF parameters for each sub-tomogram in each image of the tilt series. This can be done using the
+Note that the [http://www2.mrc-lmb.cam.ac.uk/groups/scheres/relion_prepare_subtomograms relion_prepare_subtomograms.py] script depends on [https://www.python.org/ python], [http://bio3d.colorado.edu/imod/ IMOD], RELION and [http://grigoriefflab.janelia.org/ctf CTFFIND] (version 3 or 4). The input for this script is a RELION-type STAR file with one line for each tomogram. It looks like this:
-script [[make_ctfstar.py]]. Please modify the header values in this python script. For each subtomogram, a RELION .star file will be written out. This will be used by relion_reconstruct to generate the 3D CTF volume.
-*  Run relion_reconstruct to generate all 3D CTF model volumes. This can be done using the script <code>reconstruct_CTF_volumes.sh</code> that was written out in the last step. This script uses the .star file to read the local CTF
+ data_
-parameters and use them to make the 3D CTF model volume.
+ loop_
+ _rlnMicrographName
+ Tomograms/tomo001/tomo.mrc
+ Tomograms/tomo002/tomo.mrc
+ Tomograms/tomo003/tomo.mrc
+One way to make it would be:
+ relion_star_loopheader rlnMicrographName > all_tomograms.star
+ ls Tomograms/tomo???/*.mrc >>  all_tomograms.star
+After making this STAR file, edit the header of the [http://www2.mrc-lmb.cam.ac.uk/groups/scheres/relion_prepare_subtomograms relion_prepare_subtomograms.py] script to provide information about the experimental setup and execute it using:
+ python relion_prepare_subtomograms.py
+== Generating 3D CTF models for sub-tomogram averaging ==
+The [http://www2.mrc-lmb.cam.ac.uk/groups/scheres/relion_prepare_subtomograms relion_prepare_subtomograms.py] script also generates a shell script called <code>do_all_reconstruct_ctfs.sh</code>, which calls to each of the <code>tomo_reconstruct_ctfs.sh</code> in the <code>Tomograms/</code> subdirectories. This script needs to be executed from the command line to perform the reconstructions for the 3D CTF models of all subtomograms from all tomograms. You may parallelise its execution as is most suited for your computer setup.
 == Sub-tomogram extraction ==
-* Extract sub-tomograms using RELION as you would do for 2D micrographs. If the image file is a volume and the coordinates values contain X,Y,Z entries, automatically sub-tomograms will be written out rather than 2D particles. If you add <code>--project3d</code> to the RELION extraction command, then 2D projections of each sub-tomogram will be written out. This may be useful to run reference-free 2D-class averaging in order to identify junk or otherwise unsuitable particles in your data set.
+Extract sub-tomograms using RELION as you would do for 2D micrographs. Always launch the relion GUI from the ProjectDirectory. Use the <code>all_tomograms.star</code> file generated above as the "micrograph STAR file" on the I/O tab of the particle extraction jobtype. The "Coordinate-file suffix" on that tab should be set to ".coords". The "Extract rootname" on the I/O tab and the "Particle box size" on the extract tab should be set to the same values as used in the header of the [http://www2.mrc-lmb.cam.ac.uk/groups/scheres/relion_prepare_subtomograms relion_prepare_subtomograms.py] script. Do not forget to fill in the parameters of pixel size and particle diameter on the General jobtype of the GUI as well!
+Executing this RELION job will extract and normalize all 3D subtomograms. Note that this job will generate a STAR file called <code>subtomo.star</code> (assuming the "Extract rootname" was <code>subtomo</code>). This STAR file should NOT be used for further processing. Instead, one should use the <code>particles_subtomo.star</code> file that was generated as described above by the [http://www2.mrc-lmb.cam.ac.uk/groups/scheres/relion_prepare_subtomograms relion_prepare_subtomograms.py] script.
+Note that at the particle extraction step, one could also project each 3D subtomogram along the Z-direction to yield 2D particles by providing the additional argument <code>--project3d</code> on the Running tab. In this case, you should use a different "Extract rootname" (e.g. <code>particles2d</code>), and use the generated <code>particles2d.star</code> file for standard single-particle processing in RELION. For example, you may want to run [[Calculate_2D_class_averages | 2D class averaging]] to select good particles. The following [[Relion 2Dto3D star.py]] script may be helpful in converting the STAR file with selected 2D projections back into selected 3D sub-tomograms.
-* Run [[Refine_a_structure_to_high-resolution | 3D Auto-Refine]] or [[Classify_3D_structural_heterogeneity | 3D classification]] jobs, just like you would for single-particles, but specifying the CTF volume for each image in a .star file (using the label "rlnCtfImage"). This can be done using the script [[prepare_subtomo.py]]. A sample output is shown in the script.
+== Sub-tomogram averaging ==
-* All [[Analyse_results | analyse results]] options (e.g. post-processing) stay the same as for single-particles.
+You can now run [[Refine_a_structure_to_high-resolution | 3D Auto-Refine]] or [[Classify_3D_structural_heterogeneity | 3D classification]] jobs using your 3D subtomogram particles by using the <code>particles_subtomo.star</code> file as Input images STAR file on the I/O tab. From here on, everything is analogous to the single-particle cases, including all  [[Analyse_results | analyse results]] options.

Sub-tomogram averaging: Difference between revisions