The active place avoidance (APA) task involves an arena that is rotating with respect to the visual cues in the room. A sector of the arena is punished, typically by a mild footshock, so that the animals are motivated to avoid this zone. This ‘avoidance zone’ is defined in the frame of reference of the surrounding room. That means that animals must build a spatial map of the room to successfully avoid the punished sector and cannot use olfactory or other local cues as these are constantly changing due to the rotation of the arena.
Outcome measures are typically the latency to enter the avoidance zone and the number of shocks received. A multivariable analysis of the path travelled during this task, such as provided by Rtrack, may yield insight into more subtle phenotypes—and this remains an area of active research.
The Rtrack package aims to be an easy-to-use interface for data management and analysis of spatial tracking data. This workflow describes analysis of data from the active place avoidance task. Although the APA is a very simple paradigm, experiments often accumulate many tracks each with associated metadata. Managing all these data can be overwhelming and lead to confusion and potential errors. Unfortunately, due to the potential complexity of the experiments and the range of computational abilities of the researchers (who are typically experimentalists with little background in programming or data analysis), many existing software solutions have not found their way into laboratory workflows. The Rtrack package is built on the popular and ubiquitous R platform which runs on all commonly-used operating systems, is free and open-source (so that the cost of licencing is not a limitation) and which integrates well into existing analysis environments. The data preparation involves exporting path data from the acquisition software used (outputs from a number of software platforms are supported and more are being added), defining the arenas in which the experiment was performed and creating a spreadsheet with information about each track. Once the data and information spreadsheet have been prepared, the actual analysis runs in very little time (processing for 1000 tracks takes under a minute on a typical modern computer) and the results are available in R for further analysis, or can be exported for analysis using other software if desired. Publication-quality graphs can be generated and exported directly from the functions in Rtrack. In addition, the raw path data can be saved to a standardised format to allow data sharing and to enhance reproducibility.
The small synthetic dataset provided together with this vignette has been generated purely for demonstration purposes. The simulated data consist of two groups of 15 animals in a circular arena with a 60°ree; footshock sector. The arena is rotating at the rate of 1 rpm counterclockwise with respect to the room.
In this example, an archived experiment (raw data that has been saved in the portable trackxf format) is read in directly from a URL. The experiment is reconstructed, strategies calculated and plotted for a visual overview. To explore the further functionality of the package, please work through the tutorial examples below.
experiment = Rtrack::read_experiment("https://rupertoverall.net/Rtrack/examples/APA_example.trackxf") #> Restoring archived experiment. #> Processing tracks. Rtrack::plot_variable("angle.from.aversive.zone", experiment = experiment, factor = "Group")
An ‘arena’ is a description of the experimental set-up, including the rate of rotation, the size/location of the aversive zone and the recording parameters for each session. This means that any change in set-up (for example, if the camera position is moved) will require a separate arena file. The description files are simple and consist of only a few lines:
The experiment type. For an APA experiment, this will always be apa.
The time units. The units in which the timestamps are measured. Each x,y coordinate pair in the path data is associated with a timestamp. The frequency of measurement may be in the range of milliseconds, seconds, hours or even days—depending on the type of experiment. This can either be a text code (‘s’ = seconds, ‘h’ = hours etc.)1 or a conversion factor to seconds (1 = seconds, 0.0002777778 = hours (a second is 1/3600 of an hour) etc.).
The bounds of the arena (i.e. the dimensions of the rotating arena). This line has 5 components, each is separated by a space.
The rotational speed of the arena. In the APA task, the platform is constantly rotating. The speed at which this occurs is measured in degrees per time unit (see point 2 above). A positive value means that the arena is rotating in a clockwise direction; negative values indicate a counter-clockwise rotation. As an example, the value \(-0.006\) is equivalent to 1 revolution per minute (rpm) counter-clockwise [\(-360 / (60 * 1000)\); 360 degrees in one revolution; \(60 * 1000\) milliseconds in one minute, where the time units are specified in milliseconds (ms) as in the example below].
The dimensions of the aversive zone. Shape, centre x, centre y, radius. is equivalent to 1 rpm counterclockwise
The units for the x and y coordinates do not need to be specified, but these must be the same units used in the raw track files.For example, the description for one of the arenas in the example file (‘Arena.txt’) is:
type = apa time.units = ms arena.bounds = circle 127.5 127.5 127.5 arena.rotation = -0.006 aversive.zone = sector 60 120
The key task before analysing an experiment is to gather together all the information you need for the analysis. This is always necessary for any analysis, and is always a nasty task. Nevertheless, Rtrack uses a straightforward spreadsheet format to make this task less tedious and less confusing.
Several columns are required, these all must begin with an underscore ’_’:
read_experimentfunction. See the note on relative paths below.
read_experimentfunction. See the note on relative paths below.
?Rtrack::identify_track_format) for a list of the supported file formats.
You can also add any other columns of factors. In the example, there is a factor ‘Group’, which records the tpe of housing the animals were in.
If your analysis will be done in the same directory as the raw
data files are in, then you can ignore this comment. If, however, your
raw data are large, you may have them stored on an external disc or
network volume. By specifying the
data.dir parameter, you
can keep these raw data anywhere you like and even move them without
having to update the experiment description spreadsheet. All file paths
in the experiment description are relative to the
Look at one track to get a feel for the workflow. Firstly an arena
definition must be read in. The resulting object has the class
arena = Rtrack::read_arena("APA_example/Arena.txt")
There are many different raw data formats. The format of the data
files depends on the software they were recorded with, the locale and
(sometimes) the computer system they were recorded with. Each format
supported by Rtrack has a code, which must be given to the
read_path function. Run the function
identify_track_format with one of the raw track files to
help you determine the appropriate format code for your data.
track.format = Rtrack::identify_track_format("APA_example/Data/Track_1.dat") #> ✔ This track seems to be in the format 'tracker.2.dat'.
The tracks for the example are in the format
ethovision.xt.csv2, we need to pass this information on to
the reader function. The arena is also required for reading in the path
(to provide calibration information).
path = Rtrack::read_path("APA_example/Data/Track_1.dat", arena, id = "test", track.format = "tracker.2.dat")
The path (of class
Rtrack_path) can now be used to
collect a range of metrics. This results in a list of various secondary
variables which can be used for plotting and analysis.
metrics = Rtrack::calculate_metrics(path, arena)
The path (the coordinates of the animal in the arena during the experiment) can be plotted. This representation shows the path as a black line and some informative areas of the field (called ‘zones’ by Rtrack; the zones in an open field experiment are the wall, the corners and the centre.) in shades of blue.
Rtrack::plot_path(metrics, lwd = 1)
Paths can also be plotted as a density heatmap.
Feel free to play with the colours (just please don’t use a garish ‘rainbow’ scheme). The colour scales are best defined using the ‘colorRampPalette’ function.
You can use any of the colour definitions provided in R, and reducing the number of colours in the palette gives a contour effect.
Usually, an experiment will consist of multiple subjects/animals and
possibly more than one trial per subject. Running each track separately
by hand as we have done above would be tedious and error-prone. Rtrack
allows you to set up a batch processing workflow to make this task
easier. A description of the experiment is filled out with all the
required data and passed to to the
to be processed automatically.
The experiment information is read in using metadata in a
spreadsheet. See ‘Preparing the input files’ above for details on how to
properly construct this file. The raw data are read in, metrics
calculated and returned in a list object of class
Rtrack_experiment. This is the most processor-intensive
part of the workflow and an experiment will typically consist of many
hundreds of tracks. Depending on the size of the experiment and the
speed of your computer, this step may take several minutes (a friendly
progress bar will let you know if there is time for a coffee at this
step—the software is fast though, so it may be an espresso!).
experiment = Rtrack::read_experiment("APA_example/Experiment.xlsx", data.dir = "APA_example/Data") #> Processing tracks.
By default, processing the experiment will run as one single
but is trivial to parallelise this potentially time-consuming step if
you have a large experiment to work through. Rtrack version 2 will take
care of parallelising the code and all you need to do is adjust the
threads parameter. The simple option is to specify
threads = 0, which tells Rtrack to use as much processing
power as it can. Now try running the
again and see if this makes a difference in processing time.
experiment = Rtrack::read_experiment("APA_example/Experiment.xlsx", data.dir = "APA_example/Data", threads = 0)
Once the experiment object has been constructed, you can use this to start analysing the results. Individual metrics might be of interest for separate analysis; for example, the median angle between the animal and the edge of the aversive zone is a measure of how well the animal is learning to keep its distance. The built-in plotting function allows you to quickly inspect your data and includes the ability to split the results by a grouping factor.
Rtrack::plot_variable("angle.from.aversive.zone", experiment = experiment, factor = "Group") title(main = "Median angle to the aversive zone")
The ‘summary.variables’ element shows all the metrics available
experiment$summary.variables #>  "path.length" "total.time" #>  "velocity" "immobility" #>  "angle.from.aversive.zone" "angle.from.old.aversive.zone" #>  "roaming.entropy" "latency.to.aversive.zone" #>  "latency.to.old.aversive.zone" "time.in.centre.zone" #>  "time.in.wall.zone" "time.in.aversive.zone" #>  "time.in.old.aversive.zone" "aversive.zone.crossings" #>  "old.aversive.zone.crossings"
It is also possible to create a density heatmap for many tracks together.
This will only work if all of the tracks in the experiment use the same arena (it does not make any sense otherwise). If you have multiple arenas (e.g. for different days or for training and reversal), you can subset those tracks and make a density plot for each subset. Have a look at the Morris water maze tutorial for details of how to subset a more complex experiment.
This next block of code produces a large PDF (one page for each track) including each of the paths titled with the track ID. This can be used to check everything is the way it should be and to detect any possible recording or processing problems.
To get a
data.frame containing all the experiment
metadata, metrics and strategies for each track, it is possible to
export the experiment results. The function
is really intended for saving to a file, but if no filename is given,
then you get the data as a
results = Rtrack::export_results(experiment)
The results can be written to file in any one of several formats. The format will be determined from the filename extension. The default, and most likely to be used in an experimental workflow, is the Excel ‘.xlsx’ format.
Rtrack::export_results(experiment, file = "Results/APA_results.xlsx")
Also supported are tab-delimited text (recommended for maximum portability; file extension can be any of ‘.tsv’, ‘txt’ or ‘.tab’) and comma-delimited values (‘.csv’, or ‘.csv2’ where decimal commas are needed). You can actually use any file extension, but it will be written in that case as tab-delimited text and you’ll get a warning.
It is also possible to only export some of the results. To do this, just specify the indices or names of the tracks you would like to export.
# Export just the data for Group_A. group_a = experiment$factors$Group == "Group_A" Rtrack::export_results(experiment, tracks = group_a, file = "Results/APA_results_Group_A.xlsx")
It is worthwhile noting that the order of the exported results is
also determined by the order of the values given to the
Rtrack_experiment object can easily be saved
and reloaded into a later R session. The
.RData format is a
compressed version of the
Rtrack_experiment object and
requires very little space.
save(experiment, file = "Results/APA_experiment.RData")
Load the file again (not necessary in this session, but the following
line demonstrates the command needed to read in the
file we just created).
We have also developed a format for saving the raw data in a way that
it can be accessed by other software. This allows sharing with other
people and archiving in a way that is more likely to be readable in the
future. The command below will create a file with the extension
.trackxf—you do not need to add the extension though (in
fact it is better not to) as Rtrack will take care of naming the file
Rtrack::export_data(experiment, file = "Results/APA_Experiment") #> Creating trackxf archive. #> Compressing trackxf archive.
Data saved in this way can be read back into Rtrack using the
read_experiment function (with the format
trackxf, although Rtrack will work this out for you).
Because only the raw data are saved in trackxf, recreating an
experiment in this way will re-calculate all of the Rtrack-specific
recreated.experiment = Rtrack::read_experiment("Results/APA_Experiment.trackxf") #> Restoring archived experiment. #> Processing tracks.
This experiment object recreated from the saved trackxf file is (almost) identical to the original object. Only the export information will obviously be different.
# If we set 'export.note' back to empty, then the objects are the same. recreated.experiment$info$export.note = experiment$info$export.note all.equal(recreated.experiment, experiment) #>  TRUE
The full range of supported codes is: ‘us’ or ‘micros’ for microseconds, ‘ms’ for milliseconds, ‘s’ for seconds, ‘min’ for minutes, ‘h’ for hours, ‘d’ for days and ‘y’ for years.↩︎
modern computers can multi-task and run several jobs side-by-side at the same time. These separate processes are called ‘threads’ in computer terminology. Running multiple parallel threads can make make optimal use of the multiple ‘cores’ of your CPU (the microchip at the heart of your computer) and allow programs to process data more quickly.↩︎