TrakBox Viewer User Manual


The TrakBox Viewer program is a freely distributable program that allows the user to view pre-recorded TrakBox Worm Tracks. The program not only displays the recorded data but also calculates a raft of behaviour measures and allows the user to recalculate some of these measures on the fly through adjusting a set of parameters. What is more, the user can save ALL the raw data and the processed data in two spreadsheets in the commonly readable .CSV format.

The user can run multiple instances of the Viewer program to analyse multiple tracks at the same time allowing the user to compare and contrast behaviour measures across worms.


2.Installing TrakBox Viewer

2.1.For Mac OS

Not yet complete - to be updated shortly.


2.2.For MS Windows


Make sure you have administrator permissions to allow you to install programs

  1. Reboot your system
  2. In the files you have been given locate and run:
  3. Follow all instructions given during the install – make sure you tick the box “Add a shortcut to the desktop”. Upon completion, there will be a shortcut on the Desktop called “TrakBox_Viewer”.
  4. Locate the directory where-ever data generated by TrakBox is located (note that if you do not do this step the software will still work).
  5. Right-click on the TrakBox_Viewer Desktop shortcut and select “Properties”. In the space titled “Start in:” type (or paste) the full directory path to your working directory.
  6. Click on “Apply” and then “OK” to exit.


Note that for TrakBox Viewer you do NOT need a software license – the viewer will allow you to open and view pre-recorded tracks created by TrakBox.

3.Using TrakBox Viewer

TrakBox Viewer can be launched by double clicking the Viewer Icon – once launched, multiple tracks can be viewed and analysed.

3.1.Browse tracks

When you first launch TrakBox Viewer you will see a dialog box asking you to select a Worm Track directory. This must be a directory containing a valid set of TrakBox generated data. Once you navigate to the directory of your choice you will be faced with the window in Figure 1. This window shows a summary of some of the data contained within the TrakBox data directory.

Figure 1
Figure 1: The Browse Tracks window which is part of TrakBox Viewer
  1. Indicates the filename that was used for the current Worm Track.
  2. This shows the worm type the user specified when the Worm Track was first created (if none were specified then this field will be empty).
  3. If the user entered any notes before the Worm Track was recorded then they will be displayed here (if none were specified then this field will be empty).
  4. This indicates the total duration of the recording in hours, minutes and seconds (h:m:s). The value in brackets represent the total number of frames in the recording – each frame is a snapshot taken from the USB Microscope. TrakBox analyses data and records frames in the order of 2-4 Frames per second (depending on computer speed).
  5. This shows the total distance travelled by the worm in mm’s over the duration of the whole recording.
  6. This button allows the user to browse the computer’s directory structure to look for a fresh Worm Track data directory to analyse – pressing this button brings up the dialog box asking to select a worm track – as before.
  7. This button launches the Worm Track analysis software on the data currently summarized in the TrakBox Browse Tracks screen.
  8. Pushing this button closes all open windows and quits TrakBox viewer.
  9. This plot shows an overview of the Worm Track in x-y coordinates of the recorded data. The green dot indicates the start position and the red dot the finish position.

3.2.View Trajectory

When the user clicks on Analyse, after browsing to a specific Worm Track directory, the TrakBox software launches the View Trajectory window – this displays all the tracking parameters recorded and calculated when tracking a worm. In Figure 2 it can be seen that the View Trajectory screen consists of 4 main panel of information – each panel is described below. The menu buttons shown in (1) allow the user to Print a copy of the Window, Zoom in, Zoom out, move the view, enquire about values of a specific data point, and a shortcut to the online help manual.

Figure 2: The View Trajectory window showing the worm behaviour.
    1. User menu items (described above).
    2. This shows a representation of the (circular) plate onto which the x & y coordinates of the worm over time (in cms) are plotted. The black dotted line shows the actual trajectory, whereas the blue line shows the (low-pass) filtered trajectory. Individual worm locations per frame are shown via magenta dots. Pink circles with green lines are used to indicate reversals.
    3. In this panel the blue line indicates instantaneous velocity of the worm (in mm/s) calculated on each frame. The black vertical dotted line indicates the ‘current frame’ cursor used in frame (4). The horizontal blue/red line depicts the roaming (blue) versus dwelling (red) behaviour of the worm over each time frame. Clicking anywhere in this graph will move the cursor to that time position and the current view information will change.
    4. This panel shows a multitude of information about the worm’s overall behaviour extracted from the recordings as well as some instantaneous values on a per-frame basis. Information on number of reversals and roaming versus dwelling times is variable as this panel includes some controls to vary parameters that affect these calculations. (More detailed information in 8, 9, 10, 11, 12 & 13 below).
    5. This shows the x and y coordinates of the worm over time (in cms). As before, the vertical black dotted line depicts the ‘current frame’ cursor used in panel (4). Clicking anywhere in this graph will move the cursor to that time position and the current view information will change.
