RAPTOR(1)                                                            RAPTOR(1)



NAME
       RAPTOR - Automatic alignment of tilt series with fiducial markers

SYNOPSIS
       RAPTOR [options]

DESCRIPTION
       RAPTOR (Robust Alignment and Projection Estimation for Tomographic
       Reconstruction) aligns tomographic tilt series obtained from electron
       microscopes.  It is intended to automatically obtain a full-precision
       alignment comparable to the one obtained with extended manual interven-
       tion. Fiducial particles are needed in the image for the alignment.
       RAPTOR has been tested in many different datasets (cryo-EM, plastic,
       thick sections) and has given very good results.  However, any feed-
       back, questions, or suggestions will be greatly appreciated.

       RAPTOR was developed primarily by Fernando Amat and Farshid Moussavi
       while they were at Stanford University.  They have contributed it for
       incorporation into IMOD and still maintain and develop it.

       If you use RAPTOR in your research, please cite the following paper:

       F. Amat, F. Moussavi,L.R. Comolli, G. Elidan, K.H. Downing, M.
       Horowitz. "Markov random field based automatic image alignment for
       electron tomography". Journal of Structural Biology , March 2008, pages
       260-275.

       Inside IMOD, RAPTOR is run by eTomo using a wrapper script, "runrap-
       tor".  This script must be run from inside the data directory where a
       reconstruction is being done.  It takes care of adding the -exec,
       -path, -input, -track, and -output options, and it passes other options
       through to RAPTOR.  It requires that the -diam and -mark options be
       entered.  It places output in a numbered series of subdirectories,
       "raptor1", "raptor2", etc. if it is run multiple times.  It takes care
       of making an IMOD model that can be loaded onto the image stack in
       3dmod.

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

       -execPath (-e) OR -RaptorExecPath   Text string
              Path where RAPTOR binaries are located (required)

       -path (-p) OR -InputPath       Text string
              Path where MRC stack to be aligned is located (required)

       -input (-i) OR -InputFile      File name
              Input filename, without the path (required)

       -output (-ou) OR -OutputPath   Text string
              Path where output files will be saved (required)

       -diameter (-d) OR -Diameter    Multiple integers
              Diameter(s) of the markers, in pixels.  If you bin the image
              with with the -bin option to RAPTOR, the diameter has to be the
              one in the original image indicated by the -input entry, NOT the
              binned one. If the dataset has more than one kind of marker just
              specify the different sizes separated by commas.  This entry is
              required.

       -white (-w) OR -WhiteMarkers
              Search for markers that have higher values than the background
              in the MRC stack (like quantum dots or images with inverted con-
              strast).

       -markers (-mar) OR -MarkersPerImage      Integer
              Number of markers to be tracked.  THIS IS A CRITICAL PARAMETER.
              If Raptor fails aligning the stack try increasing this number
              (it will just make the run slower). We have develop a method to
              try to estimate this parameter automatically. If you don't spec-
              ify a number, RAPTOR will perform an estimation.

       -angles (-a) OR -AnglesInHeader
              If this option is specified, RAPTOR will extract tilt angles
              from the header of the input stack.  Otherwise, it will expect
              to find tilt angles in a ".rawtlt" file.

       -bin (-b) OR -Binning     Integer
              With this option, RAPTOR will bin the stack before performing
              alignment.  Remember that binning affects the diameter of the
              markers.

       -rec (-re) OR -Reconstruction       Integer
              If this option is specified, RAPTOR will run IMOD's Tilt pro-
              gram after alignment to perform the 3D reconstruction.  The
              entry must be 0,1 or 2 to indicate the mode of the reconstruc-
              tion (0 for byte, 1 for signed integer, 2 for float).

       -thickness (-th) OR -Thickness      Integer
              Thickness of the tomogram, if -rec option is entered

       -orientation (-or) OR -Orient       Integer
              This option controls the handedness of a tomogram generated by
              the CalTech version of RAPTOR (not the one in IMOD).  Enter -1
              to use the PARALLEL option when running Tilt, which inverts
              handedness; the default is to use the RotateBy90 option.

       -tracking (-tr) OR -TrackingOnly
              If this option is specified, RAPTOR does not generate an aligned
              stack or reconstruction.  It just returns a fiducial model with
              all the tracked trajectories, like the bead tracker in IMOD.

       -xray (-x) OR -xRay
              If the images contain strong straight line features (such as
              edges of a capillary sample holder) they will affect the marker
              detection process.  Enter this option in order to remove these
              strong features and improve marker detection performance.

       -verb (-v) OR -Verbose    Integer
              Specify how much output RAPTOR should write and keep:
                0 for minimal output. Only reconstructed volume and a minimal
              log file are kept
                1 for standard output (the default).  Aligned stack is kept as
              well as fiducial model for IMOD and log with RAPTOR's progress.
                2 for debug mode. RAPTOR writes an extended output log as well
              as status in intermediate steps of the process. Useful to report
              and detect errors.

   Advanced Options
         Use these options only if you have a good understanding of the algo-
       rithm parameters.

       -maxDist (-max) OR -MaxDistanceCandidate      Integer
              Maximum distance between two markers in adjacent projections for
              them to be considered as possibly the same marker in each
              separate projection.

       -minNeigh (-mi) OR -MinNeighborsMRF      Integer
              Minimum number of neighbors per marker to build the graphical
              model when solving for the correspondence problem.

       -rollOff (-ro) OR -RollOffMRF       Integer
              Coefficient of the exponential decay to penalize markers that
              are far away when establishing correspondences between projec-
              tions

       -StandardInput
              Read parameter entries from standard input


   Output
       In the folder specified as output you will find the following subfold-
       ers: IMOD, align, temp and debug (if the option "-verb 2" was speci-
       fied).

       A. align folder: contains an aligned stack (*.ali), a RAPTOR report of
       execution (*_RAPTOR.log), and a report of IMOD commands executed within
       RAPTOR (*_IMOD.log). If you specified -rec it will contain the tomogram
       as well (*.rec)

       B. IMOD folder: contains a final fiducial model (*.fid.txt), the align
       script used to generate an aligned stack (*_tiltalignScript.txt), and
       final refined tilt angles (*.tlt).

       Note: you can use the original stack (input file or binned file in case
       you specified -bin) and the fiducial model *.fid.txt to check if the
       fiducial tracking was successful. Just open both the model and stack
       with 3dmod to visualize. You can also correct the model.  To create
       a new aligned stack just run tiltalign -param *_tiltAlignScript.txt
       from the output/IMOD folder.

       C. debug folder: if -verb 2 was specified it contains intermediate
       files to check RAPTOR performance. For example, it contains the tem-
       plate used to detect markers or fiducial models at different steps of
       the program.


AUTHORS
       Fernando Amat and Farshid Moussavi

SEE ALSO
       3dmod, tilt, tiltalign

BUGS
       Email bug reports to mast at colorado dot edu.



BL3DEMC                              4.7.3                           RAPTOR(1)