Boulder Laboratory for 3-Dimensional Electron Microscopy of Cells

MTK(1)							     MTK(1)

NAME
	mtk - to analyze spatial relationship between objects in 3D

SYNOPSIS
	mtk

DESCRIPTION

  MTK analyzes the distribution of distances of closest approach
  between objects in IMOD models.  It considers objects of 3 kinds: open
  contour objects, which are referred to as "line" objects; scattered point
  objects; and meshed closed contour objects, referred to as "meshed"
  objects.  Each kind of object is generally composed of multiple items that
  are considered separately in the analysis.  For an open contour object, each
  contour forms a separate line.  It is possible to measure the closest
  approach of other items to the whole line, or to break the line into
  multiple segments and measure the closest approaches to each of the
  segments.  For a scattered point object, each point is a separate item, a
  sphere with a defined radius that may be different for each  point.
  Distances can be measured either from the center of the sphere or from its
  surface.  For a meshed object, each connected set of mesh triangles is
  considered as a separate entity, referred to as a surface.  These surfaces
  are not the same as the surfaces that can be defined within the model in
  3dmod.  The model need not contain formally defined surfaces; Mtk will
  analyze the meshes and divide an object into surfaces based upon which
  portions of the mesh are connected to each other.

  In general, Mtk measures a quasi-density (number per cubic micron) of one
  kind of object as a function of distance from another kind of object.  It
  does this by considering each item in the second kind of object (referred to
  as reference objects) and measuring the closest approach to each of the
  items in the first kind of object (referred to as neighbor objects).  From
  this, it gets a count of the number of closest approaches at each distance
  from the reference objects.  It also estimates the amount of volume at each
  distance from the reference objects, and divides the count by the volume to
  obtain a density at each distance.  Each kind of entity (point, line, line
  segment, or mesh surface) can serve as the reference object; while points,
  whole lines, and mesh surfaces can serve as the neighboring object.  

  Ideally, a density analysis will give a graph that is flat or constant with
  distance when items are randomly arranged relative to each other.  This is
  rarely the case for the densities produced by Mtk, for several reasons.
  For anything besides measurements of distance between the center of spheres,
  the density is skewed by using a closest approach measure and by the
  difficulty of estimating the volume of space at a given distance from
  reference items.  Also, there is no provision to deal with edge effects as
  there is in Nda, so density graphs will always fall off at large distances.

  The standard way to determine whether a distribution of items is non-random
  is to shift some of the items randomly in space and compare the density
  graph with shifted items to the actual density graph.  In order for this
  approach to be valid, it is essential that the locations of the randomly
  placed items be constrained to about the same degree as they are in their
  original positions.  One main constraint is that shifted items should be
  placed only in the region where they were originally modeled.  Mtk allows
  one to specify an object with contours bounding the valid region for
  shifting.  A second kind of constraint is that items should be not occupy
  the same space as, or come too close to, other items of various kinds.
  Imposing this constraint can make the shifting process very time-consuming.

  Mtk was first written to analyze closest approaches between the trajectories
  of microtubules in 3 dimensions (i.e. MicroTubule Kissing).  It was adapted
  from Nda, and many of the entries and commands are identical. Some of the
  terminology used here is a holdover from these origins; for example, a
  "region" refers to the portion of a model being analyzed, which is generally
  the whole model here, and an IMOD model object is sometimes referred to as a
  "type".
  
  Because these analyses can be very time consuming, you will probably want to
  run mtk through a command file.  The $IMOD_DIR/com directory has 4 sample
  command files that you can examine and adapt for your use: mtksimple.com for
  complete analysis of a simple model; mtkgraph.com showing how to plot a
  saved graph to a postscript file; and mtkcomplex1.com and mtcomplex2.com,
  based on part of the analysis of Brad Marsh's HIT cell model.

  Mtk starts with a number of entries required to define a model file and the
  first analysis and get to the point where numerous options can be selected.
  These entries are:

  Name of a file to take entries from, or Return to take entries from the
  keyboard.  You can place a laborious series of initial entries into such a
  command file, with one line for each line that you would otherwise type in
  to the program.  However, you would need to have, at least, all of the
  entries that are required to get to the point in the program where options
  may be selected.  Finish the command file with a 24 to return to input from
  the keyboard, or with a 25 to exit the program.

  Name of a file to store density values in, or Return for none.  You can
  later use option 12 to store density values for selected graphs in this
  file.  This capability is not as flexible as the ones provided by the
  options for saving and reading graphs from a file (28 and 32).

  0 to get graphs displayed in a graphics window, or 1 to suppress graphs.

  0 for analysis of densities and closest approaches in 3D, or 1 for
  analysis of the frequency of MT ends as a function of distance from a
  bundle.  The latter analysis is not documented here.

  The name of the model file, or Return to skip to the point in the program
  where options may be entered.  

  After entering a model file, there are 1 or 4 entries to describe the
  scaling of the coordinates in 3-D:

  Name of file with tilt information, or Return if none
  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.
  
  IF the model file has no information about scaling in its header,
  the next three entries are required:
  
     Magnification of negatives (without any commas)
  
     Scale, in microns per pixel, at which negatives were digitized
  
     Section thickness in nanometers
  
  Next enter a list of Z values (numbered from zero) specifying gaps in the
  data across which meshed objects should be connected to form one surface
  if they overlap in X and Y.  This entry is used when you have a gap in
  modeling between two serial tomograms, and meshed objects that span the
  gap.  If you do not specify the gap, then two pieces of a meshed object
  that are located on opposite sides of the gap will be considered separate
  surfaces even if they overlap in X and Y.  With this entry, the program
  will seek to connect pieces of an object that are just adjacent to, or
  protrude into, the gap, with corresponding pieces on the oter side of the
  gap.  Enter the widest gap that will be encounted between entities that
  you want connected.

  Next enter the lower and upper section numbers within which open contour
  (line) objects will be analyzed, or enter 0,0 to have no limits in Z for
  these objects, or 0,-1 to go back and read from a new model.
  
  Next enter the bin width in microns, and the number of bins to include in
  the density graphs.
  
  Next are 4 entries that govern density measurements involving lines
  or points:

  0 to find the single closest approach over the entire length of a line,
  or the interval in microns at which lines should be sampled.  With an
  interval, each line is divided into samples, or segments, of this length,
  and distances are measured to/from each segment independently.

  The power to apply in scaling the counts of items at various distances
  from lines into relative density values, and the number of points to fit
  over to determine the 3-D trajectory of a line.  The power is relevant
  only when finding the closest approaches to whole lines rather than
  distances to line segments.  Counts are divided by distance to the given
  power.  In choosing a power, the goal is to have a scaled graph that is
  relatively flat over medium distances; a power near 0.4 may accomplish
  this for inter-microtubule distances.  The number of points to fit over
  is relevant to trajectories modeled predominantly through the Z dimension
  (e.g., MTs tracked through serial sections).  For more randomly oriented
  data (e.g., from tomograms), enter 0 for this number.  If the number of
  points to fit is 2, then the actual coordinates of digitized points, and
  the line segments connecting them, will be used to describe the position
  of the MT.  With a number great than 2, each segment of the MT will be
  represented by a line least-squares fit to that number of points.

  0 to find distances from the start of each line segment, or 1 to find the
  distance of closest approach to each segment.  This entry is relevant
  only if lines are being divided into segments.

  0 to measure distances from the center of scattered points or 1 to
  measure from the surface, relying on the radius or size of each point.  

  Next enter the number of density graphs to compute.  After this, enter
  two lines for each graph:
  
     A list of IMOD object numbers of "reference" objects to measure
        distances FROM 
     A list of the "neighboring" objects to measure the distances TO,
        from those reference objects.
  
  You can compute multiple graphs at once, as long as all of the reference
  objects are the same kind (lines, points, or meshes) and all of the
  neighboring objects are the same kind.  If objects to do satisfy this
  constraint, you will be asked to enter the graphs again.

  At this point, the program will compute the distributions then go to
  the central option point.  Here is the option summary:

  1/2: Type/Average selected bins of the graph in a specified window
  3: Compute integrated number of (excess/missing) items in selected bins
  4/5: Display one graph in a window/Enter list of graphs to display
  6/7: Rescale X or Y axis of one window/Y axis of all windows
  8/9: Plot one window/all windows to PostScript graphics file
  10/11: Output PostScript file to screen/printer
  12: Output single or average graph to file
  13: Loop back to specify new range of Z to analyze (or new model)
  14: Change radial weighting of a graph
  15: Analyze new region and average with previous region(s)
  16: Redo current region(s) with new bin size, # of bins, or types for graphs
  17: Set min & max distances at which to compute angles and add lines to model
  18: Save bins of a graph to specify rejection probabilities for random points
  19/26/20: Do current region(s) with shuffled/converted types or random shifts
  21: Save current set of objects and their types as a new model
  22/27/23: Do many sets & integrals with shuffled/converted types/random
        shifts
  24: Take command input from file        25: Exit
  28/29/30 Save a graph/Average/Combine 2 graphs into an extra graph location
  31/32: Save graph in file/Read from file into an extra graph location
  33: Replace some sets of bins by their averages
  37/38/39 Add list of graphs/Read list of graphs from file/Read&Add from file
  40: Unshift an object
  41: Toggle between including and excluding items that failed to shift
  42: Export graph values or points for drawing to file
  43: List distances of close approach between min/max limits

  Here is a specific description of each option:

  1/2: To type or average some of the bins of a graph that is currently
  displayed in a window; enter the window number (1 to 4) and the starting and
  ending bin numbers to type or average, or / for all bins.  If you enter the
  negative of the graph number for option 1, you will get the raw values of
  the number of items counted in each bin, rather than the density averaged
  over the reference items.

  3: Use this option to integrate the number of neighboring items that are
  represented by a particular set of bins in a density graph displayed in a
  window.  Enter the window number, the starting and ending bins to integrate,
  and the baseline or control level.  If you enter a control level of 0, you
  will get the total number of items in that range of radial or angular
  distances.  Otherwise, you will get the number of items that are excess or
  deficient relative to the control level.  The default value for the control
  level (selected by terminating the entry with ",," or "/" instead of a
  value) is the last average obtained with option 2.

  4: To display one graph in a window; enter the graph number and the window
  number.

  5: To display a set of graphs in up to 4 windows; enter a list (ranges
  allowed, e.g. 5-8) of up to 4 graph numbers, which will then be displayed in
  windows 1 to 4.

  6: Rescale X or Y axis of one window; enter the window number and 0 to
  rescale X or 1 to rescale Y.  The program tells you the maximum value of the
  data in that dimension and the current full-scale value on that axis.  Then
  enter the desired full scale X or Y value.

  7: Use this option to rescale the Y axis of all windows to the same value,
  the largest full-scale value needed by any one window.  Note that you need
  to set up the scaling of the graphs to your liking with options 6 and 7
  before using a plot command.

  8: Plot one window to a PostScript graphics file; enter the window number
  and either 1, 2, 3, or 4 to put the graph in one of the 4 standard positions
  on a page, or 0 to specify the graph location and dimensions.  Next, enter 1
  to start the graph on a new page from a previous graph (if there was any
  previous graph).  IF you elected to specify the graph location and position,
  you now have many entries to make; see the section at the Nda man page
  for details.

  9: Plot all windows (up to 4) to a PostScript graphics file.  The graphs
  will go in the four standard positions.  Enter 1 to start the graph on a
  new page from a previous graph.  Note that you need to set up the scaling of
  the graphs to your liking with options 6 and 7 before using a plot command.

  10: Graph the PostScript file on the screen.  When you return from this
  option, the program will start a new graphics file if you make any more
  graphs with options 8 or 9, and you will lose the file for the graphs that
  you have just seen.  So, if you want those graphs, you need to print them
  immediately with option 11 or rename the file from gmeta.ps.

  11: Print the graphs in the Postscript graphics file.

  12: Print the density values and other pertinent information about a graph
  in the output file defined when you started the program; enter the graph
  number.

  13: Loop back to specify a new range of sections to analyze (for line
  objects), or a new model file entirely.  The new results will replace any
  previously obtained results.
  
  14: Rescale an existing graph by applying a different power to
  distance in scaling the counts of numbers of items at each different
  distance.  This can be useful in making a graph appear flatter after an
  initial peak.

  15: Average a new range of sections (for line objects), or a completely
  different model, with the results already obtained.
  
  16: Re-analyze the currently defined region(s) with different bin sizes,
  number of bins, line and point parameter settings, or different
  specifications of the types to be used to build graphs from.  After
  entering a new bin size or number of bins, enter 1 if you want to change
  any of the parameters governing line and point distance measurements, or 0
  to use existing parameters.  After changing those parameters or not, as the
  case may be, enter 1 if you want to specify new types of graphs, or 0 to
  use the existing specifications.  If several regions have been averaged
  together, then the program will automatically analyze and average all of
  those regions.

  17: Set minimum and maximum distances for determining the mean angle
  of closest approach between lines and obtaining markers of points of closest
  approach when outputting a model file.  After setting these limits, the
  program will re-analyze the current data, first allowing you to enter bin
  and other parameters and define graphs as if you had selected option 16. For
  any closest approach between these two limits, the program will save the
  information about the closest approach in case you write out a new model
  file.  For an approach between two lines, it will also compute the angle
  between the two lines.

  43: List all of the distances that fell between the minimum and maximum set
  with option 17, corresponding to the lengths of the connector lines that
  would appear after saving a model file.

  18: Save the initial bins of a graph to use later as a list of probabilities
  for rejecting a randomly shifted item that is too close to another item.
  Enter the graph number and a baseline density level that corresponds to a
  probability of 1.0.  The densities in the bins that are less than this
  baseline level will be converted to probabilities between 0 and 1 and stored
  for later use with options 20 and 23.  This option is convenient but does
  not produce a very good match to the rising phase of a density graph; to do
  that, you have to adjust probabilities by hand.
    
  19: Do the currently defined analysis on the currently defined region(s),
  but with line and point contours randomly shuffled among objects.  Do not
  use this option if the model has both line and point objects.  It will work
  for line objects because each line is in one contour.  It will work properly
  for point objects only if each point is in a separate contour.

  26: Do the currently defined analysis on the currently defined region(s),
  but with some of the contours in line and point objects randomly converted
  to other objects.  This option gives more control than option 19 and is
  suitable if there are both line and point objects, because you can prevent
  conversion between them.  It will always work for line objects, but will not
  work well for point objects unless each point is in a separate contour. This
  option requires the following entries:

   Number of objects to convert into other objects

   For each of the objects to be converted, then enter:
      The object to convert, the object to change it into, and the fraction of
         contours in that object to convert

  20: Do the current region(s) after applying random shifts to the positions
  of selected objects.  Shifting typically requires many attempts (trials)
  to find a position that fits all of the constraints.  This can be done in
  a series of cycles, where the allowed distance to shift is increased from
  one cycle to the next.  There are many entries to make:

     Minimum and maximum distance to shift in the X/Y plane.  The program
     will attempt to shift objects by a distance between these limits for a
     certain number of trials on the first cycle, then increase the limits
     for each following cycle of trials.  If none of these attempts
     succeed, the entity will remain unshifted.
  
     Maximum amount to shift in Z relative to the maximum shift in the X/Y
     plane.  Enter 1.0 for shifts in Z as large as shifts in X and Y, or 0
     for no shifting in Z, or a number in between to constrain Z shifts to
     be smaller than shifts in X and Y.

     List of object numbers of objects to shift, or Return for all
     objects.  The objects must all be of the same kind.
  
     List of other objects to check distances from, or Return for all other
     objects.  When the program attempts to shift an entity, it checks its
     distance of closest approach to all entities in the objects specified
     in this entry.  This is in addition to checking its distance from
     entities in the objects that are being shifted.
  
     The number of probability curves to use for determining whether a
     shifted entity is too close to other items.  The first curve will be
     used for checking the spacing between entities in the objects being
     shifted.  Any one of the curves can be used for checking the spacing
     from other objects.

     IF you have previously saved probability values with option 18,
     enter 1 to use these values for the first curve, or 0 not to.

     Make the following entries for each of the probability curves:

        The number of bins of probability values to use for rejecting
        a shifted entity as being too close to other entities, and the bin
        size (a radial distance).  This bin size need not match the bin size
        the density analysis.

        The probability values for each bin (between 0 and 1)
     
     IF you have entered more than one curve, next enter the number of the
     probability curve to use for each of the other objects that distances
     are going to be checked against.

     Maximum distance to shift objects outside the bounding box of the
     original data, i.e., the maximum extent in X, Y, Z and Z of the
     unshifted model.

     Object number of an object with contours that surround the allowed
     volume within which shifted entities must lie.  If the model doesnot
     uniformly fill its bounding box, bounding contours can be used to
     place tighter constraints on the shifted objects and avoid having them
     placed preferentially in empty areas of the volume.

     1 to check a potentially shifted item against both items that have
     been shifted and items yet to be shifted, or 0 to check them only
     against items yet to be shifted (as well as against the other objects
     that you specified).  If there is a substantial failure rate in
     shifting items, checking against unshifted items will make the
     spacings between all items be legal after shifting, but it might
     increase the difficulty in finding shifted positions.

     Maximum total number of trials or attempts to shift an entity.

     Number of trials per cycle and factor by which to increase the maximum
     allowed shifts on each cycle.

  40: Unshift an object that has been shifted.  Enter the object number to
  unshift.  The program will remember which entities were successfully
  shifted, so you can then do an analysis of actual distances from items
  for just the items that were shifted.

  41: Toggle between including and excluding items that failed to shift from
  an analysis.  Originally all items are included; excluding ones that failed
  to shift allows you to do a density graph based on the subset that shifted,
  then unshift them and get a completely comparable density graph.

  22/27/23: Do a series of sets of items randomly shuffled or converted
  between objects or randomly shifted in order to obtain statistics on the
  significance of integrated deficiencies or excesses in the real density
  graphs.  If you select option 27, first enter 0 to use previously specified
  conversions of objects, or 1 to specify new conversions, in which case you
  would then make the entries listed under option 26 above.  If you select
  option 23, first make the entries described above under option 20 to
  control the shifting of objects.  For all of the options, then make the
  following entries to control the computation of integrals:

     0 to make a separate specification for each graph of the bins to use in
     computing the integral, or 1 to use the same specification for all graphs

     IF you entered 0, make the following entries for each graph; otherwise
     just make these entries once:

        Starting and ending bins of the peak or deficiency to integrate

        Starting and ending bins to compute a baseline density from, or 0,0 to
           use a fixed value for the baseline instead of computing it from
           each graph 

        IF you entered 0,0, then enter the fixed baseline density value.

     1 to accumulate mean and standard deviation graphs, or 0 not to.  This
     question appears after the program computes and types out the integral
     for each graph.

  The program will then ask you for the number of control sets to run.  It
  will do these control sets, and type out the mean and standard deviation of
  the integral for each graph, and the number of sets whose integrals exceed
  the integral of the real data.  You can specify a new number of sets to
  run, whose results will be accumulated with existing results, or you can
  enter 0 to return to selecting options. 

  21: can be used to save the current model, which can be either the
  original model or a model after shuffling or converting lines or points
  among objects or shifting lines or points objects randomly.  (Random
  shifts of meshed objects will not be reflected in the output model.)  If
  you have run an analysis on this model with limits set for storing
  information on closest approaches, then two new objects will be created
  in the model, one with connecting lines between the two items making a
  selected close approach, and one for scattered points at the middle of
  each connecting line. You can also transfer the contours or surfaces that
  made a close approach within the specified limits into new objects.   This
  will work for line objects, for meshed objects, and for point objects if
  every point is in a separate contour.  With a meshed object, all contours
  associated with a surface having a close approach will be transferred.
  After entering the output file name, enter a list of objects for which you
  want to transfer a contour to a new object, or Return for no such transfers.

  24: Take input from a command file; enter the file name or Return to
  continue or resume input from the keyboard.  The file should end with a 24
  and a blank line to resume input from the keyboard, or a 25 to exit the
  program.

  28:  Save a graph in an "extra" graph location.  An extra location is any
  graph location up to 50; it may already contain a graph.  Enter the graph
  number, and the number of the graph location to save it into.

  29:  Average two graphs into an extra graph location.  The program will
  average the two graphs by computing the total point count and the total area
  occupied by each bin and deriving the density from these values.  Enter the
  numbers of the two graphs to average and the number of the graph location
  (any number of 50) in which to place the result.

  30:  Linearly combine two graphs into an extra graph location.  This will
  form a weighed sum of two graphs.  Enter the numbers of the two graphs, the
  coefficients to apply to each, and the number of the location to place the
  result in.

  31:  Save a graph in a file, in a form that can be easily retrieved and
  redisplayed.  First enter the number of the graph to save.  Then enter the
  name of the file to save it in, or Return to add it to the currently open
  file if graphs have already been saved into that file.

  32:  Read a graph from a file that was saved with option 31.  First enter
  the number of the graph location to read the graph into (any value up to
  50).  Then enter the name of the file to read from, or return to read from a
  file that has been read from before.  Then enter the number of the graph in
  the file to read.

  33:  Replace some sets of bins by their averages.  In its simplest form,
  this option allows you to combine bins into larger bins and get the same
  graph you would have gotten if you had run the analysis with the larger bin
  size. However, you can choose to combine only selected sets of bins, thus
  allowing you to have a single graph with narrow bins in some places and
  apparently broader bins elsewhere.  Also, you can have the program
  automatically figure out which bins to combine where, so that the densities
  in all of the new apparent bins are based on roughly the same amount of
  area.  This will give you a graph with a noise level that is nearly constant
  across the graph, and may help you distinguish signal from noise.  For
  simple combination of bins, enter the number of bins to be averaged together
  in each replacement, and the starting and ending bin numbers to replace
  (e.g., 3,1,12 will replace bins 1, 2, and 3 by their average, 4, 5, and 6 by
  their average, and 7-9 and 10-12 by their averages).  For automatic optimal
  combination of bins, enter the NEGATIVE of the desired number of apparent
  bins to end up with over the range of bins being replaced, and the starting
  and ending bin numbers to replace.  For example, -5,1,20 will divide the 20
  bins from 1 to 20 into 5 sets that have, as nearly as possibly, the same
  amount of area for the density calculation.  The program will then replace
  the bins in each set by that set's average.
       After this first entry, next enter a list of graphs to apply the
  replacement to, or Return to apply it to all graphs.  Although you can
  validly run the option first on one set of bins and then again on a
  non-overlapping set of bins, do not run the option more than once on the
  same set of bins.  To experiment with combining bins in different ways, copy
  the desired graph into an extra graph location and combine the bins of that
  copy.  To get the best results from the automatic combination of bins, start
  with bins that are much smaller than the final desired bin size.

  37: Add a list of graphs into an extra graph loaction.  First enter the list
  of graphs to add together, then enter the location in which to place the
  sum. 

  38: Read a list of graphs from a file and place each in a separate extra
  graph location.  First enter the list of graph numbers in the file, then
  enter the list of graph locations in which to place them, then enter the
  name of the graph file from which to read the graphs.

  39: Add together a list of graphs from a file.  First enter an extra
  location in which to place the final sum, and an extra location to be used
  for temporary storage.  Then enter the list of graph numbers in the file.
  Finally enter the name of the graph file.

  42: Export a graph to a file; i.e., output the graph information in a
  format suitable for importing into a spreadsheet or graphing program.  
  First enter the number of the graph to save.  Then enter the
  name of the file to save it in (only one graph can be saved per file).
  Then enter 0 to output the density values or 1 to output raw counts in each
  bin.  Finally, enter 1 to output points that could be connected to draw a
  histogram, or 2 to output the starting distance and bin value for each bin,
  3 for the midpoint distance and bin value of each bin, or 4 for the
  starting and ending distance and bin value for each bin.

HISTORY
	  Written by David Mastronarde,  November 1991
          Expanded to full 3-D analysis, March 2000
          Documented, August 2003