Information for users of version 1

If you have been using Rtrack version 1 (the version in CRAN before August 2023), then your analysis code will need to be altered slightly.

The Rtrack package has changed significantly in version 2. Some of the changes were unavoidable, as one of the other packages we relied on has been retired and the Rtrack code needed to be extensively rewritten. Some other changes are due to the fact that we now support not only Morris water maze, but also Barnes maze, open field, novel object recognition and active place avoidance analyses. This means that the structure of the package has changed internally to allow new analysis modules to be added. It also means that some commands needed to be generalised so they work for all experiment types. Mostly, this does not affect the use of Rtrack for Morris water maze, but there are some slight modifications required for your existing code.

  1. The arena file no longer requires a trial.length parameter. However, a new parameter, time.units, is required. This value can be provided as a text abbreviation of the timestamp units in which the raw data were recorded. Check your recording software for details, but this is likely to be “s” (for seconds) or maybe “min” (for minutes) or “ms” (for milliseconds).

  2. You do not need to create clusters any more for running code in parallel. Just provide a number with the threads parameter. So, instead of ths code:

     cluster = parallel::makeForkCluster(8)
     Rtrack::read_experiment("Experiment.xlsx", cluster = cluster)
     parallel::stopCluster(cluster)                         
    

    You can just use:

     Rtrack::read_experiment("Experiment.xlsx", threads = 8)
    
  3. When you export results, the strategies are no longer automatically calculated. You need to do this explicitly.
    To export only the results (with no strategies):

     Rtrack::export_results(experiment, file = "Results.xlsx")
    

    To include strategies, calculate them separately and add them to the export:

     strategies = Rtrack::call_strategy(experiment)
     Rtrack::export_results(experiment, strategies, file = "Results.xlsx")
    

    This extra step is because not all of the new experiment formats support strategy analysis, and we want to keep the interface compatible between all experiment types.

  4. When you export raw data, we now use the trackxf format instead of the old JSON files. This new format is much more flexible and works for all sorts of behavioural data. If you have archives in the old JSON format, Rtrack can still read those and you should use Rtrack to convert them to trackxf:

     experiment = Rtrack::read_experiment("OldFormat.json")
     Rtrack::export_data(experiment, file = "NewFormat")
    

    This will save your data as a file ‘NewFormat.trackxf’, in the new trackxf format.

Installing GDAL on Linux

Some important parts of Rtrack’s functionality rely on the terra R package, which makes working with zones and complex paths very fast. In turn, terra relies on an external library called GDAL. While MacOS and Windows have precompiled binaries available, Linux users will need to install the GDAL software manually before starting the Rtrack installation. On Debian-based distributions (such as Ubuntu, which we use for testing), the required package is libgdal-dev and this can be installed with the following Terminal command:

sudo apt install libgdal-dev

Unknown track format

Rtrack can import raw track data in a number of different formats. Each of these formats has a track.format code which you need to pass to read_path or add to the experiment description spreadsheet. To work out which code is appropriate for your data, try running the helper function identify_track_format which will tell you if the track is in a supported format and what the Rtrack code for it is.

track_file = system.file("extdata", "Track_1.tab", package = "Rtrack")
Rtrack::identify_track_format(track_file)
## ✔ This track seems to be in the format 'raw.tab'.
## [1] "raw.tab"

File encodings

Life is never as simple as it could be, and working with raw data is no exception. While most text files these days use the standard UTF-8 encoding, many do not. This can be dependent on the software that exported the raw track files, the operating system you use and your locale. The function identify_track_format will also check your file for some of the more common encodings and add this information to the track.format code (if it is UTF-8 then this extra information is not necessary). If you know for certain what your file encoding is, then you can also manually add this information to the track.format code.

Unsupported track format

Although Rtrack supports many raw data formats, there are many more variations out there. There are still no standardised guidelines for tracking data, so every tracking software creates raw files in a dizzying range of formats. If identify_track_format cannot determine the format of your file, it will return NA and a message directing you to this page.

# Not a track file
arena_description = system.file("extdata", "Arena.txt", package = "Rtrack")
Rtrack::identify_track_format(arena_description)
## ✖ The format of this track cannot be determined.
##  Please visit https://rupertoverall.net/Rtrack/help.html for assistance.
## [1] NA

If this happens, first please inspect the track and try 2 or 3 other tracks from the same experiment. The identify_track_format function can fail if the track is empty (no path was recorded) or if the file is otherwise corrupt. If the files are good, but just in an unsupported format, please let us know; we will endeavour to add support for your format so you can get on with your work. In this case, we need some information from you:

  • A copy of one of the track files.
  • Some information about the source of the file (which tracking software created it?). A link to the web page of that software is also very helpful.
  • Your contact details so we can get back to you with questions or the solution.

This information can be either emailed to us or submitted to the github issues tracker.

Bugs

If you discover a bug in the package somewhere, please let us know about it. A description of the bug together with a minimal reproducible example should be submitted to the github issues tracker.

Other issues

We are happy to recieve feedback if you have any other queries. The github issues tracker can also be used for feature requests or other useabilty issues. You can also contact us directly by email.