At the heart of Rtrack is the processing of the raw paths to yield descriptive metrics. Some of these metrics, such as ‘path length’ and ‘time in wall zone’ are easily explained. Others are less clear, are named differently by different authors and/or depend on varying parameters.
This document describes each of the metrics calculated by
calculate_metrics and the parameters used in their
A core functionality of the Rtrack package is the calculation of
metrics from the path coordinates. The
object that is returned by
calculate_metrics contains the
results of these calculations which are used for prediction by the
machine learning model. This section explains the information contained
rtrack_metrics object and describes the individual
metrics in detail.
This section contains information that has been passed to the
calculate_metrics function and is embedded in the
rtrack_metrics object for convenience.
This is the track id supplied either to
read_experiment and should be a unique identifier for the
track. This will be used to name track analysis output and to title the
plots generated by
rtrack_arena object associated with this track. See
read_arena for details.
The active place avoidance arena is a circular space made up of several zones. The zones for this arena type are as follows:
read_arena). The fraction of time spent in this zone should be 1 (excepting only small calibration errors).
A list of the areas of each of the arena components. This is used in several of the metrics calculations.
This section contains all the metrics, including those calculated for all time points (such as distance from goal and heading error).
The length of the path. This is in whatever units the path was measured in (millimetres, inches, pixels).
The x coordinates of all timepoints where the subject was immobile. This is useful for plotting the spatial locations of periods of immobility.
The y coordinates of all timepoints where the subject was immobile. This is useful for plotting the spatial locations of periods of immobility.
The angle, in the direction of rotation, separating the position of the subject at each timepoint from the leading edge of the aversive zone. If the subject is in the aversive zone, this angle is 0.
The number of times the path crossed (i.e. entered and exited once) the aversive.zone.
The fraction of the arena covered by the path. This is measured by calculating the area of the minimal polygon enclosing the path (i.e. the ‘silhouette’; actually the ‘convex hull’ in technical terms) as a fraction of the area of the arena.
This is an application of the Shannon entropy measure to spatial paths. In Rtrack, it is estimated by calculating a density map with a 50 \(\times\) 50 grid (and a bandwidth of 1/50) which is clipped to the bounds of the arena. This gives a computationally fast estimate of \(p\); the likelihood of the path passing through any one of the grid cells. The entropy is then calculated using Shannon’s equation: \(-\sum(p\times log(p))\). This value is then normalised by dividing by the log of the total number of grid cells present in the arena (so that the final value ranges between 0 and 1). A roaming entropy of 1 means that the path covers the entire arena and it is impossible to predict a point on the path. A roaming entropy of 0 occurs when the entire path is within one grid cell. Lower entropy values indicate a more predictable path. The idea behind the roaming entropy measure is demonstrated at http://www.brandmaier.de/roamingentropy/.
The speed at which the subject is moving in each zone. This is a list, with values computed for each of the defined zones.
The total duration that the subject was immobile in each zone. This is a list, with values computed for each of the defined zones.
The time at which the subject first crossed each zone. This is a list, with values computed for each of the defined zones.
The fraction of the path spent in each zone. The time at which the subject first crossed the each zone. This is a list, with values computed for each of the defined zones.
The summary metrics are derived from the core metrics above, but are each only a single value (typically the mean).
This vector of (normalised) values is used for strategy calling using
the machine learning model implemented in
These are not useful for further analysis on their own.
This is a selection of summary metrics that make sense for downstream analysis. These values use the same units as the raw input data. That is, the distances are in whatever units the track acquisition software used (this may be centimetres, inches or even just pixels from the video analysis—you will need to check with your acquisition software if you are unsure of what these are). Times are in the units specified in the arena description file. These will be ( must be!) the units of the timestamps in the raw acquisition data. Most of these values are medians of the metrics calculated for each point on the path1.
The total length of the path. This is just the sum of the distance between each point and the next point in the path.
The total time the subject spent in the arena. This is not necessarily the same as the maximum trial duration; e.g. in cases where the subject finds the platform early.
velocity. The speed of movement at each time
interval. In path units per second.
The median angle of each point on the path from the leading edge of the aversive zone (see angle.from.aversive.zone above).
The median angle of each point on the path from the leading edge of the old aversive zone (see angle.from.aversive.zone above).
The roaming entropy (see roaming.entropy above).
The time at which the subject first crossed the aversive zone (see latency.to.zone above). This will be
NA if the aversive zone was never entered
The time at which the subject first crossed the old aversive zone
(see latency.to.zone above). This will be
NA if the old aversive zone was never entered or if there
was no old aversive zone defined.
The number of times the path crossed the aversive zone (see goal.crossings above).
Below is an overview of the hierarchy of the
rtrack_metrics object together with the names and classes
of each component. Where the class is not part of the R base package, it
is given in square brackets after the class name.
metrics : rtrack_metrics [Rtrack] id : character arena : rtrack_arena [Rtrack] id : character type : character description : data.frame type : character time.units : character arena.bounds : character goal : character (old.goal : character) **this component is optional and may be missing** correction : list t : numeric x : numeric y : numeric r : numeric pool : list shape : character x : numeric y : numeric radius : numeric goal : list shape : character x : numeric y : numeric radius : numeric old.goal : list shape : character x : numeric y : numeric radius : numeric zones : list arena : PackedSpatVector [terra] centre : PackedSpatVector [terra] wall : PackedSpatVector [terra] aversive.zone : PackedSpatVector [terra] (old.aversive.zone : PackedSpatVector [terra]) **this component is optional and may be missing** n.quadrant : PackedSpatVector [terra] e.quadrant : PackedSpatVector [terra] s.quadrant : PackedSpatVector [terra] w.quadrant : PackedSpatVector [terra] area : list arena : numeric centre : numeric wall : numeric aversive.zone : numeric (old.aversive.zone : numeric) **this component is optional and may be missing** n.quadrant : numeric e.quadrant : numeric s.quadrant : numeric w.quadrant : numeric path : rtrack_path id : character raw.t : numeric raw.x : numeric raw.y : numeric t : numeric x : numeric y : numeric path.length : numeric velocity : numeric immobile : numeric immobile.x : numeric immobile.y : numeric immobility : numeric total.time : numeric angle.from.aversive.zone : numeric angle.from.old.aversive.zone : numeric goal.crossings : numeric coverage : numeric roaming.entropy : numeric velocity.in.zone : numeric immobility.in.zone : numeric latency.to.zone : numeric time.in.zone : numeric zone.crossings : numeric features : numeric path.length : numeric lower.velocity : numeric median.velocity : numeric upper.velocity : numeric lower.immobility : numeric median.immobility : numeric upper.immobility : numeric coverage : numeric turning : numeric absolute.turning : numeric lower.angle.from.aversive.zone : numeric median.angle.from.aversive.zone : numeric upper.angle.from.aversive.zone : numeric lower.angle.from.old.aversive.zone : numeric median.angle.from.old.aversive.zone : numeric upper.angle.from.old.aversive.zone : numeric roaming.entropy : numeric velocity.in.centre.zone : numeric velocity.in.wall.zone : numeric velocity.in.aversive.zone : numeric velocity.in.old.aversive.zone : numeric immobility.in.centre.zone : numeric immobility.in.wall.zone : numeric immobility.in.aversive.zone : numeric immobility.in.old.aversive.zone : numeric latency.to.centre.zone : numeric latency.to.wall.zone : numeric latency.to.aversive.zone : numeric latency.to.old.aversive.zone : numeric time.in.centre.zone : numeric time.in.wall.zone : numeric time.in.aversive.zone : numeric time.in.old.aversive.zone : numeric centre.zone.crossings : numeric wall.zone.crossings : numeric aversive.zone.crossings : numeric old.aversive.zone.crossings : numeric summary : numeric path.length : numeric total.time : numeric velocity : numeric immobility : numeric angle.from.aversive.zone : numeric angle.from.old.aversive.zone : numeric roaming.entropy : numeric latency.to.aversive.zone : numeric latency.to.old.aversive.zone : numeric time.in.centre.zone : numeric time.in.wall.zone : numeric time.in.aversive.zone : numeric time.in.old.aversive.zone : numeric aversive.zone.crossings : numeric old.aversive.zone.crossings : numeric