Particle Tracking Analysis Craig Szymanski, March 28, 2011 Modified by CKP, April 8, 2011 Modified by CJS, April

8, 2011

I. Obtaining a trajectory From ImageJ analysis to Excel file 1. Import an image sequence into ImageJ and do clean up - Do any desired background subtraction, de-speckle, contrast and brightness etc. a. Loading the entire data set can be taxing on the computer. If you are looking at only 2 channels, you can load up a lot more frames if they are joined as a composite movie instead of an RGB stack.1 You can still set the contrast of each channel independently, etc. The only relevant functional difference is that you must do Alt + , and Alt + . for frame forward and back instead of just , and . . 2. Acquire X, Y, Z coordinates - X and Y are position, Z is the time frame number. There are several ways to do this: a. Use the Point Selection Tool and the Measurements tool. If you do this, make sure you have the Stack Position box checked in the Set Measurements dialog. i. You can streamline this by using a custom script2 to use the number pad 4 to measure and move back one frame, and number pad 6 to measure and move forward one frame (remove the setKeyDown lines if using with an RGB stack instead of a composite) b. Use the manual tracking plugin available for download. See plugin instructions for use. Note that the frame movement will not work with a composite movie, only with an RGB stack. c. Any other particle tracking technique can work as long as it produces the X, Y, and Z coordinates of particle trajectories 3. Copy values into Excel - These coordinates should then be copied 1.3333 1.6666 1 3 7 into Excel using a specific format, with an example shown on the 31510 right. Unnecessary, but suggested. c a. The top 4 rows are almost completely up to you as long as lamp from hyb to you do NOT use commas, but I suggest: same hyb Y Z Row 1: 1 for the first one and =A1+(1/3) and fill right. This X 443 102 550 will provide an at-a-glance view of which particles are in 449 101 551 which columns. 451 96 552 Row 2: the image set (movie) that the data came from 452 93 553 Row 3: a physical description of the trajectory 452 95 554 Row 4: x, y, and z. 446 102 555 i. Merging cells might break things so avoid it b. Data starts on the 4th row with the coordinate set for the -1 -1 -1 vesicle. Leave the units in pixels in the worksheet, they 443 102 550 will be converted to microns later. 446 102 551 c. The shaded portion of the example to the right is optional. 445 102 552 If there is also data for another particle associated with 446 102 553 445 103 554 445 red and 2GB of green data 102 555 An RGB stack allocates memory for all three color channels, regardless of any actual data in those channels. If an RGB stack is made with just 2GB of
ImageJ Macro is shown at the end of this document.

with no blue data, it will still require 6GB of memory for an RGB stack. A composite image on the other hand will only require as 4GB for the two channels mentioned earlier, which may make allow loading of all of the frames at once instead of 2/3 or 1/2 of the frames which can make tracking significantly easier.

the first particle, such as a particle that binds with the first one, add one empty row and one row of -1, -1, -1. This is immediately followed by the trajectory of the other vesicle that is for the same frame numbers (and total number of frames) as the vesicle trajectory. d. Each trajectory will be 3 columns across; A, B, C will be the first one, D, E, F will be the second one etc. Trajectories lengths do not need to be equal. e. Save the file as a .csv file, and ignore Excel warnings about lost features or other worksheets when saving in the .csv format. Note: This is not the same as saving a .xls or .xlsx and renaming it to a .csv. You must go up to the Save as and under Save as type: select .csv. II. Matlab Analysis From x,y,z coordinates to histograms and exponential fits Importing the .csv file into MATLAB 1. Things to do once - To start with, copy all of the contents of the folder this was in into your MATLAB path. Usually, this is something like c:\Users\<UserName>\Documents\MATLAB\matlab\ and is shown at the top center of the MATLAB default window as Current Folder when MATLAB starts up. Start MATLAB as an administrator by right clicking on its desktop icon and selecting that option. After it has loaded, click on File -> Set Path. Click Add with Subfolders and find the previously mentioned MATLAB folder. Click Save, then Close. After this you do not need to start as an administrator unless you need to add or remove folders with MATLAB scripts or functions in them. 2. Start the data loading function At the command prompt type: [data]=loadtrackwithtarget('path'); where path is the complete path to the .csv file, with filename, extension, and single quotes e.g. c:\documents\craig analysis rab.csv . a. Important: Make sure that the size scaling factor and time step are correct. These are displayed when the script runs in the first two lines so make sure they are correct. If they are NOT right, open the loadtrackwithtarget.m file in a text editor (MATLABs or notepad are fine), and change the lines starting with conv= and/or timescale= in the units specified on those lines. b. Warnings indicate problems with the data set in the .csv and tell you how to fix them. Sometimes they can be fixed by deleting a repeat data point in Excel, but you may need to return to the original movie to fill in a data point. The importing function should still finish even if there is an error, just be aware that you might have data that is difficult or impossible to analyze. i. Warning: Vesicle trajectory for vesicle #n is not incremental. There are at least two frames that dont increase by exactly one in this vesicle trajectory. Either one was missed in recording, or was recorded twice. ii. Warning: Target trajectory for vesicle #n is not incremental. There are at least two frames that dont increase by exactly on in this target trajectory. Either one was missed in recording, or was recorded twice. iii. Warning: Vesicle and target trajectories for vesicle #n are not the same length. The length of the vesicle and target trajectories are not equal, probably because of errors i. and/or ii. It will also indicate which one of the trajectories is longer to help in correcting the problem. iv. Warning: Vesicle and target trajectories for vesicle #n are not for the same frames. The frame numbers are okay in all other respects, but cover a different set of frames such as 20:50 for the vesicle and 25:55 for the target. 2

