Documentation

Getting Started & Tutorial

The best way to become familiar with cisTEM is to work through the tutorial, which starts with movies of apoferritin and takes the user all the way to a 3-Å reconstruction. The dataset contains 20 movies, stored in MRC format, the default format for all cisTEM image data. The size of the dataset is modest, enabling completion of the tutorial in just a few hours on most computer systems. The final result of the tutorial, a 3-Å reconstruction, is also attached below, as well as a comprehensive publication describing more technical aspects of cisTEM.

To start a new project, launch cisTEM and click on the Create a new project link on the Overview panel shown on startup. A dialog allows the user to define a project name and a path when a directory with the name of the project is created. This directory contains all project-related files, including intermediate and final class averages and reconstructions.

Once a new project is created, different types of Assets can be imported, for example, movies or micrographs (images). Actions can then be used to process Assets and produce Results, often resulting in new Assets of a different type. The different cisTEM panels are described in more detail on the Assets, Actions and Results Panel documentation pages.

Apoferritin Tutorial Dataset

If the download link for apoferritin_data.tar.gz below does not work or the download does not complete, the tutorial dataset can also be downloaded from the EMPIAR database.

 cisTEM_tutorial.pdf
 Grant_eLife2018.pdf
 apoferritin.mrc
 apoferritin_data.tar.gz

Particle Position Assets

Particle Positions are Assets that identify particles in Images and are usually generated by running the Find Particles Action. However, they can also be imported from a text file listing for each particle the Asset ID of the image they belong to, the x-coordinate in Å (along the fast axis of the image pixel array) and the y-coordinate in Å (along the slow axis of the image pixel array):

0 377.52 1888.64
0 989.04 1880.32
0 1687.92 1882.4
0 157.04 1876.16
0 799.76 1824.16
0 1045.2 1826.24
0 236.08 1822.08
0 342.16 1813.76
0 400.4 1797.12
1 546 1807.52
1 708.24 1797.12
1 957.84 1807.52
1 1174.16 1797.12
1 1490.32 1822.08
1 1669.2 1813.76
1 1723.28 1772.16
2 177.84 1753.44
2 1542.32 1745.12
2 310.96 1732.64
2 589.68 1718.08
…

Instead of the Image Asset ID, the list can also contain the file name of the Asset (the attached file at the bottom of this page contains an example script written by by Matthias Wolf to convert a Relion star file with picked particle coordinates to such a list):

May08_02.46.41.bin_0_0.mrc 377.52 1888.64
May08_02.46.41.bin_1_0.mrc 989.04 1880.32
May08_02.46.41.bin_2_0.mrc 1687.92 1882.4
May08_02.46.41.bin_3_0.mrc 157.04 1876.16
May08_02.46.41.bin_4_0.mrc 799.76 1824.16
May08_02.46.41.bin_5_0.mrc 1045.2 1826.24
May08_02.46.41.bin_6_0.mrc 236.08 1822.08
May08_02.46.41.bin_7_0.mrc 342.16 1813.76
May08_02.46.41.bin_8_0.mrc 400.4 1797.12
May08_02.48.41.bin_9_0.mrc 546 1807.52
May08_02.48.41.bin_10_0.mrc 708.24 1797.12
May08_02.48.41.bin_11_0.mrc 957.84 1807.52
May08_02.48.41.bin_12_0.mrc 1174.16 1797.12
May08_02.48.41.bin_13_0.mrc 1490.32 1822.08
May08_02.48.41.bin_14_0.mrc 1669.2 1813.76
May08_02.48.41.bin_15_0.mrc 1723.28 1772.16
May08_02.50.41.bin_16_0.mrc 177.84 1753.44
May08_02.50.41.bin_17_0.mrc 1542.32 1745.12
May08_02.50.41.bin_18_0.mrc 310.96 1732.64
May08_02.50.41.bin_19_0.mrc 589.68 1718.08
…

To import Particle Positions, click on Import on the Particle Positions Asset panel and browse to the text file containing the coordinates. Then click Open.

Using Asset groups, picked particles can be divided into subgroups. This is useful, for example, when multiple particle picking jobs were run (see Find Particles Action panel) and only particles from a specific job should be used. The picking job that generated a Particle Position is listed in the “Pick Job I.D.” column.

