Boulder Laboratory for 3-Dimensional Electron Microscopy of Cells

COMBINEFFT(1)							  COMBINEFFT(1)

NAME
	combinefft - combine FFTs of tomograms from a double-axis tilt series

SYNOPSIS
	combinefft

DESCRIPTION
  Combinefft combines the FFTs from the two tomograms of a double-axis
  tilt series, taking into account the tilt range of each tilt series
  and the transformation used to match one tomogram to the other.  For
  a location in Fourier space where there is data from one tilt series
  but not the other, it takes the Fourier value from just the one
  appropriate FFT; everywhere else it averages the Fourier values from
  the two FFTs.

  The program can take input files that are either both FFTs or both matching
  tomograms.  The FFTs would generally be from a subvolume of the tomogram;
  and if the tomograms are used as input, a subvolume would generally be
  processed.  The program will consume 8 times as much memory as the number of
  voxels being processed in either case.  It uses dynamic memory allocation
  but will refuse to process subvolumes bigger than 1 gigavoxel.  On 32-bit
  systems, the allocation will fail for size above 250-370 megavoxels,
  depending on the operating system.

  There is an option (-reduce) to reduce amplitudes in regions of the FFT
  derived from only one tomogram to match the reduction in amplitudes in
  regions where data were averaged.  Apparently, the averaged data have lower
  amplitudes when there is substantial noise in the reconstruction because
  some of the noise averages out, while the noise in regions derived from one
  tomogram is unattenuated.  This may result in directionally patterned noise.
  The reduction option will reduce the noise (and signal) in the regions
  derived from one tomogram in attempt to keep it from dominating over the
  rest of the data.

  There is an option (-weight) for more sophisticated weighting that gives
  worse results with test data.

  Combinefft uses the PIP package for input (see the manual page for pip)
  and can take input interactively for options that existed when it was
  converted, to maintain compatibility with old command files.  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 -):

 -ainput OR -AInputFFT   File name
    Input file from the first tomogram (the one being matched to): either the
    FFT of a chunk from the tomogram, or the tomogram itself, from which a
    chunk can be extracted with the 'MinAndMax' options

 -binput OR -BInputFFT   File name
    Input file from the second tomogram (the transformed one): either the FFT
    of a chunk from the tomogram, or the tomogram itself, from which a chunk
    can be extracted with the 'MinAndMax' options

 -output OR -OutputFFT   File name
    Output file for the combined FFTs or real-space volumes.  An output file
    must be entered with real-space input, but the file can be omitted for FFT
    input, in which case the program will write the combined FFT back to the
    second input file.

 -xminmax OR -XMinAndMax   Two integers
    Starting and ending X index coordinates to extract from the tomograms,
    numbered from 0.  The default is the whole width in X.

 -yminmax OR -YMinAndMax   Two integers
    Starting and ending Y index coordinates to extract from the tomograms,
    numbered from 0.  The default is the whole height in Y.

 -zminmax OR -ZMinAndMax   Two integers
    Starting and ending Z index coordinates to extract from the tomograms,
    numbered from 0.  The default is the whole depth in Z.

 -taper OR -TaperPadsInXYZ   Three integers
    Number of pixels over which to taper and pad the patches in X, Y and Z. 
    The default is 0.  The amount of tapering in any dimension may be
    increased to make that dimension suitable for taking an FFT.

 -atiltfile OR -ATiltFile   File name
    File with tilt angles used to generate first tomogram.  The file should
    have one tilt angle per line.  The first and last line in the file are
    assumed to have the starting and ending tilt angles.

 -btiltfile OR -BTiltFile   File name
    File with tilt angles used to generate second tomogram, in the same format
    as for ATiltFile.

 -ahighest OR -AHighestTilts   Two floats
    Starting and ending tilt angles used to generate first tomogram.  This
    entry and ATiltFile are mutually exclusive.

 -bhighest OR -BHighestTilts   Two floats
    Starting and ending tilt angles used to generate second tomogram.  This
    entry and BTiltFile are mutually exclusive.

 -inverse OR -InverseTransformFile   File name
    Name of file with inverse of transformation used to match the two
    tomograms (output by Matchvol).  This entry is required.

 -reduce OR -ReductionFraction   Floating point
    This option can be used to reduce the amplitudes in regions where data is
    taken only from one tomogram (missing wedge regions).  Mean amplitudes are
    measured by dividing the volume into a number of slabs in the Y dimension,
    then dividing each slab into rings based on radius from the origin. 
    Within each ring, the mean is obtained for points in the region where data
    is averaged between the two tomograms (joint data region), and the regions
    where data are available only from A or only from B (A-only or B-only
    regions).  With a fraction of 1, the values in the A-only region will be
    reduced by the ratio of the combined mean to the mean in A-only region,
    and similarly for the B-only region.  If the ratio is greater than 1, no
    reduction occurs.  A smaller fraction will reduce values by a
    proportionally smaller amount.

 -separate OR -SeparateReduction
    With this option, values in regions where data are available only from A
    will be reduced by the ratio of the mean combined value in the joint data
    region to the mean value from A in the joint data region, and similarly
    for B.

 -joint OR -JointReduction
    With this option, for points in the region where data is averaged between
    the two tomograms (joint data region), the mean is obtained within each
    ring for values from A, values from B, and the combined values.  The
    values in missing wedge regions will be reduced by the ratio of the
    combined mean to the average of the means from A and B.

 -ring OR -RingWidth   Floating point
    Width of rings or shells used to reduce amplitudes.  The default is 0.01.

 -nslabs OR -NumberOfSlabsInY   Integer
    Number of divisions in Y dimension when reducing amplitudes.  The default
    is 1, which will use spherical shells not divided into slabs.  If this
    number is increased, the ring width should be increased as well to avoid
    dividing the volume into too many regions with too few pixels.

 -radius OR -MinimumRadiusToReduce   Floating point
    Radius at which to start the first ring when reducing amplitudes (default
    0.02)

 -points OR -MinimumPointsInRing   Integer
    Minimum number of points required in each region of a ring for reducing
    amplitudes (default 30)

 -both OR -LowFromBothRadius   Floating point
    Radius below which data will always be averaged from both tomograms. 
    Sometimes a combined tomogram shows lines between the separate pieces that
    were run through Combinefft, particularly for pieces containing a boundary
    between dense material and resin.  This option will eliminate this effect
    by ensuring that the low-frequency components match between the combined
    pieces.  A value of 0.01 to 0.015 should be effective.

 -verbose OR -VerboseOutput
    With this option, the program will print the amplitudes and reduction
    factors for every region being reduced.  The columns output are: the ring
    number; the slab number (slabs are numbered sequentially from negative to
    positive Y); the zone, which is 1 for the region with data from the first
    tomogram only, and 3 for the region with data from the second tomogram
    only; the mean amplitude of the joint data region; the mean for data
    relevant to the zone in question; the target value for the reduction in
    mean; and the reduction factor.

 -weight OR -WeightingPower   Floating point
    This option allows a weighted combination of values instead of simple
    averaging when data are available from both FFTs.  A local sampling
    density is computed for the point in each of the FFTs, based upon its
    radius from the origin and the local density of tilted views.  These
    densities are raised to the given power, normalized to add to one, and
    used as weights in combining the two Fourier values.  Values between 0 and
    1 should be tried; 0 gives no weighting.

 -param OR -ParameterFile   Parameter file
    Read parameter entries from file

 -help OR -usage
    Print help output

  -StandardInput
     Read parameter entries from standard input.


  If the program is started with no command line arguments, it reverts to
  interactive input with the following entries:
  
  File name of FFT of first tomogram (the one matched TO)
  
  File name of FFT of second tomogram (the one produced by MATCHVOL)
  
  Name of output file for resulting FFT, or Return to write into the
      file of the second FFT, overwriting that FFT.
  
  Name of file with inverse of transformation used to match the two
      tomograms (output by MATCHVOL)
  
  For the first tomogram file, either the starting and ending tilt
     angles, or the name of a file with tilt angles in it.  In the
     latter case, the first number on the first line will be taken as
     the starting tilt angle; the first number on the last line will
     be taken as the ending tilt angle.
  
  For the second tomogram file, either the starting and ending tilt
     angles, or the name of a file with tilt angles in it.

HISTORY
  Written by David Mastronarde, November 1995
  Converted to PIP and experimental options added, 7/12/04