<!DOCTYPE html>
<!-- Generated by pkgdown: do not edit by hand --><html lang="en"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><meta charset="utf-8"><meta http-equiv="X-UA-Compatible" content="IE=edge"><meta name="viewport" content="width=device-width, initial-scale=1.0"><title>Calculate mouse-tracking measures. — mt_measures • mousetrap</title><!-- jquery --><script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/3.4.1/jquery.min.js" integrity="sha256-CSXorXvZcTkaix6Yvo6HppcZGetbYMGWSFlBw8HfCJo=" crossorigin="anonymous"></script><!-- Bootstrap --><link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/3.4.1/css/bootstrap.min.css" integrity="sha256-bZLfwXAP04zRMK2BjiO8iu9pf4FbLqX6zitd+tIvLhE=" crossorigin="anonymous"><script src="https://cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/3.4.1/js/bootstrap.min.js" integrity="sha256-nuL8/2cJ5NDSSwnKD8VqreErSWHtnEP9E7AySL+1ev4=" crossorigin="anonymous"></script><!-- bootstrap-toc --><link rel="stylesheet" href="../bootstrap-toc.css"><script src="../bootstrap-toc.js"></script><!-- Font Awesome icons --><link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.12.1/css/all.min.css" integrity="sha256-mmgLkCYLUQbXn0B1SRqzHar6dCnv9oZFPEC1g1cwlkk=" crossorigin="anonymous"><link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.12.1/css/v4-shims.min.css" integrity="sha256-wZjR52fzng1pJHwx4aV2AO3yyTOXrcDW7jBpJtTwVxw=" crossorigin="anonymous"><!-- clipboard.js --><script src="https://cdnjs.cloudflare.com/ajax/libs/clipboard.js/2.0.6/clipboard.min.js" integrity="sha256-inc5kl9MA1hkeYUt+EC3BhlIgyp/2jDIyBLS6k3UxPI=" crossorigin="anonymous"></script><!-- headroom.js --><script src="https://cdnjs.cloudflare.com/ajax/libs/headroom/0.11.0/headroom.min.js" integrity="sha256-AsUX4SJE1+yuDu5+mAVzJbuYNPHj/WroHuZ8Ir/CkE0=" crossorigin="anonymous"></script><script src="https://cdnjs.cloudflare.com/ajax/libs/headroom/0.11.0/jQuery.headroom.min.js" integrity="sha256-ZX/yNShbjqsohH1k95liqY9Gd8uOiE1S4vZc+9KQ1K4=" crossorigin="anonymous"></script><!-- pkgdown --><link href="../pkgdown.css" rel="stylesheet"><script src="../pkgdown.js"></script><meta property="og:title" content="Calculate mouse-tracking measures. — mt_measures"><meta property="og:description" content="Calculate a number of mouse-tracking measures for each trajectory, such as
minima, maxima, and flips for each dimension, and different measures for
curvature (e.g., MAD, AD, and AUC). Note that some
measures are only returned if distance, velocity and acceleration are
calculated using mt_derivatives before running mt_measures.
More information on the different measures can be found in the Details and
Values sections."><!-- mathjax --><script src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.5/MathJax.js" integrity="sha256-nvJJv9wWKEm88qvoQl9ekL2J+k/RWIsaSScxxlsrv8k=" crossorigin="anonymous"></script><script src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.5/config/TeX-AMS-MML_HTMLorMML.js" integrity="sha256-84DKXVJXs0/F8OTMzX4UR909+jtl4G7SPypPavF+GfA=" crossorigin="anonymous"></script><!--[if lt IE 9]>
<script src="https://oss.maxcdn.com/html5shiv/3.7.3/html5shiv.min.js"></script>
<script src="https://oss.maxcdn.com/respond/1.4.2/respond.min.js"></script>
<![endif]--></head><body data-spy="scroll" data-target="#toc">
    

    <div class="container template-reference-topic">
      <header><div class="navbar navbar-default navbar-fixed-top" role="navigation">
  <div class="container">
    <div class="navbar-header">
      <button type="button" class="navbar-toggle collapsed" data-toggle="collapse" data-target="#navbar" aria-expanded="false">
        <span class="sr-only">Toggle navigation</span>
        <span class="icon-bar"></span>
        <span class="icon-bar"></span>
        <span class="icon-bar"></span>
      </button>
      <span class="navbar-brand">
        <a class="navbar-link" href="../index.html">mousetrap</a>
        <span class="version label label-default" data-toggle="tooltip" data-placement="bottom" title="">3.2.3</span>
      </span>
    </div>

    <div id="navbar" class="navbar-collapse collapse">
      <ul class="nav navbar-nav"><li>
  <a href="../reference/mousetrap-package.html">Overview</a>
