Identify IMU columns present in a tabular data source

Determine the column sets that will be used by default when extracting IMU data from a move2 or data.frame. Column sets are processed independently, but a single source may contain multiple active column sets for one IMU sensor.

• active_acc_colsets() — column sets used by as_acc().

• active_mag_colsets() — column sets used by as_mag().

• active_gyro_colsets() — column sets used by as_gyro().

If no active colsets are found, you can use imu_colset() to specify a custom set of columns that contain IMU data.

Usage

active_acc_colsets(x)

active_mag_colsets(x)

active_gyro_colsets(x)

Arguments

x

A move2 or data.frame.

Value

A list of imu_colset objects.

Details

IMU data are stored in two ways:

• Expanded-format columns store each IMU sample (possibly for multiple axes) in its own row.

• Compact-format columns store a burst of IMU samples as a space-delimited string. This string must be segmented into axis-specific values using an associated column that indicates the axes present in the burst. A further column provides the sampling frequency of the burst. All three of these columns must be present to form a valid compact-format column set.

Alternate column name separators

Some column names may differ depending on how the data were downloaded. The Movebank API (e.g. move2::movebank_download_study()) provides columns with _ separators, while manually downloaded data uses : and - separators and occasionally includes additional prefixes. For full compatibility, the active_*_colsets() functions recognize these alternate spellings as additional column sets even though movebank_*_colsets() lists only the standard API names.

For future compatibility, consider converting data with the manually-downloaded column names to use _ separators. To use a custom column set, provide the names explicitly with imu_colset().

See also

movebank_acc_colsets(), movebank_mag_colsets(), movebank_gyro_colsets() for the supported default colsets.

as_acc(), as_mag(), as_gyro() to extract IMU data from a tabular data source.

Examples

active_acc_colsets(albatrosses())
#> $eobs
#> <imu_colset> [
#>   bursts = "eobs_accelerations_raw",
#>   axes = "eobs_acceleration_axes",
#>   frequency = "eobs_acceleration_sampling_frequency_per_axis"
#> ]
#> 

# Multiple colsets may be available
active_acc_colsets(move2::mt_stack(albatrosses(), gulls()))
#> $eobs
#> <imu_colset> [
#>   bursts = "eobs_accelerations_raw",
#>   axes = "eobs_acceleration_axes",
#>   frequency = "eobs_acceleration_sampling_frequency_per_axis"
#> ]
#> 
#> $raw_xyz
#> <imu_colset> [
#>   X = "acceleration_raw_x",
#>   Y = "acceleration_raw_y",
#>   Z = "acceleration_raw_z"
#> ]
#> 

# Missing expanded-format axes are not included in the set
g <- gulls()
g$acceleration_raw_x <- NULL
active_acc_colsets(g)
#> $raw_xyz
#> <imu_colset> [
#>   Y = "acceleration_raw_y",
#>   Z = "acceleration_raw_z"
#> ]
#> 

# Columns with no data are also removed
g$acceleration_raw_y <- NA
active_acc_colsets(g)
#> $raw_xyz
#> <imu_colset> [
#>   Z = "acceleration_raw_z"
#> ]
#> 

# Some column sets must be present in their entirety
alb <- albatrosses()
alb$eobs_acceleration_axes <- NULL

if (FALSE) { # \dontrun{
active_acc_colsets(alb)
} # }