relion_star_to_cistem.sh

3D Volume Assets

3D Volume Assets represent 3D density maps that are generated from Actions including Ab-Initio 3D, Auto Refine and Manual Refine. They can also be imported to be used as references in refinement jobs. To import a map, click Import on the 3D Volumes Asset panel, then Add Files and browse to the map file(s) to import, then click Open. Alternatively, whole directories can be imported by clicking Add Directory, then Open. For each import, the pixel size of the density map has to be entered. Then click Import. The pixel size must match the pixel size of the Movies/Images and Refinement Package that the 3D Volume(s) will be used with. Like other Assets, 3D Volumes can be grouped into subgroups.

Refinement Package Assets

Refinement Packages are defined by a particle image stack, a set of particle alignment parameters, and optionally a 3D Volume (or several 3D Volumes if more than one 3D class is requested, see "How do I start 3D classification?" in FAQs). Therefore, a Refinement Package contains all the information required to perform the refinement of a 3D density map. Refinement Packages can be created from Particle Positions by clicking Create. This will start a wizard to collect all the required information. In the simplest case, a new Refinement Package is created, using Particle Positions to box out particles, assemble them to a stack and assign a set of random alignment parameters to them. For the template Refinement Package, select New Refinement Package, click Next and select the set of Particle Positions to be used, for example All Positions, then Next and the desired particle box size (sufficiently large to include particle and CTF-delocalized signal), approximate molecular weight of the particle, the largest dimension in Å, the particle symmetry, and the number of desired 3D classes (see also "How do I start 3D classification?" in FAQs). The wizard will then create a particle stack and assign random parameters to each particle. The resulting Refinement Package can be used for Ab Initio 3D reconstruction, for example, or a 3D Volume can be assigned and used as an initial reference to align the particles in the stack. To assign a 3D Volume, double-click on the entry in Active 3D References and select one of the available 3D Volumes as a reference. Selecting Generate From Params. will calculate a 3D Volume from the current parameters assigned to the particles. For a new refinement package, this will result in an approximately spherical volume corresponding to the assigned random angles. However, if the Refinement Package was imported or derived from an earlier Refinement Package (see below), the 3D reconstruction corresponding to the imported/earlier parameters will be generated. The box size chosen for the Refinement Package has to match the box size of the 3D Volume. The particle stack can be displayed using the Display Stack button.

A Refinement Package can also be created from an existing Refinement Package. In this case, select one of the existing Refinement Packages from the menu as the template Refinement Package. After clicking Next, the menu provides a choice of alignment parameters that are associated with the chosen Refinement Package template. Usually, the parameters giving the best reconstruction in the previous refinement is selected here, often the last on the list. However, parameters corresponding to intermediate results can also be chosen. The selection can be changed later on when running a refinement (see Automatic/Manual Refinement). Default answers are provided to the remaining questions in the wizard, based on the template. The user can change these to achieve different goals. For example, the symmetry can be changed to either impose symmetry where there was no symmetry imposed before, or to remove symmetry and do an asymmetric refinement. The number of classes can also be changed to allow 3D classification (see "How do I start 3D classification?" in FAQs). Creating a Refinement Package in this way will not recreate the particle stack.

A third way to create a Refinement Package is based on 2D classification results (see 2D Classification). Selecting Create From 2D Class Average Selection as the template will provide a list of groups of 2D class averages that can be defined in the 2D Classification results panel. The remaining questions are the same as before, generating a particle stack and set of parameters that contain only the particles that ended up in the selected 2D class averages.

Finally, Refinement Packages can be imported from Frealign and Relion refinements. Click Import and select the type of the refinement to be imported. The import wizard will then ask for the location of the particle stack and parameter file (either a Frealign par file or a Relion Star file). Next, the relevant microscope parameters will have to be entered: pixel size, acceleration voltage, spherical aberration coefficient, amplitude contrast, symmetry, approximate molecular weight, largest dimension, and the “polarity” of the particle density in the images. The polarity for Frealign refinements is typically black particles on light background while it is white particles on dark background in Relion refinements. Click Finish to import the data. Please note that the particle stack is not copied and has to remain in place while being worked on using cisTEM. It is therefore good practice to import a copy of the particle stack that is placed in a safe location, for example inside the cisTEM project directory.