</li>
<li>
  <a href="../reference/index.html">Reference</a>
</li>
<li>
  <a href="../news/index.html">News</a>
</li>
      </ul><ul class="nav navbar-nav navbar-right"><li>
  <a href="https://github.com/pascalkieslich/mousetrap" class="external-link">
    <span class="fa fa-github fa-lg"></span>
     
  </a>
</li>
      </ul></div><!--/.nav-collapse -->
  </div><!--/.container -->
</div><!--/.navbar -->

      

      </header><div class="row">
  <div class="col-md-9 contents">
    <div class="page-header">
    <h1>Calculate mouse-tracking measures.</h1>
    <small class="dont-index">Source: <a href="https://github.com/pascalkieslich/mousetrap/blob/HEAD/R/measures.R" class="external-link"><code>R/measures.R</code></a></small>
    <div class="hidden name"><code>mt_measures.Rd</code></div>
    </div>

    <div class="ref-description">
    <p>Calculate a number of mouse-tracking measures for each trajectory, such as
minima, maxima, and flips for each dimension, and different measures for
curvature (e.g., <code>MAD</code>, <code>AD</code>, and <code>AUC</code>). Note that some
measures are only returned if distance, velocity and acceleration are
calculated using <a href="mt_derivatives.html">mt_derivatives</a> before running <code>mt_measures</code>.
More information on the different measures can be found in the Details and
Values sections.</p>
    </div>

    <div id="ref-usage">
    <div class="sourceCode"><pre class="sourceCode r"><code><span><span class="fu">mt_measures</span><span class="op">(</span></span>
<span>  <span class="va">data</span>,</span>
<span>  use <span class="op">=</span> <span class="st">"trajectories"</span>,</span>
<span>  save_as <span class="op">=</span> <span class="st">"measures"</span>,</span>
<span>  dimensions <span class="op">=</span> <span class="fu"><a href="https://rdrr.io/r/base/c.html" class="external-link">c</a></span><span class="op">(</span><span class="st">"xpos"</span>, <span class="st">"ypos"</span><span class="op">)</span>,</span>
<span>  timestamps <span class="op">=</span> <span class="st">"timestamps"</span>,</span>
<span>  flip_threshold <span class="op">=</span> <span class="fl">0</span>,</span>
<span>  hover_threshold <span class="op">=</span> <span class="cn">NULL</span>,</span>
<span>  hover_incl_initial <span class="op">=</span> <span class="cn">TRUE</span>,</span>
<span>  initiation_threshold <span class="op">=</span> <span class="fl">0</span>,</span>
<span>  verbose <span class="op">=</span> <span class="cn">FALSE</span></span>
<span><span class="op">)</span></span></code></pre></div>
    </div>

    <div id="arguments">
    <h2>Arguments</h2>
    <dl><dt>data</dt>
<dd><p>a mousetrap data object created using one of the mt_import
functions (see <a href="mt_example.html">mt_example</a> for details). Alternatively, a trajectory
array can be provided directly (in this case <code>use</code> will be ignored).</p></dd>


<dt>use</dt>
<dd><p>a character string specifying which trajectory data should be
used.</p></dd>


<dt>save_as</dt>
<dd><p>a character string specifying where the calculated measures
should be stored.</p></dd>


<dt>dimensions</dt>
<dd><p>a character vector specifying the two dimensions in the
trajectory array that contain the mouse positions. Usually (and by
default), the first value in the vector corresponds to the x-positions
(<code>xpos</code>) and the second to the y-positions (<code>ypos</code>).</p></dd>


<dt>timestamps</dt>
<dd><p>a character string specifying the trajectory dimension
containing the timestamps.</p></dd>


<dt>flip_threshold</dt>
<dd><p>a numeric value specifying the distance that needs to
be exceeded in one direction so that a change in direction counts as a
flip. If several thresholds are specified, flips will be returned in
separate variables for each threshold value (the variable name will be
suffixed with the threshold value).</p></dd>


