makegradtable(1)                                              makegradtable(1)



NAME
       makegradtable - make a magnification gradient table

SYNOPSIS
       makegradtable [options] output_file

DESCRIPTION
       Makegradtable can be used to construct a magnification gradient table
       from two kinds of data: gradients based upon analysis of montaged
       images at high tilt, and transformations that align images taken at
       different Z heights.  In the one case it will read a log file from run-
       ning Findgradient, and in the other case it will read the transfor-
       mation file produced by Xfalign and possibly edited in Midas.
       These data can be smoothed and extrapolated as needed.  To do this, the
       program will transform the beam intensity values into: 1 / (Intensity -
       crossover).  Gradients are nearly linearly related to this transformed
       intensity value, so lines can be fit to the points and used for smooth-
       ing and extrapolation.

       To run the program, you must have a file of the intensities extracted
       from the original image file header, which can be obtained with
         extracttilts -int input_file output_file
       You must also supply the intensity of beam crossover for the given spot
       size.

       To derive a gradient table from montages, enter the name of the log
       file from Findgradient with the FindgradFile option.  This file should
       contain program output once for each intensity that is to be included
       in the gradient table.  The output can be from running each section
       separately or from running several sections together (i.e., ones taken
       at the same intensity).  If more than one run of Findgradient was
       needed to analyze the montages, the log files can simply be concate-
       nated; just be sure that each intensity is represented only once.  The
       section numbers given in the log file will be used to look up the
       intensities from the intensity file.

       To derive a gradient table from images taken at different Z heights,
       the original image stack should consist of image pairs where the inten-
       sity is kept the same for the two images of a pair, and the stage is
       moved by the same amount and in the same direction for each pair.
       Transformations can be obtained with Xfalign using the -bpair
       option, which will just align the paired images to each other.  When
       running Makegradtable, enter the name of the transform file with the
       TransformFile option and enter the Z height change if it is different
       from 10 microns.  The program will obtain gradients from every second
       transform in the file.

       The program will produce a version 2 mag gradient table with the fol-
       lowing format, with the last line repeated for each intensity:
          Version_number
          crossover_intensity
          intensity   %_mag_change_per_micron  degrees_rotation_per_micron
          ...

       The table becomes incorrect when the microscope alignments are updated
       in a way that changes the crossover intensity.  When this happens, you
       can use Fixgradtable to make a new table with the entries adjusted
       for the change in crossover.

OPTIONS
       Makegradtable uses the PIP package for input exclusively (see the man-
       ual page for pip).  The following options can be specified either as
       command line arguments (with the -) or one per line in a command file
       or parameter file (without the -).  Options can be abbreviated to
       unique letters; the currently valid abbreviations for short names are
       shown in parentheses.


       -findgrad (-f) OR -FindgradFile     File name
              Input file with output from Findgradient

       -xffile (-x) OR -TransformFile      File name
              Input file with transforms for image pairs from stage moves in Z

       -intensity (-i) OR -IntensityFile   File name
              File with intensity values from extracttilts -int

       -output (-o) OR -OutputTable   File name
              Output file for mag gradient table.  If this option is not
              entered, the first non-option argument will be taken as the name
              of the output file.

       -raw (-ra) OR -RawOutput       File name
              Output file for raw, smoothed, and extrapolated data.  If this
              option is not entered, the same data will be printed to standard
              output.  The columns in this output are: a type identifier (1
              for measured and 2 for extrapolated data), intensity, trans-
              formed intensity, the raw and smoothed percent magnification
              change per micron, and the raw and smoothed degrees of rotation
              per micron.

       -crossover (-c) OR -CrossoverIntensity   Floating point
              Underlying intensity value at crossover.  For an FEI microscope,
              this is not the intensity value that appears in the user inter-
              face but the intensity used internally, which is saved in Seri-
              alEMcalibrations.txt when crossover is calibrated in SerialEM.
              This entry is required.

       -microns (-mi) OR -MicronsMoved     Floating point
              Number of microns of stage movement in Z (default 10)

       -msmooth (-ms) OR -SmoothMags
              Smooth magnification changes with linear fits

       -rsmooth (-rs) OR -SmoothRotations
              Smooth rotation changes with linear fits

       -sfit (-s) OR -MaxInFitForSmoothing      Two integers
              Maximum number of points in fits for smoothing mags and rota-
              tions.  If one of these values is 0, a line will be fit to all
              points on one side of crossover and the smoothed values will be
              the values in this line.  Otherwise, for each point, a line is
              fit to the nearest points up to this maximum number, and the
              value of the line is used as the smoothed value at that inten-
              sity.  The default is 5 for magnifications and 0 for rotations.

       -efit (-ef) OR -MaxInFitForExtrapolation      Two integers
              Maximum number of points in fits for extrapolating mags and
              rotations.  With the default values of 0, a line will be fit to
              all points on one side of crossover and the line will be extrap-
              olated both toward crossover and to more extreme intensities.
              Otherwise, a line will be fit to the given number of points at
              the end of the curve, and this line will be used to find the
              extrapolated value at that end of the curve.

       -extremes (-ex) OR -ExtremesForExtrapolation       Two floats
              Extreme values to extrapolate to (default 0.2 and 0.8)

       -distance (-d) OR -DistanceFromCrossover      Floating point
              Use this entry to specify how close to crossover to extrapolate
              the curves to.  The number is expressed as a fraction of the
              distance from crossover to the last measured intensity on the
              particular side of crossover, where the intensities are trans-
              formed as given above.  Typically, with the default fraction of
              0.5, the extrapolated gradient will be twice what it is at the
              last measured intensity.

       -param (-p) OR -ParameterFile       Parameter file
              Read parameter entries as keyword-value pairs from a parameter
              file.

       -help (-h) OR -usage
              Print help output.

       -StandardInput
              Read parameter entries from standard input.

HISTORY
       Written by David Mastronarde, February 2006

BUGS
       Email bug reports to mast at colorado dot edu.



BL3DEMC                              4.7.3                    makegradtable(1)