Picking Particles

The Find Particles Action panel allows automatic selection of particles in electron micrographs. Individual particles need to be located in each micrograph so that they may be used to compute a 3D reconstruction later. Ideally one would find all the particles and not make any erroneous selections.

In the absence of a pre-existing 3D model, one can either select (click on) each particle manually, or use the 'ab-initio' mode based on an algorithm described by Sigworth (2004). In this mode, a template is genated internally, which consists of a cosine-shaped blob and then matched against each micrographs. This works reasonably well to find globular protein complexes, even though it is less accurate and more error-prone than template-based search strategy.

Program Options

Input Group: The group of image assets in which to find particles.

Run Profile: The selected run profile will be used to run the job. The run profile describes how the job should be run (e.g. how many processors should be used, and on which different computers). Run profiles are set in the Run Profile panel, located under settings.

Maximum Particle Radius (Å): In Angstroms, the maximum radius of the particles to be found. This also determines the minimum distance between picks.

Characteristic Particle Radius (Å): In Angstroms, the radius within which most of the density is enclosed. The template for picking is a soft-edge disc, where the edge is 5 pixels wide and this parameter defines the radius at which the cosine-edge template reaches 0.5.

Threshold Peak Height: Particle coordinates will be defined as the coordinates of any peak in the search function which exceeds this threshold. In numbers of standard deviations above expected noise variations in the scoring function. See Sigworth (2004) for definition.

Avoid High Variance Areas? Avoid areas with abnormally high local variance. This can be effective in avoiding edges of support films or contamination. However, when particles generate strong contrast (e.g. in phase plate images), better results may be obtained by disabling this option.

Select Preview Image: Select an image from the Input Group to be used as a preview for the picking job. This is useful to see how different parameter settings influence the picking to tune the parameters.

Preview: Click this button to generate a preview of the picking job.

Auto Preview? Select this to generate previews automatically. Selecting different Preview Images will automatically run the picking job on the selected image and show the results.

Run Profile: The selected run profile will be used to run the job. The run profile describes how the job should be run (e.g. how many processors should be used, and on which different computers). Run profiles are set in the Run Profile panel, located under settings.

Expert Options

Highest Resolution Used in Picking (Å): The template and micrograph will be resampled (by Fourier cropping) to a pixel size of half the resolution given here. Note that the information in the 'corners' of the Fourier transforms (beyond the Nyquist frequency) remains intact, so that there is some small risk of bias beyond this resolution.

Set Minimum Distance From Edges (px): No particle shall be picked closer than this distance from the edges of the micrograph. Select to enable.

Avoid Areas With Abnormal Local Means: Avoid areas with abnormally low or high local mean. This can be effective to avoid picking from, e.g., contaminating ice crystals, support film.

Number of Background Boxes: Number of background areas to use in estimating the background spectrum. The larger the number of boxes, the more accurate the estimate should be, provided that none of the background boxes contain any particles to be picked.

Algorithm to Find Background Areas: Testing so far suggests that areas of lowest variance in experimental micrographs should be used to estimate the background spectrum. However, when using synthetic micrographs this can lead to bias in the spectrum estimation and the alternative (areas with local variances near the mean of the distribution of local variances) seems to perform better.

References

Sigworth F.J. 2004. Classical detection theory and the cryo-EM particle selection problem. J. Struct. Biol. 145, 111-122. doi:10.1016/j.jsb.2003.10.025

Ab-Initio 3D Reconstruction

Ab-initio 3D Volumes can be generated using the Ab Initio 3D Actions panel. When a prior 3D reconstruction of a molecule or complex is available that has a closely related structure, it is usually fastest and safest to use it to initialize 3D refinement and reconstruction of a new dataset. However, in many cases such a structure is not available, or an independently determined structure is desired. Ab-initio 3D reconstruction offers a way to start refinement and reconstruction without any prior structural information. The figure shows an ab-initio 3D reconstruction of VSV polymerase (Liang et al. 2015):

