sleepr (version 0.3.0)

sleep_annotation: Score sleep behaviour from immobility

Description

This function first uses a motion classifier to decide whether an animal is moving during a given time window. Then, it defines sleep as contiguous immobility for a minimum duration.

Usage

sleep_annotation(data, time_window_length = 10,
  min_time_immobile = 300, motion_detector_FUN = max_velocity_detector,
  ...)
sleep_dam_annotation(data, min_time_immobile = 300)

Arguments

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.

time_window_length

number of seconds to be used by the motion classifier. This corresponds to the sampling period of the output data.

min_time_immobile

Minimal duration (in s) of a sleep bout. Immobility bouts longer or equal to this value are considered as sleep.

motion_detector_FUN

function used to classify movement

...

extra arguments to be passed to motion_classifier_FUN.

Value

a behavr table similar to data with additional variables/annotations (i.e. moving and asleep). The resulting data will only have one data point every time_window_length seconds.

Details

The default time_window_length is 300 seconds -- it is also known as the "5-minute rule". sleep_annotation is typically used for ethoscope data, whilst sleep_dam_annotation only works on DAM2 data. These functions are rarely used directly, but rather passed as an argument to a data loading function, so that analysis can be performed on the go.

References

• The relevant rethomic tutorial section -- on sleep analysis

See Also

• motion_detectors -- options for the motion_detector_FUN argument

• bout_analysis -- to further analyse sleep bouts in terms of onset and length

Examples

# NOT RUN {
dt_one_animal <- toy_ethoscope_data(seed=2)
####### Ethoscope, corrected velocity classification #########
sleep_dt <-  sleep_annotation(dt_one_animal, masking_duration=0)
print(sleep_dt)
# We could make a sleep `barecode'
# }
# NOT RUN {
library(ggplot2)
ggplot(sleep_dt, aes(t,y="Animal 1",fill=asleep)) +
                                   geom_tile() + scale_x_time()
# }
# NOT RUN {
####### Ethoscope, virutal beam cross classification #########
sleep_dt2 <-  sleep_annotation(dt_one_animal,
                             motion_detector_FUN=virtual_beam_cross_detector)
# }
# NOT RUN {
library(ggplot2)
ggplot(sleep_dt2, aes(t,y="Animal 1",fill=asleep)) +
                                   geom_tile() + scale_x_time()
# }
# NOT RUN {
####### DAM data, de facto beam cross classification ######
dt_one_animal <- toy_dam_data(seed=7)
sleep_dt <- sleep_dam_annotation(dt_one_animal)
# }
# NOT RUN {
library(ggplot2)
ggplot(sleep_dt, aes(t,y="Animal 1",fill=asleep)) +
                                   geom_tile() + scale_x_time()
# }