<dt>hover_threshold</dt>
<dd><p>an optional numeric value. If specified, <code>hovers</code>
(and <code>hover_time</code>)  will be calculated as the number (and total time)
of periods without movement in a trial (whose duration exceeds the value
specified in <code>hover_threshold</code>). If several thresholds are specified,
hovers and hover_time will be returned in separate variables for each
threshold value (the variable name will be suffixed with the threshold
value).</p></dd>


<dt>hover_incl_initial</dt>
<dd><p>logical indicating if the calculation of hovers
should include a potential initial phase in the trial without mouse
movements (this initial phase is included by default).</p></dd>


<dt>initiation_threshold</dt>
<dd><p>a numeric value specifying the distance from the
start point of the trajectory that needs to be exceeded for calculating the
initiation time. By default, it is 0, meaning that any movement counts as
movement initiation.</p></dd>


<dt>verbose</dt>
<dd><p>logical indicating whether function should report its
progress.</p></dd>

</dl></div>
    <div id="value">
    <h2>Value</h2>
    

<p>A mousetrap data object (see <a href="mt_example.html">mt_example</a>) where an additional
<a href="https://rdrr.io/r/base/data.frame.html" class="external-link">data.frame</a> has been added (by default called "measures") containing
the per-trial mouse-tracking measures. Each row in the data.frame
corresponds to one trajectory (the corresponding trajectory is identified
via the rownames and, additionally, in the column "mt_id"). Each column in
the data.frame corresponds to one of the measures. If a trajectory array
was provided directly as <code>data</code>, only the measures data.frame will be
returned.</p>


<p>The following measures are computed for each trajectory (the labels
relating to x- and y-positions will be adapted depending on the values
specified in <code>dimensions</code>). Please note that additional information is
provided in the Details section.</p>
<dl><dt>mt_id</dt>
<dd><p>Trial ID (can be used for merging measures data.frame with
other trial-level data)</p></dd>

<dt>xpos_max</dt>
<dd><p>Maximum x-position</p></dd>

<dt>xpos_min</dt>
<dd><p>Minimum x-position</p></dd>

<dt>ypos_max</dt>
<dd><p>Maximum y-position</p></dd>

<dt>ypos_min</dt>
<dd><p>Minimum y-position</p></dd>

<dt>MAD</dt>
<dd><p>Signed Maximum absolute deviation from the direct path
connecting start and end point of the trajectory (straight line).
If the <code>MAD</code> occurs above the direct path, this is denoted by
a positive value; if it occurs below, by a negative value.</p></dd>

<dt>MAD_time</dt>
<dd><p>Time at which the maximum absolute deviation was reached
first</p></dd>

<dt>MD_above</dt>
<dd><p>Maximum deviation above the direct path</p></dd>

<dt>MD_above_time</dt>
<dd><p>Time at which the maximum deviation above was reached
first</p></dd>

<dt>MD_below</dt>
<dd><p>Maximum deviation below the direct path</p></dd>

<dt>MD_below_time</dt>
<dd><p>Time at which the maximum deviation below was reached
first</p></dd>

<dt>AD</dt>
<dd><p>Average deviation from direct path</p></dd>

<dt>AUC</dt>
<dd><p>Area under curve, the geometric area between the actual
trajectory and the direct path where areas below the direct path have been
subtracted</p></dd>

<dt>xpos_flips</dt>
<dd><p>Number of directional changes along x-axis (exceeding the
distance specified in <code>flip_threshold</code>)</p></dd>

<dt>ypos_flips</dt>
<dd><p>Number of directional changes along y-axis (exceeding the
distance specified in <code>flip_threshold</code>)</p></dd>

<dt>xpos_reversals</dt>
<dd><p>Number of crossings of the y-axis</p></dd>

<dt>ypos_reversals</dt>
<dd><p>Number of crossings of the x-axis</p></dd>

<dt>RT</dt>
<dd><p>Response time, time at which tracking stopped</p></dd>

<dt>initiation_time</dt>
<dd><p>Time at which first mouse movement was initiated</p></dd>

<dt>idle_time</dt>
<dd><p>Total time without mouse movement across the entirety of
the trial</p></dd>

