| Title: | An R toolbox for analysing animal movement across space and time |
|---|---|
| Description: | An R toolbox for analysing animal movement across space and time. |
| Authors: | Mikkel Roald-Arbøl [aut, cre] |
| Maintainer: | Mikkel Roald-Arbøl <[email protected]> |
| License: | MIT + file LICENSE |
| Version: | 0.4.1 |
| Built: | 2024-11-13 13:27:46 UTC |
| Source: | https://github.com/roaldarbol/animovement |
![[Experimental]](data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHhtbG5zOnhsaW5rPSJodHRwOi8vd3d3LnczLm9yZy8xOTk5L3hsaW5rIiB3aWR0aD0iMTM4IiBoZWlnaHQ9IjIwIiByb2xlPSJpbWciIGFyaWEtbGFiZWw9ImxpZmVjeWNsZTogZXhwZXJpbWVudGFsIj4KICAgIDx0aXRsZT5saWZlY3ljbGU6IGV4cGVyaW1lbnRhbDwvdGl0bGU+CiAgICA8bGluZWFyR3JhZGllbnQgaWQ9InMiIHgyPSIwIiB5Mj0iMTAwJSI+CiAgICAgICAgPHN0b3Agb2Zmc2V0PSIwIiBzdG9wLWNvbG9yPSIjYmJiIiBzdG9wLW9wYWNpdHk9Ii4xIiAvPgogICAgICAgIDxzdG9wIG9mZnNldD0iMSIgc3RvcC1vcGFjaXR5PSIuMSIgLz4KICAgIDwvbGluZWFyR3JhZGllbnQ+CiAgICA8Y2xpcFBhdGggaWQ9InIiPgogICAgICAgIDxyZWN0IHdpZHRoPSIxMzgiIGhlaWdodD0iMjAiIHJ4PSIzIiBmaWxsPSIjZmZmIiAvPgogICAgPC9jbGlwUGF0aD4KICAgIDxnIGNsaXAtcGF0aD0idXJsKCNyKSI+CiAgICAgICAgPHJlY3Qgd2lkdGg9IjU1IiBoZWlnaHQ9IjIwIiBmaWxsPSIjNTU1IiAvPgogICAgICAgIDxyZWN0IHg9IjU1IiB3aWR0aD0iODMiIGhlaWdodD0iMjAiIGZpbGw9IiNmZTdkMzciIC8+CiAgICAgICAgPHJlY3Qgd2lkdGg9IjEzOCIgaGVpZ2h0PSIyMCIgZmlsbD0idXJsKCNzKSIgLz4KICAgIDwvZz4KICAgIDxnIGZpbGw9IiNmZmYiIHRleHQtYW5jaG9yPSJtaWRkbGUiIGZvbnQtZmFtaWx5PSJWZXJkYW5hLEdlbmV2YSxEZWphVnUgU2FucyxzYW5zLXNlcmlmIiB0ZXh0LXJlbmRlcmluZz0iZ2VvbWV0cmljUHJlY2lzaW9uIiBmb250LXNpemU9IjExMCI+CiAgICAgICAgPHRleHQgYXJpYS1oaWRkZW49InRydWUiIHg9IjI4NSIgeT0iMTUwIiBmaWxsPSIjMDEwMTAxIiBmaWxsLW9wYWNpdHk9Ii4zIiB0cmFuc2Zvcm09InNjYWxlKC4xKSIgdGV4dExlbmd0aD0iNDUwIj5saWZlY3ljbGU8L3RleHQ+CiAgICAgICAgPHRleHQgeD0iMjg1IiB5PSIxNDAiIHRyYW5zZm9ybT0ic2NhbGUoLjEpIiBmaWxsPSIjZmZmIiB0ZXh0TGVuZ3RoPSI0NTAiPmxpZmVjeWNsZTwvdGV4dD4KICAgICAgICA8dGV4dCBhcmlhLWhpZGRlbj0idHJ1ZSIgeD0iOTU1IiB5PSIxNTAiIGZpbGw9IiMwMTAxMDEiIGZpbGwtb3BhY2l0eT0iLjMiIHRyYW5zZm9ybT0ic2NhbGUoLjEpIiB0ZXh0TGVuZ3RoPSI3MzAiPmV4cGVyaW1lbnRhbDwvdGV4dD4KICAgICAgICA8dGV4dCB4PSI5NTUiIHk9IjE0MCIgdHJhbnNmb3JtPSJzY2FsZSguMSkiIGZpbGw9IiNmZmYiIHRleHRMZW5ndGg9IjczMCI+ZXhwZXJpbWVudGFsPC90ZXh0PgogICAgPC9nPgo8L3N2Zz4K)
Calculate kinematics.
calculate_kinematics(data)calculate_kinematics(data)
data |
Data frame |
A data frame with kinematics calculated
Calculate summary statistics for tracks
calculate_statistics( data, measures = "median_mad", straightness = c("A", "B", "C", "D") )calculate_statistics( data, measures = "median_mad", straightness = c("A", "B", "C", "D") )
data |
A kinematics data frame |
measures |
Measures of central tendency and dispersion. Options are |
straightness |
Which method to calculate path straightness. Choose between "A" (default), "B", "C"... or a combination (e.g. "c("A","B")"). See description for details about the different calculations. |
An data frame data frame with kinematics calculated
clean_kinematics(data)clean_kinematics(data)
data |
tidy movement data frame with kinematics |
a clean kinematics data frame
Sometimes your sampling rate is too high; group_every allows you to
down-sample by creating "bins" which can subsequently be summarised on. When using n, data
needs to be regularly sampled; if there are gaps in time, the bin duration will differ.
Works well with calculate_summary() for movement data.
group_every(data, seconds = NULL, n = NULL)group_every(data, seconds = NULL, n = NULL)
data |
Input data frame |
seconds |
Number of seconds to bin together |
n |
Number of observations to include in each bin/group |
Grouped data frame, with new "bin" variable.
## Group by every 5 seconds df_time <- data.frame( time = seq(from = 0.02, to = 100, by = 1/30), # time at 30Hz, slightly offset y = rnorm(3000)) # random numbers df_time |> group_every(seconds = 5) |> # group for every 5 seconds dplyr::summarise(time = min(time), # summarise for time and y mean_y = mean(y)) |> dplyr::mutate(time = floor(time)) # floor to get the round second number # Group every n observations df <- data.frame( x = seq(1:1000), y = rnorm(1000)) df |> group_every(n = 30) |> # group every 30 observations together dplyr::summarise(mean_x = mean(x), mean_y = mean(y))## Group by every 5 seconds df_time <- data.frame( time = seq(from = 0.02, to = 100, by = 1/30), # time at 30Hz, slightly offset y = rnorm(3000)) # random numbers df_time |> group_every(seconds = 5) |> # group for every 5 seconds dplyr::summarise(time = min(time), # summarise for time and y mean_y = mean(y)) |> dplyr::mutate(time = floor(time)) # floor to get the round second number # Group every n observations df <- data.frame( x = seq(1:1000), y = rnorm(1000)) df |> group_every(n = 30) |> # group every 30 observations together dplyr::summarise(mean_x = mean(x), mean_y = mean(y))
read_animalta(path, detailed = FALSE)read_animalta(path, detailed = FALSE)
path |
An AnimalTA data frame |
detailed |
Animal export either raw (default) or detailed data files. We only have limited support for detailed data. |
a movement dataframe
read_bonsai(path)read_bonsai(path)
path |
Path to a Bonsai data file |
a movement dataframe
Read csv files from DeepLabCut (DLC). The function recognises whether it is a single- or multi-animal dataset.
read_deeplabcut(path, multianimal = NULL)read_deeplabcut(path, multianimal = NULL)
path |
Path to a DeepLabCut data file |
multianimal |
By default, whether a file is multi-animal is detected automatically. This gives an option to ensure it. logical TRUE/FALSE. |
a movement dataframe
read_idtracker(path, path_probabilities = NULL, version = 6)read_idtracker(path, path_probabilities = NULL, version = 6)
path |
Path to an idtracker.ai data frame |
path_probabilities |
Path to a csv file with probabilities. Only needed if you are reading csv files as they are included in h5 files. |
version |
idtracker.ai version. Currently only v6 output is implemented |
a movement dataframe
Read csv files from LightningPose (LP).
read_lightningpose(path)read_lightningpose(path)
path |
Path to a LightningPose data file |
a movement dataframe
read_movement(data)read_movement(data)
data |
A movement data frame |
a movement dataframe
read_sleap(path)read_sleap(path)
path |
A SLEAP analysis data frame in HDF5 (.h5) format |
a movement dataframe
Read trackball data from a variety of setups and configurations.
read_trackball( paths, setup = c("of_free", "of_fixed", "fictrac"), sampling_rate, col_time = "time", col_dx = "x", col_dy = "y", ball_calibration = NULL, ball_diameter = NULL, distance_scale = NULL, distance_unit = NULL, verbose = FALSE )read_trackball( paths, setup = c("of_free", "of_fixed", "fictrac"), sampling_rate, col_time = "time", col_dx = "x", col_dy = "y", ball_calibration = NULL, ball_diameter = NULL, distance_scale = NULL, distance_unit = NULL, verbose = FALSE )
paths |
Two file paths, one for each sensor (although one is allowed for a fixed setup, |
setup |
Which type of experimental setup was used. Expects either |
sampling_rate |
Sampling rate tells the function how long time it should integrate over. A sampling rate of 60(Hz) will mean windows of 1/60 sec are used to integrate over. |
col_time |
Which column contains the information about time. Can be specified either by the column number (numeric) or the name of the column if it has one (character). Should either be a datetime (POSIXt) or seconds (numeric). |
col_dx |
Column name for x-axis values |
col_dy |
Column name for y-axis values |
ball_calibration |
When running an |
ball_diameter |
When running a |
distance_scale |
If using computer mice, you might be getting unit-less data out. However, computer mice have a factor called "dots-per-cm", which you can use to convert your estimates into centimeters. |
distance_unit |
Which unit should be used. If |
verbose |
If |
a movement dataframe
read_treadmill(data)read_treadmill(data)
data |
A treadmill data frame |
a movement dataframe
read_trex(path)read_trex(path)
path |
Path to a TRex data frame in CSV format. |
a movement dataframe
Filtering/smoothing tracks is standard practice to root out noise in movement data. Here we provide some filter functions to do this. The function expects the data to be in the standard format, containing at least x, y and time variables.
smooth_track(data, method = c("rolling_median"), window_width = 5)smooth_track(data, method = c("rolling_median"), window_width = 5)
data |
Data frame |
method |
Which smoothing method to use. Currently only rolling mean is implemented ("rolling_mean"). |
window_width |
How many observations to use for rolling window filters (e.g. "rolling_mean" or "rolling_median"). |
A movement data frame