Calculate sample entropy for each trajectory as a measure of the complexity of movements along one specific dimension.

mt_sample_entropy(
data,
use = "tn_trajectories",
save_as = "measures",
dimension = "xpos",
m = 3,
r = NULL,
use_diff = TRUE,
verbose = FALSE
)

## Arguments

data a mousetrap data object created using one of the mt_import functions (see mt_example for details). Alternatively, a trajectory array can be provided directly (in this case use will be ignored). a character string specifying which trajectory data should be used. a character string specifying where the calculated measures should be stored. a character string specifying the dimension based on which sample entropy should be calculated. By default (xpos), the x-positions are used. an integer passed on to the sample entropy function (see Details). a numeric value passed on to the sample entropy function (see Details). logical indicating if the differences of the dimension values should be computed before calculating sample entropy (which is done by default, see Details). logical indicating whether function should report its progress.

## Value

A mousetrap data object (see mt_example).

If a data.frame with label specified in save_as (by default "measures") already exists, the sample entropy values are added as additional column.

If a trajectory array was provided directly as data, only the data.frame will be returned.

## Details

mt_sample_entropy calculates the sample entropy for each trajectory as a measure of its complexity. Hehman et al (2015) provide details on how sample entropy can be calculated and applied in mouse-tracking (following Dale et al., 2007). They apply the sample entropy measure to the differences between adjacent x-positions (which is also the default here, as in a standard mouse-tracking task with buttons located in the top-left and right corners mostly the movements in the horizontal direction are of interest). Besides, they recommend using the time-normalized trajectories so all trajectories have the same length.

Sample entropy is computed by comparing windows of a fixed size (specified using m) across all recorded positions. Sample entropy is the negative natural logarithm of the conditional probability that this window remains similar across the trial (Hehman et al., 2015). A window is considered to be similar to another if their distance is smaller than a specified tolerance value (which can be specified using r). Hehman et al. (2015) use a tolerance value of 0.2 * standard deviation of all differences between adjacent x-positions in the dataset (which is the default implemented here).

## References

Dale, R., Kehoe, C., & Spivey, M. J. (2007). Graded motor responses in the time course of categorizing atypical exemplars. Memory & Cognition, 35(1), 15-28.

Hehman, E., Stolier, R. M., & Freeman, J. B. (2015). Advanced mouse-tracking analytic techniques for enhancing psychological science. Group Processes & Intergroup Relations, 18(3), 384-401.

mt_measures for calculating other mouse-tracking measures.

## Examples

# Calculate sample entropy based on time-normalized
# trajectories and merge results with other meausres
# derived from raw trajectories
mt_example <- mt_measures(mt_example)
mt_example <- mt_time_normalize(mt_example,
save_as="tn_trajectories", nsteps=101)
mt_example <- mt_sample_entropy(mt_example,
use="tn_trajectories", save_as="measures",
dimension="xpos", m=3)