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 differ-
       ent 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 bun-
       dle, 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 bun-
       dles 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 combina-
       tion of bundles that you desire.  Alternatively, you may enter the cen-
       ter 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 pro-
       gram 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 col-
       ors 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 exam-
       ple, 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 speci-
       fying 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 bun-
       dles 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 for-
       mat 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 bun-
       dles, 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 nega-
       tive 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 aver-
       ages for all the MT's from the given direction.

       With the inverse power or exponential decay options, instead of count-
       ing 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 postscript 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 con-
       trolled 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

BUGS
       Email bug reports to mast at colorado dot edu.



BL3DEMC                              4.7.3                        mtoverlap(1)