It is advisable to precede the ab-initio step with a 2D classification step to remove junk particles and select a high-quality subset of the data. Furthermore, it may be helpful to select particles from images that are defocused by 1.5 µm or more. A refinement package has to be created (in Assets) that will be used with the ab-initio procedure, either from selected 2D classes or using picked particle position. The idea of the ab-initio algorithm is to iteratively improve a 3D reconstruction, starting with a reconstruction calculated from random Euler angles, by aligning a small percentage of the data against the current reconstruction and increasing the refinement resolution and percentage at each iteration (Grigorieff, 2016). This procedure can also be carried out using multiple references that must be specified when creating the refinement package. The procedure stops after a user-specified number of refinement cycles and restarts if more than one starts are specified.

The progress of the ab-initio reconstruction is displayed as a plot of the average sigma value that measures the average apparent noise-to-signal ratio in the data. The sigma value should decrease as the reconstruction gets closer to the true structure. The current reconstruction is also displayed as three orthogonal central slices and three orthogonal projections.

If the ab-initio procedure fails on a symmetrical particle, users should repeat it using C1 (no symmetry). This can be specified by creating a new refinement package that is based on the previous refinement package, and changing the symmetry to C1. If a particle is close to spherical, such as apoferritin, it may be necessary to change the initial and final resolution limits from 40 Å and 9 Å (default) to higher resolution, e.g. 15 Å and 6 Å (see Expert Options). Finally, it is worth repeating the procedure a few times if a good reconstruction is not obtained in the first trial.

Program Options

Input Refinement Package: The name of the refinement package previously set up in the Assets panel (providing details of particle locations, box size and imaging parameters).

Number of Starts: The number of times the ab-initio reconstruction is restarted, using the result from the previous run in each restart.

No. of Cycles per Start: The number of refinement cycles to run for each start. The percentage of particles and the refinement resolution limit will be adjusted automatically from cycle to cycle using initial and final values specified under Expert Options.
 

Expert Options

Initial Resolution Limit (Å): The starting resolution limit used to align particles against the current 3D reconstruction. In most cases, this should specify a relatively low resolution to make sure the reconstructions generated in the initial refinement cycles do not develop spurious high-resolution features.

Final Resolution Limit (Å): The resolution limit used in the final refinement cycle. In most cases, this should specify a resolution at which expected secondary structure becomes apparent, i.e. around 9 Å.

Use Auto-Masking? Should the 3D reconstructions be masked? Masking is important to suppress weak density features that usually appear in the early stages of ab-initio reconstruction, thus preventing them to get amplified during the iterative refinement. Masking should only be disabled if it appears to interfere with the reconstruction process.

Auto Percent used? Should the percentage of particles used in each refinement cycle be set automatically? If reconstructions appear very noisy or reconstructions settle into a wrong structure that does not change anymore during iterations, disable this option and specify initial and final percentages manually. To reduce noise, increase the percentage; to make reconstructions more variable, decrease the percentage. By default, the initial percentage is set to include an equivalent of 2500 asymmetric units and the final percentage corresponds to 10,000 asymmetric units used.

Initial % Used / Final % Used: User-specified percentages of particles used when Auto Percent Used is disabled.

Apply Likelihood Blurring? Should the reconstructions be blurred by inserting each particle image at multiple orientations, weighted by a likelihood function? Enable this option if the ab-initio procedure appears to suffer from over-fitting and the appearance of spurious high-resolution features.

Smoothing Factor: A factor that reduces the range of likelihoods used for blurring. A smaller number leads to more blurring. The user should try values between 0.1 and 1.
 

References

Grigorieff, N., 2016. Frealign: An exploratory tool for single-particle cryo-EM. Methods Enzymol. 579, 191-226. doi:10.1016/bs.mie.2016.04.013

Liang, B., Li, Z., Jenni, S., Rahmeh, A. A., Morin, B. M., Grant, T., Grigorieff, N., Harrison, S. C., Whelan, S. P., 2015. Structure of the L protein of vesicular stomatitis virus from electron cryomicroscopy. Cell 162, 314-327. doi:10.1016/j.cell.2015.06.018

Automatic Refinement

