`ColonyTrack_metrics_details.Rmd`

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.

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

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

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.

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.

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

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

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.

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.

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

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.

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`

.

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^{1}.

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^{2}.

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.

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^{3}.

The dominance score of the subject is reported^{4}.

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