Boulder Laboratory for 3-Dimensional Electron Microscopy of Cells

HOWFLARED(1)							   HOWFLARED(1)

NAME
  howflared - measure microtubule end flaring and curvature

SYNOPSIS
  howflared [options] output_file

DESCRIPTION
    Howflared analyzes tracings of the walls of microtubules (MTs) to compute
  various measures of the amount of curvature or "flaring" at the MT end.  The
  IMOD model with MT tracings must meet a number of requirements.  The first
  step is to extract the MTs into subvolumes so that they are oriented
  vertically, with the end facing downward.  This can be done with
  Mtrotlong.  The orientations do not need to be perfect.  Once subvolumes
  have been extracted as a set, they can be loaded into 3dmod together as a
  4-dimensional data set.  The 4th dimension is referred to as "time".
  Alternatively, a central slice can be extracted from each and a stack made
  with these central slices.

    The tracings must all be drawn starting near the top of the image in Y and
  ending at the MT end.  Each tracing defines two regions of an MT wall: a
  linear segment before the end, and a potentially curved segment.  A line is
  fit to a defined part of the linear segment and extrapolated into the region
  of the end.  The quantitative measures are based on the deviation of the
  curved segment from this extrapolated line.  Thus, a tracing must include a
  linear segment, and there must be some way to indicate where the linear
  segment ends and the measurement of the deviation should begin. There are
  essentially three different ways to indicate this boundary.

    One way is to specify how far down from the top of the tracing the
  beginning and the end of the line fit should be.  This method is suitable if
  all the tracings have similar starting points near the top of the subvolumes
  and their curvature starts at similar locations as well.  The starting and
  ending points can be specified as either absolute units (in pixels) or as a
  fraction of the distance from the maximum to the minimum Y value in the
  tracing.  The second method is to use a horizontal line, consisting of only
  two points, entered as a separate contour, to specify the boundary point.
  With this method, one might still enter an ending limit, in which case the
  maximum of the ending limit and the Y position of the marker line are used
  for the end of the linear fit, but the measurement of deviation starts at
  the marker position.  The third method is to model the linear segment with
  just two points.  In this case, one would enter 0,0 for starting and ending
  limits.  The second and third methods can both used in the same model; the
  second point will be used as the boundary only if there is no horizontal
  marker line.

    The program can analyze either two paired walls of a MT, or a single wall.
  When two walls are paired, the linear fit finds a single slope for the two
  walls, and a width between them.  This width is used for normalizing some of
  the flaring measurements.  If there are also single, unpaired walls, a width
  is assumed when normalizing these measurements (see -width option).  When a
  horizontal marker is used for a pair of walls, it should be drawn from near
  the boundary point on the left wall to near the boundary point on the right
  wall.  A single wall is treated like the wall on the left of a pair; so in
  this case a marker line should have its left end near the boundary point on
  the wall.

    The program needs to be able to tell when two MTs are paired, and when a
  marker line belongs with one or two MTs.  Nothing special needs to be done
  when modeling in only a single plane per MT.  If you are modeling in
  multiple sub-volumes, the program will segregate the tracing based on their
  times; if you are modeling in a stack of single slices from different MTs,
  the segregation will be based upon Z value.  However, if you want to trace
  multiple, unpaired walls in the Slicer, either you need to segregate them by
  placing them in either separate objects or separate surfaces, or you need to
  use the -nopairs option.  Thus, you could have one object for all of the
  first tracings in each MT, a second object for the second tracing, etc.
  Similarly, you could use the surface number 0 for the first tracing in each
  MT, 1 for the second, etc.; or you could simply put each tracing (or tracing
  pair) with associated marker into a separate surface.  If you are willing to
  have no marker lines, then you can use the -nopairs option to indicate that
  there are neither pairs nor markers.

    The program computes various quantities and stores them in columns of a
  data matrix; you specify which columns you want output with -columns.  The
  items and their units are:

    The area between the tracing and the extrapolation of the wall, down to
  the minimum Y value of the tracing (square nm).
    The square root of this area (nm)
    The sum, over all line segments, of the product of the line segment length
  and the angle between the segment and the extrapolation of the
  wall(nm*radians)
    The area divided by the square of the average MT width (square MT widths)
    The square of the area divided by the average MT width (MT widths)
    The angular sum divided by the average MT width (MT widths * radians)
    The total length of the tracing after the boundary (nm)
    The final angular deviation of the tracing from the extrapolation of the
  wall (degrees)
    The angular change in degrees per nm of length
    The average radius of curvature in nm.

    The first 6 items are placed into columns 1-6 for the left wall of a pair
  or for an unpaired wall, and into columns 7-12 for the right wall of a pair.
  The sum of the two values for left and right in placed in columns 13-18.
  The last 4 items are placed into columns 19-22 for the left wall of a pair
  or for an unpaired wall, and into columns 23-26 for the right wall of a
  pair.

    In the output file, these columns of output are preceded by 3 or 4
  numbers.  The first number is a model identifier; the second is the object
  number.  If you used surface numbers to segregate tracings, the third of 4
  numbers is the surface number; if you used the -nopairs option, the third of
  4 numbers is the contour number.  The last number is the time value, or the
  Z value.

    Howflared 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 -):

 -output OR -OutputFile   File name
    Output file for results. If this option is not entered, the first
    non-option argument will be used for the filename.

 -columns OR -ColumnsToOutput   List of integer ranges
    List of columns to output (values ranging from 1 to 26).  For paired MT
    walls, columns 1-6 and 19-22 are for the left walls, 7-12 and 23-26 are
    for the right walls, and 13-18 are the sum of values from 1-6 and 7-12. 
    Unpaired walls are treated as left walls, and their values will appear in
    both columns 1-6 and 13-18.  See description of computed values above.

 -point OR -PointOutputFile   File name
    Output file for points in each wall, starting at the point where the flare
    measurement begins.  The points are rotated so that the wall above that
    point would be vertical, and they are expressed in nanometers relative to
    the starting point.  For each MT wall, there is a line starting with the
    number of points, then containing the 3 or 4 numbers described above as
    preceding the columns of output in the standard output file, and ending
    with 1 for a left or unpaired wall, or 2 for a right wall.

 -pixel OR -PixelSizeDefault   Floating point
    Default pixel size in nm, which will be used for any models that do not
    have a pixel size defined.  The default is 1, namely results will be in
    pixels.

 -width OR -WidthDefault   Floating point
    Default width between walls in nm.  This value is used to compute
    normalized areas for unpaired walls.  The default is 20.

 -surface OR -UseSurfaceNumbers
    Use surface numbers to determine whether two wall tracings are paired and
    whether a horizontal marker contour matches a wall tracing.  This is not
    the default because surface numbers might have been introduced by
    accident.

 -nopairs OR -NoPairsOrMarkers
    There are no paired tracings and no horizontal marker lines.  With this
    option you do not need to segregate tracings in separate objects or
    surfaces.

 -model OR -ModelFile   File name
    Input model file with tracings of microtubule walls
    (Successive entries accumulate)

 -fit OR -FitTopAndBottom   Two floats
    Upper and lower limits for the line fit.  The limits are entered as either
    an absolute distance from the maximum Y for a MT or a fraction of the
    distance from the maximum to the minimum Y.  If the upper limit is 0, the
    maximum Y is used.  If the lower limit is 0, the limit used depends on
    whether there is a horizontal marker line or not.  If there is a line, it
    is used as the limit; if not, the second point of the contour is used as
    the lower limit.  Enter this option once to use the same limit for all
    models, or once per model.  If it is not entered, the default limits are
    0,0.
    (Successive entries accumulate)

 -id OR -Identifier   Integer
    ID number for output.  Enter this option either once to specify a starting
    ID number, or once per model.  If it is not entered, the ID numbers start
    at 1.
    (Successive entries accumulate)

 -help OR -usage
    Print help output

  -StandardInput
     Read parameter entries from standard input.

HISTORY
  Written by David Mastronarde in 1996
  Modified for PIP input and incorporation into IMOD, 10/14/06