Processing math: 100%

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 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’ with informative zones 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 wall zones overlap at each outer corner of the field/arena. 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).

area

A list of the areas of each of the arena components. This is used in several of the metrics calculations.

path

The rtrack_path object associated with this track. See the function read_path for details.

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).

velocity

The speed of movement at each time interval. In normalised path units per second.

immobile

A logical vector indicating whether the subject was not moving at each timepoint.

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.

immobility

The total amount of time (in seconds) that the subject was immobile.

total.time

The total time the subject spent in the arena. This is given in seconds.

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.

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.

d.centroid

The distance (in normalised units) of the subject from the path centroid at each timepoint.

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.centre

The distance (in normalised units) of the subject from the nearest part of the centre zone at each timepoint.

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 × 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: (p×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.

zone.crossings

The number of times each zone was traversed. This is a list, with values computed for each of the defined zones.

An overview of some of the terms used in the metrics definitions.

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 path1.

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 OFT, 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.

immobility

The total time spent immobile.

coverage

The area covered by the path (see coverage above).

distance.from.centre

The median distance from the nearest edge of the centre zone.

distance.from.wall

The median distance from the nearest edge of the wall zone.

distance.from.corner

The median distance from the nearest edge of the corner zone.

roaming.entropy

The roaming entropy (see roaming.entropy above).

velocity.in.centre.zone

The median velocity in the centre zone.

velocity.in.wall.zone

The median velocity in the wall zone.

velocity.in.corner.zone

The median velocity in the corner zone.

latency.to.centre.zone

The time at which the subject first crossed the centre zone (see latency.to.zone above). This will be NA if the centre was never visited.

latency.to.wall.zone

The time at which the subject first crossed the wall zone (see latency.to.zone above). This will be NA if the wall zone was never visited.

latency.to.corner.zone

The time at which the subject first crossed the corner zone (see latency.to.zone above). This will be NA if a corner was never visited.

time.in.centre.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.

time.in.wall.zone

The total time the subject spent in the wall zone (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.

centre.zone.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.

wall.zone.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.

corner.zone.crossings

The number of times the path crossed the corner zone (see goal.crossings above). This will be NA if the corner 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]
            centre : PackedSpatVector [terra]
    area : list
        field : numeric
        wall : numeric
        centre : 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.centre : 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.centroid : numeric
        median.d.centroid : numeric
        upper.d.centroid : 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.centre : numeric
        median.d.centre : numeric
        upper.d.centre : numeric
        roaming.entropy : numeric
        velocity.in.centre.zone : numeric
        velocity.in.wall.zone : numeric
        velocity.in.corner.zone : numeric
        immobility.in.centre.zone : numeric
        immobility.in.wall.zone : numeric
        immobility.in.corner.zone : numeric
        latency.to.centre.zone : numeric
        latency.to.wall.zone : numeric
        latency.to.corner.zone : numeric
        time.in.centre.zone : numeric
        time.in.wall.zone : numeric
        time.in.corner.zone : numeric
        centre.zone.crossings : numeric
        wall.zone.crossings : numeric
        corner.zone.crossings : numeric
    summary : numeric
        path.length : numeric
        total.time : numeric
        velocity : numeric
        immobility : numeric
        coverage : numeric
        distance.from.centre : numeric
        distance.from.wall : numeric
        distance.from.corner : numeric
        roaming.entropy : numeric
        velocity.in.centre.zone : numeric
        velocity.in.wall.zone : numeric
        velocity.in.corner.zone : numeric
        immobility.in.centre.zone : numeric
        immobility.in.wall.zone : numeric
        immobility.in.corner.zone : numeric
        latency.to.centre.zone : numeric
        latency.to.wall.zone : numeric
        latency.to.corner.zone : numeric
        time.in.centre.zone : numeric
        time.in.wall.zone : numeric
        time.in.corner.zone : numeric
        centre.zone.crossings : numeric
        wall.zone.crossings : numeric
        corner.zone.crossings : numeric

  1. 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.↩︎