Figure 3: View trajectory window
    1. This text displays two pieces of information – the time spent in the current zone, and when the user moves the mouse over the graph, it indicates the x & y coordinates of the cursor position. The ‘current zone’ defined as the data currently in view in panel (2) – if the user zooms in to a portion of the graph, the calculations will change to reflect the time the worm spent in that particular zone of the plate.
    2. The information in this horizontal line show roaming (blue) versus dwelling time. As the parameters used to calculate roaming versus dwelling are changed this representation will change too.
    3. If the user clicks on the ‘View Frame’ button in panel (4) then the snapshot taken for this frame is displayed, the snapshot is of the ‘current frame’ and will change as the user selects different frames to view. In this view the worm centre of mass is indicated by a red dot, if the frame happens to show a reversal the red dot will be replaced by a pink circle. If the user clicks the button again (now labelled ‘Summary’) the instantaneous values view is returned – the user can toggle between both views using this button.
    4. This panel shows some instantaneous information related to the ‘current frame’ in the trajectory. This includes current x & y coordinate, instantaneous velocity, frame as well as elapsed time – this will change of the user changes the ‘current frame’.
Figure 4: The view trajectory window
    1. This panel depicts a group of 5 buttons. The first will allow the user to export all RAW and CALCULATED data of the worm trajectory to a spreadsheet using the common CSV format. The next button toggles between View Frame and Summary and is explained in (8) above. The next button depicts a feather-plot in the plate overview frame. This is another way of depicting instantaneous velocity with direction in this view. More information is given in Figure 6 and (13) below. The next button generates a Dwell Chart – this is a separate window that depicts detailed information of roaming versus dwelling of the worm over time. More information is given in Figure 7. The final button is the Create Movie button and when that is pressed an .AVI movie is generated by stitching together all the frame snapshots as well as including an overview of worm position through an inset. More information on the worm movie can be found in Figure 9.
    2. When the Save plot button is pressed the window of Figure 5 appears, this figure allows the user to select any of the 4 plots in the main window and save them to a .PNG graphics file.
    3. When the Quit button is pressed the Worm Trajectory window is removed and the user is returned to the overview window shown in Figure 1. The user can open multiple trajectory view windows at any given time.
    4. This panel depicts a series of analysis parameters that allow the user to vary variables and the system will recalculate behaviour such as reversals and roaming vs dwelling ‘on the fly’. For reversals there are two parameters that can be varied: Minimum distance for reversals (in microns) and Reverse Angle (in degrees). By varying these two parameters the user can experiment with different worm behaviours based on worm type/size/etc. as these parameters are changed the values on screen are calculated and updated in real-time. The final control is a tick-box that shows where to show reversals (pink circles) in other panels – or not. For dwelling analysis the Minimum distance for dwelling can be varied in microns too (the equivalent minimum worm speed in mm/s is also calculated in real time and displayed the min distance for dwelling is varied). Finally the Step through frames allows the user to step through each frame in turn (remember that the user can go to a specific frame directly by clicking anywhere within the graphs of the Instantaneous velocity and x&y coordinates graphs too).
Figure 5: The Save plot window.
    1. This is the currently selected plot, as selected by the drop down menu of (15) below. 4 different plots are available to the user.
    2. This drop-down menu allows the user to select one of the four plots to be displayed then saved.
    3. When this tick box is selected, some information that can be considered as ‘clutter’ is removed from the plot so that the plot can be saved with minimal confounding information. (What is actually removed from each plot is given by the note after the *).
    4. When Save plot is clicked a dialog box appears promoting the user to select a directory location as well as a filename for the *.PNG graphics file that will be saved.
    5. This button closes the Save plot window.
Figure 6: The View trajectory window
    1. Figure 6 shows how the overall worm trajectory view can be altered by a) zooming in onto a particular area and b) using Featherplot to indicate instantaneous velocity where by direction is given by the arrow orientation and magnitude is correlated with the size of the arrow.
Figure 6
Figure 7: Confirmation following saving data to .CSV file.
  1. Figure 7 shows the completion of the Export to excel operation whereby the worm trajectory data is saved to the TWO .CSV files indicated. One gives overview data of the entire track and the other gives frame by frame information for all parameters.

3.3.Dwelling Chart

Figure 7 shows the Dwelling Chart which shows a detailed analysis of roaming versus dwelling behaviour, spread over time, as well as indicating times the worm is quiescent (i.e. completely immobile).

