Supported kinematics and statistics

[roaldarbol]

What should we include in our summary statistics? Should we always provide both central estimates and uncertainty estimates? Here's a list of potential ideas.

Also, I think it would make sense to have the ability to generate different summaries that require different information, something along the lines of:

• Kinematics (single individual, doesn't care about absolute position)
  • Criteria: Single individual, independent of external world
    • Kinematics for all keypoints individually
    • Kinematics relative to other keypoints
• Navigation
  • Criteria: Relative to external object
    • Types of external objects:
      • Arena/enclosure
        • Distance to walls
        • Distance to nearest corner
        • Zone (make some defaults for square and round arenas)
        • Heading relative to nearest wall
      • Object
        • Distance to object
        • Heading relative to object
• Social
  • Criteria: Relative to other individual
    • Keypoint-pairs of interests (one on self, one on other individual)
      • Distance between keypoints
    • Whole-individual
      • Relative speed
      • Relative heading
      • Minimum distance between any two keypoints

For position, pose and social, we need to think of a good way of making a general solution that handles relational information.

Kinematics

Translation

• distance Distance covered since last timepoint
• s_translation Instantaneous translational speed
• v_translation Instantaneous translational velocity (can be different from s_translation when you have a heading too)
• a_translation Instantaneous translational acceleration

Rotation

• heading Heading of animal (or vector between two keypoints)
• direction Direction of movement since last timepoint
• rotation Change of direction since last timepoint
• s_rotation Instantaneous rotational speed
• v_rotation Instantaneous rotational velocity
• a_rotation Instantaneous rotational acceleration

Summary statistics

See e.g. Joo et al (2019) for a wide range of possibilities. Also in the MARS paper https://elifesciences.org/articles/63720.

Statistical measures

I think it's worth considering whether these should all be possible to use. E.g. velocities will necessarily not follow a Gaussian, so median + a measure of dispersion (MAD or some range) will likely always be preferable.

• Central tendency (CT)
  • Mean
  • Median
  • Mode
• Dispersion (D)
  • SD
  • MAD
• Other
  • Total / sum

Movement metrics

Translation

• distance, total
• v_translation, CT + D
• a_translation, CT + D

Rotation

• rotation, total
• v_rotation, CT + D
• a_rotation, CT + D

Combinations

There are a bunch of measures that basically describe the path straightness, which have gathered interest in relation to search/movement patterns in particular (random walks, Levy walks, etc.). Different authors use different terms for them (path straightness, sinuosity, tortuosity), so I think it's best to pinpoint the first paper to describe each metric and use the author and year as their name.

• total_distance / shortest line between beginning and end
• shortest line between beginning and end / total_distance
• 1 - (shortest line between beginning and end / total_distance)
• CT + D of something that's calculated for each frame

Other?

Are there other things I've missed that would be of interest?
Also happy to think of relational summaries (e.g. distance between two individuals or an individual and an object, or time inside ROI, distance between keypoints), but maybe that would best be its own function.

[Gerrry27]

You could also add a column for the cumulative distance from the start of the test. To do that, you just need to "cumsum(df$distance)".