<dt>hover_time</dt>
<dd><p>Total time of all periods without movement in a trial
(whose duration exceeds the value specified in <code>hover_threshold</code>)</p></dd>

<dt>hovers</dt>
<dd><p>Number of periods without movement in a trial (whose duration
exceeds the value specified in <code>hover_threshold</code>)</p></dd>

<dt>total_dist</dt>
<dd><p>Total distance covered by the trajectory</p></dd>

<dt>vel_max</dt>
<dd><p>Maximum velocity</p></dd>

<dt>vel_max_time</dt>
<dd><p>Time at which maximum velocity occurred first</p></dd>

<dt>vel_min</dt>
<dd><p>Minimum velocity</p></dd>

<dt>vel_min_time</dt>
<dd><p>Time at which minimum velocity occurred first</p></dd>

<dt>acc_max</dt>
<dd><p>Maximum acceleration</p></dd>

<dt>acc_max_time</dt>
<dd><p>Time at which maximum acceleration occurred first</p></dd>

<dt>acc_min</dt>
<dd><p>Minimum acceleration</p></dd>

<dt>acc_min_time</dt>
<dd><p>Time at which minimum acceleration occurred first</p></dd>

</dl></div>
    <div id="details">
    <h2>Details</h2>
    <p>Note that some measures are only returned if distance, velocity and
acceleration are calculated using <a href="mt_derivatives.html">mt_derivatives</a> before
running <code>mt_measures</code>. Besides, the meaning of these measures
depends on the values of the arguments in <a href="mt_derivatives.html">mt_derivatives</a>.</p>
<p>If the deviations from the idealized response trajectory have been calculated
using <a href="mt_deviations.html">mt_deviations</a> before running
<code>mt_measures</code>, the corresponding data in the trajectory array
will be used. If not, <code>mt_measures</code> will calculate these
deviations automatically.</p>
<p>The calculation of most measures can be deduced directly from their
definition (see Value). For several more complex measures, a few details are
provided in the following.</p>
<p>The signed <strong>maximum absolute deviation</strong> (<code>MAD</code>) is the maximum
perpendicular deviation from the straight path connecting start and end point
of the trajectory (e.g., Freeman &amp; Ambady, 2010). If the <code>MAD</code> occurs
above the direct path, this is denoted by a positive value. If it occurs
below the direct path, this is denoted by a negative value. This assumes that
the complete movement in the trial was from bottom to top (i.e., the end
point has a higher y-position than the start point). In case the movement was
from top to bottom, <code>mt_measures</code> automatically flips the signs. Both
<code>MD_above</code> and  <code>MD_below</code> are also reported separately.</p>
<p>The <strong>average deviation</strong> (<code>AD</code>) is the average of all deviations
across the trial. Note that <code>AD</code> ignores the timestamps when calculating
this average. This implicitly assumes that the time passed between each
recording of the mouse is the same within each individual trajectory. If the
<code>AD</code> is calculated using raw data that were obtained with an
approximately constant logging resolution (sampling rate), this assumption is
usually justified (<a href="mt_check_resolution.html">mt_check_resolution</a> can be used to check this).
Alternatively, the <code>AD</code> can be calculated based on time-normalized
trajectories; these can be computed using <a href="mt_time_normalize.html">mt_time_normalize</a> which
creates equidistant time steps within each trajectory.</p>
<p>The <code>AUC</code> represents the <strong>area under curve</strong>, i.e., the geometric
area between the actual trajectory and the direct path. Areas above the
direct path are added and areas below are subtracted. The <code>AUC</code> is
calculated using the <a href="https://rdrr.io/pkg/pracma/man/polyarea.html" class="external-link">polyarea</a> function from the pracma
package.</p>
<p>Note that all <strong>time</strong> related measures (except <code>idle_time</code> and
<code>hover_time</code>) are reported using the timestamp metric as present in the
data. To interpret the timestamp values as time since tracking start, the
assumption has to be made that for each trajectory the tracking started at
timestamp 0 and that all timestamps indicate the time passed since tracking
start. Therefore, all timestamps should be reset during data import by
subtracting the value of the first timestamp from all timestamps within a
trial (assuming that the first timestamp corresponds to the time when
tracking started). Timestamps are reset by default when importing the data
using one of the mt_import functions (e.g., <a href="mt_import_mousetrap.html">mt_import_mousetrap</a>). Note
that <code>initiation_time</code> is defined as the last timestamp before the
<code>initiation_threshold</code> was crossed.</p>
    </div>
    <div id="references">
    <h2>References</h2>
    <p>Kieslich, P. J., Henninger, F., Wulff, D. U., Haslbeck, J. M. B.,
