Skip to contents

Calculate kinematics from position data

Source: R/calculate_kinematics.R
calculate_kinematics.Rd

[Experimental]

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.49777739 0.40353812            NA            NA            NA
#> 2     2 0.28976724 0.06366146     0.3984776     0.3984776            NA
#> 3     3 0.73288199 0.38870131     0.5495467     0.5495467    0.15106915
#> 4     4 0.77252151 0.97554784     0.5881838     0.5881838    0.03863705
#> 5     5 0.87460066 0.28989230     0.6932126     0.6932126    0.10502882
#> 6     6 0.17494063 0.67838043     0.8002794     0.8002794    0.10706687
#> 7     7 0.03424133 0.73531960     0.1517839     0.1517839   -0.64849552
#> 8     8 0.32038573 0.19595673     0.6105661     0.6105661    0.45878214
#> 9     9 0.40232824 0.98053967     0.7888504     0.7888504    0.17828435
#> 10   10 0.19566983 0.74152153     0.3159705     0.3159705   -0.47287989
#>    direction d_rotation v_rotation a_rotation
#> 1         NA         NA         NA         NA
#> 2  4.1631806         NA         NA         NA
#> 3  0.6328795  2.7528842 -2.7528842         NA
#> 4  1.5033521  0.8704726 -0.8704726  1.8824116
#> 5  4.8601816 -2.9263558  2.9263558  3.7968284
#> 6  2.6347256 -2.2254560  2.2254560 -0.7008998
#> 7  2.7570523  0.1223267 -0.1223267 -2.3477827
#> 8  5.2001558  2.4431034 -2.4431034 -2.3207767
#> 9  1.4667328  2.5497623 -2.5497623 -0.1066589
#> 10 3.9994718  2.5327390 -2.5327390  0.0170233

# 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.0514 0.706  A                NA            NA            NA     
#>  2     2 0.530  0.949  A                 0.537         0.537        NA     
#>  3     3 0.696  0.180  A                 0.786         0.786         0.249 
#>  4     4 0.689  0.217  A                 0.0373        0.0373       -0.749 
#>  5     5 0.0312 0.680  A                 0.804         0.804         0.767 
#>  6     1 0.226  0.499  B                NA            NA            NA     
#>  7     2 0.301  0.642  B                 0.161         0.161        NA     
#>  8     3 0.636  0.660  B                 0.336         0.336         0.175 
#>  9     4 0.479  0.0960 B                 0.586         0.586         0.250 
#> 10     5 0.432  0.766  B                 0.671         0.671         0.0854
#> # ℹ 4 more variables: direction <circular>, d_rotation <circular>,
#> #   v_rotation <circular>, a_rotation <circular>