Calculate kinematics from position data

Calculates kinematic measurements including translational and rotational motion from position data. The function computes velocities, accelerations, and angular measurements from x-y coordinate time series data.

Usage

calculate_kinematics(data, by = NULL)

Arguments

data

A data frame containing at minimum:

• time (numeric): Time points of measurements

• x (numeric): X-coordinates

• y (numeric): Y-coordinates

by

Character vector specifying additional grouping variables (optional). If the input data frame is already grouped, those groups will be preserved and any additional groups specified in by will be added.

Value

A data frame containing the original data plus calculated kinematics:

• distance: Distance traveled between consecutive points

• v_translation: Translational velocity

• a_translation: Translational acceleration

• direction: Movement direction in radians

• rotation: Angular change between consecutive points

• v_rotation: Angular velocity

• a_rotation: Angular acceleration

Warning

Time points should be regularly sampled for accurate derivatives.

Examples

# Basic usage with just x-y coordinates
df <- data.frame(
  time = 1:10,
  x = runif(10),
  y = runif(10)
)
calculate_kinematics(df)
#>    time           x          y d_translation v_translation a_translation
#> 1     1 0.080750138 0.87460066            NA            NA            NA
#> 2     2 0.834333037 0.17494063     1.0283051     1.0283051            NA
#> 3     3 0.600760886 0.03424133     0.2726761     0.2726761   -0.75562901
#> 4     4 0.157208442 0.32038573     0.5278422     0.5278422    0.25516613
#> 5     5 0.007399441 0.40232824     0.1707551     0.1707551   -0.35708708
#> 6     6 0.466393497 0.19566983     0.5033719     0.5033719    0.33261675
#> 7     7 0.497777389 0.40353812     0.2102241     0.2102241   -0.29314777
#> 8     8 0.289767245 0.06366146     0.3984776     0.3984776    0.18825346
#> 9     9 0.732881987 0.38870131     0.5495467     0.5495467    0.15106915
#> 10   10 0.772521511 0.97554784     0.5881838     0.5881838    0.03863705
#>    direction d_rotation v_rotation  a_rotation
#> 1         NA         NA         NA          NA
#> 2  5.5348753         NA         NA          NA
#> 3  3.6837606 -1.8511147  1.8511147          NA
#> 4  2.5686559 -1.1151047  1.1151047 -0.73600997
#> 5  2.6410711  0.0724152 -0.0724152 -1.18751993
#> 6  5.8601301 -3.0641263  3.0641263  3.13654148
#> 7  1.4209484  1.8440035 -1.8440035 -4.90812981
#> 8  4.1631806  2.7422322 -2.7422322 -0.89822869
#> 9  0.6328795  2.7528842 -2.7528842 -0.01065199
#> 10 1.5033521  0.8704726 -0.8704726  1.88241160

# Using with grouping variables
df_grouped <- data.frame(
  time = rep(1:5, 2),
  x = runif(10),
  y = runif(10),
  individual = rep(c("A", "B"), each = 5)
)
calculate_kinematics(df_grouped, by = "individual")
#> # A tibble: 10 × 11
#> # Groups:   individual [2]
#>     time      x      y individual d_translation v_translation a_translation
#>    <int>  <dbl>  <dbl> <chr>              <dbl>         <dbl>         <dbl>
#>  1     1 0.290  0.0312 A                NA            NA             NA    
#>  2     2 0.678  0.226  A                 0.434         0.434         NA    
#>  3     3 0.735  0.301  A                 0.0944        0.0944        -0.340
#>  4     4 0.196  0.636  A                 0.635         0.635          0.541
#>  5     5 0.981  0.479  A                 0.800         0.800          0.165
#>  6     1 0.742  0.432  B                NA            NA             NA    
#>  7     2 0.0514 0.706  B                 0.743         0.743         NA    
#>  8     3 0.530  0.949  B                 0.537         0.537         -0.206
#>  9     4 0.696  0.180  B                 0.786         0.786          0.249
#> 10     5 0.689  0.217  B                 0.0373        0.0373        -0.749
#> # ℹ 4 more variables: direction <circular>, d_rotation <circular>,
#> #   v_rotation <circular>, a_rotation <circular>