<!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 distance, velocity, and acceleration. — mt_derivatives • 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 distance, velocity, and acceleration. — mt_derivatives"><meta property="og:description" content="Calculate distance traveled, velocity, and acceleration for each logged
position. Distance is calculated as the Euclidean distance between successive
coordinates, and velocity as distance covered per time interval. The
acceleration denotes the difference in absolute velocity, again normalized
per time."><!-- 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 distance, velocity, and acceleration.</h1>
    <small class="dont-index">Source: <a href="https://github.com/pascalkieslich/mousetrap/blob/HEAD/R/derivatives.R" class="external-link"><code>R/derivatives.R</code></a></small>
    <div class="hidden name"><code>mt_derivatives.Rd</code></div>
    </div>

    <div class="ref-description">
    <p>Calculate distance traveled, velocity, and acceleration for each logged
position. Distance is calculated as the Euclidean distance between successive
coordinates, and velocity as distance covered per time interval. The
acceleration denotes the difference in absolute velocity, again normalized
per time.</p>
    </div>

    <div id="ref-usage">
    <div class="sourceCode"><pre class="sourceCode r"><code><span><span class="fu">mt_derivatives</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="va">use</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>  prefix <span class="op">=</span> <span class="st">""</span>,</span>
<span>  absolute <span class="op">=</span> <span class="cn">FALSE</span>,</span>
<span>  return_delta_time <span class="op">=</span> <span class="cn">FALSE</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 resulting trajectory
data should be stored.</p></dd>


<dt>dimensions</dt>
<dd><p>a character vector specifying across which dimension(s)
distances, velocity, and acceleration are calculated. By default
(<code>c("xpos","ypos")</code>), they are calculated across both x and y
dimensions. Alternatively, only one dimension can be specified, e.g.,
<code>"xpos"</code> or <code>"ypos"</code>.</p></dd>


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


<dt>prefix</dt>
<dd><p>an optional character string that is added as a prefix to the
to be created new trajectory dimensions.</p></dd>


<dt>absolute</dt>
<dd><p>logical indicating if absolute values for distances and
velocities should be reported. Only relevant if a single dimension is
specified in <code>dimensions</code> (see Details).</p></dd>


<dt>return_delta_time</dt>
<dd><p>logical indicating if the timestamp differences
should be returned as well (as "delta_time").</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>) with Euclidian
distance, velocity, and acceleration added as additional variables to the
trajectory array (called <code>dist</code>, <code>vel</code>, and  <code>acc</code>, if no
prefix was specified). If the trajectory array was provided directly as
<code>data</code>, only the trajectory array will be returned.</p>
    </div>
    <div id="details">
    <h2>Details</h2>
    <p>Distances, velocities and acceleration are computed as follows:</p>
<p>The first entry in each respective vector is always zero. Each subsequent
entry thus represents the Euclidean distance traveled since the previous
recorded set of coordinates and the velocity with which the movement between
both samples took place. Thus, both distance and velocity represent the
intervening period between the previous sample and the one with which the
numeric value is saved.</p>
<p>The acceleration, by contrast, denotes the change in absolute velocity
between two adjacent periods. Because of this, it is shifted forward to best
match the actual time point at which the acceleration was measured. Because
there will always be one less value computed for acceleration than for
velocity, the final value in the acceleration vector has been padded with an
NA.</p>
<p>If the distance is calculated across both horizontal and vertical (x and y)
dimensions, distance and velocity is always positive (or 0). If only one
dimension is used, by default (<code>absolute=FALSE</code>), increases in x (or y)
values result in positive distances and velocity values, decreases in
negative distances and velocity values. If <code>absolute=TRUE</code>, absolute
values for distance and velocity are reported.</p>
    </div>
    <div id="see-also">
    <h2>See also</h2>
    <div class="dont-index"><p><a href="mt_average.html">mt_average</a> for averaging trajectories across constant time
intervals.</p>
<p><a href="mt_measures.html">mt_measures</a> for calculating per-trial mouse-tracking
measures.</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="co"># Calculate derivatives looking at movement</span></span></span>
<span class="r-in"><span><span class="co"># across both dimensions</span></span></span>
<span class="r-in"><span><span class="va">mt_example</span> <span class="op">&lt;-</span> <span class="fu">mt_derivatives</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"># Calculate derivatives only looking at movement along x dimension</span></span></span>
<span class="r-in"><span><span class="co"># reporting absolute values for distance and velocity</span></span></span>
<span class="r-in"><span><span class="va">mt_example</span> <span class="op">&lt;-</span> <span class="fu">mt_derivatives</span><span class="op">(</span><span class="va">mt_example</span>,</span></span>
<span class="r-in"><span>  dimensions<span class="op">=</span><span class="st">"xpos"</span>, absolute<span class="op">=</span><span class="cn">TRUE</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>