This Auto Refine Actions panel allows users to refine a 3D reconstruction to high resolution using Frealign (Grigorieff, 2016) without the need to set many of the parameters that are required for manual refinement (see Manual Refine panel). In the simplest case, all that is required is the specification of a refinement package (set up under Assets), a starting reference (for example, a reconstruction obtained from the ab-initio procedure) and an initial resolution limit used in the refinement. The resolution should start low, for example at 30 or 40 Å, to remove potential bias in the starting reference. However, for particles that are close to spherical, such as apoferritin, a higher resolution should be specified, between 8 and 12 Å (see Expert Options).

Program Options

Starting Reference: The initial 3D reconstruction used to align particles against. This should be of reasonable quality to ensure successful refinement.

Initial Res. Limit (Å): The starting resolution limit used to align particles against the starting reference. In most cases, this should specify a relatively low resolution to remove potential bias in the starting reference.

Refinement Run Profile: The run profile used for particle alignment. This can be set to a large number if desired and CPUs are available, for example 300 or 1000. The alignment job will be divided into smaller jobs accordingly. The user is encouraged to test which number to use to achieve the best compromise between job time and resource requirements.

Reconstruction Run Profile: The run profile used for calculating 3D reconstructions. The reconstruction will be divided into multiple reconstructions, each using part of the data. A merge step at the end is then executed to calculate the final reconstruction. It is advisable not to use more than 50 - 100 CPUs for reconstructions to limit the number of intermediate reconstruction dump files. Writing and reading more than 100 will limit the speed of the job due to disk speed limitations and may also require large amounts of free disk space.

Expert Options

General Refinement

Low/High-Resolution Limit (Å): The data used for refinement is usually bandpass-limited to exclude spurious low-resolution features in the particle background (set by the low-resolution limit) and high-resolution noise (set by the high-resolution limit). It is good practice to set the low-resolution limit to 2.5x the approximate particle mask radius. The high-resolution limit should remain significantly below the resolution of the reference used for refinement to enable unbiased resolution estimation using the Fourier Shell Correlation curve.

Inner/Outer Mask Radius (Å): Radii describing a spherical mask with an inner and outer radius that will be applied to the final reconstruction and to the half reconstructions to calculate Fourier Shell Correlation curve. The inner radius is normally set to 0.0 but can assume non-zero values to remove density inside a particle if it represents largely disordered features, such as the genomic RNA or DNA of a virus.

Global Search

Global Mask Radius (Å): The radius describing the area within the boxed-out particles that contains the particles. This radius us usually larger than the particle radius to account for particles that are not perfectly centered. The best value will depend on the way the particles were picked.

Number of Results to Refine: For a global search, an angular grid search is performed and the alignment parameters for the N best matching projections are then refined further in a local refinement. Only the set of parameters yielding the best score (correlation coefficient) is kept. Increasing N will increase the chances of finding the correct particle orientations but will slow down the search. A value of 20 is recommended.

Search Range in X/Y (Å): The global search can be limited in the X and Y directions (measured from the box center) to ensure that only particles close to the box center are found. This is useful when the particle density is high and particles end up close to each other. In this case, it is usually still possible to align all particles in a cluster of particles (assuming they do not significantly overlap). The values provided here for the search range should be set to exclude the possibility that the same particle is selected twice and counted as two different particles.

Reconstruction

Autocrop Images? Should the particle images be cropped to a minimum size determined by the mask radius to accelerate 3D reconstruction? This is usually not recommended as it increases interpolation artifacts.

Apply Likelihood Blurring? Should the reconstructions be blurred by inserting each particle image at multiple orientations, weighted by a likelihood function? Enable this option if the ab-initio procedure appears to suffer from over-fitting and the appearance of spurious high-resolution features.

Smoothing Factor: A factor that reduces the range of likelihoods used for blurring. A smaller number leads to more blurring. The user should try values between 0.1 and 1.

Masking

Use Auto-Masking? Should the 3D reconstructions be masked? Masking can suppress spurious density features that could be amplified during the iterative refinement. Masking should only be disabled if it appears to interfere with the reconstruction process.

References

Grigorieff, N., 2016. Frealign: An exploratory tool for single-particle cryo-EM. Methods Enzymol. 579, 191-226. doi:10.1016/bs.mie.2016.04.013

3D Classification

