Overview
Automatic subtomogram aligment for particle reconstruction not always produces the desired outcome. In order to guide particle reconstruction, the use of a reference may be necessary. By manually superimposing a reference density on the desired location of a subtomogram one can guide alignment, this can be done in visualization software, such as UCSF Chimera. We provide two python scripts that together take the reference alignment information from a UCSF Chimera session and produce a RELION *.star file with initialized Euler angles and rotations origins that transform particles to the reference. This results in the alignment and superimposition of all user-defined subtomogram locations.
Installation
The easiest way to manage the libraries needed to run these scripts is to install Anaconda, and use it to generate the follwing environments:
pychimera
, with the libraries necessary to interpret UCSF Chimera session files.
py37
, with a version scipy that has the Rotation object.
-
Install Anaconda following the instruction in their website.
-
Clone this repository:
git clone https://github.com/GrotjahnLab/guided_tomo_align.git
cd guided_tomo_align
-
For the pychimera library to work, you need to install UCSF Chimera and direct pychimera to its directory. See pychimeras' help for more information, specially points 2 and 4 in this page. Avoiding launching of the UCSF Chimera GUI may be desirable, specially when working from a computing cluster. For this, make sure you obtain the UCSF Chimera "headless" version. In order to execute the downloaded *.bin file, make it into an executable by running
chmod +x ucsfchimera_download.bin
. Finally, set the CHIMERADIR environment variable (in bash):export CHIMERADIR=/your/chimera/intallation/dir/
-
Create
pychimera
andpy37
using the provided *.yml files:
conda env create -f ./pychimera.yml
conda env create -f ./py37.yml
Usage of Chimera-to-Euler scripts
- First, activate the pychimera environment using
conda activate pychimera
to runchim_session_to_mtx.py
. You can print a help message typing:
python ./chim_session_to_mtx.py --help
It will generate the following output:
usage: chim_session_to_mtx.py [-h] --sessions_path SESSIONS_PATH
--reference_name REFERENCE_NAME
[--particle_name_prefix PARTICLE_NAME_PREFIX]
[--particle_name_postfix PARTICLE_NAME_POSTFIX]
[--particle_origin PARTICLE_ORIGIN]
[--reference_origin REFERENCE_ORIGIN]
--particle_angpix PARTICLE_ANGPIX
--reference_angpix REFERENCE_ANGPIX --r_box
R_BOX --p_box P_BOX [--output_name OUTPUT_NAME]
Use UCSF Chimera *.py sessions to extract the rotation matrix that transforms
particles to references. It is recommended particle densities are named as
they appear in the RELION *.star file. Access to the session MRC files is not
required.
optional arguments:
-h, --help show this help message and exit
--sessions_path SESSIONS_PATH
Absolute path to directory where all sessions are
stored, e.g., "/User/sessions/"
--reference_name REFERENCE_NAME
Name of reference density in the Chimera sessions as
it appears in it. E.g., "low_passed_ribosome.mrc"
--particle_name_prefix PARTICLE_NAME_PREFIX
Prefix used to parse particle densities from Chimera
sessions. If all your particles are named
"tomogram_<something>.mrc", then use "tomogram_" as
prefix to find them in each session.
--particle_name_postfix PARTICLE_NAME_POSTFIX
Postfix used to parse particle densities from Chimera
sessions. If all your particles are named
"tomogram_<something>_foo.mrc", then use "_foo.mrc" as
postfix to find them in each session.
--particle_origin PARTICLE_ORIGIN
Index origin of particle *.mrc if different from
0,0,0. It is assumed to be the same for all particles.
Enter as X,Y,Z
--reference_origin REFERENCE_ORIGIN
Index origin of reference *.mrc if different from
0,0,0. Enter as X,Y,Z
--particle_angpix PARTICLE_ANGPIX
Pixel size, in Angstroms, of particle *.mrc. It is
assumed to be the same for all particles.
--reference_angpix REFERENCE_ANGPIX
Pixel size, in Angstroms, of reference *.mrc.
--r_box R_BOX Reference box size
--p_box P_BOX Particle box size
--output_name OUTPUT_NAME
Name for output file containing a transformation
matrix for each particle.
Here's a commandline example:
python ./chim_session_to_mtx.py --sessions_path /path/to/chimerasessions/ --reference_name reference.mrc --particle_name_prefix deconv_lam2_TS4 --particle_angpix 10.88 --reference_angpix 10.88 --r_box 44,44,44 --p_box 44,44,44
NOTE: There is a known issue with some UCSF Chimera installations where the libgfxinfo.so library will produce a "undefined symbol" error. We have been able to fix this by removing the pcre package from the pychimera environment: conda remove --force pcre
- Deactivate the
pychimera
environment by typingconda deactivate
. Then, activate the py37 environment usingconda activate py37
to runmtx_to_star.py
.
python ./mtx_to_star.py --help
It will generate the following output:
usage: mtx_to_star.py [-h] --template_star TEMPLATE_STAR --chimera_mtx_output
CHIMERA_MTX_OUTPUT
[--rln_particle_particle_csv RLN_PARTICLE_PARTICLE_CSV]
[--angpix ANGPIX] [--output_name OUTPUT_NAME]
Use transformation matrices generated by chim_session_to_mtx.py to populate a
template relion star file Euler angles and rotation origins.
optional arguments:
-h, --help show this help message and exit
--template_star TEMPLATE_STAR
RELION *.star file to use as template.
--chimera_mtx_output CHIMERA_MTX_OUTPUT
Output file from chim_session_to_mtx.py
--rln_particle_particle_csv RLN_PARTICLE_PARTICLE_CSV
A "coma separated values" file denoting equivalences
between the naming of particles in the *.star file and
chimera sessions. E.g., if a particle is named "Partic
les/Tomograms/tomogram101/tomogram101_subtomo000004.mr
c" in the star file, and "tomo1_4.mrc" in the Chimera
session, the *.csv file should have a line with the
following format:
"tomogram101_subtomo000004.mrc,tomo1_4.mrc". There
should be one pair per line.
--angpix ANGPIX Particle pixel size.
--output_name OUTPUT_NAME
Name for output *.star file
Here's a commandline example:
python ./mtx_to_star.py --template_star you_template.star --chimera_mtx_output matrix_dictionary.txt --rln_particle_particle_csv equiv.csv --angpix 10.88
Usage of script for shifting particles according to the final reconstruction
Activate the py37 environment using conda activate py37
to run shift_particles_starfile.py
.
python ./shift_particles_starfile.py --help
It will generate the following output:
usage: shift_particles_starfile.py [-h] --template_star TEMPLATE_STAR
[--angpix ANGPIX] --translation TRANSLATION
--particle_box_size PARTICLE_BOX_SIZE
[--output_name OUTPUT_NAME]
Use transformation matrices generated by chim_session_to_mtx.py to populate a
template relion star file Euler angles and rotation origins.
optional arguments:
-h, --help show this help message and exit
--template_star TEMPLATE_STAR
RELION *.star file containing particles to be shifted.
--angpix ANGPIX Particle pixel size.
--translation TRANSLATION
Desired translation in pixels: X,Y,Z
--particle_box_size PARTICLE_BOX_SIZE
Particle box size in pixels: X,Y,Z
--output_name OUTPUT_NAME
Name for output *.star file. Otherwise it will be
called "<original name>.shifted.star".
Here's a commandline example:
python ./shift_particles_starfile.py --template_star skeletondata.init_from_Chimera.star --angpix 8.52 --translation 0,0,-15 --particle_box_size 96,96,96
Usage of UCSF Chimera fitmap iterator
- First, activate the pychimera environment using
conda activate pychimera
to runchimera_fitmap_search.py
. You can print a help message typing:
python ./chimera_fitmap_search.py --help
It will generate the following output:
usage: chimera_fitmap_search.py [-h] --subtomogram_path SUBTOMOGRAM_PATH --reference_path
REFERENCE_PATH --s_angpix S_ANGPIX --r_angpix R_ANGPIX
--s_level S_LEVEL --r_level R_LEVEL
This script uses the UCSF Chimera fitmap function to generate sessions with a
reference density of interest docked in a series of subtomograms. We recomend
to first open a few subtomograms along the reference to evaluate ideal
isosurface countour levels. See Volume Viewer > Level in the UCSF Chimera
graphical interface.
optional arguments:
-h, --help show this help message and exit
--subtomogram_path SUBTOMOGRAM_PATH
Absolute path to directory where all subtomograms are
stored, e.g., "/User/sessions/*.mrc"
--reference_path REFERENCE_PATH
Absolute path to reference density. E.g.,
"./low_passed_ribosome.mrc"
--s_angpix S_ANGPIX Pixel size of subtomograms
--r_angpix R_ANGPIX Pixel size of references
--s_level S_LEVEL Subtomogram isosurface contour level
--r_level R_LEVEL Reference isosurface contour level
Here's a commandline example:
python ./chimera_fitmap_search.py --subtomogram_path ./tomogram1_subtomo000007_gaussian.mrc --reference_path ./dynactin_resampled.8p52.mrc --s_angpix 8.25 --r_angpix 8.25 --s_level 1.25 --r_level 0.036
If you are interested in only running the fitmap iterator, and you already have the chimera command line interpreter, we provide a version of chimera_fitmap_search.py (chimera_fitmap_search_quick.py) that you can run using, for example:
chimera --nogui --script "chimera_fitmap_search_quick.py --subtomogram_path ./tomogram1_subtomo000007_gaussian.mrc --reference_path ./dynactin_resampled.8p52.mrc --s_angpix 8.25 --r_angpix 8.25 --s_level 1.25 --r_level 0.036"