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.
       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, setname.srec01, etc.

       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.

       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.

       -nu (-n) 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.

       -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 (-f) 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 sigma for the high-frequency cutoff of the
              filter used in the backprojections.  The default is 0.4,0.05 for
              a mild filtering.

       -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.

       -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*

       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".
       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
       When SIRT is done internally, only setname.srecnn, setname.sintnn, set-
       name.strmnn, and setname.vsrnn are produced.

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.

       Email bug reports to mast at colorado dot edu.



BL3DEMC                              4.7.3                        sirtsetup(1)