The individual metrics

Description of the individual metrics

The colonytrack_metrics object contains features/metrics calculated from the tracking data. This vignette gives details of the individual component, which holds the core metrics for each time window.

distance.moved

This is simply the number of cage transitions performed by the subject during each time window.

time.per.cage

The total time (in seconds) spent in each separate cage is calculated. This metric reports the average (mean) time over all cages.

high.activity

The total time (in seconds) the subject spent in each cage, where the time in each cage was less than 1 second. The mean across all cages is reported.

sustained.activity

The total time (in seconds) the subject spent in each cage, where the time in each cage was greater than or equal to 1 second but less than 10 seconds. The mean across all cages is reported.

cage.variability

The fraction of each day spent in each cage is calculated. This metric reports the standard deviation of that score across all cages.

cage.time.entropy

The Shannon entropy is calculated from the fraction of time spent in each cage on each day. \[\frac{ -\sum_{i=1}^{n}p_{i} \cdot \log(p_{i}) }{ \log(n) }\] where $p$ is the fraction of time spent in each cage (the probability of being in that cage) and $n$ is the number of cages. The denominator term serves to normalise the resulting score to $0 \le x \le 1$.

adjusted.cage.time.entropy

As for cage.time.entropy but where the cage probability has been corrected for the likelihood of entering the cage by chance. The chance level of cage presence is estimated using the centrality (‘betweenness’) of the cage in the cage network (using the function betweenness from the igraph package).

\[\frac{ -\sum_{i=1}^{n}p_{adj}{}_{i} \cdot \log(p_{adj}{}_{i}) }{ \log(n) }\] where $p_{adj}$ denotes the residuals ($p_{adj} = \sum (y - \hat{y})$) from a regression of $p$ on the betweenness score.

cage.location.entropy

As for cage.time.entropy but where $p$ is the fraction of times the subject entered each cage; i.e. the probability of entering that cage—regardless how long it spent in the cage.

revisit.time

The time between consecutive visits to the same cage is calculated and the mean across all visits and all cages is reported.

revisit.length

The number of other cages visited (the path length) between consecutive visits to the same cage is calculated and the mean across all visits and all cages is reported.

Cage transitions (black vertical lines at the base of the graph) are summarised using a kernel density estimate (black curve). The times of highest (‘peak active’; green vertical line) and lowest (‘peak inactive’; orange vertical line) activity are calculated, as well as the broad blocks/bouts of activity (pale blue shaded regions).

peak.inactive

Activity (cage transitions) is summarised as a density over the window period (see the figure above). Peaks and troughs are detected from the density curve and $x$-axis position of the lowest trough is reported as peak.inactive.

peak.active

As above; the highest peak is reported as peak.active.

activity.blocks

The activity peaks are thresholded and divided into blocks (activity bouts). The number of blocks is reported.

The number of other occupants in the same cage as the subject is counted for each time interval where that number stays constant (as subjects move in and out of cages, this value changes during the measurement period). The cage occupancy counts are then weighted by the length of each time interval and the weighted mean across all cages is reported¹.

time.alone

The total amount of time (in seconds) that the subject is in a cage alone.

The total amount of time spent with each other animal is calculated. The mean value across all other animals is reported.

The distance between the subject and every other animal is calculated as the shortest path through the cage network that separates them. These distances are calculated as a mean for each time interval where the subject positions remain constant (as subjects move in and out of cages, the values change during the measurement period). The average distances for each interval are then weighted by the length of the interval and the weighted mean across all cage transitions is reported².

For each cage transition the subject makes, the question is asked: was the cage change to a more- or less-populated cage? The difference in cage occupancy in the cage the subject just entered and the cage the subject just left is calculated. The mean value across all cage transitions is reported.

For each cage transition the subject makes, the question is asked: how many animals were in the cage when the subject leaves, vs. the number that were in the cage when it entered? The difference in cage occupancy in the cage when the subject left and when the subject entered is calculated. The mean value across all cage transitions is reported.

follow.events

Each case where the subject moves through a tunnel within 1 second after another animal crossed the same tunnel in the same direction is recorded. The total number of all such events (for all other animals) is reported³.

follow.dominance

The dominance score of the subject is reported⁴.

The calculation of this metric changed in version 1.0.4↩︎
The calculation of this metric changed in version 1.0.4↩︎
The individual ‘follow events’, grouped by protagonist and then by each other target animal, are also stored in the follow.events component.↩︎
This is the basic win/loss fraction. The user may wish to calculate more refined scores such as the David’s score—there are several variants in the literature and it is left to the user to select an appropriate one for their work. Alternative scores can readily be calculated using the matrices in the clustering$following component of the metrics object. See the description of the clustering component for more information.↩︎