sirtsetup

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.2.0 sirtsetup(1)