bout_analysis {sleepr}

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)

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.

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.

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)