Skip to content
PhagoSight edited this page Apr 19, 2018 · 2 revisions

Visualisation Tools

The tracks that have been generated contain a large amount of information: velocity, angles, meandering indices (ratios), etc. which in some cases can be very important for a thorough analysis but it may not always be easy to observe.


We have developed a large collection of visualisation tools to plot the tracks and some statistical measurements derived from the tracks in several useful ways. These tools are divided in 2 commands: plotTracks and plotTrackStats.


The command plotTracks was briefly introduced in one of the previous chapters, it will be used to display the tracks as a three-dimensional plot of lines, using either the X,Y,Z coordinates or the X,Y,T coordinates. The parameters that can be used as input for the function follow this structure:


handles is the output of NeutrophilAnalysis.

typeOfPlot for plotTracks

typeOfPlot is a single number that will define the way the data is displayed. The number can be between 1 and 14 and can be negative or positive. The following list explains the type of plots:

   1  = highlights longer (in distance) branches
   2  = highlights faster branches
   3  = highlights longer (in number of frames) branches
   4  = highlights shorter branches
   5  = highlights slower branches
   6  = highlights smaller branches
   7  = discard branches with small total distance, i.e. 10% of upper half average distance
   8  = discard branches with less than 3 nodes
   9  = plot ONLY those branches crossing the present Frame
   10 = with labels (numbers) for the tracks
   11 = all tracks in green
   12 = all tracks in red
   13 = top in red, bottom in green
   14 = top in green, bottom in red

When positive values are used for typeOfPlot, the tracks are displayed in X,Y,T coordinates. When negative values are used for typeOfPlot, the tracks are displayed in X,Y,Z coordinates.


For some plotting option number 9, a specific frame can be selected, only the tracks that are present in that frame are highlighted.

micronsPerPixel and framesPerSec

These two parameters are used to callibrate the plots, from [pixels] to [um] and from [frames/s] to [um/s]


Selected examples of plotTracks in X,Y,T

The first and most simple case, is plotting all the tracks in X,Y,T


This view will highlight (brown-red colours) the longest tracks against the smaller tracks (blue-cyan) and medium ones will be green-yellow. When there is a large number of tracks, it can become rather complicated to understand the plot. You can rotate the plot to find the best view, either with the mouse on the plot, or through the command view:


Options 1-6 will highlight the branches in different ways, that is, the colours assigned to them will depend on the parameter you select. In the case of option 2, a colour bar is automatically added on the right hand side. FOR ADVANCED USERS: It is possible to add a colour bar automatically for all options by uncommenting a few of the last lines on the code of plotTracks.



Adding labels to the tracks

Sometimes, you may be interested in knowing which track is which. Option 10 adds a text label to each track:


Large number of tracks

Some datasets may contain a large number of tracks and then the plots with all the tracks may results a bit confusing:

figure plotTracks(handles,10); view(-41,50)

In those cases, there are several visualisation options that may be useful. First, it may be interesting to show all the tracks of the set, but highlight a few of them at a certain moment in time, so you know what is happening at a certain moment. For example compare the following plots with the time frames 20 and 80 selected:


figure plotTracks(handles,9,80); view(20,14)

The second option, is to select a subset of tracks to plot just this subset (and not plot all the other ones) by passing a matrix with the tracks to plot, for instance:



If you do not know the number of the tracks you want to plot, but instead you know some characteristics, such as the length, for instance, you can pass that parameter to the function. For example, if you want to plot only the tracks that exceed, say 50 hops, you can use the handles.distanceNetwork.numHops field in the following way:


Notice that you need to use find to properly address the matrix, if you do (handles.distanceNetwork.numHops>50) it is a logical operation where you ask what elements of that vector are bigger than 50, so the answer is only a yes or no, 1-0. When you use find you then get which of those elements are the ones you want.

plotting in X,Y,Z

To display tracks in X,Y,Z you can use the same options as before, but with a negative value, that is, typeOfPlot -1 is the same as typeOfPlot 1 but in X,Y,Z, instead of X,Y,T. For example:



plotTrackStats introduces several visualisation tools that may be useful while analysing datasets. Unlike plotTracks, which plots the tracks in a three-dimensional way, either in the X,Y,Z coordinate system, or the X,Y,T coordinate system, plotTrackStats displays derived measurement or statistics from the tracks and not the tracks themselves. Like plotTracks, the first input parameter to the function is the handles and the second parameter is typeOfPlot:


typeOfPlot for plotTrackStats

typeOfPlot is a single number that will define the way the data is displayed. The number can be between 1 and 14 and can be negative or positive. The following list explains the type of plots:

     0  = distance per frame      single track
     1  = angle per frame         single track
     2  = distance from start     single track
     3  = angle from start        single track
     4  = cumulative distance     single track
     5  = distance per frame      all tracks
     6  = angle per frame         all tracks
     7  = distance from start     all tracks
     8  = angle from start        all tracks
     9  = cumulative distance     all tracks
     10 = av distance vs angle polar plot
     11 = Average track velocity as a angle polar plot
     11 = Total track distance as a polar plot
     12 = Maximum track velocity as a polar plot
     13 = meandering index (ratio) as a polar plot
     14 = the tracks in velocity and time as "events"

Single track plots

Options 0-4 will display the characterstics of a single track in terms of the distance or angle in different ways, for example:


Multiple track plots

options 5-9 will display the same measurements as in 0-4 but for all the tracks of the dataset. These plots are good to analyse all the tracks at once and discover which track is the longest, or windiest, etc.


Number of Turns

You might have noticed that when the angles are plotted with options 1 and 6, the turns of the object are calculated as the number of complete 360 degree rotations that appear.

For the plots of the individual tracks these are displayed as the number of turns in the title, and a marker is placed at the moment in time in which each turn appears. The markers are alternated in position to indicate if they turn clockwise or counter clockwise.

In the multiple track plot, the number of turns are placed next to the number of the track and there is no differentiation between clockwise or counter clockwise. Look at these two examples:


Polar plots

Polar plots are good to analyse the behaviour of tracks according to the orientation of the track. Since all tracks can be seen at once, detection of outliers is extremely simple.


Tracks as events

A final visualisation tool will display tracks as lines with time on the x-axis and velocity on the y-axis. Each track will be displayed as a line bounded by square markers when the track begins and ends, and the position in the y-axis is given by how fast or slow the neutrophil that formed that track was. A red line shows the average velocity of the whole set for each moment in time. This plot is extremely useful to observe longitudinal changes of behaviour of the neutrophils.