Calculation of tracking metrics.

Calculates metrics from cage location data.

calculate_metrics(
  data,
  days = "all",
  drop.days = NULL,
  subjects = "all",
  drop.subjects = NULL,
  trim = c(0, 0),
  estimate = FALSE,
  log = FALSE,
  n.cores = parallel::detectCores() - 1
)

Arguments

data

A colonytrack_data object, generated by read_data.

days

Specify the days to be included is the metrics calculation. This may be in any of the standard formats (names, indices, or a logical vector). Default is to include all days present in the input data file.

drop.days

Specify the days to be _excluded_ is the metrics calculation. This takes precedence over the days parameter. This may be in any of the standard formats (names, indices, or a logical vector). Default is not to exclude any days.

subjects

Specify the subjects to be included is the metrics calculation. This may be in any of the standard formats (names, indices, or a logical vector). Default is to include all subjects present in the input data file.

drop.subjects

Specify the subjects to be _excluded_ is the metrics calculation. This takes precedence over the subjects parameter. This may be in any of the standard formats (names, indices, or a logical vector). Default is not to exclude any subjects.

trim

An integer vector of length 2, specifying the number of hours (in Zeitgeber time) to be trimmed off the ends of the metrics calculation period. This may be useful to allow focus on a core segment of nightly activity. Default is no trimming.

estimate

Logical (default FALSE) Whether an estimate of total runtime should be shown as the calculation proceeds. The calculation of metrics on a large dataset can take many hours, so thus can be a useful indicator. Performance is, however, better when this option is set to false.

log

Logical (default FALSE) indicating whether a file should be created for each job. This is useful for monitoring large experiments and for estimating total run time. Note that a progress bar is not provided as the computational overhead is too high.

n.cores

The number of CPU cores to use. The default tries to estimate an optimal value but, especially on Linux, it may be better to set this manually based on the available hardware. If n.cores is set higher than the number of days to be calculated, then the cluster will be created with only one node per day.

Value

An colonytrack_metrics object. The calls element contains the called strategy/strategies as well as confidence scores for all possible strategies.

Details

This function takes the pre-processed data from read_data and calculates a range of behavioural metrics. Metrics are calculated daily, with the exception of the ethogram data which are calculated hourly.

See also

read_data.