Boulder Laboratory for 3-Dimensional Electron Microscopy of Cells

MTOVERLAP(1)							   MTOVERLAP(1)

NAME
	mtoverlap - to sdisplay and analyze overlap of spindle MTs

SYNOPSIS
	mtoverlap

DESCRIPTION
  MTOVERLAP allows one to display sets of "bundles" of microtubules
  (MT's) and to compute overlap between MT's coming from the two
  different directions.  It has a lot of flexibility but one can select
  a default, standard display format fairly easily.
  
  Before running the program, you must figure out how to specify which
  MT's are in a bundle.  If all of the MT's in a model belong to
  one bundle, then this task is easy.  If you have several bundles in
  one model, then you have several alternatives.  One is to determine
  the lower and upper X, Y and Z coordinates of a box, such that the
  bundle consists of all MT's that contain at least one point within
  the box.  Another way is to make a model contour within the plane
  of one section to serve as a boundary contour.  This contour,
  together with a lower and upper Z coordinate, specifies a "cylinder",
  and this program will include in the bundle any MT with at least one
  point inside this cylinder.  The most elaborate way is to make a
  series of model contours for boundary contours in different sections.
  The program will then include in the bundle any MT that is included
  within any one of the contours.
  
  For each bundle that the program deals with, it will want to know a
  center Z coordinate; this center value is used to align different
  bundles for display and to compute the average distance past center
  that each class of MT extends.  The program can compute the center
  value that makes two classes of MT's extend past the center by the
  same amount (in opposite directions).  It can do this computation
  for each bundle separately, for all bundles pooled together, or
  for any combination of bundles that you desire.  Alternatively, you
  may enter the center Z coordinates.

  When you enter X, Y or Z coordinates for either of the above
  purposes, they must be index coordinates of the image file.  That
  is, X and Y values must be in terms of pixel coordinates, and Z
  values must be in units of the original section numbers, before
  adjustment for tilt or scaling by section thickness.

  If the sections were significantly tilted during microscopy, the
  program can adjust for these tilts given the proper information.
  Prepare a file in which the first line shows the Z value and the
  tilt of the first tilted section (or of the first section, if that
  one was tilted), and each successive line shows the Z value and tilt
  for each section on which tilt was changed.  Z values should occur in
  ascending order.

  The program refers to different kinds of MTs as "types".  For an IMOD
  model, the type is simply the object number; for data from a WIMP
  model file, the type is 256 minus the object color, or the negative
  of this value if the WIMP object is turned off.  A default display 
  format is set up to be used with either kind of model file.  To use
  the defaults with an IMOD model, MTs starting at low and high Z
  should be in objects 1 and 2 respectively; continuous MTs in object
  3, and free MTs in object 4.  With a WIMP model, MTs from low and
  high Z should have colors 250 and 251 (types 6 and 5 in the
  program), and continuous and free MTs 252 and 255 (types 4 and 1).

  When you start the program, you will have to make a standard series
  of entries until you get the first display.  From there, you can
  select a number of options to loop back and change those entries.
  Initial entries in order are:
  
  Name of command file to take entries from, or Return to continue
  making entries from the keyboard. The program can read entries from
  a file instead of from the keyboard, then switch back to keyboard
  input if the file ends with the appropriate entry. 
  
  A list of types to be mapped, or changed, into new types, or
  Return for no mapping of one type into another.  This option is
  useful if you have several different types that you want to combine
  into one.  For example, if you want to treat types 11 and 13 like
  type 1, and types 12 and 14 like 2, and if you also have some
  existing MT's of types 1 and 2 that you don't want to include
  with these types, then you need to remap all of these types by
  entering 11-14,1,2
  
  IF you entered some types to remap, next enter the types to change
  them into.  For the example just described, you would enter:
  1,2,31,32

  Number of bundles to read from model files, or 0 if the entries
  specifying all of the bundles are in yet another file.

  IF you enter a positive number, then enter for each bundle:
  
     Name of model file with bundle in it, or Return to use same file
     as previous bundle
  
     IF you enter the name of file, make the following 1-3 entries:

        Name of file with information on tilt angles, or Return if
        there is no such file (pictures taken at 0 tilt)
  
        IF the model header has no scaling information, make the next
        two entries as well to specify scaling:

          Section thickness in nm, to scale Z coordinates to microns;
          or / to leave Z values unscaled
  
          Magnification of negatives, and scale of digitization (the
          value of microns/pixel from VIDS), to scale the X/Y
          coordinates correctly; or / to leave X/Y coordinates
          unscaled.  This entry makes no difference unless you choose
          to calculate one of the special three-dimensional overlap
          factors.
  
     Number of limiting regions (boundary contours or rectangles
     defined by X/Y coordinates) needed to specify the bundle, or
     0 to take all of the objects in the model.
  .
     For each limiting region, then enter:

        Either IMOD object number and contour number of the boundary
        contour, or a WIMP object number and 0 for data taken from a
        WIMP model file, or 0,0 to enter limiting X and Y coordinates
        of a box.
  
           IF you entered 0,0 next enter the lower and upper X index
           coordinates and the lower and upper Y coordinates of the
           box, or enter / to have no limit on the X and Y coordinates
           THEN enter the lower and upper Z coordinates of the box (in
           units of sections), or / to have no limits on Z coordinates
  
           IF you entered numbers for a boundary contour, next enter
           lower and upper Z coordinates of the "cylinder", or /
           to set those limiting coordinates to the Z coordinate of the
           boundary contour.  The latter is typical if one uses several
           contours in different sections to specify the bundle.
  
  IF you entered 0 for the number of bundles, next enter instead the 
  name of a file.  The first line of this file should have the number
  of bundles specified there.  The rest of the file should be all of
  the entries just described for each bundle.
  
  Enter 0 if you want to specify EVERYTHING or 1 to use the default
  format for types, display colors, etc. with an IMOD model, or 2 to
  use defaults for a WIMP model.  With an entry of 1, you will
  get centers of bundles calculated from MT types 1 and 2, overlap
  calculated from types 1 and 2, and a display occupying the whole
  screen with, from top down, type 4 in order by increasing length,
  types 1 and 2 interleaved with 1 in order by increasing Z of
  endpoint and 2 in order by decreasing Z or startpoint, then type
  3 in order by increasing length.
  
  Enter a list of numbers of the bundles to work with.  Ranges may be
  entered, e.g. 1-3,7-9.

  Enter 1 to have each bundle's center computed separately, 2 to have a
  single center Z value computed with all bundles pooled together,
  3 to specify a single center Z coordinate for all bundles, or
  4 to control center specification more intimately.
  
  IF you entered 3, next enter the Z value to use as center for all
  bundles, in units of original section numbers.
  
  IF you entered 4, next enter a set of numbers, one for each bundle:
  either a specific Z center section value for that bundle, or the
  negative of a specific Z center value in microns, or 0 to have its
  center computed separately from other bundles, or a negative number
  less than -100; all bundles with the same negative number will be
  pooled and given the same computed center value.
  
  IF you did not select default display, next enter two lists of
  types to calculate the center from, where ranges may be entered:
  
     List of types coming from low Z

     List of types extending to high Z
  
  IF you did not select default display, next enter two lists of types
  to compute the overlap from, or 2 Returns to omit computing overlap:

     List of types coming from low Z

     List of types extending to high Z
  
  Enter 0 for simple overlap factor (without considering proximity
  in the X/Y plane), or 1, 2 or 3 for a 3-D overlap factor, where the
  amount of overlap between two MT's per section decays with increasing
  distance between them in the X/Y plane, either as a step function (1
  within a certain distance and 0 beyond it), an inverse power, or
  exponentially.
  
     IF you entered 1-3, next enter 0 to compute an average
     overlap factor for each MT, then average those values over the
     MT's, or 1 to compute the sum of overlap factors for each MT, then
     average those sums over the MT's.  In the latter case, the
     resulting values may depend heavily on bundle size.

     IF you entered 1-3, next enter the distance in the X/Y plane
     at and below which overlap will equal 1.  The distance should be
     in microns if you have scaled X/Y values, or in pixels if you
     have not.  For the step function option, enter the maximum
     preferred distance between MT's.
  
     IF you entered 2, next enter the power for the decay (e.g., with
        a power of 2, overlap will decay as the inverse square of
        distance)
  
     IF you entered 3, enter instead the space constant for exponential
     decay.  Overlap will be 1/e less for MT's separated by 2 space
     constants than for MT's separated by 1 space constant.  Distance
     should be in microns if you have scaled X/Y values, or in pixels
     if you have not.
  
  IF you did not select default display, make the following entries
  to control the display:
  
     List of types to display, or Return for no display.  Ranges OK.
  
     Colors to display them as, or / to take standard colors.  Colors
     are specified as numbers from 0 to 255.  0-240 correspond to gray
     scales from black to white, then 237-255 give olive, dim yellow,
     orange, red, green, blue, yellow, magenta, and cyan. For data
     from an IMOD model, / will assign colors as 256 minus the type.
     For data from a WIMP model, / will give the same colors as in the
     model, unless types have been remapped.
  
     Enter a number for each type to control the ordering of the MT's
     from the top down: 1 or -1 to have in order by increasing or
     decreasing Z of the starting point; 2 or -2 for order by
     increasing or decreasing ending Z; 3 or -3 for order by
     increasing or decreasing length
  
     Enter a positional value for each type, where positions are
     numbered from the top down; two types with the same position
     number will be displayed with their MT's interleaved.
  
  Enter 1 to plot all bundles in the same graph, 2 to plot each bundle
  in a separate graph, or 3 to specify more complicated combinations
  
  IF you entered 3, enter a graph number for each bundle included in
  the display, where graphs are numbered from the top down.  Bundles
  with the same graph number will be pooled for display.
  
  IF you did not select default display, make three more entries
  
     Either the negative of the total horizontal size of display, in
     pixels, or the number of pixels per unit of Z,
     or / to use the default indicated (initally 1280 pixels).

     Total vertical size of display, in pixels, or / to use the default
  
     Line spacing in regions where MT's are interleaved relative to
     spacing in non-interleaved regions, line thickness, axis
     thickness, label thickness, and lengths of major and minor ticks.
     (It will tell you what the defaults are.)  A thickness of 2 IS
     available, but higher even thicknesses are rounded up by 1 (so
     only odd thicknesses are available above 3).  To get lines drawn
     in order from the bottom up instead of from the top down, enter
     the negative of the desired value for interleaved line spacing
     (typically, the negative of the indicated default value.)
  
     Colors for the axes, the labels, and the fitted lines; size of
     labels; # of pixels of additional shift leftward and downward
     for labels; intervals (in # of ticks) at which to have major
     ticks and labels.  It will tell you the defaults; enter / to use
     them.

  At this point you will get the display and some output: the number of
  each type of tube in each graph and the mean and standard deviation
  of their lengths, and computed overlap values for each bundle
  separately and for all bundles together (the last line of output).
  Four overlap values are computed (mean, S.D., and # of MT's
  contributing to each value are printed).  The first is the
  distance past the center that each MT extends.  The other three are
  overlap values for MT's coming from low Z (from the left), for
  MT's coming from high Z (from the right), and for both of those sets
  of MT's combined.  With the simplest overlap computation, the
  overlap value for a single MT is the average amount of Z overlapping
  with other MT's, where the average is only over those MT's from the
  other direction that actually do overlap with the given MT.  The
  values printed out are the mean and S.D. of these averages for all
  the MT's from the given direction.

  With the inverse power or exponential decay options, instead of
  counting 1 unit of overlap per section of overlap between two MT's,
  the amount of "overlap" in each section is computed from the
  distance between the two MT's in that section, giving a number that
  is 1 for nearest neighbor MT's and less for more separated MT's.
  This overlap factor is then summed over all sections in which both
  MT's appear.  For a given MT, the program will then form either the
  mean or the sum of the summed overlap factor between that MT and all
  other overlapping MT's.  The sum is probably a more meaningful
  measure.  Finally, these means or sums are averaged over all MT's
  from a given direction, including MT's with 0 overlap.

  Now you can loop back to various parts of the program. Enter:
  1 to combine the overlap calculation for a group of bundles
  2 to change the display size or interleave/non-interleave spacing
  3 to specify which bundles should go in which graphs
  4 to specify the types to display, and their colors, positions and
     ordering parameters
  5 to specify the types to compute overlap from, or the way of
     computing the overlap factor
  6 to change which bundles are included in the display or computations
  7 to control output of numbers of MT's and overlap values to a file
  8 to read in new bundles and add them to existing ones
  9 to read in new bundles and replace previously read ones
  10 to take commands from a file (next enter filename, or Return to
     take input from the keyboard)
  11 to exit
  12 to fit lines to the starting and ending points of certain types
  13 to change the mapping of one type into another
  14 to plot the graph to a postscript file
  15 to display such a postscript file on the screen
  16 to print the postcript file
  
  IF you enter 1, next enter the list of bundles to combine for
  computing overlap (ranges are ok).  If there are, say, 4 bundles 
  included in the computation and/or display, they are referred to as
  numbers 1 to 4, regardless of their numbers among the entire set of
  bundles that have been read in.
  
  IF you enter 7, on the first such occasion, enter the name of a file
  to store output into.  Then enter:
  0 to turn off output to the file
  1 to output only the overlap calculations to the file
  2 to output only the numbers of MT's to the file
  3 to output both overlap and numbers.

  IF you enter 6, 8, or 9, you will loop back and have to make all of
  entries that follow the point to which you looped back; other options
  involve re-entering only a subset of the parameters.
  
  IF you enter 12, the program will fit a line to the starting points
  of one type of MT, and another line to the ending points of another
  type of MT.  It will display the fitted lines and report two factors:
  the slope, in units of percent of that type of MT starting (or
  ending) per unit of Z; and the distance past the center at which the
  line crosses the level of 50% of the MT's.  It reports these factors
  separately for the two lines, and also shows the average of the
  values for the two lines.  If there are too few MTs to derive a
  value, the value is reported as 0.  It also reports the number of
  MT's used to derive the factors.  Each line displayed on the screen
  occupies the vertical extent of the MT's included in the fit.  When
  you enter 12, you next make two entries:
  
     The type to whose starting points a line will be fit, and the type
     to whose ending points a line will be fit, or / to accept the
     defaults, which are initially the types used to calculate overlap.

     The lower and upper percentile limits for the MT's to be included
     in the fits, or / to accept the defaults shown in parentheses.
     MT's are counted from the top of the display downward.  For
     example, if you enter 5 and 85, then the top 5% and the bottom 15%
     of MT's in each type will NOT be included in the fits.

  IF you enter 13 to change type mapping, you should then select
  option 6 in order to make sure that the new types are being used
  correctly for display or computation.
  
  IF you enter 14 to plot the graphs, the program will ask for the 
  X and Y size and lower left X and Y coordinates, in inches, of
  the location on paper corresponding to the full screen display.  You
  can use these entries to change the size or aspect ratio of the
  display.  Next the program will ask for a label for the X axis; enter
  Return for no label.  The size and spacing of the axis numeric and
  text labels can be controlled by the entries that one sets when
  displaying the graphs on the screen.

HISTORY
  Written by David Mastronarde, 10/3/90
  2/21/92: changes to scale data into microns, add line fits
  5/1/92: implemented simple distance-dependent overlap
  6/9/92: implemented mapping of types
  11/5/94: fixed interset and intergraph spacing, aligned interleaves
           at the bottom of each set to obviate need to invert drawing
  6/14/96: added plotting output
  4/28/97: changes for IMOD models