mtk(1) General Commands Manual mtk(1)
NAME
mtk - to analyze spatial relationship between objects in 3D
SYNOPSIS
mtk [-comfile filename] [graph options]
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 sepa-
rate 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 orig-
inally 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 trajec-
tories of microtubules in 3 dimensions (i.e. MicroTubule Kissing). It
was adapted from Nda, and many of the entries and commands are identi-
cal. Some of the terminology used here is a holdover from these ori-
gins; 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 mtkcom-
plex1.com and mtcomplex2.com, based on part of the analysis of Brad
Marsh's HIT cell model.
Mtk takes several standard command-line options about the graphics win-
dow, plus the option -comfile followed by the name of a file to take
commands from, which works just like the first entry to the program
described below. The graphics options are: -s followed by a window
size in x and y, -p followed by a window position in x and y, -message
followed by a message to be shown in a message box, -tooltip followed
by a tooltip for the graphics window, and -nograph to disable the
graphics window. The latter should be after a -comfile entry, if any.
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 other-
wise 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 pro-
gram.
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 pro-
gram 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
These are obsolete specifications based on digitizing from negatives
and, if possible, you should add a pixel size to the model header in
the 3dmod Edit-Model-Header dialog. If not, to get isotropic pixels
with a nominal size of 1 nm, you could enter 1000, 1, and 1. If you do
have a pixel size, enter 1000, the pixel size in nm, and either the
pixel size to get isotropic pixels or the actual section thickness.
Or, enter 1, the pixel size in microns, and the pixel size or actual
thickness in nm.
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 con-
tour (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 rele-
vant only when finding the closest approaches to whole lines rather
than distances to line segments. In other cases, the initial power is
2. Counts are divided by distance to the particular power, so a power
of 2 is appropriate for measuring density as a function of distance
from points. In choosing a power in other cases, 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 num-
ber of points to fit over is relevant to trajectories modeled predomi-
nantly through the Z dimension (e.g., MTs tracked through serial sec-
tions). 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 connect-
ing them, will be used to describe the position of the MT. With a num-
ber 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 rele-
vant only if lines are being divided into segments.
0 to measure distances from the center of scattered points or 1 to mea-
sure 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 refer-
ence 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 45: Set PostScript filename
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
44: Toggle between recording distances to all and nearest neighbors
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 start-
ing 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 dis-
played 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 num-
ber of items that are excess or deficient relative to the control
level. The default value for the control level (selected by terminat-
ing 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 dis-
played 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 num-
ber 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 sec-
tion 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 measure-
ments, or 0 to use existing parameters. After changing those parame-
ters 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 automati-
cally 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 clos-
est 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 pro-
gram 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 proba-
bilities 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 ris-
ing phase of a density graph; to do that, you have to adjust probabili-
ties 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 ran-
domly 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 frac-
tion of
contours in that object to convert
20: Do the current region(s) after applying random shifts to the posi-
tions 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 sub-
set 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 previ-
ously specified conversions of objects, or 1 to specify new conver-
sions, 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 devi-
ation 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 loca-
tion 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 cur-
rently 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 com-
bination 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.
44: Toggle between recording distances to all and nearest neighbors.
Initially, the program records in the graphs the distances between each
reference item and all of its neighbors. This option switches it to
recording only the distance to the nearest neighbor for each reference
item, or back again. With nearest neighbor distances, the vertical
scale of the graph is the fraction of reference items that have a near-
est neighbor at the given distance; the initial power entry has no
effect on the graph scaling.
45: Set name of output file for PostScript graphics; this can include a
relative or absolute path. If a graphics file has already been
started, it will be closed, and the file entered here will opened for
the next set of graphics output.
HISTORY
Written by David Mastronarde, November 1991
Expanded to full 3-D analysis, March 2000
Documented, August 2003
BUGS
Email bug reports to mast at colorado dot edu.
IMOD 4.11.0 mtk(1)