3. Explaining the structure of the resulting data variable - The imported data is all in one variable that Ill call data. data is a cell array of N elements, where each cell array element is a structure. What this means is that to access the data for trajectory #4, you would type: data{4}. You would then see that there are three objects under it called v, t, and validtarget. v is the vesicle trajectory, t is the target trajectory, and validtarget is used to make other scripting easier and is explained below. So to obtain an array of the x data for the vesicle in trajectory #4, you would type data{4}.v(:,1) while the coordinates of the last location in target #17 would be data{17},t(end,:). a. validtarget is 1 if a real target trajectory was provided in the data file and no warnings occurred. validtarget is 0 if no trajectory was provided or if any warnings occurred. It can be seen for vesicle n by typing data{n}.validtarget. This could be useful for scripting one thing to happen if valid and another thing if not valid. b. The units for the x and y data is in m, while the z data is in seconds. These parameters are defined at the beginning of loadtrackwithtarget.m and will need to be changed if different experimental settings are used. Automated trajectory analysis 1. Type [dataout]=vesicleanalysisscript(data). This will produce a complex new variable with all of the processed data and the original data. The structure of this variable is several levels deep and is described below. In {n}, substitute the number of the individual vesicle you are interested in for n (but leave the braces in there).

dataout .count .time .seplist .ilist .v .t .v .t .v .t .v

.alldist .allsteps .th_rel

.centroid

.t .v

.radius

.x .y .t .singles{n} .v .traj

.i

.j

.pol

(:,1) (:,2) .th_rel .msd .t

3

.x .y

Number of trajectories in this data set The amount of time that each trajectory lasted in seconds Initial separation distances for the vesicle and target. If no target, is the distance from the particle start point to the particle end point. The list of all of the i component movements for the vesicle. See the later entry on i for a full explanation. The i list for the target. The total distance traveled along each of the vesicle trajectories. Same as above, but for all of the targets. All of the step sizes for all of the vesicles. Same as above for all of the targets. The angle of vesicle movement relative to the direction to the target. This value ranges from 0 radians, for a vesicle traveling directly at the target, increasing clockwise to /2 for traveling right, relative to the target, to , for traveling directly away from the target, through 3/2 for left, back to 2 (equal to 0) again for traveling directly towards the target. This array only includes values for which the particle actually moved. Same as above for all of the targets, relative to the vesicle. Average distance from the trajectory centroid. For this, the centroid x location was taken as the average of all of the individual x locations for a particular trajectory, with the y centroid location determined the same way. The average radial distance from this centroid coordinate was then calculated to determine this radius number. See above. See above. The centroid radius, x, and y for the target calculated in the same way as the vesicle. The set of x, y, and z coordinates for vesicle #n. Units are in m and seconds. This is copied from the original imported data set for convenience. The component of each movement that is directly towards the target. This is positive when the vesicle moves closer to the target, negative when the vesicle move farther away, and zero if the movement is either sideways or if the particle doesnt move at all.3 Distance is in m. The component of each movement that is right or left, with respect to the target. It is positive for movements that are right and negative for movements that are left. Distance is in m. The angle of movement from 0 to 2 increasing clockwise. Distance traveled between frames in m. The angle traveled relative to the target for each step in this trajectory, as describe in the other .th_rel entry above. The x axis of the mean squared deviation in seconds. The y axis of the mean squared deviation in m2 This is that same as each entry in the .v entry above, except that this is for the target and, where applicable, is relative to the vesicle.

For i and j, it might be helpful to think of it this way. For any particle movement in a frame, it will move some amount in the x direction and some amount in the y direction. The y part is positive for movements that take it closer to the top of the frame and negative for those that move it away from the top of the frame. For x movements, positive movements are to the right and negative movements are to the left. The i and j work exactly the same way, only for movement with respect to the target destination (where ever it happens to be at that moment), instead of the top of the frame.

To obtain data from the structure, follow the hierarchy to the variable you want. Some examples: To show all of the trajectory times, just type dataout.time. To see the list of relative angles of the vesicles, type dataout.th_rel.v. To see the relative angles for trajectory #12, type dataout.singles{12}.v.th_rel. To see a subset, such as just the 3rd through 5th y coordinates of target #17, you would type dataout.singles{17}.t.traj(3:5,2).

Plotting and fitting Plotting and fitting is done with an automated script called plot_fit_hist.m. It will carry out histogramming, fitting, and plotting on the above structure. Changes to settings are done by editing the script itself. Once a good set of setting for a particular data set is found, you can save the script as something else, such as plot_lamp1_data.m which would complement plot_rab7_data.m. Sample plots with graphically relevant settings are shown below. Settings for all plots:
dataout=dataout;

