Define Events of Collective Motion

This function adds a keep TRUE/FALSE column in the input dataframe based on whether the average speed and polarization of the group is larger than the input thresholds, reflecting whether a timestep is considered part of a collective event or not.

Usage

define_events(df, sp_lim, pol_lim, step2time, noise_thresh = 0)

Arguments

df

A dataframe with a pol_av and speed_av columns for polarization and speed, respectively (as calculated by the group_metrics_per_set function).

sp_lim

The (lower) threshold of speed to use for defining which timesteps are part of an events of collective motion. In other words, during an event the group should have an average speed of at least sp_lim.

pol_lim

The (lower) threshold of polarization to use for defining which timesteps are part of an events of collective motion. In other words, during an event the group's polarization should be at least pol_lim.

step2time

Sampling frequency, i.e. the relation between time steps (rows) in the input dataframe and real time (in seconds).

noise_thresh

The limit of time difference between consecutive events to be considered the same event. The default value is 0 (no event merging).

Value

the dataframe that was given as input with an extra keep column. The function also prints the number and duration of the defined events.

See also

pick_threshold, group_metrics_per_set

Author

Marina Papadopoulou m.papadopoulou.rug@gmail.com

Examples

data <- data.frame(
set = rep('1', 50),
pol_av = rnorm(50, mean = 0.5, sd = 0.2),
speed_av = rnorm(50, mean = 5)
)
data <- define_events(data, sp_lim = 5, pol_lim = 0.4, step2time = 1)
#> Given thresholds return a total of:
#> 8 events, over 0.166666666666667 min.