subtomosetup(1) General Commands Manual subtomosetup(1)
NAME
subtomosetup - Sets up command files for reconstructing multiple sub-
volumes
SYNOPSIS
subtomosetup options
DESCRIPTION
Subtomosetup creates a set of command files for directly reconstructing
multiple numbered subvolumes from an aligned tilt series. Its main use
is to allow subtomogram alignment and averaging to be done on unbinned
data after selecting particle positions on a binned-down tomogram,
without having to build a full unbinned tomogram. It also allows one
to apply CTF correction to the aligned stack for a series of Z depths
in the tomogram, and use the appropriate corrected stack in recon-
structing each subvolume. Note that if the unbinned tomogram already
exists, the program Boxstartend can be used to extract subvolumes
from it.
Rules of Operation
The program allows considerable flexibility as long as several restric-
tions are followed.
1) The program must be run from the dataset reconstruction directory.
2) The raw tilt series stack must still be present. Alternatively, a
file with the same name as the stack containing just the header can be
used.
3) The new aligned stack must already be made at the desired size and
binning.
4) The tomogram on which points were selected for reconstruction must
be available and entered with the -volume option, although it need not
be in the current directory. Alternatively, a file with just the
header of this volume can be supplied.
5) The tilt series alignment, tomogram positioning parameters, the X-
axis tilt, and the tilt angle offset in the Tomogram Generation panel
of Etomo must not be changed between the binned tomogram and subvolume
reconstructions. Whether to use a GPU may be changed, and the current
choice will determine whether a GPU is used for the reconstructions.
6) If you apply any processing to that volume outside of Etomo, the
header entries for pixel spacing, origin, and tilt angles must be pre-
served in the file entered with the -volume option. If you need to
trim some more, use Trimvol; if you need to bin, use Binvol.
7) If you need to apply other software that does not preserve these
header entries, follow these procedures: Make sure that the file ana-
lyzed has the same dimensions as the IMOD-based file from which it was
derived. Enter the name of the IMOD-based file instead of the analyzed
file with the -volume option. Supply a point coordinate file instead
of a model file for the -center option (use Model2Point(1) with the
-float option to make such a file). Other alternatives are to load a
model onto the IMOD-based file with the -m option and save it again, or
to run Imodtrans on a model with the -image option and the name of
the IMOD-based files, and use the resulting model.
To make a file with a copy of the header from the raw stack or modeled
volume, you can use the script "copyheader" with two arguments: the
name of the input image file and the file in which to write the header,
e.g.:
copyheader setname.st setname_header.st
You are free to make an aligned stack from a centered subarea or an
over-sized area and to change this area between the binned and subvol-
ume reconstructions. You can apply any trimming options in the Post-
processing panel in Etomo. Note that the subvolumes will be reoriented
the same way that the binned tomogram was.
3-D CTF Correction
3-D CTF correction is activated with the -zlevels option, which speci-
fies the number of levels in Z at which to compute CTF corrections, or
with the -extent option, which sets the range in Z over which each CTF
correction is used The total Z range of the subvolume centers will be
divided into levels based on one or the other entry, and each subvolume
will be reconstructed from the aligned stack for its Z-level. The com-
mand files are set up to process the Z-levels in order, with the CTF-
corrected stack from the previous Z-level deleted before going on to a
new Z-level. The command file for correction ("ctfcorrection.com" by
default) must already include the necessary options before running this
program, including the correct pixel size for the aligned stack. The
aligned stack must not already be CTF-corrected, but it may have gold
fiducials erased already. Alternatively, fiducials can be erased in
each corrected stack with the -erase option. If so, the command file
for erasing ("golderaser.com" by default) must also have the correct
options before running this program.
A GPU can be used for both correction and reconstruction, for neither,
or for correction but not reconstruction. If the reconstruction com-
mand file specifies use of the GPU, then it will be used for CTF cor-
rection as well, regardless of the setting in the command file for cor-
rection. However, if reconstruction is done on CPUs instead, the set-
ting in the correction command file determines whether correction is
done on a GPU. It may be more efficient to do correction on one GPU
even when many CPUs are available, because correction with CPUs will be
split into many jobs to be run in parallel, which incurs some overhead
and delays. When correction is done on CPUs, the operation will be
split up by assuming there are 8 CPUs, unless a specific number is
specified with -proc. Also, if reconstruction is set to be done on a
GPU, correction (on the GPU) will be split into jobs when -proc is
entered with a value higher than 1.
If an X-axis tilt is included in either the reconstruction or correc-
tion command files, then the program evaluates whether it is similar
enough in the two operations. If an X-axis tilt is being applied at
all during correction, it should closely match the value used for
reconstruction, otherwise the program gives a warning. If there is an
X-axis tilt in reconstruction but not correction, the program will
determine the maximum difference in defocus produced by the two differ-
ent X-axis tilt values, which occurs at the extremes of the reconstruc-
tion in Y. If this defocus is larger than a certain fraction of the Z-
level extent, the program issues a warning.
Chunks, Subvolumes, and Running the Jobs
Subtomosetup generates command files named with the root name of the
Tilt command file ("tilt" by default) plus "-sub-001.com", etc. By
default, each command file will produce ten subtomograms named "root-
name-N.mrc" where "rootname" is the dataset root name, and "N" is a
number that increases sequentially for all subvolumes computed, but
with enough leading zeros so that all files have the same number of
digits and will list in order. The numbers will be in the same order
as the points in the model or point file, but with 3-D CTF correction,
they will not be computed in order. If a position is too close to the
top or bottom of the Y-extent that can be reconstructed from the cur-
rent aligned stack, the particle will be skipped, but output files will
still be numbered sequentially unless the -skip option is entered. For
positions not quite so close to the limits in Y, a Tilt run will be
included to generate a subvolume with up to 1/6 of the extent blank in
that direction.
Multiple Tilt runs are put in each command file in order to reduce
the overhead in starting and monitoring commands, and to reduce the
number of .com and .log files in the directory. The division of runs
into jobs can be controlled by the -proc and -runs options. When doing
3-D CTF correction, runs at each Z level are apportioned into chunks
using the same strategy, but with the same target for the total number
of reconstruction chunks.
The command files can be run with Subm, Processchunks, or the
generic parallel processing interface in Etomo. For example
subm tilt-sub*.com
to run all files in sequence, or
processchunks 8 tilt-sub
to run in parallel on 8 processors, as can also be done in the Etomo
interface. A GPU will be used if specified in the original command
file. The Etomo interface can be used to run on multiple GPUs located
on different machines, but to run on multiple GPUs in one machine, pro-
cesschunks must be run directly, such as with
processchunks -G localhost:1:2:3
OPTIONS
Subtomosetup uses the PIP package for input (see the manual page for
pip). Options can be specified either as command line arguments
(with the -) or one per line in a command file (without the -).
Options can be abbreviated to unique letters; the currently valid
abbreviations for short names are shown in parentheses.
-root (-ro) OR -RootName Text string
Root name of dataset. For one axis of a dual-axis data set,
include the "a" or "b" in this name. This option is required.
-center (-ce) OR -CenterPositionFile File name
Name of an IMOD model file or a point coordinate file with the
center positions of the desired subvolumes. A point coordinate
file should have one point per line, with its X, Y, and Z coor-
dinates separated by spaces, not commas. These coordinates
should correspond to pixels in the full file specified with
-volume, where the first pixel in any dimension spans coordi-
nates from 0 to 1. This option is required.
-volume (-v) OR -VolumeModeled File name
Name of the image volume in which points were selected. If a
model file is supplied for the -center option, this entry should
be the image volume that was modeled. If a point coordinate
file is supplied with -center, the coordinates must correspond
to pixel positions in this volume file. This option is
required.
-objects (-o) OR -ObjectsToUse List of integer ranges
If only a subset of objects in the model contain points to be
reconstructed, this option can be used to enter a list of those
objects (comma-separated ranges are allowed).
-size (-si) OR -SizeInXYZ Three integers
Final size of subvolumes in X, Y, and Z, in unbinned pixels. If
the modeled volume was reoriented by rotation or flipping, sub-
volumes will be treated similarly, and this entry specifies the
size after reorienting. If the aligned stack is binned, the
actual size will the specified size divided by its binning.
This option is required.
-dir (-d) OR -DirectoryForOutput File name
Name of directory to place subvolumes into. By default, the
subvolumes will be written into the dataset directory; this
option can be used to place them in a subdirectory or, in fact,
in a directory located anywhere. If the directory does not
exist yet, it will be created.
-skip (-sk) OR -SkipSubVolNumbers
Skip subvolume numbers whenever points near the border of the
volume are skipped, thus keeping the subvolume and point numbers
in register even when points are skipped. The default is to put
out sequentially numbered subvolumes with no gaps, which is
required when processing the subvolumes in PEET with template
specifications for a series of volumes.
-com (-co) OR -CommandFile File name
Starting command file for running Tilt to make the reconstruc-
tions. The default is to use "tilt.com", so this option is
needed for a dual-axis data set or to use a copy of the file.
-zlevels (-z) OR -NumberOfZLevels Integer
Number of different depths in Z at which to make CTF-corrected
aligned stacks. Either this option or -thickness must be
entered, but not both. This entry must be at least 2.
-extent (-ex) OR -ExtentOfZLevelsInNm Integer
The maximum depth in Z over which to use one CTF correction, in
nanometers nanometers. This value, if entered, must be less
than the maximum distance in Z between subvoluyme centers, so
that at least two CTF corrections are computed.
-ctfcom (-ct) OR -CorrectionComFile File name
Command file for CTF correction, which can be entered with or
without its extension of ".com". If this option is not entered,
"ctfcorrection" will be substituted for "tilt" in the name of
the command file for reconstruction.
-erase (-er) OR -EraseFiducials
Run a command file to erase gold after CTF correction of the
aligned stack. Gold may be erased in the aligned stack prior to
CTF correction, but this option can be used to erase after cor-
rection, which is the preferred order of operations in Etomo
and Batchruntomo. That order is better in principle but may
make little difference in practice.
-goldcom (-g) OR -GoldEraserComFile File name
Name of command file to use for erasing gold after CTF correc-
tion, which can be entered with or without its extension of
".com". If this option is not entered, "golderaser" will be
substituted for "tilt" in the name of the command file for
reconstruction.
-reorient (-re) OR -ReorientionType Integer
This option can be used to specify the type of reorientation
that was applied to the original reconstruction to obtain the
modeled volume, in the unlikely event that the program cannot
detect which was used. Reorientation by rotation around the X
axis can be detected by the tilt angles in the volume header;
swapping of Y and Z can be detected only if the "clip: flipyz"
title is still present. If necessary, the program will assume
that swapping occurred if the Y dimension is more than twice the
Z dimension, or that no reorientation occurred if the Z dimen-
sion is more than twice the Y dimension. If the program makes a
wrong assumption or insists that this option be used, enter a 0
for no reorientation, 1 for swapping of Y and Z, or -1 for rota-
tion around X.
-proc (-p) OR -ProcessorNumber Integer
Number of processing units, either CPUs or GPUs, that the jobs
will be run on. The program will divide the jobs into 10 com-
mand files (chunks) per processor if this results in fewer than
1000 chunks, or with fewer chunks per processor, down to 5, in
an attempt to keep the number of chunks under 1000.
-runs (-ru) OR -RunsPerChunk Integer
Number of Tilt runs per command file (chunk). The program will
create chunks with this number of runs, or with more runs to
keep the total number of chunks under 100,000. This option can-
not be entered with -proc. The default is 10.
-help (-h) OR -usage
Print help output
-StandardInput
Read parameter entries from standard input
FILES
All temporary files are removed by each command file as it runs, and
command and log files except "-finish.log" file are removed by the
"-finish.com" file.
AUTHOR
David Mastronarde
SEE ALSO
tilt, subm, processchunks, boxstartend, trimvol, bin-
vol(1), model2point, imodtrans
BUGS
Email bug reports to mast at colorado dot edu.
IMOD 4.11.0 subtomosetup(1)