This call will ask the user to select any frame of the sequence in folder /images (see ... This call will start a graphical user interface to the LAPTrack package.
Cluster Track Software Guide Introduction
The following guide presents the software package ClusterTrack used for the detection, tracking, and growth track clustering of +TIP comets in the analysis of microtubule dynamics, as described in Matov et al. Nature Methods, 2010. The software modules are independent of one another and communicate via data files. This is a proof-of-principle software and serves mainly the purpose of documenting the code that was used to generate the data of this publication. The last data processing with this software was performed on MATLAB 2006a on Windows XP. A more integrated and user-friendly package with a convenient graphical user interface and statistical tools for the post-processing of track clusters is downloadable from lccb.hms.harvard.edu. The package is called PlusTipTracker. PlusTipTracker will be continuously upgraded and maintained for use on newer Matlab versions running both on Windows and Linux operating systems. We recommend users to download PlusTipTracker for image processing and consult the present software modules only for algorithm documentation. The ClusterTrack zip file contains two top folders, software, and testdata. The folder testdata contains two directories with the raw TIFF image series of the dual-color movie used for the validation of the algorithm in Fig. 3. A readme file documents the image acquisition parameters. The operation of the software modules are explained based on this data set. The folder software contains five top-level Matlab functions: • • • • •
detectFeature.m trackFeature.m trackCluster.m plotGroup.m parseGroup.m
Each of these functions is described in the following documentation. Besides these functions there is an extensive directory tree. Of note, trackFeature calls a particle tracking software, called LAPtrack, with much more functionality than needed for the comet tracking. While we gladly provide all functions of LAPtrack (documented in \laptrack\currentManualFiles) we point out that these functions are not part of the methods described in the paper. The core tracking algorithm in LAPtrack has been published and validated in Yang et al. 2005 (Ref. 13 of the manuscript). To prepare the software for test runs we recommend renaming the folder software with an unambiguous name. This folder with all subfolders has to be included in the Matlab path (see File -> Set Path of the Matlab menu).
1
Feature Detect Module Guide detectFeature is the main function of the Feature Detect module All input parameters are described in Supplementary Table 1. >> help detectFeature SYNOPSIS
feats
INPUT
testOpt:
= detectFeature(testOpt,coef,coef2,sigma,sigma2,s,k)
coef: coef2: sigma: sigma2: s:
k:
OUTPUT
feats:
(0) runs through the whole sequence, performs comet detection and saves the results to disk. (1) plots the analysis for a single frame for the purpose of parameter testing. noise thresholding coefficient (default 1) feature template thresholding coefficient (default 1) std for Gaussian filter kernel for high spatial frequencies std for Gaussian filter kernel for low spatial frequencies length of time stamp in image filename (2) for time stamps 10-99 (3) for time stamps 100-999 number of frames in the sequence to be analyzed If testOpt is set to 1 then only the k-th frame is analyzed a structure of the length of the number of frames processed with four fields per frame containing the following: 1. [y] position of the centroid; 2. [x] position of the centroid; 3. (0-1) value for the eccentricity; 4. spatial orientation in radians;
2
Examples for the dual-color movie
>> detectFeature(1,2.5,1,1,3,2,45) This call will ask the user to select any frame of the sequence in folder /images (see screenshot above). Subsequently, the comets will be detected in frame 45 and results will be presented as shown below. >> detectFeature(0,2.5,1,1,3,2,97) This call will ask the user to select the first frame of the sequence, and then run through the entire sequence of subsequent frames. Results will be saved as .mat file for each image to disk in folder /cands which the user needs to create prior to running the function (see screenshot above).
3
Feature Track Module Guide trackFeature is the main function of the Feature Track module. All input parameters are described in Supplementary Table 1. >> trackFeature This call will start a graphical user interface to the LAPTrack package. In the following we guide the user step by step through the operations required for the tracking of the detected comets. 1. Select Set project path from Data Input/Output drop down menu This step will set the project path; you will click on folder /EB1 for the example on the previous page.
4
2. Generate feature data file from the Preprocessing drop down menu This step will load the data files generated by the detectFeature function.
5
3. Select Tracking File Generation from the Preprocessing drop down menu Use Old Format as shown. This will call another dialog window allowing the user to define control parameters for the tracking.
6
Type in 4 for both Minimum search radius and Maximum search radius as shown in the figure below and then press Start configuration file generation. For comet tracking the other parameter inputs of this window are meaningless.
7
4. Select Tracking Batch File Generation from the Preprocessing drop down menu. Then a new window will pop-up (not shown). In the new window, press the button Generate tracking batch file.
5. Go to the project folder and double click on \point_files\lapbatch.bat This batch file will start the core module of the LAPtrack software, which consists of compiled modules written in C++.
8
6. Select Convert Text Track File to MAT File from the Data Input/Output drop down menu. This will call another dialog window (not shown). In this window click the button on the right (ASCII data files) where the text file is listed. Then select Convert to .mat file.
This last step will generate an output file called config001_4p00_bidir.mat containing the tracks and it will save the file in the automatically generated folder /point_files (see screen shot below; note that with default settings of Windows Explorer the extension ‘.mat’ is not shown):
9
Loading the file back into the MATLAB workspace generates a variable tracks with the following structure (example for dual-color movie):
10
7. In the Set Analysis Parameters (highlighted in blue) menu fill in: a. Set Minimum Lifetime = 4 b. Set Calibration Scale Factor i. pixel size = 0.107 microns ii. sampling = 0.62 sec Then select Generate Static Track Color Map (second from top down) from the Data Analysis drop down menu
11
A figure with the results of the particle tracking (screen shot below) and the corresponding velocity histogram (not shown) will appear.
12
Track Cluster Module Guide trackCluster is the main function of the module that clusters growth tracks to generate additional parameters of microtubule dynamics. All input parameters are described in Supplementary Table 1 >> help trackCluster SYNOPSIS
group = trackCluster(coneAngPos,trackAng,alpha,nbFrames,… fileName,dirName)
INPUT
coneAngPos: forward cone opening trackAng: maximal angle for directional changes between track pairs alpha: multiplication factor for microtubule shortening rates nbFrames: number of frames in the time-lapse sequence fileName: file name (can be omitted and file can be selected manually) dirName: directory name (can be omitted and directory can be selected manually)
OUTPUT
group:
a structure containing a field ‘list’ where the indexes of all tracks associated with the current cluster are listed
Example for the dual-color movie >> group = trackCluster(45,60,2,97) This call will ask the user to select the config001_4p00_track_bidir.mat file (see screen shot below) resulting from the feature tracking and perform the grouping.
13
The grouping results will be saved in a folder /group automatically created in the project folder (see below).
14
In this folder a file group.mat will be stored. It contains an array of lists, each one representing on group of clustered growth tracks. In the example below, the sixth group consists of tracks 2407, 518, 179, 16, and 166.
15
Functions for Plotting and Data Parsing The plotGroup function serves to visualize the clusters of tracks. It is called at the end of the trackCluster function to provide for the user visual feedback with the results (see below). Users, who want to run this function outside the trackCluster function have to load into the MATLAB workspace two data structures, group and tracks. These variables can be retrieved from disk from the subdirectories /group and /point_files which store the outputs of the trackCluster and trackFeature functions. >> help plotGroup SYNOPSIS
plotGroup(tracks,group)
INPUT
tracks: group:
structure with tracks participating in the trajectories structure with track assignments into groups that form clustered trajectories.
Example for the dual-color movie >> cd >> load /groups/group.m >> load /point_files/config001_4p00_track_bidir.mat >> plotGroup(tracks,group)
16
In the resulting plot black squares indicate the beginning of groups and asterisks indicate the end of tracks or gaps. Red lines terminated by a red asterisk indicate measured growth tracks. The black dotted lines connect the tail to the head of these tracks. Green lines terminated by a green asterisk indicate forward and backward gaps extracted from the clustering.
17
The parseGroup function can be called to assign each track within a cluster to growth or shortening event. It takes as input the name of directory where the project is and parses through the ‘groups’ folder to compute the inferred microtubule parameters discussed in the paper.
>> help parseGroup SYNOPSIS
parser = parseGroup(dirName)
INPUT
dirName:
project directory
OUTPUT
parser:
a structure containing several fields
Example for the dual-color movie >> parser = plotGroup()
Parser is a structure with the following fields containing distributions of parameters:
18
The user can plot histograms of these distributions and derive statistical properties for the comparison of different experiments. Following is a table with the contents of the individual fields. growth_speeds_tracks
growth_speeds_gaps
growth_speeds_groups
growth_speeds_gaps_minLT4 growth_speeds_gaps_maxLT3 growth_times_tracks growth_times_groups growth_times_gaps shrink_speeds_gaps
shrink_times_gaps shrink_speeds_gaps_minLT4 shrink_speeds_gaps_maxLT3 growth_percentGap
Speed of all measured comet growth tracks, calculated as the distance between track start and track end divided by the track lifetime. Speeds of all forward gaps found between growth tracks, calculated as the distance between gap start and gap end divided by the gap lifetime (see field ‘growth_times_gaps’ below). Speeds of groups of consecutive growth tracks and forward gaps, calculated as head-to-tail distance of the track divided by the lifetime of the growth group (see field ‘growth_times_groups’ below). These groups indicate the apparent speed of microtubule growth ignoring the possibility of forward gaps being associated with pause events. Speeds of the subpopulation forward gaps with a lifetime equal or greater than four frames. Speeds of the subpopulation forward gaps with a lifetime less than four frames. Lifetimes of all growth tracks participating in a group. Lifetimes of groups of consecutive growth tracks and forward gaps. Lifetimes of forward gaps. Speeds of all backward gaps found between growth tracks, calculated as the distance between gap start and gap end divided by the gap lifetime (see field ‘shrink_times_gaps’ below). Lifetimes of backward gaps. Speeds of the subpopulation backward gaps with a lifetime equal or greater than four frames. Speeds of the subpopulation backward gaps with a lifetime less than four frames. Fraction of time spent in growth within groups of consecutive growth tracks and forward gaps.
In addition to the parser structure, the function writes a file parameters.mat to the project directory including the following parameters: - number of track clusters; - percentage of tracks participating in a cluster; - number of tracks with lifetime less than four frames; - number of features belonging to tracks with lifetime four frames or more; - number of forward gaps in groups of consecutive growth tracks and forward gaps; - probability of switch to a backward gap at the end of growth tracks participating in a group; - fraction of time spent in a backward gap within a cluster of growth tracks.
19
