mtk(1) General Commands Manual mtk(1)NAMEmtk - to analyze spatial relationship between objects in 3DSYNOPSISmtk [-comfile filename] [graph options]DESCRIPTIONMTK 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-comfilefollowed 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:-sfollowed by a window size in x and y,-pfollowed by a window position in x and y,-messagefollowed by a message to be shown in a message box,-tooltipfollowed by a tooltip for the graphics window, and-nographto disable the graphics window. The latter should be after a-comfileentry, 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.HISTORYWritten by David Mastronarde, November 1991 Expanded to full 3-D analysis, March 2000 Documented, August 2003BUGSEmail bug reports to mast at colorado dot edu. IMOD 4.10.18 mtk(1)