Figure 7
Figure 7: Dwelling Chart showing worm roaming/dwelling behaviour over the recording.
  1. Dwelling times are shown in red, this depicts the overall dwelling time in h:m:s format as well as a percentage.
  2. Quiescent times are shown in green in h:m:s format as before. Quiescent time is reported along side of Dwelling time.
  3. This depicts the (user definable) minimum distance for dwelling parameter used to calculate this chart. If this changes the chart will change. It is possible to generate multiple charts for different minimum distance values.
  4. This Pie-chart shows the time (and percentages of time) spent Dwelling, Quiescent and Roaming (in Red, Green and Blue respectively). The format in each case, as before, is in h:m:s.
  5. Roaming times are shown in blue, this depicts the overall roaming time in h:m:s format as well as a percentage.
  6. Periods of roaming are indicated in blue, along with the time spent roaming.
  7. Periods of dwelling are indicated in red, along with the time spent dwelling (quiescent time is shown in green but in the first part of the movement window and NOT at the ACTUAL time the worm was quiescent.)
  8. Pressing the Close button will close the Dwelling Chart window and return to the View Trajectory window – although its possible to have multiple Dwelling Charts open and return to View Trajectory view leaving them open.

3.4.Make Movie

It is possible to create a movie of all the frame snapshots put together by pressing the Create Movie button in (10) of Figure 4. The View trajectory window will be suspended temporarily whilst the movie is being generated – once done the movie window (Figure 8 below) will be removed and the View Trajectory window returned.

Figure 8
Figure 8: The Make Movie button allows an .AVI movie to be generated of the whole work trajectory.
  1. Roaming versus dwelling is shown as a blue and red line respectively, reaching across the top part of the movie.
  2. The movie will depict the time of each frame versus overall time in the top left hand corner of the movie.
  3. The worm itself will appear, in a contrast enhanced image, such that it is always centered in the field of view of the movie.
  4. The inset depicts an overview of the worm location on the plate with a blue line depicting the position over time. A green dot represents the starting point and a red dot represents the current position over time.
  5. The name of the movie being generated is given here – the movie will appear in the root directory of the data folder the user is working with.


Do I need a license to run TrakBox Viewer?

No – TrakBox Viewer is freely distributable to anyone who wants to run this program on either an MS Windows or Mac OS platform. The user will need to install the Matlab Runtime Compiler for this program to work – it is install automatically as part of the install process if you do not already have it installed.

What is a Worm Track?

A Worm Track is a data-set generated by the TrakBox system which automatically detects the presence of a worm on a plate through its centre of mass and tracks it movement over time. The track is then used to calculate a raft of behavioural measures of the worm under analysis.

What is the worm’s centre of mass and why is it important?

As TrakBox tries to automatically detect the presence of the worm in REAL TIME, it needs to be quick in order to keep the frames-per-second to at least 2-3 frames per second, this means that the worm presence needs to be detected using “simple” (fast) methods. TrakBox does this by calculating the centre of mass of the worm based on contrast – essentially the darkest patches in the target area. At the same time, TrakBox removes dark patches related other non-worm images in the field of view. The centre of mass is a single point is space that best locates the worm in space, depending on the shape of the worm the centre of mass will be either on or outside the worm’s body – but will never be more than a 1/4 of the worm’s body length outside the worm body.

How is a worm reversal calculated?

A reversal in a worm is calculated based on two major parameters, the reversal angle and the minimum distance for reversal. A reversal is automatically detected if the worm moves a distance in the REVERSE direction GREATER THAN the minimum distance for reversal. The REVERSE direction is determined through the reversal angle – this can vary from 0 to 180 degrees, where 0 is “dead ahead” and 180 is a “straight reversal”. If the reversal angle is made larger the number of reversals detected will typically drop as the criteria for reversals is more strictly being defined. Similarly, as the minimum distance for reversal is made larger the number of reversals detected would typically drop as the worm will need to travel a greater distance for a reversal to be detected. Both these parameters are user adjustable in the TrakBox Viewer program and the user can see changes “on the fly”.

How is roaming versus dwelling calculated?

The worm is classed as dwelling if the worm’s centre of mass does not move beyond a certain radius (known as the minimum distance for dwelling) over set amount of time. The system low-pass filters the worm-track first before calculating this measure – this has the effect of removing high-frequency (fast moving) “jitter” in the worm’s centre of mass. If the worm exceeds the minimum then it is classed as roaming. A further measure called “quiescence” is calculated as the point where the centre of mass of the worm is completely immobile (in real terms the well dwells at a tenth or less of the minimum distance of dwelling).



If you have any issues with the TrakBox Viewer software please contact us using the form below, we do not guarantee 24/7 support however we will endeavour to respond with some help as soon as possible.

Suggest Edit