sirtsetup(1) 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.
The reconstructions are named setname.srec00, setname.srec01, etc.
Once some of these reconstructions exist, it is easy to do additional
iterations simply by running this script again.
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; i.e., SLICE and WIDTH
entries are not allowed. This means that if you want to do a trial
reconstruction on a subarea, you need to make the aligned stack
smaller, either by copying it to a smaller size with Newstack or by
modifying the command used to make it in newst.com or blend.com. In
addition, you need to change the SUBSETSTART entry in the tilt command
file to indicate the starting coordinates of this subarea. Typically
the starting coordinate would be (full size - trimmed size) / 2. For
example, if the original size of the aligned stack would be 2048x2048
and you make a 512x512 subarea, the SUBSETSTART entry would be 768 768.
The SUBSETSTART entry must be in unbinned pixels, if binning was used.
The FULLIMAGESIZE entry would stay the same. These changes are all
handled when making a subset aligned stack in eTomo.
If the tilt command file takes the log of the projection data, then the
starting command file will use Densnorm to create a new stack with
the logarithm of the projections. This log stack will be used in all
of the operations listed above.
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 parallel processing interface in eTomo.
Each of the log files from performing operation 5 above uses "clip
stat" to get statistics from a central area of 10 slices from the dif-
ference reconstruction. The summary values from these statistics are
gathered at the end of the tiltroot_sirt-finish.log file. 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 iterations.
Options
-nu <value>
Use this option to specify the number of machines that you
expect to run the command files on. It is passed directly to
Splittilt. The default is 8.
-st Do an initial reconstruction, numbered 00, even if it or later
reconstructions already exist. The default is to iterate from
the last existing reconstruction.
-it <value>
Set the number of iterations to run; the default is 10.
-le <value>
Set the number of reconstructions to leave for examination; the
default is 5.
-al Always retain that number of reconstructions during the itera-
tions, deleting older ones as new ones are made after the number
is reached. The default is to retain only the reconstructions
at the end of the set of iterations. For example, if 15 itera-
tion are being done and 5 are being retained, by default only
the reconstructions for iterations 11 through 15 would be saved.
With this option, there would be 5 retained reconstructions
throughout the processing.
-sc <min,max>
Scale each retained reconstruction to integers, with the minimum
and maximum in the reconstruction scaled to the given min and
max values. This 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
after it is superceded by a new iteration, so at the end of the
processing the last reconstruction will still be floating point
while the previous retained one will be scaled to integers. The
file setname.srec01 is scaled to setname.sint01, etc. To scale
the final reconstruction to integers in the same way, just run
newstack -sc min,max
Values of -20000,20000 are recommended.
-tr <options>
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 <value>
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
given quicker convergence. The default is 1.0 for no mixing.
-ri <#,#>
Set the radius and sigma for the high-frequency cutoff of the
radial filter in the initial reconstruction. The default is
0.5,0.05 for no filtering.
-rd <#,#>
Set the radius and sigma for the high-frequency cutoff of the
radial filter in the difference reconstructions. The default is
0.5,0.05 for no filtering.
-zp Constrain the reconstruction to positive values when subtracting
the difference reconstruction. This option is appropriate only
if the projection data are normalized to be linearly propor-
tional to projected mass density and have positive values.
-zn Constrain the reconstruction to negative values when subtracting
the difference reconstruction. This option is appropriate only
if the projection data are normalized to be linearly propor-
tional to projected mass density and have negative values, as
usually produced by Densnorm.
-ch Write reconstructions in chunks to separate files and assemble
these into a single tomogram. The default is to write directly
to the output file. This option should be needed only if the
corresponding option is needed with Splittilt for parallel
reconstructions on your computer systems.
-di Write reprojections directly to a single output file. The
default is to write chunks to separate files that are assembled
with Assemblevol, because direct writing can give empty lines
with a typical multiple-computer setup. This option may be safe
if no remote machines are used for processing, particularly if
the local machine is not writing to a remote server.
-mo <value>
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 <value>
Run in a test mode. A value of 1 will leave the reprojection,
projection difference, and difference reconstruction at the end
of every iteration. A value of 2 will also leaves command and
log files at the end of the processing.
EXAMPLE
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. Also note that you may need to set the X-axis
tilt to zero for a cryo data set; see BUGS below.
If the number of desired iterations is not known in advance, a subarea
can be reconstructed with the following steps:
Set the Size to output in Advanced mode in the Newstack/Blendmont sec-
tion of the Tomogram Generation panel in eTomo. Generate the aligned
stack. Apply 2D filter if desired.
Turn off local alignments if they are on, to speed up this test. Gen-
erate a reconstruction by standard back-projection.
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, then
use
sirtsetup -it 25 -le 11 tilt.com
If storage space is an issue, also use "-sc -20000,20000". However,
loading the retained reconstructions is simpler if you do not.
Run processchunks on "tilt_sirt".
Load the trial reconstructions into 3dmod
3dmod -Y setname.srec* setname.rec
for one axis of a dual axis set, or for a single axis set:
3dmod -Y setname_full.srec* setname_full.rec
If you need to do more iterations, just rerun sirtsetup and process
some more. Once you have decided on the right number of iterations,
you should remove or rename all of the .srec and/or .sint files:
rm -f setname*.srec* setname*.sint*
Remove the Size to output entry in eTomo and regenerate the aligned
stack. Apply 2D filter if desired.
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, and retaining only
the last, e.g.:
sirtsetup -it 17 -le 1 tilt.com
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 5 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 files pro-
duced during the procedure are:
setname.alilog10 Log of projections if the tilt command file contains
a LOG entry
setname.srec00 Initial reconstruction
setname.srecnn Numbered iterative reconstructions
setname.proj Reprojection of current reconstruction
setname.diff Difference of reprojection and original projections
setname.drec Correction reconstruction from projection difference
setname.sintnn Iterative reconstruction scaled to integers
setname.strmnn Iterative reconstruction run through Trimvol
AUTHOR
David Mastronarde
SEE ALSO
tilt, densnorm, newstack, subimage, processchunks,
splittilt, trimvol
BUGS
With several cryoEM data sets that included an X-axis tilt, bad strip-
ing artifacts developed and increased through the iterations. Setting
the X-axis tilt to 0 eliminated this problem.
There is not yet a way to tell when to stop iterating. Densities get
progressively farther off at the edges of the reconstruction. There
are low frequency artifacts, particularly near edges.
Email bug reports to mast at colorado dot edu.
BL3DEMC 3.13.2 sirtsetup(1)