Description of Barnes maze metrics calculated by the Rtrack package
Source:../../Rtrack_website/vignettes/Rtrack_Barnes_metrics_description.Rmd
Rtrack_Barnes_metrics_description.RmdAt the heart of Rtrack is the processing of the raw paths to yield descriptive metrics. Some of these metrics, such as ‘path length’ and ‘latency to goal’ 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
definition.
The metrics object
A core functionality of the Rtrack package is the calculation of
metrics from the path coordinates. The rtrack_metrics
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
in the rtrack_metrics object and describes the individual
metrics in detail.
Object metadata
This section contains information that has been passed to the
calculate_metrics function and is embedded in the
rtrack_metrics object for convenience.
id
This is the track id supplied either to read_path or
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 plot_path or
plot_density.
arena
The rtrack_arena object associated with this track. See
the function read_arena for details.
Arena zones
The Barnes maze is a circular arena with a series of holes placed regularly near the outer edge. One of these holes leads to an escape box and is defined as the ‘goal’ for the purposes of this task. Several zones are defined that partition the arena into informative regions. The zones for this arena type are as follows:
- The arena is defined as the circular region in which the
task is performed. The raw size, shape and centre point (to allow for
path recording calibration) are set by the experimenter in the arena
definition file/s (see the function
read_arena). The fraction of time spent in this zone should be 1 (excepting only small calibration errors). - The centre is defined as a ring with a radius 20 % of the arena diameter, and which is centred on the centre of the arena.
- The annulus is defined as a ring, centred on the centre of the pool/arena, with a width such that all of the holes, and their buffer zones (see below), exactly fit inside it.
- The goal is the target platform. This is generally required, even for
a probe trial where the platform is not physically present. The size and
position are defined by the experimenter in the arena definition file/s
(see the function
read_arena). - The goal.vicinity is a buffer zone1 around the goal whose with is 5 % of the arena radius.
- The old goal is the previous position the target platform
was in before a reversal. This is optional and will not be present
during training/acquisition or a probe trial. The size and position (if
present) are defined by the experimenter in the arena definition file/s
(see the function
read_arena). - The quadrants. The north quadrant is the quarter of the arena area that is centred on the goal. The other quadrants are defined based on this. The quadrant definitions thus change when the goal is moved (such as during a reversal).
Core metrics
This section contains all the metrics, including those calculated for all time points (such as distance from goal and heading error).
path.length
The length of the path. This is in whatever units the path was measured in (millimetres, inches, pixels).
immobile.x
The x coordinates of all timepoints where the subject was immobile. This is useful for plotting the spatial locations of periods of immobility.
immobile.y
The y coordinates of all timepoints where the subject was immobile. This is useful for plotting the spatial locations of periods of immobility.
clockwise.chain.length
Chains are defined as visits to multiple adjacent holes in a single direction. This value is the sum of the lengths of all clockwise chains.
anticlockwise.chain.length : numeric
This value is the sum of the lengths of all anticlockwise chains.
coverage
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.
initial.path
The initial path is the section of the path from the start to a length equal to the direct distance between the start and the centre of the goal.
initial.heading.error
The angle between each point of the initial path and the direct line from start to goal.
initial.displacement.error
The distance between each point of the initial path and the corresponding point on the direct path from start to goal.
initial.trajectory.error
The distance between the last point of the initial path and the centre of the goal.
roaming.entropy
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/.
velocity.in.zone
The speed at which the subject is moving in each zone. This is a list, with values computed for each of the defined zones.
immobility.in.zone
The total duration that the subject was immobile in each zone. This is a list, with values computed for each of the defined zones.
latency.to.zone
The time at which the subject first crossed each zone. This is a list, with values computed for each of the defined zones.
time.in.zone
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.
goal.crossings
Zone crossings are the number of times the path crossed (i.e. entered and exited once) a particular zone. This is measured by calculating the intersection of the path and the zone polygon and identifying the transitions between ‘inside’ and ‘outside’ of the zone. Half of these transitions will be entries which is equivalent to the number of crossings (this value is in fact rounded up in case the track ends in a goal zone, as expected for the goal, which should be counted as a ‘crossing’).
Summary metrics
The summary metrics are derived from the core metrics above, but are each only a single value (typically the mean).
features
This vector of (normalised) values is used for strategy calling using
the machine learning model implemented in call_strategy.
These are not useful for further analysis on their own.
summary
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 path2.
path.length
The total length of the path. This is just the sum of the distance between each point and the next point in the path.
total.time
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 median velocity. The speed of movement at each time
interval. In path units per second.
roaming.entropy
The roaming entropy (see roaming.entropy above).
holes.before.goal
The number of holes visited before first visiting the goal. A goal
visit is classed as entry into the goal vicinity zone (see goal.vicinity above). This will be
NA if the goal was not reached.
holes.before.old.goal
The number of holes visited before first visiting the old goal. This
will be NA if the old goal was not reached or if there was
no old goal present.
latency.to.goal
The time at which the subject first crossed the goal zone (see latency.to.zone above). This will be
NA if the goal was not reached.
latency.to.old.goal
The time at which the subject first crossed the old goal zone (see latency.to.zone above). This will be
NA if the old goal was not reached or if there was no old
goal present.
time.in.centre.zone
Total time spent in the centre zone (see Arena zones above for a definition of this zone).
time.in.far.wall.zone
Time in the wall zone (see Arena zones above for a definition of this zone).
time.in.annulus.zone
Time in the wall zone (see Arena zones above for a definition of this zone).
time.in.goal.zone
Time in the wall zone (see Arena zones above for a definition of this zone).
time.in.old.goal.zone
Time in the wall zone (see Arena zones above for a definition of this zone).
time.in.n.quadrant
Time in the north quadrant (centred on the goal position; see Arena zones above for a definition of this zone).
time.in.e.quadrant
Time in the east quadrant (see Arena zones above for a definition of this zone).
time.in.s.quadrant
Time in the south quadrant (see Arena zones above for a definition of this zone).
time.in.w.quadrant
Time in the west quadrant (see Arena zones above for a definition of this zone).
goal.crossings
The number of times the path crossed the goal zone (see goal.crossings above).
old.goal.crossings
The number of times the path crossed the old goal zone (see goal.crossings above).
Structure of the metrics object
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]
annulus : PackedSpatVector [terra]
goal : PackedSpatVector [terra]
goal.vicinity : PackedSpatVector [terra]
old.goal : PackedSpatVector [terra]
old.goal.vicinity : PackedSpatVector [terra]
hole_1—hole_n : PackedSpatVector [terra]
hole_1_vicinity—hole_n_vicinity : PackedSpatVector [terra]
hole.vicinity : PackedSpatVector [terra]
goal.adjacent : PackedSpatVector [terra]
old.goal.adjacent : PackedSpatVector [terra]
n.quadrant : PackedSpatVector [terra]
e.quadrant : PackedSpatVector [terra]
s.quadrant : PackedSpatVector [terra]
w.quadrant : PackedSpatVector [terra]
goal.corridor : PackedSpatVector [terra]
area : list
pool : numeric
wall : numeric
far.wall : numeric
annulus : numeric
goal : numeric
old.goal : numeric
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
total.time : numeric
velocity : numeric
immobile : numeric
immobile.x : numeric
immobile.y : numeric
immobility : numeric
turning : numeric
clockwise.chain.length : numeric
anticlockwise.chain.length : numeric
coverage : numeric
outliers : numeric
initial.path : numeric
initial.heading.error : numeric
initial.displacement.error : numeric
initial.trajectory.error : numeric
efficiency : numeric
roaming.entropy : numeric
alpha : numeric
heading.error : numeric
velocity.in.zone : numeric
immobility.in.zone : numeric
latency.to.zone : numeric
time.in.zone : numeric
goal.crossings : numeric
old.goal.crossings : numeric
features : numeric
path.length : numeric
total.time : numeric
lower.velocity : numeric
median.velocity : numeric
upper.velocity : numeric
clockwise.chain.length : numeric
anticlockwise.chain.length : numeric
absolute.chain.length : numeric
coverage : numeric
lower.d.centroid : numeric
median.d.centroid : numeric
upper.d.centroid : numeric
lower.d.goal : numeric
median.d.goal : numeric
upper.d.goal : numeric
lower.d.old.goal : numeric
median.d.old.goal : numeric
upper.d.old.goal : numeric
centroid.goal.displacement : numeric
centroid.old.goal.displacement : numeric
median.initial.heading.error : numeric
initial.trajectory.error : numeric
initial.reversal.error : numeric
turning : numeric
absolute.turning : numeric
efficiency : numeric
roaming.entropy : numeric
holes.before.goal : numeric
holes.before.old.goal : numeric
velocity.in.centre.zone : numeric
velocity.in.annulus.zone : numeric
velocity.in.goal.zone : numeric
velocity.in.goal.vicinity : numeric
velocity.in.goal.adjacent : numeric
velocity.in.goal.corridor : numeric
velocity.in.old.goal.zone : numeric
velocity.in.old.goal.vicinity : numeric
velocity.in.old.goal.adjacent : numeric
velocity.in.hole.vicinity : numeric
velocity.in.n.quadrant : numeric
velocity.in.e.quadrant : numeric
velocity.in.s.quadrant : numeric
velocity.in.w.quadrant : numeric
immobility.in.centre : numeric
immobility.in.annulus.zone : numeric
immobility.in.goal.zone : numeric
immobility.in.goal.vicinity : numeric
immobility.in.goal.adjacent : numeric
immobility.in.goal.corridor : numeric
immobility.in.old.goal.zone : numeric
immobility.in.old.goal.vicinity : numeric
immobility.in.old.goal.adjacent : numeric
immobility.in.hole.vicinity : numeric
immobility.in.n.quadrant : numeric
immobility.in.e.quadrant : numeric
immobility.in.s.quadrant : numeric
immobility.in.w.quadrant : numeric
latency.to.centre.zone : numeric
latency.to.annulus.zone : numeric
latency.to.goal.zone : numeric
latency.to.goal.vicinity : numeric
latency.to.goal.adjacent : numeric
latency.to.goal.corridor : numeric
latency.to.old.goal.zone : numeric
latency.to.old.goal.vicinity : numeric
latency.to.old.goal.adjacent : numeric
latency.to.hole.vicinity : numeric
latency.to.n.quadrant : numeric
latency.to.e.quadrant : numeric
latency.to.s.quadrant : numeric
latency.to.w.quadrant : numeric
time.in.centre.zone : numeric
time.in.annulus.zone : numeric
time.in.goal.zone : numeric
time.in.goal.vicinity : numeric
time.in.goal.adjacent : numeric
time.in.goal.corridor : numeric
time.in.old.goal.zone : numeric
time.in.old.goal.vicinity : numeric
time.in.old.goal.adjacent : numeric
time.in.hole.vicinity : numeric
time.in.n.quadrant : numeric
time.in.e.quadrant : numeric
time.in.s.quadrant : numeric
time.in.w.quadrant : numeric
centre.zone.crossings : numeric
annulus.zone.crossings : numeric
goal.zone.crossings : numeric
old.goal.zone.crossings : numeric
hole.vicinity.crossings : numeric
n.quadrant.crossings : numeric
e.quadrant.crossings : numeric
s.quadrant.crossings : numeric
w.quadrant.crossings : numeric
goal.reached : numeric
old.goal.reached : numeric
summary : numeric
path.length : numeric
total.time : numeric
velocity : numeric
immobility : numeric
distance.from.goal : numeric
distance.from.old.goal : numeric
roaming.entropy : numeric
holes.before.goal : numeric
holes.before.old.goal : numeric
latency.to.goal : numeric
latency.to.old.goal : numeric
time.in.centre.zone : numeric
time.in.annulus.zone : numeric
time.in.goal.zone : numeric
time.in.old.goal.zone : numeric
time.in.hole.vicinity : numeric
time.in.n.quadrant : numeric
time.in.e.quadrant : numeric
time.in.s.quadrant : numeric
time.in.w.quadrant : numeric
goal.crossings : numeric
old.goal.crossings : numericThis buffer are used to detect investigation of the holes as the subjects should not be able to actually enter the holes (or if they do, in the case of the goal, then they may disappear from sight) and the subject’s centre of mass (used by most tracking software to define the tracked coordinates) will remain in the arena outside the actual hole region.↩︎
Most of the metrics are not normally distributed so so-called parametric statistics may not be appropriate. For this reason, Rtrack defaults to using non-parametric descriptive statistics such as median and the upper/lower quartiles.↩︎