For 3D classification, it is recommended in most cases to first refine with a single class (see "How do I start 3D classification?" in FAQs). This saves time since only one class is refined, and it ensures that the classes that emerge out of classification will be all be roughly aligned with each other, making it easier to recognize structural differences between the classes. However, if particles in a dataset vary significantly in size and structure, it may be better to refine with several classes from the beginning, skipping the refinement with a single class.

3D classification starts with the creation of a Refinement Package that specifies the number of desired classes. Follow the steps described in Refinement Package Assets and create a Refinement Package either using another Refinement Package as a template, or by creating one based on Particle Positions or 2D class averages. The number of 3D classes has to be specified in the field “Number of classes for 3D refinement” when running the Refinement Package wizard.

When using a Refinement Package as a template that has more than one class (from an earlier 3D classification), the wizard solicits a number of additional questions that allows the user to select which of the existing classes (particles and alignment parameters) will be used, and how to assign these classes to the classes in the new Refinement Package. A particle is assigned to the class for which it has the highest occupancy. Classes can be excluded from the new Refinement Package by answering No to “Carry over all particles?” The corresponding particles will be excluded from the newly created stack and subsequent refinement. All classes that are carried forward can then be assigned to the classes in the new Refinement Package. This step also allows the combination of several classes into a single new class. Therefore, using the wizard, all possible combinations of class selections and removals are possible.

To start refinement and classification with the new Refinement Package, use the Auto Refine or Manual Refine Action and select the new Refinement Package as the active input for the refinement. Active references for each of the classes in a Refinement Package can be selected or changed in the Assets panel, as well as in the Manual Refine Actions panel. When running Auto Refine, the starting references will always be generated from the parameters after randomizing the particle occupancies.

Settings

cisTEM can be run on a local workstation or remotely on a computer cluster. After installation, appropriate Run Profiles should be defined under Settings. The Settings panel can be used to manage Run Profiles that specify where cisTEM runs its jobs and how many jobs are run in parallel to speed up processing. cisTEM runs jobs through a job manager. A set of default profiles can be stored in a file called default_run_profiles.txt and placed into the bin directory containing the cisTEM executable. On startup, cisTEM loads the file and makes the Run Profiles available to all users. It is recommended to set up such defaults when cisTEM is installed to enable users to easily run jobs. cisTEM comes with a Run Profile to run on a local workstation with 20 CPU cores.

A Run Profile specifies the path for the manager command, as well as for the different job commands used to perform Actions (for example, Unblur, CTFfind). In the simplest case, all of these commands are located in the cisTEM bin directory and the bin directory is contained in the PATH environment variable. This will make the commands accessible by executing the name of the command without an additional path or directory. If the bin directory is not contained in the PATH environment variable, the full directory path has to be given (see below).

Run Profiles can be created, edited and deleted, imported from a file and exported to a file, for example default_run_profiles.txt. To create a new Run Profile, click Add next to the list of profiles on the left, then select the new profile from the list. Double-click on the name to rename it as desired. To create a profile that executes jobs locally, click on Add under the large Command box. This adds a line with the text $command and specifying a single copy with a 100 ms delay time. Double-click on the newly created line and edit the number of copies to run. When run locally, this should be the number of CPU cores available on the machine, plus 1 for the manager command. For example, if a workstation has 16 CPU cores, the number of copies to run should be set to 17 to make full use of the workstation. Click OK to accept the updated number of copies, then click Save to save the changes to the Run Profile. The Launch Delay does not usually have to be adjusted.

If the path to the cisTEM bin directory must be included (see above), add the full path to the manager command (the line with $command), double-click on the line in the large Command box and add the path again to the line containing $command. Click OK, then Save to save the changes.

The following lines provide examples of Run Profiles for more complicated computational infrastructure. Add the appropriate profiles to default_run_profiles.txt to make them available to all users. The examples assume that cisTEM is run on a workstation that has ssh access to the cluster head node. If this type of access is not available, it is recommended to run an interactive session on one of the cluster nodes. When the cisTEM GUI is run on a cluster node, the manager command line comes simply $command or /cisTEM_bin_directory/$command.

SGE cluster

Manager command

ssh -f head_node 'nohup /cisTEM_bin_directory/$command'

Job command

qsub -N cisTEM -j y -o  /dev/null -b y -cwd -V /cisTEM_bin_directory/$command

