Gather data columns into key-value pairs

Reformat viewr data into a "tidy" format so that every row corresponds to the position (and potentially rotation) of a single subject during an observed frame and time.

Usage

gather_tunnel_data(obj_name, NA_drop = TRUE, ...)

Arguments

obj_name

The input viewr object; a tibble or data.frame with attribute pathviewr_steps that includes "viewr"

NA_drop

Should rows with NAs be dropped? Defaults to TRUE

...

Additional arguments that can be passed to other pathviewr functions such as relabel_viewr_axes() or read_motive_csv()

Value

A tibble in "tidy" format which is formatted to have every row correspond to the position (and potentially rotation) of a single subject during an observed frame and time. Subjects' names are automatically parsed from original variable names (e.g. subject1_rotation_width extracts "subject1" as the subject name) and stored in a Subjects column in the returned tibble.

Details

The tibble or data.frame that is fed in must have variables that have subject names and axis names separated by underscores. Axis names must be one of the following: position_length, position_width, or position_height. Each of these three dimensions must be present in the data. Collectively, this means that names like bird01_position_length or larry_position_height are acceptable, but bird01_x or bird01_length are not.

See also

Other data cleaning functions: get_full_trajectories(), quick_separate_trajectories(), redefine_tunnel_center(), relabel_viewr_axes(), rename_viewr_characters(), rotate_tunnel(), select_x_percent(), separate_trajectories(), standardize_tunnel(), trim_tunnel_outliers(), visualize_frame_gap_choice()

Author

Vikram B. Baliga

Examples

library(pathviewr)

## Import the Motive example data included in the package
motive_data <-
  read_motive_csv(system.file("extdata", "pathviewr_motive_example_data.csv",
                             package = 'pathviewr'))

## First use relabel_viewr_axes() to rename these variables using _length,
## _width, and _height instead
motive_data_relabeled <- relabel_viewr_axes(motive_data)

## Now use gather_tunnel_data() to gather colums into tidy format
motive_data_gathered <- gather_tunnel_data(motive_data_relabeled)

## Column names reflect the way in which data were reformatted:
names(motive_data_gathered)
#>  [1] "frame"             "time_sec"          "subject"          
#>  [4] "position_length"   "position_width"    "position_height"  
#>  [7] "rotation_length"   "rotation_width"    "rotation_height"  
#> [10] "rotation_real"     "mean_marker_error"