&amp; Schulte-Mecklenbeck, M. (2019). Mouse-tracking: A practical guide to
implementation and analysis. In M. Schulte-Mecklenbeck, A. Kühberger, &amp; J.
G. Johnson (Eds.), <em>A Handbook of Process Tracing Methods</em> (pp.
111-130). New York, NY: Routledge.</p>
<p>Freeman, J. B., &amp; Ambady, N. (2010). MouseTracker: Software for studying
real-time mental processing using a computer mouse-tracking method.
<em>Behavior Research Methods, 42</em>(1), 226-241.</p>
    </div>
    <div id="see-also">
    <h2>See also</h2>
    <div class="dont-index"><p><a href="mt_sample_entropy.html">mt_sample_entropy</a> for calculating sample entropy.</p>
<p><a href="mt_standardize.html">mt_standardize</a> for standardizing the measures per subject.</p>
<p><a href="mt_check_bimodality.html">mt_check_bimodality</a> for checking bimodality of the measures using
different methods.</p>
<p><a href="mt_aggregate.html">mt_aggregate</a> and <a href="mt_aggregate_per_subject.html">mt_aggregate_per_subject</a> for aggregating the
measures.</p>
<p><a href="https://dplyr.tidyverse.org/reference/mutate-joins.html" class="external-link">inner_join</a> for merging data using the <code>dplyr</code> package.</p></div>
    </div>
    <div id="author">
    <h2>Author</h2>
    <p>Pascal J. Kieslich</p>
<p>Felix Henninger</p>
    </div>

    <div id="ref-examples">
    <h2>Examples</h2>
    <div class="sourceCode"><pre class="sourceCode r"><code><span class="r-in"><span><span class="va">mt_example</span> <span class="op">&lt;-</span> <span class="fu"><a href="mt_derivatives.html">mt_derivatives</a></span><span class="op">(</span><span class="va">mt_example</span><span class="op">)</span></span></span>
<span class="r-in"><span><span class="va">mt_example</span> <span class="op">&lt;-</span> <span class="fu"><a href="mt_deviations.html">mt_deviations</a></span><span class="op">(</span><span class="va">mt_example</span><span class="op">)</span></span></span>
<span class="r-in"><span><span class="va">mt_example</span> <span class="op">&lt;-</span> <span class="fu">mt_measures</span><span class="op">(</span><span class="va">mt_example</span><span class="op">)</span></span></span>
<span class="r-in"><span></span></span>
<span class="r-in"><span><span class="co"># Merge measures with trial data</span></span></span>
<span class="r-in"><span><span class="va">mt_example_results</span> <span class="op">&lt;-</span> <span class="fu">dplyr</span><span class="fu">::</span><span class="fu"><a href="https://dplyr.tidyverse.org/reference/mutate-joins.html" class="external-link">inner_join</a></span><span class="op">(</span></span></span>
<span class="r-in"><span>  <span class="va">mt_example</span><span class="op">$</span><span class="va">data</span>, <span class="va">mt_example</span><span class="op">$</span><span class="va">measures</span>,</span></span>
<span class="r-in"><span>  by<span class="op">=</span><span class="st">"mt_id"</span><span class="op">)</span></span></span>
<span class="r-in"><span>  </span></span>
</code></pre></div>
    </div>
  </div>
  <div class="col-md-3 hidden-xs hidden-sm" id="pkgdown-sidebar">
    <nav id="toc" data-toggle="toc" class="sticky-top"><h2 data-toc-skip>Contents</h2>
    </nav></div>
</div>


      <footer><div class="copyright">
  <p></p><p>Developed by Pascal J. Kieslich, Dirk U. Wulff, Felix Henninger, Jonas M. B. Haslbeck.</p>
</div>

<div class="pkgdown">
  <p></p><p>Site built with <a href="https://pkgdown.r-lib.org/" class="external-link">pkgdown</a> 2.0.7.</p>
</div>

      </footer></div>

  


  

  </body></html>

