sirtsetup(1) General Commands Manual sirtsetup(1)
NAME
sirtsetup - Produce multiple command files for iterative reconstruction
SYNOPSIS
sirtsetup [options] Tilt_command_file
DESCRIPTION
Sirtsetup sets up command files to do a form of Simultaneous Iterative
Reconstruction Technique (SIRT) using backprojection and reprojection
with the Tilt program. Because reprojection is done with Tilt
and not Xyzproj, the reconstruction can include options such as
local alignments and Z factors. The SIRT uses the following scheme:
1) An initial reconstruction is computed, using a filter function
that is either flat or a mixture of flat and R-weighted.
2) The reconstruction is reprojected with Tilt.
3) The original projections are subtracted from these reprojections.
4) This reprojection difference is backprojected with a flat filter
function and appropriate scaling to distribute differences among the
pixels along a ray.
5) The error reconstruction is subtracted from the initial recon-
struction.
To iterate, steps 2 through 5 are repeated with the original recon-
struction replaced by the corrected reconstruction created in step 5.
These steps can all be done within Tilt provided that a single
reconstructed slice backprojects from, and reprojects to, a set of
lines at one Y value in the input projection images. When this is the
case, all of the selected iterations are done internally as much as
possible, and the results are written to files only at the iterations
that you specify. This one-to-one relationship does not exist when
there are Z-factors (produced by the stretching solution in Tiltal-
ign(1) unless you choose not to use them), variable X-axis tilt (needed
when correcting for beam tilt), or local alignments. In any of those
cases, steps 2 and 3 are done in Tilt and the entire reprojection
difference must be written to file, then steps 4 and 5 are done in
another run of Tilt and the new reconstruction must be written to
file again. Thus, on each iteration a file is produced by step 5,
named setname_srec00.mrc, setname_srec01.mrc, etc. (or setname.srec00,
setname.srec01, etc. with old descriptive extension naming style)
After running some iterations of SIRT, it is easy to do additional
iterations simply by running this script again.
For data sets with X-axis tilt where the iterations are done inter-
nally, the default is to save the untilted slices that were computed in
a file separate from the reconstruction slices, which are obtained by
interpolating from the untilted slices. This capability is crucial
when saving data from several different iterations with cryoEM data
sets, because otherwise the multiple interpolations of the data blur
out the reconstruction and lead to instabilities. When doing a large
reconstruction, this secondary output can be suppressed with the "-sk"
option (see below). Edge effects may still build up with cryoEM data
when the computations are stopped and restarted several times, so it is
recommended that the full reconstruction be produced in a single run
after the desired number of iterations is determined. These considera-
tions do not apply (and no vertical slice file is produced) when there
is no X-axis tilt or when there is a beam tilt correction or other
alignment features that prevent Tilt from running the iterations
internally.
To prevent some edge effects, Sirtsetup sets a value for the MASK
option to Tilt, which is the X size of the input tilt series divided
by 500, or at least 2 pixels. However, if a larger value is found in
the Tilt command file, that will be used instead.
Sirtsetup is meant to be used with a command file for running Tilt
that has all of the entries produced when running through Etomo. There
is one main restriction on this file. The reconstruction must be the
same size in X and Y as the aligned stack; this means both a SLICE
entry and a WIDTH entry will be ignored if present. In addition, an X
shift specified with the first value in a SHIFT entry will also be
ignored. Sirtsetup does allow you to reconstruct a subarea that can be
offset in Y (along the tilt axis) but must be centered in X. It
extracts the specified subarea from the full aligned stack into a new
stack that is used for the reconstruction, and adjusts the SUBSETSTART
entry in the tilt command file to indicate the starting coordinates of
this subarea. Note that with this subarea option, the reconstruction
and intermediate files are named differently so that they are distinct
from files for a full reconstruction (see FILES).
Displacing a subset laterally is more complicated because it would
require: 1) running Tiltalign with the AxisXShift option specifying
the offset; 2) making the subarea from the raw stack with Newstack,
using the same X offset in the -offset option; 3) adding the same off-
set as a second number in the OFFSET entry to Tilt, as well as
adjusting the X component of SUBSETSTART.
If the tilt command file takes the log of the projection data and the
iterations are not being done internally in Tilt, then the starting
command file will use Densnorm to create a new stack with the loga-
rithm of the projections. This log stack will be used in all of the
operations listed above. Such a stack is not needed for internal oper-
ations.
If you are not taking the log, you may still want to scale the projec-
tion data to provide a mass normalization. You can do this with Den-
snorm(1). If you just want a relative normalization to compensate for
different exposures, you have two choices: 1) Use Densnorm to create
a normalized stack, then either rename it to the aligned stack name or
modify the input file name in the tilt command file. 2) Use Den-
snorm(1) to create a file with weighting factors, and add a WeightFile
entry to the tilt command file. If you want an absolute normalization
so that you can experiment with constraining the data to be positive or
negative, then you need to create a normalized stack and either rename
it to the aligned stack name or change the input file name in the com-
mand file. If you use Densnorm to normalize the data absolutely,
they will be negative values, in which case the -zn option would be
used to constrain the reconstruction to negative values.
If the name of the command file is tiltroot.com, this script produces
files named tiltroot_sirt-*.com. These files can be run from the com-
mand line with
processchunks machine_list tiltroot_sirt
or from the generic parallel processing interface in Etomo.
Whenever a difference reconstruction is computed, its mean and standard
deviation of the central portion are determined and output to the log
file for the individual Tilt run. The summary values from these
statistics are gathered in the tiltroot_sirt-finish.log file. If the
reconstruction was done in chunks, there will be multiple lines for
each iteration. The last two numbers on each line are the mean and the
standard deviation of the difference reconstruction. The fall in the
latter value provides some indication of the progress of the itera-
tions.
OPTIONS
Sirtsetup 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.
-co OR -CommandFile File name
Command file for reconstruction, which can be entered with or
without its extension of ".com". If this option is not entered,
a non-option argument is used for the command file. If the root
name of this file ends in "_for_sirt" and the processing is not
starting from the zero iteration, that ending will be stripped
from the command files produced.
-naming (-na) OR -NamingStyle Integer
0 if image files have descriptive extensions like ".preali", or
1 or 2 if descriptive text is before the extension ".mrc" or
".hdf". This entry is needed only if the style cannot be deter-
mined from files in the dataset.
-nu OR -NumberOfProcessors Integer
Use this option to specify the number of machines that you
expect to run the command files on. It is passed directly to
Splittilt unless it is 1, in which case the processing is not
divided into chunks. The default is 8 unless the command file
contains the option to use the GPU, in which case it is 1.
-ra OR -ChunksPerProcessor Integer
Use this option to set the number of chunks per processor; it
will be multiplied by the number of processors to give a value
for the -TargetChunks option to Splittilt.
-st OR -StartFromZero
Do an initial reconstruction, numbered 00, even if it or later
reconstructions already exist. The default is to iterate from
the last existing reconstruction.
-re OR -ResumeFromIteration Integer
Resume from the given iteration rather than from the last one.
You can resume from any iteration that has a .srec file, but not
from ones for which there is only a scaled integer or trimmed
file.
-it (-i) OR -IterationsToRun Integer
Set the number of iterations to run. If this option is not
entered, the number that will be run depends on whether the
LeaveIterations option is used. If it is not, 10 iterations
will be done. If it is, iterations will be done up to the last
interation number in the list being left.
-le (-l) OR -LeaveIterations List of integer ranges
Leave reconstructions at the listed iterations, which are num-
bered by absolute iteration number. For example, if 10 itera-
tions have already been done and you are doing another 10,
entering 14,17-19 will retain the reconstructions named set-
name.srec14, setname.srec17, etc, produced at the 4th, 7th, 8th
and 9th new iteration. In addition, the reconstruction from the
final iteration is always retained.
-sk OR -SkipVertSliceOutput
Do not make the vertical slice output files that are needed for
resuming without interpolation when SIRT is done internally. If
the iterations will be run internally in Tilt and there is a
non-zero X-axis tilt, the default is to create an output file
containing the internal, vertical slices along with every regu-
lar reconstruction file. When resuming for the next iteration,
using such a file avoids the effects of interpolating twice
between internal slices and reconstruction slices. These
effects are much more severe for cryo data than plastic section
data. Use this option if storage space is an issue and if you
are leaving one iteration that you do not anticipate resuming
from. The entry is irrelevant if you have Z-factors, local
alignments, no X-axis tilt, or varying X-axis tilt resulting
from solving for beam tilt.
-cl OR -CleanUpPastStart
Remove all existing reconstructions past the starting point of
this run, for the kind of reconstruction currently being done
(subarea or full). Specifically, this includes files with
extensions containing .srec, .sint, and .strm and with a root
name matching the root name used for subarea or full reconstruc-
tions (see FILES). Sirtsetup does not remove the files; rather,
it places a command to remove them into the first command file
to be run and outputs a list of the files that will be deleted.
If you resume at, say, iteration 5, then the list will include
all files numbered 06 and above. If you restart at the begin-
ning, the list will include all existing files.
-su OR -SubareaSize Two integers
Size in X and Y of a subarea to use from the aligned stack, in
actual pixels of that stack, which might be binned relative to
the original tilt series. When a subarea is specified, output
files are named differently (see FILES).
-yo (-y) OR -YOffsetOfSubarea Integer
Offset in Y from center of aligned image to center of subarea
whose size is specified with the -su option. The shifted sub-
area must lie completely within the image area. Enter a value
in actual pixels of the aligned stack (positive for an area
above the center). If you want to do more iterations, you need
to enter the same subarea size and offset as when you started.
-sc OR -ScaleToInteger Two floats
Scale each retained reconstruction to integers, with the minimum
and maximum in the reconstruction scaled to the given min and
max values. Values of -20000,20000 are recommended. This scal-
ing will reduce the space needed for retained reconstructions
twofold, since by default each reconstruction is generated as
floating point. This scaling is done on each file just after it
is produced, so at the end of the processing the last recon-
struction will be in both floating point and scaled integer
form. The file setname.srec01 is scaled to setname.sint01, etc.
-tr OR -TrimvolOptions Text string
Run Trimvol on each retained reconstruction with the given
options. The options must be enclosed in single or double
quotes. If the options specify a scaling to bytes, this will
reduce the space needed for retained reconstructions by at least
fourfold. Each reconstruction to be retained is trimmed as soon
as it is made, so at the end of the processing the last recon-
struction exists in both floating point and trimmed form. The
file setname.srec01 is trimmed to setname.strm01, etc. The
trimvol options can be extracted from etomo_err.log after run-
ning the Trimvol step in Etomo.
-fl OR -FlatFilterFraction Floating point
Set the fraction of a flat filter function to apply in the ini-
tial reconstruction. A flat function will be mixed with the
standard radial filter if the fraction is less than 1; this may
give quicker convergence. The default is 1.0 for no mixing.
-rd OR -RadiusAndSigma Two floats
Set the radius and falloff for the high-frequency cutoff of the
filter used in the backprojections. The default provides a mild
filtering with a radius is 0.4 and Gaussian falloff with a true
sigma of 0.035 (which is produced by a value of 0.05 when the
-FalloffIsTrueSigma option is not entered)
-falloff (-fa) OR -FalloffIsTrueSigma
Use the falloff value entered with the -RadiusAndSigma option
directly as the sigma of the Gaussian filter instead of using a
sigma that is 0.707 times the entered value. This option was
added in IMOD 4.8.59, after the incorrect scaling of the falloff
value was discovered in the Tilt code, so that newer command
files could show the true sigma value while older command files
without the option would still produce the same result.
-cs OR -ConstrainSign
Enter 1 or -1 to constrain the reconstruction to positive or
negative values when subtracting the difference reconstruction.
This option is appropriate only if the projection data are nor-
malized to be linearly proportional to projected mass density
and have positive or negative values, respectively.
-ch OR -SeparateRecChunks
Write reconstructions in chunks to separate files and assemble
these into a single tomogram. The default is to write directly
to the output file. Neither this option nor the SeparatePro-
jChunks option should be needed with the protections provided by
saving pixels at chunk boundaries into separate files; if arti-
facts do occur, try using the BoundaryPixels option to increase
the number of pixels saved.
-pc (-p) OR -SeparateProjChunks
Write reprojections in chunks to separate files instead of
directly to a single output file. The separate files are assem-
bled with Assemblevol. See the SeparateRecChunks option.
-bo (-b) OR -BoundaryPixels Integer
Set the number of boundary pixels saved in separate files to the
given value when writing reconstructions or projections directly
to a single output file. The boundary pixels are rewritten to
the output file after all chunks are done.
-mo (-m) OR -OutputMode Integer
Set the mode of the output files. The default is 2 because
scaling is somewhat unpredictable, and values generally become
much larger than in standard R-weighted back-projection with
Tilt.
-te OR -TestMode Integer
Run in a test mode. A value of 1 will leave the reprojection
difference between iterations and at the end, except when run-
ning SIRT internally in Tilt. A value of 2 will also leave
command and log files at the end of the processing.
-help (-h) OR -usage
Print help output
-StandardInput
Read parameter entries from standard input
EXAMPLE OF COMMAND LINE USE
It is important that the reconstruction include all significant mate-
rial, including gold fiducials on both sides of a section, if any.
Thus, in Tomogram Positioning, you need to draw contours that include
all of the fiducials.
A convenient interface for Sirtsetup now exists in Etomo. The rest of
this section provides an example based on use at the command line. If
the number of desired iterations is not known in advance, a subarea can
be reconstructed with the following steps:
Prepare the full aligned stack as usual in Etomo. Examine the aligned
stack and select the size of the subarea, and an offset in Y if
desired.
If you are using local alignments and do not have a GPU, you can turn
off the local alignments to speed up this test.
Set parameters in the Tomogram Generation panel of Etomo then press
Postpone to get the command file saved.
Run sirtsetup with the needed number of iterations, and retaining as
many reconstructions as might be needed. For example, if you are con-
fident that at least 15 iterations are needed and want to run 25, you
might use
sirtsetup -su 512,256 -yo 600 -it 25 -le 15,17,19,21,23 tilt.com
If storage space is an issue, also use "-sc -20000,20000".
Run processchunks on "tilt_sirt".
Load the trial reconstructions into 3dmod
3dmod -Y setname_sub_srec*.mrc
If you need to do more iterations, just rerun sirtsetup and process
some more.
Turn local alignments back on if they were turned off. Generate a
reconstruction by standard back-projection if desired. If not, be sure
to press Postpone or Done in the Tomogram Generation panel to ensure
that tilt.com is saved.
Run sirtsetup with the needed number of iterations, e.g.,
sirtsetup -st -it 17 tilt.com
The "-st" option makes it start from the beginning.
If you still want to leave more than one iteration, then disk space
becomes a serious issue. For a single axis data set, the best approach
would be to run Trimvol on the standard reconstruction. Then extract
the trimvol command from etomo_err.log, e.g.:
grep trimvol etomo_err.log
Cut and paste the options (excluding "trimvol" and the file names) and
enter them within quotes, e.g.:
sirtsetup -tr "-rx -f -z 30,160 -sz 50,99" -it 19 -le 15-19
tilt.com
Otherwise, especially for a dual-axis data set where it is not conve-
nient to run Trimvol in Etomo, use "-sc -20000,20000" instead of the
"-tr" option.
FILES
This procedure creates many large files, so it generally purges a pre-
vious version of each file before a new one is created. The names of
files produced during the procedure depend on whether a subarea is
being done or not. In the following, aliname is the root name of
aligned stack, and recname is the root name of reconstruction in the
original command file when no subarea is being done. With a subarea,
recname is either the root name plus "_sub", or the root name with
"_sub" substituted for "_full" if it ends in "_full".
Old style names:
aliname_sub.ali Subarea of aligned stack if any
aliname.alilog10 Log of projections if the tilt command file contains
a LOG entry
aliname_sub.alilog10 Log of subarea of aligned stack
recname.srec00 Initial reconstruction
recname.srecnn Numbered iterative reconstructions
recname.diff Difference of reprojection and original projections
recname.sintnn Iterative reconstruction scaled to integers
recname.strmnn Iterative reconstruction run through Trimvol
recname.vsrnn Vertical slice file used with internal iterations
New style names:
aliname_sub_ali.mrc Subarea of aligned stack if any
aliname_alilog10.mrc Log of projections if the tilt command file contains
a LOG entry
aliname_sub_alilog10.mrc Log of subarea of aligned stack
recname_srec00.mrc Initial reconstruction
recname_srecnn.mrc Numbered iterative reconstructions
recname_diff.mrc Difference of reprojection and original projections
recname_sintnn.mrc Iterative reconstruction scaled to integers
recname_strmnn.mrc Iterative reconstruction run through Trimvol
recname_vsrnn.mrc Vertical slice file used with internal iterations
When SIRT is done internally, only setname_srecnn.mrc, set-
name_sintnn.mrc, setname_strmnn.mrc, and setname_vsrnn.mrc are pro-
duced.
AUTHOR
David Mastronarde
SEE ALSO
tilt, densnorm, newstack, processchunks, splittilt,
trimvol
BUGS
There is not yet a way to tell when to stop iterating. There are low
frequency artifacts, particularly near edges. Use the SIRT-like filter
instead.
Email bug reports to mast at colorado dot edu.
IMOD 5.0.2 sirtsetup(1)