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.  Note that if the
       unbinned tomogram already exists, the program Boxstartend can be
       used to extract subvolumes from it.

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

       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.  If a position is too close to the top
       or bottom of the Y-extent that can be reconstructed from the current
       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.

       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.

       -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 processors that the jobs will be run on.  The program
              will divide the jobs into 10 command files (chunks) per proces-
              sor if this results in fewer than 1000 chunks, or with fewer
              chunks per processor, down to 5, in an attempt to keep the num-
              ber 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.10                    subtomosetup(1)