TrackMateR is an R package to analyse TrackMate XML outputs.

TrackMate is a single-particle tracking plugin for ImageJ/Fiji. The standard output from a tracking session is in TrackMate XML format.

The goal of this R package is to import all of the data associated with the final filtered tracks in TrackMate for further analysis and visualization in R.

Installation

Once you have installed R and RStudio Desktop, you can install TrackMateR using devtools

# install.packages("devtools")
devtools::install_github("quantixed/TrackMateR")

An Example

A basic example is to load one TrackMate XML file and analyse it. This would typically be a tracking session associated with a single movie (referred to here as a single dataset).

library(ggplot2)
library(TrackMateR)
# an example file is provided, otherwise use file.choose()
xmlPath <- system.file("extdata", "ExampleTrackMateData.xml", package="TrackMateR")
# read the TrackMate XML file into R using
tmObj <- readTrackMateXML(XMLpath = xmlPath)
#> Units are:  1 pixel and 0.07002736 s 
#> Spatial units are in pixels - consider transforming to real units
#> Collecting spot data. Using 4 cores
#> Matching track data...
#> Calculating distances...

With the example data, we got a warning telling us that the data is scaled as pixels. If your TrackMate data is correctly calibrated you can skip this step but if you need to recalibrate it:

# Pixel size is 0.04 um and original data was 1 pixel, xyscalar = 0.04
tmObj <- correctTrackMateData(dataList = tmObj, xyscalar = 0.04, xyunit = "um")
#> Correcting XY scale.

With this done, we can have a look at the data.

So, after reading in the TrackMate file with readTrackMateXML() we have an object which we can visualise using plot_tm_allTracks().

TrackMateR can generate several different types of plot individually using commands like plot_tm_allTracks() or it can make them all automatically and create a report for you.

In the next section you will see how to do more advanced analysis, and pick and choose what outputs you will make. However, it is possible to change the defaults of reportDatasets() to tune things a bit more while still making a nice report. For example, reportDatasets(tmObj, radius = 100) will use the defaults for everything except the radius for searching for neighbours in the track density analysis. Parameters that can be changed are:

  • N, short - from MSD analysis
  • deltaT, mode, nPop, init, timeRes, breaks - from jump distance calculation and fitting
  • radius - from track density analysis

A more advanced example

Perhaps the default options do not suit your needs. With just a few more lines of code, you can tweak the report to do the analysis you want.

Below you will see that the dataset we read in was not scaled correctly. After reading in, we rescale it and then we start to generate the report.

The report shows analysis of mean squared displacement, jump distance and track density, among other plots. These three things must be calculated first using calculateMSD(), calculateJD() and calculateTrackDensity. This allows you to have some control over the analysis, for example setting the search radius for Track Density. Finally, these items can be fed into makeSummaryReport() as shown below, and the report is created.

# we can get a data frame of the correct TrackMate data 
tmDF <- tmObj[[1]]
# and a data frame of calibration information
calibrationDF <- tmObj[[2]]
# we can calculate mean squared displacement
msdObj <- calculateMSD(df = tmDF, method = "ensemble", N = 3, short = 8)
# and jump distance
jdObj <- calculateJD(dataList = tmObj, deltaT = 1)
# and look at the density of tracks
tdDF <- calculateTrackDensity(dataList = tmObj, radius = 1.5)
# and calculate fractal dimension
fdDF <- calculateFD(dataList = tmObj)
# if we extract the name of the file
fileName <- tools::file_path_sans_ext(basename(xmlPath))
# we can send all these things to makeSummaryReport() to get a nice report of our dataset
makeSummaryReport(tmList = tmObj, msdList = msdObj, jumpList = jdObj, tddf = tdDF, fddf = fdDF,
titleStr = "Report", subStr = fileName, auto = FALSE)

Note that makeSummaryReport can take additional arguments to give the user some control over fitting to jump distance. For example, nPop = 1 will fit one population instead of two (the dafault), and init = list() can be a list of guesses for the initial fit.

This vignette described the analysis of a single dataset. For analysis of more than one dataset, see vignette("comparison")