mousetrap (version 2.0.0)

mt_sample_entropy: Calculate sample entropy.

Description

Calculate sample entropy for each trajectory.

Usage

mt_sample_entropy(data, use = "tn_trajectories", save_as = "measures", dimension = "xpos", method = "pracma", lag = 3, r = NULL, verbose = FALSE, show_progress = NULL)

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).

use

a character string specifying which trajectory data should be used.

save_as

a character string specifying where the calculated measures should be stored.

dimension

a character string specifying the dimension based on which sample entropy should be calculated. By default (xpos), the x-positions are used.

method

a character string specifying the method used for calculating sample entropy (see Details).

lag

an integer passed on to the sample entropy function (see Details).

r

a numeric value passed on to the sample entropy function (see Details).

verbose

logical indicating whether function should report its progress.

show_progress

Deprecated. Please use verbose instead.

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(s).If not, an additional data.frame will be added.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 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 lag) across all recorded positions. Sample entropy is the negative natural logarithm of the conditional probability that this windows 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).

The specific formula for sample entropy depends on the function specified in method. Per default ("pracma"), the sample_entropy function from the pracma package is used. Alternatively ("hehman") the function by Hehman et al. (2015) is used. Finally, it is also possible to calculate sample_entropy values using both functions ("both").

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.

See Also

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",
  method="pracma", dimension="xpos", lag=3)