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)

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

# NOT RUN {
# 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)
# }