AxisLabelFontSize=26; AxisNumFontSize=20; AxisFonts='Arial'; AddGreaterThanSign=1; BoxBorderWidth=2; FitLineWidth=2; FitLineColor=[.6 .6 .6]; BarLineWidth=2; BarColor=[0 0 0];

BarEdgeColor=[0 0 0]; MCFits=100;

An alias that lets the user plot any data they like, without needing to rename all of the following instances of dataout that occur later. For instance, you might have the LAMP1 data in dataoutLAMP and the Rab7 data in dataoutRab. One version of this script could begin with dataout=dataoutLAMP; while the other could begin with dataout=dataoutRab; and have all of the same later steps applied to each. The font size to use for the axis labels. The font size to use for the axis numbers. The font to use for all of the labels. Whether the user would like to have a > sign added automatically when data is piled up at the end of the histogram. The thickness of the border to use around the plot. The thickness of fit lines. The color of fit lines to use. [.6 .6 .6] is the gray seen in the top plot fit below. Thickness of the lines at the edge of each bar in the histogram. If this is greater than BoxBorderWidth it will look funny. Color of the inside of each bar. Overridden with none (transparent) when a fit is done. Override this none behavior by commenting the line: set(get(gca,'Children'),'FaceColor','none'). Color of the edge of each bar. Number of Monte-Carlo fits to do. See below for more information

All sizes are in points (72 pts. to an inch), and colors are fractional RGB values. White is [1 1 1] (100% for red, green, and blue), black is [0 0 0], 50% red is [0.5 0 0] etc. See note above in the BarColor explanation about how it is changed when fitting. As far as calculations are concerned, the first step is the binning of data. This is done with bin centers at the locations laid out by the user in HistBins. Bin edges are half-way between centers. The left edge of the lowest bin is at infinity, while the right edge of the highest bin is +infinity. The results of this binning may be normalized by division by the highest value in the binned data. The resulting data is then displayed as a bar graph. Before fitting is done, the raw data is re-binned with centers the same distance apart, but a range that goes up to the highest value, to prevent piling up on the high side. Fitting is then done with a single exponential function with no offset in X or Y allowed, to generate the decay constant. Error values are estimated using the Monte-Carlo synthesis of synthetic data sets technique (see Numerical Recipes for details) and the number of synthesized fits can be changed in the setup section. When the actual fitting is done, new bins are done that automatically prevent such piling up. The equation of an exponential decay is Y = A*exp(-X / ), where Y is the histogram height at X, A is the amplitude a X = 0, X is a bin center, and is the decay constant. The decay constant is the time in units of the X axis that it takes the distribution to drop to A / e intensity. The script, as of the time of this writing, will produce 4 histograms: separation distance, instantaneous velocity, efficiency, and radius (mobility), all binned according to their respective HistBins. 6

More plots can be added easily. Each plot is defined completely within a block of text at the beginning of the script. The velocity plot is set up with:
%------------------ Velocity Setup -----------------DataSetNumber=2; YDataSets{DataSetNumber}=0.5*dataout.allsteps.v; %Divide between frames DoFit(DataSetNumber)=1; HistBins{DataSetNumber}=0.05:0.1:2; ViewAreas{DataSetNumber}=[0 2 0 1]; DoNorm(DataSetNumber)=1; FitSteps{DataSetNumber}=0:0.05:2; XAxisLabels{DataSetNumber}='Velocity (\mum/s)'; YAxisLabels{DataSetNumber}='Frequency';

the

step

sizes

by

the

time

If the user were interested in the distance traveled by each of the particles and wanted to see a plot and fit for this data, they could create a plot #5 by adding this block of text:
%------------------ Alldist Setup -----------------DataSetNumber=5; YDataSets{DataSetNumber}=dataout.alldist.v; %Divide the step sizes by the time between frames DoFit(DataSetNumber)=1; HistBins{DataSetNumber}=2.5:5:60; ViewAreas{DataSetNumber}=[0 60 0 1]; DoNorm(DataSetNumber)=1; FitSteps{DataSetNumber}=0:2.5:60; XAxisLabels{DataSetNumber}='Distance Traveled (\mum)'; YAxisLabels{DataSetNumber}='Frequency';

Notice the changes from the velocity block of text above, most importantly, the DataSetNumber. When plotting the data, you might not be sure what range the values cover. Are all of them below 2? Are most of them higher than 100? This makes it difficult to guess appropriate bin centers to put into HistBins. The easiest way to get this is to choose the variable you want to see the distribution of, and use the MATLAB hist command. For the alldist example above, you would type hist(dataout.alldist.v). This shows all of the data in dataout.alldist.v in a histogram with ten evenly divided bins covering the entire range of values. This makes it significantly easier to choose reasonable bins. Particle tracking IJ macro mentioned in footnote 2:
macro "Macro1[n4]" { run("Measure"); setKeyDown("alt"); run("Previous Slice [<]"); setKeyDown("none"); } macro "Macro2[n6]" { run("Measure"); setKeyDown("alt"); run("Next Slice [>]"); setKeyDown("none"); }