LSF cluster

Manager command

ssh -f head_node 'nohup /cisTEM_bin_directory/$command'

Job command

bsub -J cisTEM -n 1 -o /dev/null /cisTEM_bin_directory/$command

SLURM cluster with srun

Manager command

ssh -f head_node 'nohup /cisTEM_bin_directory/$command'

Job command

srun -n 1 -o /dev/null /cisTEM_bin_directory/$command

SLURM cluster with sbatch

Manager command

ssh -f head_node 'nohup /cisTEM_bin_directory/$command'

Job command

sbatch --export=c='$command' /cisTEM_bin_directory/slurm.sh

The slurm.csh script must be made executable (chmod +x slurm.csh) and contain the following lines:

#!/bin/bash
#SBATCH --nodes 1
#SBATCH --ntasks-per-node=1
#SBATCH --mem-per-cpu 5000
#SBATCH --time 120:00:00
#SBATCH --partition general
#SBATCH --mail-type=ALL
#SBATCH -o slurm.%j.out
#SBATCH -e slurm.%j.err
$c

SSH cluster

An "SSH cluster" is not a real cluster; it consists of independent workstations that are SSH-accessible and share diskspace. Using the following Run Profile, a job can be distributed over several workstations. The number of jobs to run on each workstation can be set for each job command line.

Manager command

ssh -f head_node 'nohup /cisTEM_bin_directory/$command'

Job command to include three workstations named machine1, machine2 and machine3

ssh -f machine1 /cisTEM_bin_directory/$command
ssh -f machine2 /cisTEM_bin_directory/$command
ssh -f machine3 /cisTEM_bin_directory/$command

Torque cluster

Please read Reply #7 of Forum topic "Unable to get a cisTEM job to parallelize on multiple nodes in cluster" for further details.

Database Commands

cisTEM stores all the meta data information in an SQLite database. This makes it possible to interact with the database using the sqlite3 command line program, and SQL commands. To open a database with sqlite3, simply run

sqlite3 my_database.db

Once connected, typing

.tables

(include the "."), will list all tables that the data is stored in, typing

.schema name_of_table

will give you information about what is in that particular table. It is fairly straightforward to manipulate the database with some experience with SQL. It is also possible to run an SQL query in a single line. This is useful for quick queries, or for incorporating the query into a script. In this case, simply run

sqlite3 my_database.db "desired command"

By default the output from a query will be returned using “|” as the separator between columns. This default behavior can be changed by providing the -separator argument, e.g. to run a query where the output is separated by spaces run

sqlite3 -separator ' ' database_name.db "desired command"

To quit sqlite3, type

.quit

Below are a number of examples for retrieving specific information from the database.

Images in a Group

The filenames and x,y positions of all particle position assets in a specific image group can be retrieved using the following procedure:

1) Determine the group ID for the desired group. Within sqlite3, run

select * from image_group_list;

(include the ";" at the end). This will produce a list of the image groups with their IDs in the first column.

2) Run the command below, replacing $group_id (it appears twice) with the ID of the desired group to obtain the filenames of all the members in the group:

select filename from image_assets, image_group_$group_id where image_assets.image_asset_id = image_group_$group_id.image_asset_id;

e.g. to obtain the filenames of all the images in group 1, type

select filename from image_assets, image_group_1 where image_assets.image_asset_id = image_group_1.image_asset_id;

Particle Positions

The filenames and x,y positions of all particle position assets can be retrieved by running (within sqlite3):

select filename, x_position, y_position from image_assets, particle_position_assets where image_assets.image_asset_id = particle_position_assets.parent_image_asset_id;

It is also possible to access only the particle position information for the particles in a given refinement package, or to compare particles between refinement packages. Determine the ID for the desired refinement package by running

select * from refinement_package_assets;

This will return a list of all refinement packages with their IDs in the first column. To return a list of all the original position asset IDs for a given refinement_package_id, use

select original_particle_position_asset_id from refinement_package_contained_particles_$wanted_id;

For example, to return all the positions for the refinement package with the ID 1, use

select original_particle_position_asset_id from refinement_package_contained_particles_1;

If there are two refinement packages, created from the same initial refinement package, the particles contained in both packages can be listed using

