sleepr (version 0.3.0)

bout_analysis: Find "bouts" in categorical time series

Description

This function is used to find contiguous regions of unique value in a -- potentially irregular/heterogeneous -- univariate categorical time series.

Usage

bout_analysis(var, data)

Value

an object of the same type as data (i.e. data.table::data.table or behavr::behavr). Each row is a specific bout characterised by three columns.

• t -- its onset

• duration -- its length

• <var> -- a column with the same name as var. The value of var for this bout.

Arguments

var

name of the variable to use from data

data

data.table containing behavioural variable from or one multiple animals. When it has a key, unique values, are assumed to represent unique individuals (e.g. in a behavr table). Otherwise, it analysis the data as coming from a single animal. data must have a column t representing time.

References

• The relevant rethomic tutorial section -- on sleep analysis

See Also

• sleep_annotation -- to generate a binary sleep variable

• rle run length encoding function -- on which this analysis is based

Examples

# Bout analysis on binary variable:
dt <- toy_dam_data()
dt[, moving := activity > 0]
bdt <- bout_analysis(moving,dt)
print(bdt)
# With multiple states
dt <- toy_ethoscope_data()
# we discretise x position in three states: left, middle and right (1/3 each)
dt[, location := as.character( cut(x,
                               breaks = c(0.0, .33, .67, 1.0),
                               labels = c("left", "middle", "right")))]

bdt <- bout_analysis(location, dt)