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
       determined the maximum difference in defocus produced by the two dif-
       ferent X-axis tilt values, which occurs at the extremes of the recon-
       struction 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.

       -volume (-v) OR -VolumeModeled      File name
              Name of the volume in which points were selected.  If a model
              file is supplied, this should be the volume that was modeled.
              If a point coordinate file is supplied, the coordinates must
              correspond to pixel positions in this file.  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.

       -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.10.22                    subtomosetup(1)