select refinement_package_contained_particles_$first_id.original_particle_position_asset_id from refinement_package_contained_particles_$first_id,refinement_package_contained_particles_$second_id where refinement_package_contained_particles_$first_id.original_particle_position_asset_id = refinement_package_contained_particles_$second_id.original_particle_position_asset_id;

For example, to return all particles contained in refinement packages 7 and 9, type

select refinement_package_contained_particles_7.original_particle_position_asset_id from refinement_package_contained_particles_7,refinement_package_contained_particles_9 where refinement_package_contained_particles_7.original_particle_position_asset_id = refinement_package_contained_particles_9.original_particle_position_asset_id;

Defocus Parameters

The defocus parameters for an image is contained in the image asset and can be found in the database table image_assets. The CTF parameters are in a table called estimated_ctf_parameters. To list filename followed by defocus1, defocus2, defocus_angle and phase_shift (from the active result if you have multiple CTF estimations) for all images, run

select image_assets.filename, estimated_ctf_parameters.defocus1, estimated_ctf_parameters.defocus2, estimated_ctf_parameters.defocus_angle, estimated_ctf_parameters.additional_phase_shift from image_assets, estimated_ctf_parameters where image_assets.ctf_estimation_id = estimated_ctf_parameters.ctf_estimation_id;

This will return the phase shift as radians, which is how it is stored in the database. SQLite allows math commands that can be used to convert the output. To list phase shift in degrees, use the command

select image_assets.filename, estimated_ctf_parameters.defocus1, estimated_ctf_parameters.defocus2, estimated_ctf_parameters.defocus_angle, (estimated_ctf_parameters.additional_phase_shift * 57.29578) from image_assets, estimated_ctf_parameters where image_assets.image_asset_id = image_assets.ctf_estimation_id = estimated_ctf_parameters.ctf_estimation_id;

System Requirements

Parallelization in cisTEM is achieved by running multiple instances of a process. For example, movie alignment is parallelized by running multiple instances of unblur (one of the programs in the cisTEM install directory) while particle refinement is parallelized by running multiple instances of refine3d. This means that job execution speed is roughly proportional to the number of CPU cores available to cisTEM. When running cisTEM on a computer cluster with many CPUs, execution times may also depend on network speed if running processes have to wait for data read from network disks. Given the speed of cisTEM, it is becoming increasingly feasible to carry out all processing on a local workstation, thereby diminishing the need for fast networking and access to computer clusters. The following provides some advice on how to design a workstation suitable to run cisTEM.

CPU

Given the parallelization scheme, the more cores are available, the better. The downloadable precompiled cisTEM executables are optimized for Intel Xeon processors. For example, a workstation with two Xeon E5-2699 v4 processors, each containing 22 cores, provides excellent processing power.

Memory

Most processes run by cisTEM do not require much memory (RAM). However, movie alignment and 3D reconstruction can be memory-intensive. For example, aligning a super-resolution movie with 50 frames and binned by 2 requires about 2.6 GB/process, and 11 GB/process if no binning is used. 3D reconstruction of a 512 x 512 x 512 pixel volume requires about 1.5 GB/process, and a 1024 x 1024 x 1024 pixel volume requires 12 GB/process. For most projects, the requirements will not exceed about 2.5 GB/process and, therefore, the workstation should be equipped with about 2.5 GB/CPU core.

Scratch Disk

To speed up processing, it is recommended to keep the project directory on a local scratch disk for fast disk access. Importing data after copying them to the scratch disk will further accelerate processing. The space requirement for movies often exceeds available scratch disk capacity but compression may help. For most projects, a 4 TB scratch disk will provide sufficient space for all files within the project directory. Ideally, the scratch directory is built as a RAID 0 using multiple smaller SSD disks. For example, a 4 TB disk could be built from four 1 TB SSD disks to create a very fast scratch disk. It is recommended to use enterprise-graded SSDs to allow for sustained high load.

Display

The minimum display size to run cisTEM is 1920 x 1080 pixels (high definition). Larger display sizes will improve the visibility of small details in images and plots.

Example System for Single Particle Processing

(Prices in $US, October 2017)

Example System for 2D Template Matching

(Grigorieff lab configuration, October 2024)