Description of the novel object recognition task metrics calculated by the Rtrack package
Source:../../Rtrack_website/vignettes/Rtrack_NOR_metrics_description.Rmd
Rtrack_NOR_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 ‘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
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 open field arena is defined as a ‘field’ and two objects together with several informative zones. The two objects are simply called object.1 and object.2 and are associated with buffer zones (the ‘object vicinity’).1 The zones are defined as follows:
- The field is defined as the square arena which the animals
explore. The shape and size (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 square with a width of 20 % of the arena width and centred on the centre of the field/arena.
- The wall is defined as a hollow square with the outer extent bounded by the arena and the inner edge equal to 60 % of the arena width (i.e. the wall zone width is 20 % of the arena width).
- The corner is defined as the square regions where the wallzones overlap at each outer corner of the field. The four corners are considered as one zone and this overlaps 100 % with the wall zone (so the subject can be present in both at the same time).
- object.1 and object.2 represent the bounds of the test objects. These may be circular or quadrilateral.
- object.1.vicinity and object.2.vicinity are buffers around the test objects. The width of the buffer is 10 % of the arena width.
- object is a composite zone comprising both objects2. This is used to detect investigation of any object.
- object.vicinity is a buffer around the object zone.
A further object definition is used for some calculations—this is the ‘novel object’. This may be none, either or both of the objects. The definition of which objects are novel is established in the arena description. Several of the metrics are calculated using this information.
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.
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.
d.origin
The distance (in normalised units) of the subject from the points at the centre of the field at each timepoint.
d.wall
The distance (in normalised units) of the subject from the nearest part of the wall zone at each timepoint.
d.corner
The distance (in normalised units) of the subject from the nearest part of any corner zone at each timepoint.
d.object.1
The distance (in normalised units) of the subject from the nearest part of object 1 at each timepoint.
d.object.2
The distance (in normalised units) of the subject from the nearest part of the object 2 at each timepoint.
d.object
The distance (in normalised units) of the subject from the nearest part of any object at each timepoint.
d.novel.object
The distance (in normalised units) of the subject from the nearest part of any object that is marked as ‘novel’ at each timepoint.
turning
The angle between each point in the path and the x-axis. This is also
used to generate the turning and
absolute.turning metrics by calculating the difference in
angles between adjacent points.
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.
Summary metrics
The summary metrics are derived from the core metrics above, but are each only a single value. Where metrics have been calculated for every timepoint, the value given here is either a sum, where appropriate, or the median together with the upper and lower quartiles.
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 path3.
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. For NOR, this should be the same as the fixed trial duration.
velocity
The median velocity. The speed of movement at each time
interval. In path units per time unit.
coverage
The area covered by the path (see coverage above).
roaming.entropy
The roaming entropy (see roaming.entropy above).
latency.to.object.vicinity
The time at which the subject first visited any object (see latency.to.zone above). This will be
NA if the centre was never visited.
latency.to.novel.object.vicinity
The time at which the subject first visited the/any novel object (see
latency.to.zone above). This will be
NA if the wall zone was never visited.
time.in.centre.zone
The total time the subject spent in the vicinity of any object (see
latency.to.zone above). This will be
NA if a corner was never visited.
time.in.wall.zone
The total time the subject spent in the vicinity of the/any novel
object (see latency.to.zone above). This
will be NA if the wall zone was never visited.
time.in.corner.zone
The total time the subject spent in the corner zone (see latency.to.zone above). This will be
NA if a corner was never visited
object.vicinity.crossings
The number of times the path crossed the centre zone (see goal.crossings above). This will be
NA if the centre zone was never visited.
novel.object.vicinity.crossings
The number of times the path crossed the wall zone (see goal.crossings above). This will be
NA if the wall zone was never visited.
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
correction : list
t : numeric
x : numeric
y : numeric
r : numeric
field : list
shape : character
x : numeric
y : numeric
radius : numeric
zones : list
field : PackedSpatVector [terra]
wall : PackedSpatVector [terra]
corner : PackedSpatVector [terra]
object.1 : PackedSpatVector [terra]
object.2 : PackedSpatVector [terra]
object.1.vicinity : PackedSpatVector [terra]
object.2.vicinity : PackedSpatVector [terra]
object : PackedSpatVector [terra]
object.vicinity : PackedSpatVector [terra]
area : list
field : numeric
wall : numeric
corner : numeric
object.1 : numeric
object.2 : numeric
object.1.vicinity : numeric
object.2.vicinity : numeric
object : numeric
object.vicinity : 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
coverage : numeric
turning : numeric
d.centroid : numeric
d.origin : numeric
d.wall : numeric
d.corner : numeric
d.object.1 : numeric
d.object.2 : numeric
d.object : numeric
d.novel.object : numeric
turning : 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
total.time : numeric
lower.velocity : numeric
median.velocity : numeric
upper.velocity : numeric
immobility : numeric
turning : numeric
absolute.turning : numeric
coverage : numeric
lower.d.origin : numeric
median.d.origin : numeric
upper.d.origin : numeric
lower.d.wall : numeric
median.d.wall : numeric
upper.d.wall : numeric
lower.d.corner : numeric
median.d.corner : numeric
upper.d.corner : numeric
lower.d.object : numeric
median.d.object : numeric
upper.d.object : numeric
lower.d.novel.object : numeric
median.d.novel.object : numeric
upper.d.novel.object : numeric
roaming.entropy : numeric
velocity.in.wall.zone : numeric
velocity.in.corner.zone : numeric
velocity.in.object.1.vicinity : numeric
velocity.in.object.2.vicinity : numeric
velocity.in.object.vicinity : numeric
velocity.in.novel.object.vicinity : numeric
immobility.in.wall.zone : numeric
immobility.in.corner.zone : numeric
immobility.in.object.1.vicinity : numeric
immobility.in.object.2.vicinity : numeric
immobility.in.object.vicinity : numeric
immobility.in.novel.object.vicinity : numeric
latency.to.wall.zone : numeric
latency.to.corner.zone : numeric
latency.to.object.1.vicinity : numeric
latency.to.object.2.vicinity : numeric
latency.to.object.vicinity : numeric
latency.to.novel.object.vicinity : numeric
time.in.wall.zone : numeric
time.in.corner.zone : numeric
time.in.object.1.vicinity : numeric
time.in.object.2.vicinity : numeric
time.in.object.vicinity : numeric
time.in.novel.object.vicinity : numeric
wall.zone.crossings : numeric
corner.zone.crossings : numeric
object.1.vicinity.crossings : numeric
object.2.vicinity.crossings : numeric
object.vicinity.crossings : numeric
novel.object.vicinity.crossings : numeric
summary : numeric
path.length : numeric
total.time : numeric
velocity : numeric
immobility : numeric
coverage : numeric
distance.from.object : numeric
distance.from.novel.object : numeric
roaming.entropy : numeric
latency.to.object.vicinity : numeric
latency.to.novel.object.vicinity : numeric
time.in.wall.zone : numeric
time.in.corner.zone : numeric
time.in.object.vicinity : numeric
time.in.novel.object.vicinity : numeric
object.vicinity.crossings : numeric
novel.object.vicinity.crossings : numericThese buffers are used to detect investigation of the objects as it may not be possible to enter the actual object zones and the subject’s centre of mass (used by most tracking software to define the tracked coordinates) can be a short distance from the point of contact. That being said, unless the objects are quite tall, it is often possible for animals to climb on top of them. This is not, and should not be, required for the detection of investigation of the object/s however.↩︎
This may not be the sum of results from both objects. If the object vicinities (or, indeed, the objects) overlap (because they were placed too close to each other), then the overlapping region will not be considered as part of the vicinity of either object. This is because the intention of the subject cannot be correctly determined in such cases. Presence in the overlap region will however be assigned to the total object vicinity.↩︎
Most of the metrics are not normally distributed and therefore 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.↩︎