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.
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).
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)
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.
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.
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
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"
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.
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:
This information can be either emailed to us or submitted to the github issues tracker.
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.
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.