motion_detectors {sleepr}

Motion detector for Ethocope data

Description

Defines whether a single animal is moving according to:

Usage

max_velocity_detector(data, time_window_length,
  velocity_correction_coef = 0.003, masking_duration = 6)

max_velocity_detector_legacy(data, velocity_threshold = 0.006)

virtual_beam_cross_detector(data, time_window_length)

Arguments

data

data.table::data.table containing behavioural variables of a single animal (no id). It must have the columns xy_dist_log10x1000(for computing subpixel velocity), x(beam cross), t and has_interacted (whether a stimulus was delivered).

time_window_length

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

velocity_correction_coef

an empirical coefficient to correct velocity with respect to variable framerate.

masking_duration

number of seconds during which any movement is ignored (velocity is set to 0) after a stimulus is delivered (a.k.a. interaction).

velocity_threshold

uncorrected velocity above which an animal is classified as ‘moving’ (for the legacy version).

Details

• Validated and corrected subpixel velocity (max_velocity_detector), the most rigorous

• Uncorrected subpixel velocity (max_velocity_detector_legacy)

• Crossing a virtual beam in the middle of the region of interest (virtual_beam_cross_detector)

max_velocity_detector is the default movement classification for real-time ethoscope experiments. It is benchmarked against human-generated ground truth.

These functions are rarely called directly, but typically used is in the context of sleep_annotation.

Value

an object of the same type as data (i.e. data.table::data.table or behavr::behavr) with additional columns:

• moving Logical, TRUE iff. motion was detected.

• beam_crosses The number of beam crosses (when the animal crosses x = 0.5 – that is the midpoint of the region of interest) within the time window

• max_velocity The maximal velocity within the time window. The resulting data is sampled at a period equals to time_window_length.

See Also

• sleep_annotation – which requieres a motion detector