Boulder Laboratory for 3-Dimensional Electron Microscopy of Cells

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 running Findgradient, and in
  the other case it will read the transformation 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 smoothing 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 concatenated; 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 intensity 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 following
  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.

  Makegradtable uses the PIP package for input exclusively (see the manual
  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 -):

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

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

 -intensity OR -IntensityFile   File name
    File with intensity values from extracttilts -int

 -output 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 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, transformed intensity, the raw and smoothed
    percent magnification change per micron, and the raw and smoothed degrees
    of rotation per micron.

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

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

 -msmooth OR -SmoothMags
    Smooth magnification changes with linear fits

 -rsmooth OR -SmoothRotations
    Smooth rotation changes with linear fits

 -sfit OR -MaxInFitForSmoothing   Two integers
    Maximum number of points in fits for smoothing mags and rotations.  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 intensity.  The default is 5 for magnifications and 0 for rotations.

 -efit 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 extrapolated 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 OR -ExtremesForExtrapolation   Two floats
    Extreme values to extrapolate to (default 0.2 and 0.8)

 -distance 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 transformed 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 OR -ParameterFile   Parameter file
    Read parameter entries as keyword-value pairs from a parameter file.

 -help OR -usage
    Print help output.

  -StandardInput
     Read parameter entries from standard input.

HISTORY
  Written by David Mastronarde, February 2006