Parallel cryo electron tomography (PACEtomo) is a set of SerialEM scripts written in Python that allows the collection of an arbitrary number of tilt series in parallel via beam image shift. A key feature is the consideration of the sample geometry for the prediction of sample movement throughout a tilt series. Please refer to the publication (pdf) for more details.
PACEtomo has been tested on a variety of high-end JEOL (F200, cryoARM 300) and Thermo Fisher Scientific (Krios G2, G3i, G4) instruments using the dedicated computer for the Gatan K2 or K3 direct electron detector. The open-source microscope control software SerialEM should be installed and well calibrated.
PACEtomo does not require the installation of any stand-alone software. However, it does require SerialEM 4.1 or higher capable of running Python scripts.
You can run the following lines of code in a SerialEM script window to test if Python is configured correctly:
#!Python
import serialem as sem
sem.OKBox("Python works!")
If you get an error message, please consult the SerialEM website on how to setup Python for SerialEM.
Additionally, you will require several Python modules. I highly recommend using the miniconda package manager. This will require network connection. Please contact your responsible IT specialist if it's possible to temporarily allow network connection or setup a proxy.
If everything goes well, you can install all dependencies by downloading the SPACEenvironment.yaml file and running the following line the Anaconda Prompt:
conda env create -f <your path>\PACEenvironment.yaml
Alternatively, you can download the packages individually and install them using pip
. It might take some trial and error to satisfy all version compatibilities.
To let SerialEM access the correct Python environment, you have to adjust the PathToPython
entry in the SerialEM_properties.txt file to include the Python path to your environment. More info here!
If everything is set up properly, you can run this script inside a SerialEM script window without any errors:
#!Python
import serialem as sem
import numpy as np
from scipy import optimize
import matplotlib.pyplot as plt
import mrcfile
sem.OKBox("All necessary modules are installed!")
To use PACEtomo just copy the content of PACEtomo.py and PACEtomo_selectTargets.py as well as any auxiliary scripts you want to use in an empty SerialEM script slot each.
For optimal results, load the sample such that the lamellae are oriented with the milling direction perpendicular to the tilt axis (schematic for a Krios autoloader). Set up SerialEM low dose mode like you would for conventional tilt series acquisition. Make sure buffer O is outside the range of Roll Buffers (Buffer controls window). Offsets for Focus and Trial areas can be set to 0 to preserve specimen area. Make sure to set the appropriate tilt axis offset (more details below). It is recommended to do a coma-free alignment and a coma vs image shift calibration to minimise beam tilt for large image shifts (you might need a carbon film to get nice power spectra for CTF fitting). However, in most cases beam tilt will not be resolution limiting.
Before you run a PACEtomo acquisition, you must define the targets using the PACEtomo_selectTargets script.
Inside the script, there are several settings you can adjust before you start. If you set guidance
to True
, message boxes will guide you through the target selection procedure. Once you are familiar enough with the steps, you can set guidance
to False
which should streamline the setup.
When picking targets in close proximity, it is useful to keep the illuminated area in mind as the stage is tilting. Set drawBeam
to True
to show an approximation of the exposure on your sample around selected targets. You can set a fixed beamDiameter
or set it to 0
to use the IlluminatedArea value on Thermo Scientific microscopes. You can also adjust the simulated stretching of the beam for a tilted sample using the maxTilt
value.
There is a variety of ways to select targets and their suitability will be sample and personal preference dependent.
Manually: Selecting targets by dragging the image and centring features of interest.
targetByShift
and targetPattern
to False
.Fixed shifts: Selecting targets by specifying relative image shifts in specimen coordinates.
targetByShift
to True
. Set targetPattern
to False
.Pattern: Selecting a target pattern that can be applied to arbitrary stage positions.
targetPattern
to True
.alignToP
to True
.size
to the appropriate value n for your desired pattern (2n+1)x(2n+1), e.g. 2 for a 5x5 pattern.Polygon: Filling an area with a regular pattern of targets.
targetPattern
to True
and alignToP
to False
.vecA
and vecB
at (0, 0)
and set the rotation of the target grid using patternRot
. This will use the beam diameter to place targets far enough apart. Alternatively, you can define the grid vectors in specimen coordinates (µm, x along tilt axis).beamDiameter
setting to spread out the targets.maxTilt
setting is used to scale the distance between the targets perpendicular to the tilt axis.viewAli
to True
in the PACEtomo script to use the view images for initial target alignment.Virtual maps (experimental): Pick targets without taking new images.
noUI
to True
.SPACEtomo: Automatic target setup on lamellae.
All targets are saved in the navigator and a rootname_tgts.txt file is created. Target 1 is set to Acquire and the name of the rootname_tgts.txt file is saved in its Note entry.
Once target selection is completed a GUI will open showing a schematic of your targets and some additional information. This GUI will also open if you select a navigator item with an already associated target file and run the target selection script. It allows you to view, edit, add targets and specify settings for acquisition.
The main components are a list of all targets with associated file names, image shifts and skip flag, and a plot of all targets with the origin at the tracking target.
You can select targets by left clicking them in the list or in the plot. Right clicking targets in the plot toggles their skip flag. While you cannot delete targets, setting skip to True ensures they will be ignored during acquisition.
Make Track can be used to make the selected target the tracking target instead. This requires some realignment and hence, additional Preview exposures on the new tracking target. Use with caution!
Load Map prompts you to enter a navigator label and will load the associated map in SerialEM. This is useful when you want to load a montage to get an overview over your target area. It will also load a binned version of the map inside the GUI and roughly align it with the target plot. This is meant to give you a better idea to choose points for geometry measurement. If you want to inspect target placement, please refer to the map loaded in the SerialEM window.
Add Targets will realign to your tracking target and re-enter the target selection loop.
Save Views will take a View image at every target position and save it as a map. It will also save a JPG snapshot of the map with all navigator items marked. This might be useful to revisit the wider context of a tomogram after reconstruction. In the future, these view images containing centred targets could be potentially used to train a neural network for automated picking of target regions.
If you used SPACEtomo to setup targets, each target received a score. Color by Score will use this score to color the targets according to their score.
Reorder will read the current order of targets displayed in the list. You can change the order by dragging and dropping.
Copy to Acq is only accessible when targetPattern was used for target selection. It will copy the target file for all points in the navigator that have been set to acquire (excluding points already associated with a target file).
Save will save all changes to the target file. Reset will reset changes made since the GUI was opened (except changes to the tracking area).
Settings can be saved in the targets file and overwrite values given in the PACEtomo.py script.
Another feature of the GUI is the Measure geometry procedure. This automates the estimation of pretilt and rotation on your sample. Basically, it measures the defocus at >3 points on the sample and fits a plane to estimate values for pretilt and rotation. You can select these points directly on the plot using the middle mouse button. Make sure to avoid targets to prevent additional exposures of areas of interest. Ideally, five or more points should be spread evenly across the sample area while dark spots, ice chunks and holes are avoided. You can reset the point selection using the Reset geo pts button and once you selected your points you can press Measure geometry. The estimated pretilt and rotation will be filled into the associated text fields, but you still have to save them to the targets file.
For targetPattern selections geo points are automatically suggested. However, geometry values might not be applicable if you plan to use the pattern on different stage positions. For that purpose, the PACEtomo.py script has an automated routine using the suggested points to measure the geometry at every stage position before starting the acquisition (more details below).
In the bottom left you can find the visual controls for the plot.
On the right, you can find Toggle beam to show or hide the beam diameter visualization, and buttons to swap or mirror the axes to make the plot fit your SerialEM view.
If you made any changes, please don't forget to click Save. Once you are done you can close the window and a message box will tell you the number of selected targets.
Caution: Only target 1 of each PACEtomo acquisition area should be set to Acquire!
PACEtomo runs a grouped dose-symmetric tilt scheme. Before starting the PACEtomo collection, please check the settings inside the PACEtomo.py script. Most settings are self-explanatory, but here is a more detailed description for some of them:
startTilt
in degrees is usually 0 or, in case of a lamella, the compensating tilt for the pretilt
(in case of a pretilt
of -10 degrees, a startTilt
of 10 degrees can be used). The startTilt
has to be divisible by the tilt step
.minTilt
, maxTilt
and step
values in degree. The tilt series branches do not have to be symmetrical.groupSize
parameter. stepDefocus
) for each target. If you want to use the same target defocus, keep minDefocus
and maxDefocus
the same.focusSlope
to compensate in subsequent acquisitions. Alternatively, refine the tilt axis offset to minimise the slope. When using SerialEM’s fine eucentricity routine to obtain a tilt axis offset, a significant focus slope remains. You can use the PACEtomo_measureOffset.py script to get a PACEtomo optimised estimate for the tilt axis offset.zeroExpTime
can be a custom exposure time in seconds for the first tilt image. This can be useful for hybrid processing approaches. When set to 0
the same exposure time will be used for all tilt angles.zeroDefocus
can be a custom target defocus for the first tilt image. When set to 0
the same target defocus will be used for all tilt angles.Track settings:
trackExpTime
allows for a custom exposure time used only for the tracking tilt series. When set to 0
the same exposure time will be used for all tilt series.trackDefocus
allows for a custom defocus value used only for the tracking tilt series. When set to 0
the same defocus range will be used for all tilt series.trackMag
allows for custom magnification used only for the tracking tilt series. This should only be necessary on bad stages.trackTwice
is set to True
, a second tracking image might be taken in case of a large shift. This causes significantly more exposure on the tracking tilt series and should only be necessary on bad stages.Geometry settings:
pretilt
of the lamella (if applicable) is determined during the focused ion beam milling process and is usually between 8-15 degrees. The sign is important and depends on the orientation in which the grid was loaded into the microscope. For example, in case of a FIB milling angle of 10 degrees: If the lamella appears thinner/brighter at +10 degrees stage tilt angle, the pretilt value should be -10 degrees and vice versa. (It is recommended to load lamella containing grids consistently in the same orientation.) You can use the measure geometry routine in the target selection GUI to get an estimate of your lamella (or holey support) geometry.rotation
should be 0 degrees. If there is a residual rotation you can estimate and enter it for the initial estimation of the eucentric offset (CCW = positive).measureGeometry
to True
will allow PACEtomo to estimate the sample geometry immediately before acquiring an area. For target patterns, the script will automatically determine five points between the targets to measure the defocus and estimate the pretilt and rotation values of the sample support. This can be useful for bent sample supports exhibiting varying geometries from grid square to grid square. It should be avoided if the pattern is tight and additional exposures within the grid would overlap with target positions. It is also needed for SPACEtomo.Holey support settings:
tgtPattern
to True
. Additionally, set alignToP
to True
if you saved a hole template to buffer P to use for target alignment.refineVec
is set to True
, PACEtomo uses the template in buffer P to refine the grid vectors of the target pattern at the current position. The grid of holes can vary slightly from grid square to grid square, which can become problematic for large target patterns (7x7 or larger).refineGeo
is set to True
, PACEtomo will try to refine the sample geometry model after the first Record image of every target was taken. It will use the defoci determined by CTF estimation to fit a plane or paraboloid and overwrite the previously determined geometry estimation. This is useful for large target patterns (7x7 or larger) on bent or wavy support film. More settings for refineGeo
are mentioned below.Session settings:
beamTiltComp
should be set to True
if you did the coma vs image shift calibration.addAF
to True
you can add additional autofocus routines on target 1 at every branch switch of the dose-symmetric tilt series. This should help keeping the defocus spread low at the cost of overexposing the tracking tilt series.previewAli
can be set to True
if you want to align every target to its saved Preview image. This helps to keep your target centred if your startTilt
is not 0. If your field of view is large and your feature of choice does not have to be centred precisely, previewAli
can be set to False
to reduce the initial dose on your targets. previewAli
can also be used for a “targetPattern” if the grid is not very regular and vectors alone are not precise enough. In this case you should also have alignToP
set to True
.viewAli
works similar to previewAli
but only uses a View mag image for initial alignment to save exposure on the targets. If you rely on View images taken with high defocus offset, it is recommended to do the "High-Defocus Mag" and especially the "High-Defocus IS" calibrations. It is also used for SPACEtomo.Advanced settings:
sortByTilt
to True
. This will also resort the accompanying mdoc files, but keep unsorted versions for dose filter considerations.doCtfFind
is set to True
. It is fast, but not very reliable especially at higher tilt angles. IMOD's ctfplotter is more robust and now also integrated in SerialEM. You can use it by setting doCtfPlotter
to True
. Currently, CTF estimation is only used for refineGeo
.refineGeo
, fitLimit
is the resolution cut-off beyond which CTF estimates will not be considered for the geometry refinement routine. parabolTh
is the minimum threshold of available CTF estimates to fit a paraboloid instead of a plane.imageShiftLimit
will overwrite this SerialEM property. The maximum amount of image shift is system dependent and the limit for Thermo Scientific TEM systems is always somewhere below 25 µm.dataPoints
used for the calculation of the eucentric offset of each target was kept at 4 throughout all experiments. Changes could be beneficial to performance but have not been extensively explored.alignLimit
should keep the cross-correlation alignment in check in cases of low contrast. On good stages the alignment error should never be worse than 0.5 µm.minCounts
greater than 0, a branch of a target can be terminated independently if the image mean counts were below the threshold. The counts are considered per second of exposure and the ReportExposure
command in SerialEM 4.0+ is used to obtain the exposure time.ignoreFirstNegShift
usually improves the alignment of the first tilt images from the negative branch and should generally be set to True
.slowTilt
should only be set to True
if you need additional tilt backlash corrections for the positive tilt branch, which should not be necessary for good stages.taOffsetPos
and taOffsetNeg
allow you to apply additional tilt axis offsets for positive and negative branches, respectively (as used for the side-entry holder dataset in the manuscript). These offsets are applied on top of the global offset set in SerialEM and are only used for the internal calculations.extendedMdoc = True
saves additional information like estimated defoci from CTF fitting, specimen shifts and eucentric offset estimations to the mdoc files.checkDewar
will check if the microscope dewars are filling before taking a Record image. (Can cause weird behaviour on some microscope without a dewar.)cryoARM = True
to always fill both dewars at the same time.coldFEG = True
to flash the gun regularly according to the flashInterval
in hours. (On a Krios, the interval is ignored and the FlashingAdvised function is used instead.)slitInterval
to a number (in minutes) greater than 0, the script will move to a position out side the target pattern to run RefineZLP before continuing acquisition.Target montage settings:
tgtMontage
to True
and set the size and overlap with tgtMntSize
and tgtMntOverlap
, respectively. The montage uses the shorter camera length to determine the tile displacement. This was implemented for use with a square beam (square C2 aperture).tgtMntFocusCor
lets you apply an additional focus offset between the tiles to compensate for the tilt angle dependent z-offset. This might require additional processing considerations when reconstructing the tomogram.tgtTrackMnt
determines if the tracking tilt series should also be a montage or not.Any numerical setting in the script can be overwritten by settings in the target file (rootname_tgts.txt). This allows for varying settings during batch acquisition of several PACEtomo areas. To overwrite a setting add a line like _set varName = numericalValue
at the beginning or end of the targets file.
You can run the PACEtomo acquisition script either by selecting the entry of target 1 in the Navigator (its Note entry contains rootname_tgts.txt) and pressing Run in the script window or you can run it in batch via the Acquire at Items... dialogue. In the latter case, you can uncheck any eucentricity and realign checkboxes as the script will take care of it.
In case you want to run PACEtomo on a regular grid targetPattern, you can set all desired tracking stage positions to Acquire in the navigator and run the PACEtomo_selectTargets.py script on the original navigator item. Within the GUI, you can click Copy to Acq to copy the target file to all marked points. Alternatively, you can copy the targets file manually and edit the Note entry of all target positions to contain the target file name.
All files are created in the folder you specified during target selection. Target images have the suffix tgt_xxx and collected tilt series have been saved with the suffix ts_xxx and their accompanying .mdoc file. Additionally, a rootname_tgts_runXX.txt is created containing all information to restart an acquisition after it was aborted or crashed. The .log file is saved for every PACEtomo run individually.
In case a PACEtomo run crashes or is aborted, you can attempt to recover and resume the acquisition. Run the PACEtomo.py script on the same navigator item and if a run file is present, it will ask you if you want to recover the run. Recovery will likely not track as accurately as a continuous run for the first few images. Especially if time passed or the stage was moved between crash and recovery attempt.
If you feel confident in the recovery capabilities, you can stop an acquisition, run the PACEtomo_selectTargets.py, use the GUI to set targets to be skipped or even change the tilt angle range, and resume the acquisition.
SerialEM usually estimates the tilt axis offset using y-displacements measured during the fine eucentricity routine, which yields suboptimal results for PACEtomo. This script will estimate the tilt axis offset optimized for movement along the z-axis during tilting (Thanks to Wim Hagen for the suggestion!). It will use SerialEM's autofocus routine to measure the z-height at 3 (or more) positions (on tilt axis and ± the given offset
) throughout a limited tilt series (given by increment
and maxTilt
). The results should be within 0.1-0.2 µm of the optimal position for PACEtomo and you can adjust it depending on the focus slope you observe during a PACEtomo run.
maxTilt
and tilt increment
for more or less datapoints used in the estimation.This script uses a group of navigator points, measures the z-height using the autofocus routine at these points and estimates pretilt and rotation values for the sample assuming all points are on a plane. These values should give you an estimate of the sample geometry, but don't account for sample deformations. The more points you select, the better the fit should get (5-9 data points should be sufficient).
A selection of video tutorials was uploaded to Youtube. These were recorded using older versions of PACEtomo and some features and settings might be missing. The general workflows, however, remain the same.
imageShiftLimit
setting in the PACEtomo acquisition script accordingly.checkDewar
to False
.More bug fixes and quality of life improvements.
More bug fixes and quality of life improvements.
Mostly small fixes and quality of life improvements.
Mostly small fixes and quality of life improvements.
This update includes mainly options for more robust tracking (e.g. for cryoARMs), CFEG functions and bug fixes.
Notes:
When using lower mag tracking, make sure the record beam settings still cover the camera!
The CFEG flashing for TFS instruments was not tested!
Added mag offset for tracking tilt series.
Added trackTwice option to take a second tracking shot if the alignment was bad.
Output file containing all script settings.
Fixed progress not considering skipped targets.
Added check for existence of ComaVsIS calibration.
Added overwriting of existing tilt series file when restarting an acquisition (not for recovery).
Changed initial target alignment of targetPattern collection to only use View mag.
Added defocus offset for previewAli to boost contrast.
Added specimen coords obtainable from stage coords in tgts file. This allows for more flexible creation of tgts file in dummy mode.
Switched from targeted tilt angle to microscope tilt angle value when predicting specimen movement.
Added sanity check warning boxes.
Added functions for CFEG flashing.
Minor text fixes.
Lots of bug fixes, addition of target setup from polygons and initial grid vector estimation.
This script can use a medium mag montage to crop out virtual maps as targets (similar to py-EM). It is still experimental and works decently well on high-contrast features. Huge thanks to Zhengyi Yang for doing a lot of testing and troubleshooting!