| Title: | Wrangle, Analyze, and Visualize Animal Movement Data |
|---|---|
| Description: | Tools to import, clean, and visualize movement data, particularly from motion capture systems such as Optitrack's 'Motive', the Straw Lab's 'Flydra', or from other sources. We provide functions to remove artifacts, standardize tunnel position and tunnel axes, select a region of interest, isolate specific trajectories, fill gaps in trajectory data, and calculate 3D and per-axis velocity. For experiments of visual guidance, we also provide functions that use subject position to estimate perception of visual stimuli. |
| Authors: | Vikram B. Baliga [aut, cre] (ORCID: <https://orcid.org/0000-0002-9367-8974>), Melissa S. Armstrong [aut] (ORCID: <https://orcid.org/0000-0002-3059-0094>), Eric R. Press [aut] (ORCID: <https://orcid.org/0000-0002-1944-3755>), Anne-Sophie Bonnet-Lebrun [rev], Marco Sciaini [rev] |
| Maintainer: | Vikram B. Baliga <[email protected]> |
| License: | GPL-3 |
| Version: | 1.1.8 |
| Built: | 2025-06-13 20:26:46 UTC |
| Source: | https://github.com/ropensci/pathviewr |
Should you have data from a non-Motive, non-Flydra source, this function canbe used to ensure your data are put into the right format to work with otherpathviewr functions.
as_viewr( obj_name, frame_rate = 100, frame_col, time_col, subject_col, position_length_col, position_width_col, position_height_col, include_rotation = FALSE, rotation_real_col, rotation_length_col, rotation_width_col, rotation_height_col)as_viewr( obj_name, frame_rate=100, frame_col, time_col, subject_col, position_length_col, position_width_col, position_height_col, include_rotation=FALSE, rotation_real_col, rotation_length_col, rotation_width_col, rotation_height_col)
obj_name | A tibble or data frame containing movement trajectories |
frame_rate | Must be a single numeric value indicating capture framerate in frames per second. |
frame_col | Column number of obj_name that contains frame numbers |
time_col | Column number of obj_name that contains time (must be inseconds) |
subject_col | Column number of obj_name that contains subject name(s) |
position_length_col | Column number of obj_name that containslength-axis position values |
position_width_col | Column number of obj_name that contains width-axisposition values |
position_height_col | Column number of obj_name that containsheight-axis position values |
include_rotation | Are rotation data included? Defaults to FALSE |
rotation_real_col | Column number of obj_name that contains the "real"axis of quaternion rotation data |
rotation_length_col | Column number of obj_name that contains the lengthaxis of quaternion rotation data |
rotation_width_col | Column number of obj_name that contains the widthaxis of quaternion rotation data |
rotation_height_col | Column number of obj_name that contains the heightaxis of quaternion rotation data |
A tibble that is organized to be compliant with otherpathviewr functions and that contains the attributespathviewr_steps with entries set toc("viewr", "renamed_tunnel", "gathered_tunnel")
Vikram B. Baliga
Other data import functions:import_and_clean_batch(),import_batch(),read_flydra_mat(),read_motive_csv()
## Create a dummy data frame with simulated (nonsense) datadf <- data.frame(frame = seq(1, 100, by = 1), time_sec = seq(0, by = 0.01, length.out = 100), subject = "birdie_sanders", z = rnorm(100), x = rnorm(100), y = rnorm(100))## Use as_viewr() to convert it into a viewr objecttest <- as_viewr( df, frame_rate = 100, frame_col = 1, time_col = 2, subject_col = 3, position_length_col = 5, position_width_col = 6, position_height_col = 4 )## Create a dummy data frame with simulated (nonsense) datadf<- data.frame(frame= seq(1,100, by=1), time_sec= seq(0, by=0.01, length.out=100), subject="birdie_sanders", z= rnorm(100), x= rnorm(100), y= rnorm(100))## Use as_viewr() to convert it into a viewr objecttest<- as_viewr( df, frame_rate=100, frame_col=1, time_col=2, subject_col=3, position_length_col=5, position_width_col=6, position_height_col=4)
Combine a list of multiple viewr objects into a single viewr object
bind_viewr_objects(obj_list)bind_viewr_objects(obj_list)
obj_list | A list of viewr objects |
A single viewr object (tibble or data.frame with attributepathviewr_steps that includes"viewr") that combines all therows of the source viewr objects inobj_list. Metadata may notnecessarily be retained and thereforeattributes should be used withcaution.
Vikram B. Baliga
Other batch functions:clean_viewr_batch(),import_and_clean_batch(),import_batch()
## Since we only have one example file of each type provided## in pathviewr, we will simply import the same example multiple## times to simulate batch importing. Replace the contents of## the following list with your own list of files to be imported.## Make a list of the same example file 3ximport_list <- c(rep( system.file("extdata", "pathviewr_motive_example_data.csv", package = 'pathviewr'), 3 ))## Batch importmotive_batch_imports <- import_batch(import_list, import_method = "motive", import_messaging = TRUE)## Batch cleaning of these imported files## via clean_viewr_batch()motive_batch_cleaned <- clean_viewr_batch( file_announce = TRUE, motive_batch_imports, desired_percent = 50, max_frame_gap = "autodetect", span = 0.95 )## Alternatively, use import_and_clean_batch() to## combine import with cleaning on a batch of filesmotive_batch_import_and_clean <- import_and_clean_batch( import_list, import_method = "motive", import_messaging = TRUE, motive_batch_imports, desired_percent = 50, max_frame_gap = "autodetect", span = 0.95 )## Each of these lists of objects can be bound into## one viewr object (i.e. one tibble) via## bind_viewr_objects()motive_bound_one <- bind_viewr_objects(motive_batch_cleaned)motive_bound_two <- bind_viewr_objects(motive_batch_import_and_clean)## Either route results in the same object ultimately:identical(motive_bound_one, motive_bound_two)## Since we only have one example file of each type provided## in pathviewr, we will simply import the same example multiple## times to simulate batch importing. Replace the contents of## the following list with your own list of files to be imported.## Make a list of the same example file 3ximport_list<- c(rep( system.file("extdata","pathviewr_motive_example_data.csv", package='pathviewr'),3))## Batch importmotive_batch_imports<- import_batch(import_list, import_method="motive", import_messaging=TRUE)## Batch cleaning of these imported files## via clean_viewr_batch()motive_batch_cleaned<- clean_viewr_batch( file_announce=TRUE, motive_batch_imports, desired_percent=50, max_frame_gap="autodetect", span=0.95)## Alternatively, use import_and_clean_batch() to## combine import with cleaning on a batch of filesmotive_batch_import_and_clean<- import_and_clean_batch( import_list, import_method="motive", import_messaging=TRUE, motive_batch_imports, desired_percent=50, max_frame_gap="autodetect", span=0.95)## Each of these lists of objects can be bound into## one viewr object (i.e. one tibble) via## bind_viewr_objects()motive_bound_one<- bind_viewr_objects(motive_batch_cleaned)motive_bound_two<- bind_viewr_objects(motive_batch_import_and_clean)## Either route results in the same object ultimately:identical(motive_bound_one, motive_bound_two)
Calculate minimum distance to lateral and end walls in a box-shapedexperimental tunnel
calc_min_dist_box(obj_name)calc_min_dist_box(obj_name)
obj_name | The input viewr object; a tibble or data.frame with attribute |
calc_min_dist_box() assumes the subject locomotes facingforward, thereforemin_dist_end represents the minimum distancebetween the subject and the end wall to which it is moving towards.All outputs are in meters.
A tibble or data.frame with added variables formin_dist_pos,min_dist_neg, andmin_dist_end,.
Eric R. Press
Other visual perception functions:get_sf(),get_vis_angle()
## Import sample data from package flydra_data <- read_flydra_mat(system.file("extdata", "pathviewr_flydra_example_data.mat", package = 'pathviewr'), subject_name = "birdie_sanders") ## Process data up to and including insert_treatments() flydra_data_full <- flydra_data %>% redefine_tunnel_center(length_method = "middle", height_method = "user-defined", height_zero = 1.44) %>% select_x_percent(desired_percent = 50) %>% separate_trajectories(max_frame_gap = "autodetect") %>% get_full_trajectories(span = 0.95) %>% insert_treatments(tunnel_config = "box", tunnel_length = 3, tunnel_width = 1, stim_param_lat_pos = 0.1, stim_param_lat_neg = 0.1, stim_param_end_pos = 0.3, stim_param_end_neg = 0.3, treatment = "lat10_end_30") %>% ## Now calculate the minimum distances to each wall calc_min_dist_box() ## See 3 new variables for calculations to lateral and end walls names(flydra_data_full)## Import sample data from package flydra_data<- read_flydra_mat(system.file("extdata","pathviewr_flydra_example_data.mat", package='pathviewr'), subject_name="birdie_sanders")## Process data up to and including insert_treatments() flydra_data_full<- flydra_data%>% redefine_tunnel_center(length_method="middle", height_method="user-defined", height_zero=1.44)%>% select_x_percent(desired_percent=50)%>% separate_trajectories(max_frame_gap="autodetect")%>% get_full_trajectories(span=0.95)%>% insert_treatments(tunnel_config="box", tunnel_length=3, tunnel_width=1, stim_param_lat_pos=0.1, stim_param_lat_neg=0.1, stim_param_end_pos=0.3, stim_param_end_neg=0.3, treatment="lat10_end_30")%>%## Now calculate the minimum distances to each wall calc_min_dist_box()## See 3 new variables for calculations to lateral and end walls names(flydra_data_full)
Calculate minimum distance to lateral and end walls in a V-shapedexperimental tunnel
calc_min_dist_v(obj_name, simplify_output = TRUE)calc_min_dist_v(obj_name, simplify_output=TRUE)
obj_name | The input viewr object; a tibble or data.frame with attribute |
simplify_output | If TRUE, the returned object includes only the minimumdistance between the subject and the lateral/end walls. If FALSE, thereturned object includes all variables internal to the calculation. |
For tunnels in whichvertex_angle is >90 degree,bound_pos andbound_neg represent a planes orthogonal to thelateral walls and are used to modifymin_dist_pos andmin_dist_neg calculations to prevent erroneous outputs.calc_min_dist_v() assumes the subject locomotes facing forward,thereforemin_dist_end represents the minimum distance between thesubject and the end wall to which it is moving towards All outputs are inmeters.
A tibble or data.frame with added variables forheight_2_vertex,height_2_screen,width_2_screen_pos,width_2_screen_neg,min_dist_pos,min_dist_neg,min_dist_end,bound_pos, andbound_neg.
Eric R. Press
Other mathematical functions:deg_2_rad(),find_curve_elbow(),get_2d_angle(),get_3d_angle(),get_3d_cross_prod(),get_dist_point_line(),get_traj_velocities(),get_velocity(),rad_2_deg()
## Import sample data from packagemotive_data <- read_motive_csv(system.file("extdata", "pathviewr_motive_example_data.csv", package = 'pathviewr')) ## Process data up to and including insert_treatments()motive_data_full <- motive_data %>% relabel_viewr_axes() %>% gather_tunnel_data() %>% trim_tunnel_outliers() %>% rotate_tunnel() %>% select_x_percent(desired_percent = 50) %>% separate_trajectories(max_frame_gap = "autodetect") %>% get_full_trajectories(span = 0.95) %>% insert_treatments(tunnel_config = "v", perch_2_vertex = 0.4, vertex_angle = 90, tunnel_length = 2, stim_param_lat_pos = 0.1, stim_param_lat_neg = 0.1, stim_param_end_pos = 0.3, stim_param_end_neg = 0.3, treatment = "lat10_end_30") %>% ## Now calculate the minimum distances to each wall calc_min_dist_v(simplify_output = TRUE) ## See 3 new variables for calculations to lateral and end walls names(motive_data_full)## Import sample data from packagemotive_data<- read_motive_csv(system.file("extdata","pathviewr_motive_example_data.csv", package='pathviewr'))## Process data up to and including insert_treatments()motive_data_full<- motive_data%>% relabel_viewr_axes()%>% gather_tunnel_data()%>% trim_tunnel_outliers()%>% rotate_tunnel()%>% select_x_percent(desired_percent=50)%>% separate_trajectories(max_frame_gap="autodetect")%>% get_full_trajectories(span=0.95)%>% insert_treatments(tunnel_config="v", perch_2_vertex=0.4, vertex_angle=90, tunnel_length=2, stim_param_lat_pos=0.1, stim_param_lat_neg=0.1, stim_param_end_pos=0.3, stim_param_end_neg=0.3, treatment="lat10_end_30")%>%## Now calculate the minimum distances to each wall calc_min_dist_v(simplify_output=TRUE)## See 3 new variables for calculations to lateral and end walls names(motive_data_full)
Remove file_sub_traj entries that do not span the full region of interest
clean_by_span( obj_name, axis = "position_length", min_value = NULL, max_value = NULL, tolerance = 0.1)clean_by_span( obj_name, axis="position_length", min_value=NULL, max_value=NULL, tolerance=0.1)
obj_name | The input viewr object; a tibble or data.frame with attribute |
axis | Along which axis should restrictions be enforced? |
min_value | Minimum coordinate value; setting this to NULL willauto-compute the best value |
max_value | Maximum coordinate; setting this to NULL will auto-computethe best value |
tolerance | As a proporiton of axis value |
A viewr object (tibble or data.frame with attributepathviewr_steps. Trajectories that do not span the full region ofinterest have been removed; trajectory identities (file_sub_traj) havenot been changed.
Vikram B. Baliga
Other utility functions:insert_treatments(),remove_duplicate_frames(),remove_vel_anomalies(),set_traj_frametime()
For an imported viewr object, run through the cleaning pipeline as desired
clean_viewr( obj_name, relabel_viewr_axes = TRUE, gather_tunnel_data = TRUE, trim_tunnel_outliers = TRUE, standardization_option = "rotate_tunnel", get_velocity = TRUE, select_x_percent = TRUE, rename_viewr_characters = FALSE, separate_trajectories = TRUE, get_full_trajectories = TRUE, fill_traj_gaps = FALSE, ...)clean_viewr( obj_name, relabel_viewr_axes=TRUE, gather_tunnel_data=TRUE, trim_tunnel_outliers=TRUE, standardization_option="rotate_tunnel", get_velocity=TRUE, select_x_percent=TRUE, rename_viewr_characters=FALSE, separate_trajectories=TRUE, get_full_trajectories=TRUE, fill_traj_gaps=FALSE,...)
obj_name | The input viewr object; a tibble or data.frame with attribute |
relabel_viewr_axes | default TRUE, should axes be relabeled? |
gather_tunnel_data | default TRUE, should tunnel data be gathered? |
trim_tunnel_outliers | default TRUE, outliers be trimmed? |
standardization_option | default "rotate_tunnel"; which standardizationoption should be used? See Details for more. |
get_velocity | default TRUE, should velocity be computed? |
select_x_percent | default TRUE, should a region of interest beselected? |
rename_viewr_characters | default FALSE, should subjects be renamed? |
separate_trajectories | default TRUE, should trajectories be defined? |
get_full_trajectories | default TRUE, should only full trajectories beretained? |
fill_traj_gaps | default FALSE, should gaps in trajectories be filled? |
... | Additional arguments passed to any of the corresponding functions |
Each argument corresponds to a standalone function inpathviewr. E.g. the parameterrelabel_viewr_axes allows auser to choose whetherpathviewr::relabel_viewr_axes() is runinternally. Should the user desire to use any non-default parameter valuesfor any functions included here, they should be supplied to this functionas additional arguments formatted exactly as they would appear in theircorresponding function(s). E.g. if the "autodetect" feature inpathviewr::separate_trajectories() is desired, add an argumentmax_frame_gap = "autodetect" to the arguments supplied to thisfunction.
A viewr object (tibble or data.frame with attributepathviewr_steps that includes"viewr") that has passedthrough severalpathviewr functions as desired by the user,resulting in data that have been cleaned and ready for analyses.
Vikram B. Baliga
Other all in one functions:import_and_clean_viewr()
library(pathviewr)## Import the example Motive data included in the packagemotive_data <- read_motive_csv(system.file("extdata", "pathviewr_motive_example_data.csv", package = 'pathviewr'))motive_full <- motive_data %>% clean_viewr(desired_percent = 50, max_frame_gap = "autodetect", span = 0.95)## Alternatively, used the import_and_clean_viewr()## function to combine these stepsmotive_import_and_clean <- import_and_clean_viewr( file_name = system.file("extdata", "pathviewr_motive_example_data.csv", package = 'pathviewr'), desired_percent = 50, max_frame_gap = "autodetect", span = 0.95 )library(pathviewr)## Import the example Motive data included in the packagemotive_data<- read_motive_csv(system.file("extdata","pathviewr_motive_example_data.csv", package='pathviewr'))motive_full<- motive_data%>% clean_viewr(desired_percent=50, max_frame_gap="autodetect", span=0.95)## Alternatively, used the import_and_clean_viewr()## function to combine these stepsmotive_import_and_clean<- import_and_clean_viewr( file_name= system.file("extdata","pathviewr_motive_example_data.csv", package='pathviewr'), desired_percent=50, max_frame_gap="autodetect", span=0.95)
For a list of viewr objects, run through the pipeline (from relabel axesup through get full trajectories, as desired) via clean_viewr()
clean_viewr_batch(obj_list, file_announce = FALSE, ...)clean_viewr_batch(obj_list, file_announce=FALSE,...)
obj_list | A list of viewr objects (i.e. a list of tibbles that eachhave attribute |
file_announce | Should the function report each time a file isprocessed? Default FALSE; if TRUE, a message will appear in the consoleeach time a file has been cleaned successfully. |
... | Arguments to be passed in that specify how this function shouldclean files. |
viewr objects should be in a list, e.g. the object generated byimport_batch().
Seeclean_viewr() for details of how cleaning steps are handledand/or refer to the corresponding cleaning functions themselves.
A list of viewr objects (tibble or data.frame with attributepathviewr_steps that includes"viewr") that have been passedthrough the corresponding cleaning functions.
Vikram B. Baliga
Other batch functions:bind_viewr_objects(),import_and_clean_batch(),import_batch()
## Since we only have one example file of each type provided## in pathviewr, we will simply import the same example multiple## times to simulate batch importing. Replace the contents of## the following list with your own list of files to be imported.## Make a list of the same example file 3ximport_list <- c(rep( system.file("extdata", "pathviewr_motive_example_data.csv", package = 'pathviewr'), 3 ))## Batch importmotive_batch_imports <- import_batch(import_list, import_method = "motive", import_messaging = TRUE)## Batch cleaning of these imported files## via clean_viewr_batch()motive_batch_cleaned <- clean_viewr_batch( file_announce = TRUE, motive_batch_imports, desired_percent = 50, max_frame_gap = "autodetect", span = 0.95 )## Alternatively, use import_and_clean_batch() to## combine import with cleaning on a batch of filesmotive_batch_import_and_clean <- import_and_clean_batch( import_list, import_method = "motive", import_messaging = TRUE, motive_batch_imports, desired_percent = 50, max_frame_gap = "autodetect", span = 0.95 )## Each of these lists of objects can be bound into## one viewr object (i.e. one tibble) via## bind_viewr_objects()motive_bound_one <- bind_viewr_objects(motive_batch_cleaned)motive_bound_two <- bind_viewr_objects(motive_batch_import_and_clean)## Either route results in the same object ultimately:identical(motive_bound_one, motive_bound_two)## Since we only have one example file of each type provided## in pathviewr, we will simply import the same example multiple## times to simulate batch importing. Replace the contents of## the following list with your own list of files to be imported.## Make a list of the same example file 3ximport_list<- c(rep( system.file("extdata","pathviewr_motive_example_data.csv", package='pathviewr'),3))## Batch importmotive_batch_imports<- import_batch(import_list, import_method="motive", import_messaging=TRUE)## Batch cleaning of these imported files## via clean_viewr_batch()motive_batch_cleaned<- clean_viewr_batch( file_announce=TRUE, motive_batch_imports, desired_percent=50, max_frame_gap="autodetect", span=0.95)## Alternatively, use import_and_clean_batch() to## combine import with cleaning on a batch of filesmotive_batch_import_and_clean<- import_and_clean_batch( import_list, import_method="motive", import_messaging=TRUE, motive_batch_imports, desired_percent=50, max_frame_gap="autodetect", span=0.95)## Each of these lists of objects can be bound into## one viewr object (i.e. one tibble) via## bind_viewr_objects()motive_bound_one<- bind_viewr_objects(motive_batch_cleaned)motive_bound_two<- bind_viewr_objects(motive_batch_import_and_clean)## Either route results in the same object ultimately:identical(motive_bound_one, motive_bound_two)
Convert degrees to radians
deg_2_rad(deg)deg_2_rad(deg)
deg | Degrees (a numeric of any length >= 1) |
The angle(s) in radians (as a numeric vector of the same length)
Vikram B. Baliga
Other mathematical functions:calc_min_dist_v(),find_curve_elbow(),get_2d_angle(),get_3d_angle(),get_3d_cross_prod(),get_dist_point_line(),get_traj_velocities(),get_velocity(),rad_2_deg()
## One inputdeg_2_rad(90)## Multiple inputsdeg_2_rad(c(5, 10, 15, 20))## One inputdeg_2_rad(90)## Multiple inputsdeg_2_rad(c(5,10,15,20))
Remove trajectories from a viewr object that contain instances of velocityknown to be spurious.
exclude_by_velocity(obj_name, vel_min = NULL, vel_max = NULL)exclude_by_velocity(obj_name, vel_min=NULL, vel_max=NULL)
obj_name | The input viewr object; a tibble or data.frame with attribute |
vel_min | Default |
vel_max | Default |
A new viewr object that is identical to the input object but nowexcludes any trajectories that contain observations with velocity less thanvel_min (if specified) and/or velocity greater thanvel_max(if specified)
Vikram B. Baliga
## Import and clean the example Motive datamotive_import_and_clean <- import_and_clean_viewr( file_name = system.file("extdata", "pathviewr_motive_example_data.csv", package = 'pathviewr'), desired_percent = 50, max_frame_gap = "autodetect", span = 0.95 )## See the distribution of velocitieshist(motive_import_and_clean$velocity)## Let's remove any trajectories that contain## velocity < 2motive_vel_filtered <- motive_import_and_clean %>% exclude_by_velocity(vel_min = 2)## See how the distribution of velocities has changedhist(motive_vel_filtered$velocity)## Import and clean the example Motive datamotive_import_and_clean<- import_and_clean_viewr( file_name= system.file("extdata","pathviewr_motive_example_data.csv", package='pathviewr'), desired_percent=50, max_frame_gap="autodetect", span=0.95)## See the distribution of velocitieshist(motive_import_and_clean$velocity)## Let's remove any trajectories that contain## velocity < 2motive_vel_filtered<- motive_import_and_clean%>% exclude_by_velocity(vel_min=2)## See how the distribution of velocities has changedhist(motive_vel_filtered$velocity)
Use LOESS smoothing to fill in gaps of missing data within trajectories ina viewr object
fill_traj_gaps( obj_name, loess_degree = 1, loess_criterion = c("aicc", "gcv"), loess_family = c("gaussian", "symmetric"), loess_user_span = NULL)fill_traj_gaps( obj_name, loess_degree=1, loess_criterion= c("aicc","gcv"), loess_family= c("gaussian","symmetric"), loess_user_span=NULL)
obj_name | The input viewr object; a tibble or data.frame with attribute |
loess_degree | See "degree" argument of fANCOVA::loess.as() |
loess_criterion | See "criterion" argument of fANCOVA::loess.as() |
loess_family | See "family" argument of fANCOVA::loess.as() |
loess_user_span | See "user.span" argument of fANCOVA::loess.as() |
It is strongly recommended that the input viewr object be "cleaned"viaselect_x_percent() ->separate_trajectories() ->get_full_trajectories() prior to using this function. Doing so willensure that only trajectories with minor gaps will be used in youranalyses. This function will then enable you to interpolate missing data inthose minor gaps.
Interpolation is handled by first fitting a series of LOESS regressions(viafANCOVA::loess.as()). In each regression, a position axis (e.g.position_length) is regressed againstframe (frame isx-axis). From that relationship, values of missing position data aredetermined and then inserted into the original data set.
Seeloess.as for further details on parameters.
A viewr object; a tibble or data.frame with attributepathviewr_steps that includes"viewr" that now includes newobservations (rows) as a result of interpolation to fill in missing data. Anew columngaps_filled is added to the data to indicate originaldata ("No") vs data that have been inserted to fill gaps ("Yes").
Vikram B. Baliga
library(pathviewr)## Import the example Motive data included in the packagemotive_data <- read_motive_csv(system.file("extdata", "pathviewr_motive_example_data.csv", package = 'pathviewr'))## Clean, isolate, and label trajectoriesmotive_full <- motive_data %>% clean_viewr(desired_percent = 50, max_frame_gap = "autodetect", span = 0.95)## Interpolate missing data via this functionmotive_filling <- motive_full %>% fill_traj_gaps()## plot all trajectories (before)plot_viewr_trajectories(motive_full, multi_plot = TRUE)## plot all trajectories(after)plot_viewr_trajectories(motive_filling, multi_plot = TRUE)library(pathviewr)## Import the example Motive data included in the packagemotive_data<- read_motive_csv(system.file("extdata","pathviewr_motive_example_data.csv", package='pathviewr'))## Clean, isolate, and label trajectoriesmotive_full<- motive_data%>% clean_viewr(desired_percent=50, max_frame_gap="autodetect", span=0.95)## Interpolate missing data via this functionmotive_filling<- motive_full%>% fill_traj_gaps()## plot all trajectories (before)plot_viewr_trajectories(motive_full, multi_plot=TRUE)## plot all trajectories(after)plot_viewr_trajectories(motive_filling, multi_plot=TRUE)
For bivariate data that show monotonic decreases (e.g. plots of trajectorycount vs. frame gap allowed, or scree plots from PCAs), this function willfind the "elbow" point. This is done by drawing an (imaginary) line betweenthe first observation and the final observation. Then, the distance betweenthat line and each observation is calculated. The "elbow" of the curve is theobservation that maximizes this distance.
find_curve_elbow(data_frame, export_type = "row_num", plot_curve = FALSE)find_curve_elbow(data_frame, export_type="row_num", plot_curve=FALSE)
data_frame | A two-column data frame (numeric entries only), orderedx-axis first, y-axis second. |
export_type | If "row_num" (the default), the row number of the elbowpoint is returned. If anything else, the entire row of the original dataframe is returned. |
plot_curve | Default FALSE; should the curve be plotted? |
Ifexport_type isrow_num the row number of the elbowpoint is returned. If anything else is used for that argument, the entirerow of the original data frame on which the "elbow" is located is returned.Ifplot_curve isTRUE, the curve is plotted along with avertical line drawn at the computed elbow point.
Vikram B. Baliga
Other mathematical functions:calc_min_dist_v(),deg_2_rad(),get_2d_angle(),get_3d_angle(),get_3d_cross_prod(),get_dist_point_line(),get_traj_velocities(),get_velocity(),rad_2_deg()
df <- data.frame(x = seq(1:10), y = 1/seq(1:10))plot(df)find_curve_elbow(df, plot_curve = TRUE)df<- data.frame(x= seq(1:10), y=1/seq(1:10))plot(df)find_curve_elbow(df, plot_curve=TRUE)
Reformatviewr data into a "tidy" format so that every row correspondsto the position (and potentially rotation) of a single subject during anobserved frame and time.
gather_tunnel_data(obj_name, NA_drop = TRUE, ...)gather_tunnel_data(obj_name, NA_drop=TRUE,...)
obj_name | The input viewr object; a tibble or data.frame with attribute |
NA_drop | Should rows with NAs be dropped? Defaults to |
... | Additional arguments that can be passed to other |
The tibble or data.frame that is fed in must have variables thathave subject names and axis names separated by underscores. Axis names mustbe one of the following:position_length,position_width, orposition_height. Each of these three dimensions must be present in thedata. Collectively, this means that names likebird01_position_lengthorlarry_position_height are acceptable, butbird01_x orbird01_length are not.
A tibble in "tidy" format which is formatted to have every rowcorrespond to the position (and potentially rotation) of a single subjectduring an observed frame and time. Subjects' names are automatically parsedfrom original variable names (e.g. subject1_rotation_width extracts"subject1" as the subject name) and stored in aSubjects column in thereturned tibble.
Vikram B. Baliga
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()
library(pathviewr)## Import the Motive example data included in the packagemotive_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 insteadmotive_data_relabeled <- relabel_viewr_axes(motive_data)## Now use gather_tunnel_data() to gather colums into tidy formatmotive_data_gathered <- gather_tunnel_data(motive_data_relabeled)## Column names reflect the way in which data were reformatted:names(motive_data_gathered)library(pathviewr)## Import the Motive example data included in the packagemotive_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 insteadmotive_data_relabeled<- relabel_viewr_axes(motive_data)## Now use gather_tunnel_data() to gather colums into tidy formatmotive_data_gathered<- gather_tunnel_data(motive_data_relabeled)## Column names reflect the way in which data were reformatted:names(motive_data_gathered)
Compute an angle in 2D space
get_2d_angle(x1, y1, x2, y2, x3, y3)get_2d_angle(x1, y1, x2, y2, x3, y3)
x1 | x-coordinate of first point |
y1 | y-coordinate of first point |
x2 | x-coordinate of second point (vertex) |
y2 | y-coordinate of second point (vertex) |
x3 | x-coordinate of third point |
y3 | y-coordinate of third point |
Everything supplied to arguments must be numeric values or vectorsof numeric values. The second point (x2, y2) is treated as the vertex, andthe angle between the three points in 2D space is computed.
A numeric vector that provides the angular measurement in degrees.
Vikram B. Baliga
Other mathematical functions:calc_min_dist_v(),deg_2_rad(),find_curve_elbow(),get_3d_angle(),get_3d_cross_prod(),get_dist_point_line(),get_traj_velocities(),get_velocity(),rad_2_deg()
get_2d_angle( 0, 1, 0, 0, 1, 0)get_2d_angle(0,1,0,0,1,0)
Compute an angle in 3D space
get_3d_angle(x1, y1, z1, x2, y2, z2, x3, y3, z3)get_3d_angle(x1, y1, z1, x2, y2, z2, x3, y3, z3)
x1 | x-coordinate of first point |
y1 | y-coordinate of first point |
z1 | z-coordinate of first point |
x2 | x-coordinate of second point (vertex) |
y2 | y-coordinate of second point (vertex) |
z2 | y-coordinate of second point (vertex) |
x3 | x-coordinate of third point |
y3 | y-coordinate of third point |
z3 | z-coordinate of third point |
Everything supplied to arguments must be numeric values or vectorsof numeric values. The second point (x2, y2, z2) is treated as the vertex,and the angle between the three points in 3D space is computed.
A numeric vector that provides the angular measurement in degrees.
Vikram B. Baliga
Other mathematical functions:calc_min_dist_v(),deg_2_rad(),find_curve_elbow(),get_2d_angle(),get_3d_cross_prod(),get_dist_point_line(),get_traj_velocities(),get_velocity(),rad_2_deg()
get_3d_angle( 0, 1, 0, 0, 0, 0, 1, 0, 0)get_3d_angle(0,1,0,0,0,0,1,0,0)
Compute the cross product of two 3D vectors
get_3d_cross_prod(v1, v2)get_3d_cross_prod(v1, v2)
v1 | First vector, as c(x,y,z) |
v2 | Second vector, as c(x,y,z) |
A vector of length 3 that describes the cross-product
Vikram B. Baliga
Other mathematical functions:calc_min_dist_v(),deg_2_rad(),find_curve_elbow(),get_2d_angle(),get_3d_angle(),get_dist_point_line(),get_traj_velocities(),get_velocity(),rad_2_deg()
v1 <- c(1, 1, 3)v2 <- c(3, 1, 3)get_3d_cross_prod(v1, v2)v1<- c(1,1,3)v2<- c(3,1,3)get_3d_cross_prod(v1, v2)
Compute distance between a point and a line
get_dist_point_line(point, line_coord1, line_coord2)get_dist_point_line(point, line_coord1, line_coord2)
point | 2D or 3D coordinates of the point as c(x,y) or c(x,y,z) |
line_coord1 | 2D or 3D coordinates of one point on the line as c(x,y) orc(x,y,z) |
line_coord2 | 2D or 3D coordinates of a second point on the line asc(x,y) or c(x,y,z) |
The function accepts 2D coordinates or 3D coordinates, but note thatthe dimensions of all supplied arguments must match; all coordinates mustbe 2D or they all must be 3D.
A numeric vector of length 1 that provides the euclidean distancebetween the point and the line.
Vikram B. Baliga
Other mathematical functions:calc_min_dist_v(),deg_2_rad(),find_curve_elbow(),get_2d_angle(),get_3d_angle(),get_3d_cross_prod(),get_traj_velocities(),get_velocity(),rad_2_deg()
## 2D caseget_dist_point_line( point = c(0, 0), line_coord1 = c(1, 0), line_coord2 = c(1, 5))## 3D caseget_dist_point_line( point = c(0, 0, 0), line_coord1 = c(1, 0, 0), line_coord2 = c(1, 5, 0))## 2D caseget_dist_point_line( point= c(0,0), line_coord1= c(1,0), line_coord2= c(1,5))## 3D caseget_dist_point_line( point= c(0,0,0), line_coord1= c(1,0,0), line_coord2= c(1,5,0))
Specify a minimum span of the selected region of interest and then keeptrajectories that are wider than that span and go from one end to the otherof the region.
get_full_trajectories(obj_name, span = 0.8, ...)get_full_trajectories(obj_name, span=0.8,...)
obj_name | The input viewr object; a tibble or data.frame with attribute |
span | Span to use; must be numeric and between 0 and 1 |
... | Additional arguments passed to/from other pathviewr functions |
Because trajectories may not have observations exactly at thebeginning or the end of the region of interest, it may be necessary to allowtrajectories to be slightly shorter than the range of the selected region ofinterest. Thespan parameter of this function handles this. Bysupplying a numeric proportion from 0 to 1, a user may allow trajectories tospan that proportion of the selected region. For example, settingspan= 0.95 will keep all trajectories that span 95% of the length of theselected region of interest. Settingspan = 1 (not recommended) willstrictly keep trajectories that start and end at the exact cut-offs of theselected region of interest. For these reasons,spans of 0.99 to 0.95are generally recommended.
A viewr object (tibble or data.frame with attributepathviewr_steps that includes"viewr") in which onlytrajectories that span the region of interest are retained. Data arelabeled by direction (either "leftwards" or "rightwards") with respect totheir starting and endingposition_length values in thedirection column.
Vikram B. Baliga
Other data cleaning functions:gather_tunnel_data(),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()
Other functions that define or clean trajectories:quick_separate_trajectories(),separate_trajectories(),visualize_frame_gap_choice()
motive_data <- read_motive_csv(system.file("extdata", "pathviewr_motive_example_data.csv", package = 'pathviewr'))## Clean the file. It is generally recommended to clean up to the## "separate" step before running select_x_percent().motive_separated <- motive_data %>% relabel_viewr_axes() %>% gather_tunnel_data() %>% trim_tunnel_outliers() %>% rotate_tunnel() %>% select_x_percent(desired_percent = 50) %>% separate_trajectories(max_frame_gap = "autodetect", frame_rate_proportion = 0.1)## Now retain only the "full" trajectories that span## across 0.95 of the range of position_lengthmotive_full <- motive_separated %>% get_full_trajectories(span = 0.95)motive_data<- read_motive_csv(system.file("extdata","pathviewr_motive_example_data.csv", package='pathviewr'))## Clean the file. It is generally recommended to clean up to the## "separate" step before running select_x_percent().motive_separated<- motive_data%>% relabel_viewr_axes()%>% gather_tunnel_data()%>% trim_tunnel_outliers()%>% rotate_tunnel()%>% select_x_percent(desired_percent=50)%>% separate_trajectories(max_frame_gap="autodetect", frame_rate_proportion=0.1)## Now retain only the "full" trajectories that span## across 0.95 of the range of position_lengthmotive_full<- motive_separated%>% get_full_trajectories(span=0.95)
A function to quickly return the information stored in the header of theoriginal data file imported viapathviewr'sread_ functions.
get_header_viewr(obj_name, ...)get_header_viewr(obj_name,...)
obj_name | The input viewr object; a tibble or data.frame with attribute |
... | Additional arguments that may be passed to other |
The value of theheader attribute, or NULL if no exact matchis found and no or more than one partial match is found.
Vikram B. Baliga
library(pathviewr)## Import the Motive example data included in the packagemotive_data <- read_motive_csv(system.file("extdata", "pathviewr_motive_example_data.csv", package = 'pathviewr'))## Now display the Header informationget_header_viewr(motive_data)library(pathviewr)## Import the Motive example data included in the packagemotive_data<- read_motive_csv(system.file("extdata","pathviewr_motive_example_data.csv", package='pathviewr'))## Now display the Header informationget_header_viewr(motive_data)
Estimate the spatial frequency of visual stimuli from the subject'sperspective in an experimental tunnel.
get_sf(obj_name)get_sf(obj_name)
obj_name | The input viewr object; a tibble or data.frame with attribute |
get_sf() assumes the following:
The subject's gaze is fixed at the point on the either side of the tunnelthat minimizes the distance to visual stimuli and therefore maximizes visualangles.
The subject's head is facing parallel to the length axis of the tunnel.Visual perception functions in future versions of pathviewr will integratehead orientation coordinates.Spatial frequency is reported in cycles/degree and is the inverse of visualangle (degrees/cycle).
A tibble or data.frame with added variables forsf_pos,sf_neg, andsf_end.angle.
Eric R. Press
Other visual perception functions:calc_min_dist_box(),get_vis_angle()
## Import sample data from packagemotive_data <- read_motive_csv(system.file("extdata", "pathviewr_motive_example_data.csv", package = 'pathviewr'))flydra_data <- read_flydra_mat(system.file("extdata", "pathviewr_flydra_example_data.mat", package = 'pathviewr'), subject_name = "birdie_sanders") ## Process data up to and including get_vis_angle()motive_data_full <- motive_data %>% relabel_viewr_axes() %>% gather_tunnel_data() %>% trim_tunnel_outliers() %>% rotate_tunnel() %>% select_x_percent(desired_percent = 50) %>% separate_trajectories(max_frame_gap = "autodetect") %>% get_full_trajectories(span = 0.95) %>% insert_treatments(tunnel_config = "v", perch_2_vertex = 0.4, vertex_angle = 90, tunnel_length = 2, stim_param_lat_pos = 0.1, stim_param_lat_neg = 0.1, stim_param_end_pos = 0.3, stim_param_end_neg = 0.3, treatment = "lat10_end_30") %>% calc_min_dist_v(simplify_output = TRUE) %>% get_vis_angle() %>% ## Now calculate the spatial frequencies get_sf() flydra_data_full <- flydra_data %>% redefine_tunnel_center(length_method = "middle", height_method = "user-defined", height_zero = 1.44) %>% select_x_percent(desired_percent = 50) %>% separate_trajectories(max_frame_gap = "autodetect") %>% get_full_trajectories(span = 0.95) %>% insert_treatments(tunnel_config = "box", tunnel_length = 3, tunnel_width = 1, stim_param_lat_pos = 0.1, stim_param_lat_neg = 0.1, stim_param_end_pos = 0.3, stim_param_end_neg = 0.3, treatment = "lat10_end_30") %>% calc_min_dist_box() %>% get_vis_angle() %>% ## Now calculate the spatial frequencies get_sf()## Import sample data from packagemotive_data<- read_motive_csv(system.file("extdata","pathviewr_motive_example_data.csv", package='pathviewr'))flydra_data<- read_flydra_mat(system.file("extdata","pathviewr_flydra_example_data.mat", package='pathviewr'), subject_name="birdie_sanders")## Process data up to and including get_vis_angle()motive_data_full<- motive_data%>% relabel_viewr_axes()%>% gather_tunnel_data()%>% trim_tunnel_outliers()%>% rotate_tunnel()%>% select_x_percent(desired_percent=50)%>% separate_trajectories(max_frame_gap="autodetect")%>% get_full_trajectories(span=0.95)%>% insert_treatments(tunnel_config="v", perch_2_vertex=0.4, vertex_angle=90, tunnel_length=2, stim_param_lat_pos=0.1, stim_param_lat_neg=0.1, stim_param_end_pos=0.3, stim_param_end_neg=0.3, treatment="lat10_end_30")%>% calc_min_dist_v(simplify_output=TRUE)%>% get_vis_angle()%>%## Now calculate the spatial frequencies get_sf() flydra_data_full<- flydra_data%>% redefine_tunnel_center(length_method="middle", height_method="user-defined", height_zero=1.44)%>% select_x_percent(desired_percent=50)%>% separate_trajectories(max_frame_gap="autodetect")%>% get_full_trajectories(span=0.95)%>% insert_treatments(tunnel_config="box", tunnel_length=3, tunnel_width=1, stim_param_lat_pos=0.1, stim_param_lat_neg=0.1, stim_param_end_pos=0.3, stim_param_end_neg=0.3, treatment="lat10_end_30")%>% calc_min_dist_box()%>% get_vis_angle()%>%## Now calculate the spatial frequencies get_sf()
Recompute trajectory-specific velocities
get_traj_velocities( obj_name, time_col = "time_sec", length_col = "position_length", width_col = "position_width", height_col = "position_height", set_init_vel_zero = FALSE, velocity_min = NA, velocity_max = NA)get_traj_velocities( obj_name, time_col="time_sec", length_col="position_length", width_col="position_width", height_col="position_height", set_init_vel_zero=FALSE, velocity_min=NA, velocity_max=NA)
obj_name | The input viewr object; a tibble or data.frame with attribute |
time_col | Name of the column containing time |
length_col | Name of the column containing length dimension |
width_col | Name of the column containing width dimension |
height_col | Name of the column containing height dimension |
set_init_vel_zero | Should the first value be zero or can it be aduplicate of the second velocity value? Defaults to FALSE. |
velocity_min | Should data below a certain velocity be filtered out ofthe object? If so, enter a numeric. If not, keep NA. |
velocity_max | Should data above a certain velocity be filtered out ofthe object? If so, enter a numeric. If not, keep NA. |
Instantaneous velocity is not truly "instantaneous" but rather isapproximated as the change in distance divided by change in time from oneobservation (row) to the previous observation (row). Each component ofvelocity is computed (i.e. per axis) along with the overall velocity ofthe subject.
Ifadd_to_viewr isTRUE, additional columns areappended to the input viewr object. IfFALSE, a standalone tibble iscreated. Either way, an "instantaneous" velocity is computed as thedifference in position divided by the difference in time as each successiverow is encountered. Additionally, velocities along each of the threeposition axes are computed and provided as additional columns.
Vikram B. Baliga
Other mathematical functions:calc_min_dist_v(),deg_2_rad(),find_curve_elbow(),get_2d_angle(),get_3d_angle(),get_3d_cross_prod(),get_dist_point_line(),get_velocity(),rad_2_deg()
Velocity (both overall and per-axis) is computed for each row in the data(see Details)
get_velocity( obj_name, time_col = "time_sec", length_col = "position_length", width_col = "position_width", height_col = "position_height", add_to_viewr = TRUE, velocity_min = NA, velocity_max = NA, ...)get_velocity( obj_name, time_col="time_sec", length_col="position_length", width_col="position_width", height_col="position_height", add_to_viewr=TRUE, velocity_min=NA, velocity_max=NA,...)
obj_name | The input viewr object; a tibble or data.frame with attribute |
time_col | Name of the column containing time |
length_col | Name of the column containing length dimension |
width_col | Name of the column containing width dimension |
height_col | Name of the column containing height dimension |
add_to_viewr | Default TRUE; should velocity data be added as newcolumns or should this function create a new simpler object? |
velocity_min | Should data below a certain velocity be filtered out ofthe object? If so, enter a numeric. If not, keep NA. |
velocity_max | Should data above a certain velocity be filtered out ofthe object? If so, enter a numeric. If not, keep NA. |
... | Additional arguments passed to or from other pathviewr functions. |
Instantaneous velocity is not truly "instantaneous" but rather isapproximated as the change in distance divided by change in time from oneobservation (row) to the previous observation (row). Each component ofvelocity is computed (i.e. per axis) along with the overall velocity ofthe subject.
Ifadd_to_viewr isTRUE, additional columns areappended to the input viewr object. IfFALSE, a standalone tibble iscreated. Either way, an "instantaneous" velocity is computed as thedifference in position divided by the difference in time as each successiverow is encountered. Additionally, velocities along each of the threeposition axes are computed and provided as additional columns.
Vikram B. Baliga and Melissa S. Armstrong
Other mathematical functions:calc_min_dist_v(),deg_2_rad(),find_curve_elbow(),get_2d_angle(),get_3d_angle(),get_3d_cross_prod(),get_dist_point_line(),get_traj_velocities(),rad_2_deg()
## Import the example Motive data included in the packagemotive_data <- read_motive_csv(system.file("extdata", "pathviewr_motive_example_data.csv", package = 'pathviewr'))## Clean the file. It is generally recommended to clean up to the## "standarization" step before running get_velocity(). motive_cleaned <- motive_data %>% relabel_viewr_axes() %>% gather_tunnel_data() %>% trim_tunnel_outliers() %>% rotate_tunnel()## Now compute velocity and add as columns motive_velocity_added <- motive_cleaned %>% get_velocity(add_to_viewr = TRUE)## Or set add_to_viewr to FALSE for a standalone object motive_velocity_standalone <- motive_cleaned %>% get_velocity(add_to_viewr = TRUE)## Import the example Motive data included in the packagemotive_data<- read_motive_csv(system.file("extdata","pathviewr_motive_example_data.csv", package='pathviewr'))## Clean the file. It is generally recommended to clean up to the## "standarization" step before running get_velocity(). motive_cleaned<- motive_data%>% relabel_viewr_axes()%>% gather_tunnel_data()%>% trim_tunnel_outliers()%>% rotate_tunnel()## Now compute velocity and add as columns motive_velocity_added<- motive_cleaned%>% get_velocity(add_to_viewr=TRUE)## Or set add_to_viewr to FALSE for a standalone object motive_velocity_standalone<- motive_cleaned%>% get_velocity(add_to_viewr=TRUE)
Estimate visual angles from a subject's perspective in an experimental tunnel
get_vis_angle(obj_name)get_vis_angle(obj_name)
obj_name | The input viewr object; a tibble or data.frame withattributes |
get_vis_angle() assumes the following:
The subject's gaze is fixed at the point on the either side of the tunnelthat minimizes the distance to visual stimuli and therefore maximizes visualangles.
The subject's head is facing parallel to the length axis of the tunnel.Visual perception functions in future versions of pathviewr will integratehead orientation coordinates.Angles are reported in radians/cycle (vis_angle_pos_rad) anddegrees/cycle (vis_angle_pos_deg).
A tibble or data.frame with added variables forvis_angle_pos_rad,vis_angle_pos_deg,vis_angle_neg_rad,vos_angle_neg_deg,vis_angle_end_rad, andvis_angle_end_deg.
Eric R. Press
Other visual perception functions:calc_min_dist_box(),get_sf()
## Import sample data from packagemotive_data <- read_motive_csv(system.file("extdata", "pathviewr_motive_example_data.csv", package = 'pathviewr'))flydra_data <- read_flydra_mat(system.file("extdata", "pathviewr_flydra_example_data.mat", package = 'pathviewr'), subject_name = "birdie_sanders") ## Process data up to and including get_min_dist()motive_data_full <- motive_data %>% relabel_viewr_axes() %>% gather_tunnel_data() %>% trim_tunnel_outliers() %>% rotate_tunnel() %>% select_x_percent(desired_percent = 50) %>% separate_trajectories(max_frame_gap = "autodetect") %>% get_full_trajectories(span = 0.95) %>% insert_treatments(tunnel_config = "v", perch_2_vertex = 0.4, vertex_angle = 90, tunnel_length = 2, stim_param_lat_pos = 0.1, stim_param_lat_neg = 0.1, stim_param_end_pos = 0.3, stim_param_end_neg = 0.3, treatment = "lat10_end_30") %>% calc_min_dist_v(simplify_output = TRUE) %>% ## Now calculate the visual angles get_vis_angle() flydra_data_full <- flydra_data %>% redefine_tunnel_center(length_method = "middle", height_method = "user-defined", height_zero = 1.44) %>% select_x_percent(desired_percent = 50) %>% separate_trajectories(max_frame_gap = "autodetect") %>% get_full_trajectories(span = 0.95) %>% insert_treatments(tunnel_config = "box", tunnel_length = 3, tunnel_width = 1, stim_param_lat_pos = 0.1, stim_param_lat_neg = 0.1, stim_param_end_pos = 0.3, stim_param_end_neg = 0.3, treatment = "lat10_end_30") %>% calc_min_dist_box() %>% ## Now calculate the visual angles get_vis_angle()## Import sample data from packagemotive_data<- read_motive_csv(system.file("extdata","pathviewr_motive_example_data.csv", package='pathviewr'))flydra_data<- read_flydra_mat(system.file("extdata","pathviewr_flydra_example_data.mat", package='pathviewr'), subject_name="birdie_sanders")## Process data up to and including get_min_dist()motive_data_full<- motive_data%>% relabel_viewr_axes()%>% gather_tunnel_data()%>% trim_tunnel_outliers()%>% rotate_tunnel()%>% select_x_percent(desired_percent=50)%>% separate_trajectories(max_frame_gap="autodetect")%>% get_full_trajectories(span=0.95)%>% insert_treatments(tunnel_config="v", perch_2_vertex=0.4, vertex_angle=90, tunnel_length=2, stim_param_lat_pos=0.1, stim_param_lat_neg=0.1, stim_param_end_pos=0.3, stim_param_end_neg=0.3, treatment="lat10_end_30")%>% calc_min_dist_v(simplify_output=TRUE)%>%## Now calculate the visual angles get_vis_angle() flydra_data_full<- flydra_data%>% redefine_tunnel_center(length_method="middle", height_method="user-defined", height_zero=1.44)%>% select_x_percent(desired_percent=50)%>% separate_trajectories(max_frame_gap="autodetect")%>% get_full_trajectories(span=0.95)%>% insert_treatments(tunnel_config="box", tunnel_length=3, tunnel_width=1, stim_param_lat_pos=0.1, stim_param_lat_neg=0.1, stim_param_end_pos=0.3, stim_param_end_neg=0.3, treatment="lat10_end_30")%>% calc_min_dist_box()%>%## Now calculate the visual angles get_vis_angle()
Likeclean_viewr_batch(), but with import as the first step too
import_and_clean_batch( file_path_list, import_method = c("flydra", "motive"), file_id = NA, subject_name = NULL, frame_rate = NULL, simplify_marker_naming = TRUE, import_messaging = FALSE, ...)import_and_clean_batch( file_path_list, import_method= c("flydra","motive"), file_id=NA, subject_name=NULL, frame_rate=NULL, simplify_marker_naming=TRUE, import_messaging=FALSE,...)
file_path_list | A list of file paths leading to files to be imported. |
import_method | Either "flydra" or "motive" |
file_id | (Optional) identifier for this file. If not supplied, thisdefaults to |
subject_name | For Flydra, the subject name applied to all files |
frame_rate | For Flydra, the frame rate applied to all files |
simplify_marker_naming | For Motive, if Markers are encountered, shouldthey be renamed from "Subject:marker" to "marker"? Defaults to TRUE |
import_messaging | Should this function report each time a file has beenprocessed? |
... | Additional arguments to specify how data should be cleaned. |
viewr objects should be in a list, e.g. the object generated byimport_batch().
Seeclean_viewr() for details of how cleaning steps are handledand/or refer to the corresponding cleaning functions themselves.
A list of viewr objects (tibble or data.frame with attributepathviewr_steps that includes"viewr") that have been passedthrough the corresponding cleaning functions.
Vikram B. Baliga
Other data import functions:as_viewr(),import_batch(),read_flydra_mat(),read_motive_csv()
Other batch functions:bind_viewr_objects(),clean_viewr_batch(),import_batch()
## Since we only have one example file of each type provided## in pathviewr, we will simply import the same example multiple## times to simulate batch importing. Replace the contents of## the following list with your own list of files to be imported.## Make a list of the same example file 3ximport_list <- c(rep( system.file("extdata", "pathviewr_motive_example_data.csv", package = 'pathviewr'), 3 ))## Batch importmotive_batch_imports <- import_batch(import_list, import_method = "motive", import_messaging = TRUE)## Batch cleaning of these imported files## via clean_viewr_batch()motive_batch_cleaned <- clean_viewr_batch( file_announce = TRUE, motive_batch_imports, desired_percent = 50, max_frame_gap = "autodetect", span = 0.95 )## Alternatively, use import_and_clean_batch() to## combine import with cleaning on a batch of filesmotive_batch_import_and_clean <- import_and_clean_batch( import_list, import_method = "motive", import_messaging = TRUE, motive_batch_imports, desired_percent = 50, max_frame_gap = "autodetect", span = 0.95 )## Each of these lists of objects can be bound into## one viewr object (i.e. one tibble) via## bind_viewr_objects()motive_bound_one <- bind_viewr_objects(motive_batch_cleaned)motive_bound_two <- bind_viewr_objects(motive_batch_import_and_clean)## Either route results in the same object ultimately:identical(motive_bound_one, motive_bound_two)## Since we only have one example file of each type provided## in pathviewr, we will simply import the same example multiple## times to simulate batch importing. Replace the contents of## the following list with your own list of files to be imported.## Make a list of the same example file 3ximport_list<- c(rep( system.file("extdata","pathviewr_motive_example_data.csv", package='pathviewr'),3))## Batch importmotive_batch_imports<- import_batch(import_list, import_method="motive", import_messaging=TRUE)## Batch cleaning of these imported files## via clean_viewr_batch()motive_batch_cleaned<- clean_viewr_batch( file_announce=TRUE, motive_batch_imports, desired_percent=50, max_frame_gap="autodetect", span=0.95)## Alternatively, use import_and_clean_batch() to## combine import with cleaning on a batch of filesmotive_batch_import_and_clean<- import_and_clean_batch( import_list, import_method="motive", import_messaging=TRUE, motive_batch_imports, desired_percent=50, max_frame_gap="autodetect", span=0.95)## Each of these lists of objects can be bound into## one viewr object (i.e. one tibble) via## bind_viewr_objects()motive_bound_one<- bind_viewr_objects(motive_batch_cleaned)motive_bound_two<- bind_viewr_objects(motive_batch_import_and_clean)## Either route results in the same object ultimately:identical(motive_bound_one, motive_bound_two)
Import a file and then, akin toclean_viewr, run through as manycleaning steps as desired.
import_and_clean_viewr( file_name, file_id = NA, relabel_viewr_axes = TRUE, gather_tunnel_data = TRUE, trim_tunnel_outliers = TRUE, standardization_option = "rotate_tunnel", get_velocity = TRUE, select_x_percent = TRUE, rename_viewr_characters = FALSE, separate_trajectories = TRUE, get_full_trajectories = TRUE, fill_traj_gaps = FALSE, ...)import_and_clean_viewr( file_name, file_id=NA, relabel_viewr_axes=TRUE, gather_tunnel_data=TRUE, trim_tunnel_outliers=TRUE, standardization_option="rotate_tunnel", get_velocity=TRUE, select_x_percent=TRUE, rename_viewr_characters=FALSE, separate_trajectories=TRUE, get_full_trajectories=TRUE, fill_traj_gaps=FALSE,...)
file_name | Target file |
file_id | Optional |
relabel_viewr_axes | default TRUE, should axes be relabeled? |
gather_tunnel_data | default TRUE, should tunnel data be gathered? |
trim_tunnel_outliers | default TRUE, outliers be trimmed? |
standardization_option | default "rotate_tunnel"; which standardizationoption should be used? See Details for more. |
get_velocity | default TRUE, should velocity be computed? |
select_x_percent | default TRUE, should a region of interest beselected? |
rename_viewr_characters | default FALSE, should subjects be renamed? |
separate_trajectories | default TRUE, should trajectories be defined? |
get_full_trajectories | default TRUE, should only full trajectories beretained? |
fill_traj_gaps | default FALSE, should gaps in trajectories be filled? |
... | Additional arguments passed to the corresponding functions. |
Each argument corresponds to a standalone function inpathviewr. E.g. the parameterrelabel_viewr_axes allows auser to choose whetherpathviewr::relabel_viewr_axes() is runinternally. Should the user desire to use any non-default parameter valuesfor any functions included here, they should be supplied to this functionas additional arguments formatted exactly as they would appear in theircorresponding function(s). E.g. if the "autodetect" feature inpathviewr::separate_trajectories() is desired, add an argumentmax_frame_gap = "autodetect" to the arguments supplied to thisfunction.
A viewr object (tibble or data.frame with attributepathviewr_steps that includes"viewr") that has passedthrough severalpathviewr functions as desired by the user,resulting in data that have been cleaned and ready for analyses.
Vikram B. Baliga
Other all in one functions:clean_viewr()
library(pathviewr)## Import the example Motive data included in the packagemotive_data <- read_motive_csv(system.file("extdata", "pathviewr_motive_example_data.csv", package = 'pathviewr'))motive_full <- motive_data %>% clean_viewr(desired_percent = 50, max_frame_gap = "autodetect", span = 0.95)## Alternatively, used the import_and_clean_viewr()## function to combine these stepsmotive_import_and_clean <- import_and_clean_viewr( file_name = system.file("extdata", "pathviewr_motive_example_data.csv", package = 'pathviewr'), desired_percent = 50, max_frame_gap = "autodetect", span = 0.95 )library(pathviewr)## Import the example Motive data included in the packagemotive_data<- read_motive_csv(system.file("extdata","pathviewr_motive_example_data.csv", package='pathviewr'))motive_full<- motive_data%>% clean_viewr(desired_percent=50, max_frame_gap="autodetect", span=0.95)## Alternatively, used the import_and_clean_viewr()## function to combine these stepsmotive_import_and_clean<- import_and_clean_viewr( file_name= system.file("extdata","pathviewr_motive_example_data.csv", package='pathviewr'), desired_percent=50, max_frame_gap="autodetect", span=0.95)
Batch import of files for either Motive or Flydra (but not a mix of both)
import_batch( file_path_list, import_method = c("flydra", "motive"), file_id = NA, subject_name = NULL, frame_rate = NULL, simplify_marker_naming = TRUE, import_messaging = FALSE, ...)import_batch( file_path_list, import_method= c("flydra","motive"), file_id=NA, subject_name=NULL, frame_rate=NULL, simplify_marker_naming=TRUE, import_messaging=FALSE,...)
file_path_list | A list of file paths |
import_method | Either "flydra" or "motive" |
file_id | Optional |
subject_name | For Flydra, the assigned subject name |
frame_rate | For Flydra, the assigned frame rate |
simplify_marker_naming | default TRUE; for Motive, whether marker namingshould be simplified |
import_messaging | default FALSE; should this function report each timea file has been imported? |
... | Additional arguments (may remove this if needed) |
Refer toread_motive_csv() andread_flydra_mat() fordetails of data import methods.
A list of viewr objects (tibble or data.frame with attributepathviewr_steps that includes"viewr").
Vikram B. Baliga
Other data import functions:as_viewr(),import_and_clean_batch(),read_flydra_mat(),read_motive_csv()
Other batch functions:bind_viewr_objects(),clean_viewr_batch(),import_and_clean_batch()
## Since we only have one example file of each type provided## in pathviewr, we will simply import the same example multiple## times to simulate batch importing. Replace the contents of## the following list with your own list of files to be imported.## Make a list of the same example file 3ximport_list <- c(rep( system.file("extdata", "pathviewr_motive_example_data.csv", package = 'pathviewr'), 3 ))## Batch importmotive_batch_imports <- import_batch(import_list, import_method = "motive", import_messaging = TRUE)## Batch cleaning of these imported files## via clean_viewr_batch()motive_batch_cleaned <- clean_viewr_batch( file_announce = TRUE, motive_batch_imports, desired_percent = 50, max_frame_gap = "autodetect", span = 0.95 )## Alternatively, use import_and_clean_batch() to## combine import with cleaning on a batch of filesmotive_batch_import_and_clean <- import_and_clean_batch( import_list, import_method = "motive", import_messaging = TRUE, motive_batch_imports, desired_percent = 50, max_frame_gap = "autodetect", span = 0.95 )## Each of these lists of objects can be bound into## one viewr object (i.e. one tibble) via## bind_viewr_objects()motive_bound_one <- bind_viewr_objects(motive_batch_cleaned)motive_bound_two <- bind_viewr_objects(motive_batch_import_and_clean)## Either route results in the same object ultimately:identical(motive_bound_one, motive_bound_two)## Since we only have one example file of each type provided## in pathviewr, we will simply import the same example multiple## times to simulate batch importing. Replace the contents of## the following list with your own list of files to be imported.## Make a list of the same example file 3ximport_list<- c(rep( system.file("extdata","pathviewr_motive_example_data.csv", package='pathviewr'),3))## Batch importmotive_batch_imports<- import_batch(import_list, import_method="motive", import_messaging=TRUE)## Batch cleaning of these imported files## via clean_viewr_batch()motive_batch_cleaned<- clean_viewr_batch( file_announce=TRUE, motive_batch_imports, desired_percent=50, max_frame_gap="autodetect", span=0.95)## Alternatively, use import_and_clean_batch() to## combine import with cleaning on a batch of filesmotive_batch_import_and_clean<- import_and_clean_batch( import_list, import_method="motive", import_messaging=TRUE, motive_batch_imports, desired_percent=50, max_frame_gap="autodetect", span=0.95)## Each of these lists of objects can be bound into## one viewr object (i.e. one tibble) via## bind_viewr_objects()motive_bound_one<- bind_viewr_objects(motive_batch_cleaned)motive_bound_two<- bind_viewr_objects(motive_batch_import_and_clean)## Either route results in the same object ultimately:identical(motive_bound_one, motive_bound_two)
Adds information about treatment and experimental set up to viewr objects foranalysis in other pathviewr functions
insert_treatments( obj_name, tunnel_config = "box", perch_2_vertex = NULL, vertex_angle = NULL, tunnel_width = NULL, tunnel_length = NULL, stim_param_lat_pos = NULL, stim_param_lat_neg = NULL, stim_param_end_pos = NULL, stim_param_end_neg = NULL, treatment = NULL)insert_treatments( obj_name, tunnel_config="box", perch_2_vertex=NULL, vertex_angle=NULL, tunnel_width=NULL, tunnel_length=NULL, stim_param_lat_pos=NULL, stim_param_lat_neg=NULL, stim_param_end_pos=NULL, stim_param_end_neg=NULL, treatment=NULL)
obj_name | The input viewr object; a tibble or data.frame with attribute |
tunnel_config | The configuration of the experimental tunnel.Currently, pathviewr supports rectangular "box" and V-shaped tunnelconfigurations. |
perch_2_vertex | If using a V-shaped tunnel, this is the verticaldistance between the vertex and the height of the perches. If the tunnel doesnot have perches, insert the vertical distance between the vertex and theheight of the origin (0,0,0). |
vertex_angle | If using a V-shaped tunnel, the angle of the vertex (indegrees) |
tunnel_width | If using a box-shaped tunnel, the width of the tunnel. |
tunnel_length | The length of the tunnel. |
stim_param_lat_pos | The size of the stimulus on the lateral positivewall of the tunnel. Eg. for 10cm wide gratings, |
stim_param_lat_neg | The size of the stimulus on the lateral negativewall of the tunnel.. |
stim_param_end_pos | The size of the stimulus on the end positivewall of the tunnel. |
stim_param_end_neg | The size of the stimulus on the end negativewall of the tunnel. |
treatment | The name of the treatment assigned to all rows of the viewrobject. Currently only able to accept a single treatment per viewr dataobject. |
All length measurements reported in meters.
A viewr object (tibble or data.frame with attributepathviewr_steps that includes"treatments added"). Dependingon the argumenttunnel_config, the viewr object also includescolumns storing the values of the supplied arguments. This experimentalinformation is also stored in the viewr object's metadata
Eric R. Press
Other utility functions:clean_by_span(),remove_duplicate_frames(),remove_vel_anomalies(),set_traj_frametime()
## Import sample data from package motive_data <- read_motive_csv(system.file("extdata", "pathviewr_motive_example_data.csv", package = 'pathviewr')) flydra_data <- read_flydra_mat(system.file("extdata", "pathviewr_flydra_example_data.mat", package = 'pathviewr'), subject_name = "birdie_sanders") ## Clean data up to and including get_full_trajectories()motive_data_full <- motive_data %>% relabel_viewr_axes() %>% gather_tunnel_data() %>% trim_tunnel_outliers() %>% rotate_tunnel() %>% select_x_percent(desired_percent = 50) %>% separate_trajectories(max_frame_gap = "autodetect") %>% get_full_trajectories(span = 0.95) flydra_data_full <- flydra_data %>% redefine_tunnel_center(length_method = "middle", height_method = "user-defined", height_zero = 1.44) %>% select_x_percent(desired_percent = 50) %>% separate_trajectories(max_frame_gap = "autodetect") %>% get_full_trajectories(span = 0.95)## Now add information about the experimental configuration. In this example,## a V-shaped tunnel in which the vertex is 90deg and lies 0.40m below the## origin. The visual stimuli on the lateral and end walls have a cycle## length of 0.1m and 0.3m respectively, and the treatment is labeled## "lat10_end30"motive_v <-motive_data_full %>% insert_treatments(tunnel_config = "v", perch_2_vertex = 0.4, vertex_angle = 90, tunnel_length = 2, stim_param_lat_pos = 0.1, stim_param_lat_neg = 0.1, stim_param_end_pos = 0.3, stim_param_end_neg = 0.3, treatment = "lat10_end_30")# For an experiment using the box-shaped configuration where the tunnel is 1m# wide and 3m long and the visual stimuli on the lateral and end walls have a# cycle length of 0.2 and 0.3m, respectively, and the treatment is labeled# "lat20_end30".flydra_box <- flydra_data_full %>% insert_treatments(tunnel_config = "box", tunnel_width = 1, tunnel_length = 3, stim_param_lat_pos = 0.2, stim_param_lat_neg = 0.2, stim_param_end_pos = 0.3, stim_param_end_neg = 0.3, treatment = "lat20_end30")## Check out the new columns in the resulting objectsnames(motive_v)names(flydra_box)## Import sample data from package motive_data<- read_motive_csv(system.file("extdata","pathviewr_motive_example_data.csv", package='pathviewr')) flydra_data<- read_flydra_mat(system.file("extdata","pathviewr_flydra_example_data.mat", package='pathviewr'), subject_name="birdie_sanders")## Clean data up to and including get_full_trajectories()motive_data_full<- motive_data%>% relabel_viewr_axes()%>% gather_tunnel_data()%>% trim_tunnel_outliers()%>% rotate_tunnel()%>% select_x_percent(desired_percent=50)%>% separate_trajectories(max_frame_gap="autodetect")%>% get_full_trajectories(span=0.95) flydra_data_full<- flydra_data%>% redefine_tunnel_center(length_method="middle", height_method="user-defined", height_zero=1.44)%>% select_x_percent(desired_percent=50)%>% separate_trajectories(max_frame_gap="autodetect")%>% get_full_trajectories(span=0.95)## Now add information about the experimental configuration. In this example,## a V-shaped tunnel in which the vertex is 90deg and lies 0.40m below the## origin. The visual stimuli on the lateral and end walls have a cycle## length of 0.1m and 0.3m respectively, and the treatment is labeled## "lat10_end30"motive_v<-motive_data_full%>% insert_treatments(tunnel_config="v", perch_2_vertex=0.4, vertex_angle=90, tunnel_length=2, stim_param_lat_pos=0.1, stim_param_lat_neg=0.1, stim_param_end_pos=0.3, stim_param_end_neg=0.3, treatment="lat10_end_30")# For an experiment using the box-shaped configuration where the tunnel is 1m# wide and 3m long and the visual stimuli on the lateral and end walls have a# cycle length of 0.2 and 0.3m, respectively, and the treatment is labeled# "lat20_end30".flydra_box<- flydra_data_full%>% insert_treatments(tunnel_config="box", tunnel_width=1, tunnel_length=3, stim_param_lat_pos=0.2, stim_param_lat_neg=0.2, stim_param_end_pos=0.3, stim_param_end_neg=0.3, treatment="lat20_end30")## Check out the new columns in the resulting objectsnames(motive_v)names(flydra_box)
Plots all trajectories and generates density plots of position by subjectfrom elevation and bird's eye views.
plot_by_subject(obj_name, col_by_treat = FALSE, ...)plot_by_subject(obj_name, col_by_treat=FALSE,...)
obj_name | A viewr object (a tibble or data.frame with attribute |
col_by_treat | If multiple treatments or sessions, color data pertreatment or session. Treatments must be levels in a column named |
... | Additional arguments passed to/from other pathviewr functions. |
The input viewr object should have passed throughseparate_trajectories() orget_full_trajectories().Optionally, treatments should have been added as levels in a column namedtreatment. Two plots will be produced, one from a "bird's eye view"of width against length and one from an "elevation view" of height againstlength. All trajectories will be plotted on a per subject basis, along withdensity plots of width or height depending on the view.col_by_treat = TRUE, data will be plotted by color according totreatment in both the trajectory plots and the density plots.
A "bird's eye view" plot and an "elevation view" plot, made viaggplot2.
Melissa S. Armstrong
Other plotting functions:plot_viewr_trajectories(),visualize_frame_gap_choice()
library(pathviewr)library(ggplot2)library(magrittr)if (interactive()) { ## Import the example Motive data included in the package motive_data <- read_motive_csv(system.file("extdata", "pathviewr_motive_example_data.csv", package = 'pathviewr')) ## Clean, isolate, and label trajectories motive_full <- motive_data %>% clean_viewr(desired_percent = 50, max_frame_gap = "autodetect", span = 0.95) ## Plot all trajectories by subject motive_full %>% plot_by_subject() ## Add treatment information motive_full$treatment <- c(rep("latA", 100), rep("latB", 100), rep("latA", 100), rep("latB", 149)) ## Plot all trajectories by subject, color by treatment motive_full %>% plot_by_subject(col_by_treat = TRUE)}library(pathviewr)library(ggplot2)library(magrittr)if(interactive()){## Import the example Motive data included in the package motive_data<- read_motive_csv(system.file("extdata","pathviewr_motive_example_data.csv", package='pathviewr'))## Clean, isolate, and label trajectories motive_full<- motive_data%>% clean_viewr(desired_percent=50, max_frame_gap="autodetect", span=0.95)## Plot all trajectories by subject motive_full%>% plot_by_subject()## Add treatment information motive_full$treatment<- c(rep("latA",100), rep("latB",100), rep("latA",100), rep("latB",149))## Plot all trajectories by subject, color by treatment motive_full%>% plot_by_subject(col_by_treat=TRUE)}
Plot each trajectory within a viewr object
plot_viewr_trajectories( obj_name, plot_axes = c("length", "width"), multi_plot = FALSE)plot_viewr_trajectories( obj_name, plot_axes= c("length","width"), multi_plot=FALSE)
obj_name | A viewr object (a tibble or data.frame with attribute |
plot_axes | Which position axes should be plotted? A character vectorincluding exactly two of the following choices must be supplied: |
multi_plot | Should separate plots (one per trajectory) be created orshould one multi-plot grid be generated. Defaults to FALSE, which producesseparate plots. |
A (base-R) series of plots or single plot (ifmulti_plot = TRUE) that depict each trajectory along the chosen axes.
Vikram B. Baliga
Other plotting functions:plot_by_subject(),visualize_frame_gap_choice()
library(pathviewr)## Import the example Motive data included in the packagemotive_data <- read_motive_csv(system.file("extdata", "pathviewr_motive_example_data.csv", package = 'pathviewr'))motive_full <- motive_data %>% clean_viewr(desired_percent = 50, max_frame_gap = "autodetect", span = 0.95)plot_viewr_trajectories(motive_full, multi_plot = FALSE)plot_viewr_trajectories(motive_full, multi_plot = TRUE)library(pathviewr)## Import the example Motive data included in the packagemotive_data<- read_motive_csv(system.file("extdata","pathviewr_motive_example_data.csv", package='pathviewr'))motive_full<- motive_data%>% clean_viewr(desired_percent=50, max_frame_gap="autodetect", span=0.95)plot_viewr_trajectories(motive_full, multi_plot=FALSE)plot_viewr_trajectories(motive_full, multi_plot=TRUE)
Mostly meant for internal use but available nevertheless.
quick_separate_trajectories(obj_name, max_frame_gap = 1, ...)quick_separate_trajectories(obj_name, max_frame_gap=1,...)
obj_name | The input viewr object; a tibble or data.frame with attribute |
max_frame_gap | Unlike the corresponding parameter in |
... | Additional arguments passed to/from other pathviewr functions |
This function is designed to separate rows of data into separatelylabeled trajectories.
Themax_frame_gap parameter determines how trajectories will beseparated.max_frame_gap defines the largest permissible gap in databefore a new trajectory is forced to be defined. In this function, only asingle numeric can be supplied to this parameter (unlike the case inseparate_trajectories).
A viewr object (tibble or data.frame with attributepathviewr_steps that includes"viewr") in which a new columnfile_sub_traj is added, which labels trajectories within the data byconcatenating file name, subject name, and a trajectory number (allseparated by underscores).
Vikram B. Baliga
Other data cleaning functions:gather_tunnel_data(),get_full_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()
Other functions that define or clean trajectories:get_full_trajectories(),separate_trajectories(),visualize_frame_gap_choice()
## This function is not recommended for general use.## See separate_trajectories() instead## This function is not recommended for general use.## See separate_trajectories() instead
Convert radians to degrees
rad_2_deg(rad)rad_2_deg(rad)
rad | Radians (a numeric of any length >= 1) |
The angle(s) in degrees (as a numeric vector of the same length)
Vikram B. Baliga
Other mathematical functions:calc_min_dist_v(),deg_2_rad(),find_curve_elbow(),get_2d_angle(),get_3d_angle(),get_3d_cross_prod(),get_dist_point_line(),get_traj_velocities(),get_velocity()
## One inputrad_2_deg(pi/2)## Multiple inputsrad_2_deg(c(pi / 2, pi, 2 * pi))## One inputrad_2_deg(pi/2)## Multiple inputsrad_2_deg(c(pi/2, pi,2* pi))
read_flydra_mat() is designed to import data from a.mat filethat has been exported from Flydra software. The resultant object is a tibblethat additionally has important metadata stored as attributes (see Details).
read_flydra_mat(mat_file, file_id = NA, subject_name, frame_rate = 100, ...)read_flydra_mat(mat_file, file_id=NA, subject_name, frame_rate=100,...)
mat_file | A file (or path to file) in .mat format, exported from Flydra |
file_id | (Optional) identifier for this file. If not supplied, thisdefaults to |
subject_name | Name that will be assigned to the subject |
frame_rate | The capture frame rate of the session |
... | Additional arguments that may be passed from other pathviewrfunctions |
A tibble with numerical data in columns. The first two columns willhave frame numbers and time (assumed to be in secs), respectively. Columns3 through 5 will contain position data. Note that unlike the behavior ofread_motive_csv() this function produces "tidy" data that havealready been gathered into key-value pairs based on subject.
Vikram B. Baliga
read_motive_csv for importing Motive data
Other data import functions:as_viewr(),import_and_clean_batch(),import_batch(),read_motive_csv()
library(pathviewr)## Import the example Flydra data included in the packageflydra_data <- read_flydra_mat(system.file("extdata", "pathviewr_flydra_example_data.mat", package = 'pathviewr'), subject_name = "birdie_wooster")## Names of variables in the resulting tibblenames(flydra_data)## A variety of metadata are stored as attributes. Of particular interest:attr(flydra_data, "pathviewr_steps")library(pathviewr)## Import the example Flydra data included in the packageflydra_data<- read_flydra_mat(system.file("extdata","pathviewr_flydra_example_data.mat", package='pathviewr'), subject_name="birdie_wooster")## Names of variables in the resulting tibblenames(flydra_data)## A variety of metadata are stored as attributes. Of particular interest:attr(flydra_data,"pathviewr_steps")
read_motive_csv() is designed to import data from a CSV that has beenexported from Optitrack's Motive software. The resultant object is a tibblethat additionally has important metadata stored as attributes (see Details).
read_motive_csv(file_name, file_id = NA, simplify_marker_naming = TRUE, ...)read_motive_csv(file_name, file_id=NA, simplify_marker_naming=TRUE,...)
file_name | A file (or path to file) in CSV format |
file_id | (Optional) identifier for this file. If not supplied, thisdefaults to |
simplify_marker_naming | If Markers are encountered, should they berenamed from "Subject:marker" to "marker"? Defaults to TRUE |
... | Additional arguments passed from other |
Usesdata.table::fread() to import data from a CSV file andultimately store it in a tibble. This object is also labeled with theattributepathviewr_steps with valueviewr to indicate that ithas been imported bypathviewr and should be friendly towards use withother functions in our package. Additionally, the following metadata arestored in the tibble's attributes: header information from the Motive CSVfile (header), original IDs for each object (Motive_IDs), thename of each subject in each data column (subject_names_full) andunique values of subject names (subject_names_simple), the type ofdata (rigid body or marker) that appears in each column(data_types_full) and overall (data_types_simple), and originaldata column names in the CSV (d1, d2). See Example below for examplecode to inspect attributes.
A tibble with numerical data in columns. The first two columns willhave frame numbers and time (assumed to be in secs), respectively. Columns 3and beyond will contain the numerical data on the position or rotation ofrigid bodies and/or markers that appear in the Motive CSV file. Each rowcorresponds to the position or rotation of all objects at a given time(frame).
This function was written to read CSVs exported using Motive's Format Version1.23 and is not guaranteed to work with those from other versions. Pleasefile an Issue on our Github page if you encounter any problems.
Vikram B. Baliga
read_flydra_mat for importing Flydra data
Other data import functions:as_viewr(),import_and_clean_batch(),import_batch(),read_flydra_mat()
library(pathviewr)## Import the example Motive data included in the packagemotive_data <- read_motive_csv(system.file("extdata", "pathviewr_motive_example_data.csv", package = 'pathviewr'))## Names of variables in the resulting tibblenames(motive_data)## A variety of metadata are stored as attributes. Of particular interest:attr(motive_data, "pathviewr_steps")attr(motive_data, "file_id")attr(motive_data, "header")attr(motive_data, "Motive_IDs")attr(motive_data, "subject_names_full")attr(motive_data, "subject_names_simple")attr(motive_data, "motive_data_names")attr(motive_data, "motive_data_types_full")attr(motive_data, "motive_data_types_simple")## Of course, all attributes can be viewed as a (long) list via:attributes(motive_data)library(pathviewr)## Import the example Motive data included in the packagemotive_data<- read_motive_csv(system.file("extdata","pathviewr_motive_example_data.csv", package='pathviewr'))## Names of variables in the resulting tibblenames(motive_data)## A variety of metadata are stored as attributes. Of particular interest:attr(motive_data,"pathviewr_steps")attr(motive_data,"file_id")attr(motive_data,"header")attr(motive_data,"Motive_IDs")attr(motive_data,"subject_names_full")attr(motive_data,"subject_names_simple")attr(motive_data,"motive_data_names")attr(motive_data,"motive_data_types_full")attr(motive_data,"motive_data_types_simple")## Of course, all attributes can be viewed as a (long) list via:attributes(motive_data)
Redefine the center(0, 0, 0,) of the tunnel data via translatingpositions along axes.
redefine_tunnel_center( obj_name, axes = c("position_length", "position_width", "position_height"), length_method = c("original", "middle", "median", "user-defined"), width_method = c("original", "middle", "median", "user-defined"), height_method = c("original", "middle", "median", "user-defined"), length_zero = NA, width_zero = NA, height_zero = NA, ...)redefine_tunnel_center( obj_name, axes= c("position_length","position_width","position_height"), length_method= c("original","middle","median","user-defined"), width_method= c("original","middle","median","user-defined"), height_method= c("original","middle","median","user-defined"), length_zero=NA, width_zero=NA, height_zero=NA,...)
obj_name | The input viewr object; a tibble or data.frame with attribute |
axes | Names of axes to be centered |
length_method | Method for length |
width_method | Method for width |
height_method | Method for height |
length_zero | User-defined value |
width_zero | User-defined value |
height_zero | User-defined value |
... | Additional arguments passed to/from other pathviewr functions |
For each_method argument, there are four choices of how centering ishandled: 1) "original" keeps axis as is – this is how width and (possibly)height should be handled for flydra data; 2) "middle" is the middle of therange of data: (min + max) / 2; 3) "median" is the median value of data onthat axis. Probably not recommended; and 4) "user-defined" lets the usercustomize where the (0, 0, 0) point in the tunnel will end up. Each_zero argument is subtracted from its corresponding axis' data.
A viewr object (tibble or data.frame with attributepathviewr_steps that includes"viewr") in which data havebeen translated according to the user's inputs, generally with(0, 0, 0,) being relocated to the center of the tunnel.
Vikram B. Baliga
Other data cleaning functions:gather_tunnel_data(),get_full_trajectories(),quick_separate_trajectories(),relabel_viewr_axes(),rename_viewr_characters(),rotate_tunnel(),select_x_percent(),separate_trajectories(),standardize_tunnel(),trim_tunnel_outliers(),visualize_frame_gap_choice()
Other tunnel standardization functions:rotate_tunnel(),standardize_tunnel()
## Import the Flydra example data included in## the packageflydra_data <- read_flydra_mat( system.file("extdata", "pathviewr_flydra_example_data.mat", package = 'pathviewr'), subject_name = "birdie_wooster" )## Re-center the Flydra data set.## Width will be untouched## Length will use the "middle" definition## And height will be user-defined to be## zeroed at 1.44 on the original axisflydra_centered <- flydra_data %>% redefine_tunnel_center(length_method = "middle", height_method = "user-defined", height_zero = 1.44)## Import the Flydra example data included in## the packageflydra_data<- read_flydra_mat( system.file("extdata","pathviewr_flydra_example_data.mat", package='pathviewr'), subject_name="birdie_wooster")## Re-center the Flydra data set.## Width will be untouched## Length will use the "middle" definition## And height will be user-defined to be## zeroed at 1.44 on the original axisflydra_centered<- flydra_data%>% redefine_tunnel_center(length_method="middle", height_method="user-defined", height_zero=1.44)
Axes are commonly labeled as "x", "y", and "z" in recording software yetpathviewr functions require these to be labeled as "length", "width",and "height".relabel_viewr_axes() is a function that takes aviewr object and allows the user to rename its variables.
relabel_viewr_axes( obj_name, tunnel_length = "_z", tunnel_width = "_x", tunnel_height = "_y", real = "_w", ...)relabel_viewr_axes( obj_name, tunnel_length="_z", tunnel_width="_x", tunnel_height="_y", real="_w",...)
obj_name | The input viewr object; a tibble or data.frame with attribute |
tunnel_length | The dimension that corresponds to tunnel length. Set to |
tunnel_width | The dimension that corresponds to tunnel width. Followsthe same conventions as |
tunnel_height | The dimension that corresponds to tunnel height. Followsthe same conventions as |
real | The dimension that corresponds to the "real" parameter inquaternion notation (for data with "rotation" values). Follows the sameconventions as |
... | Additional arguments to be passed to |
Each argument must have a leading underscore ("_") and eachargument must have an entry. E.g. tunnel_length = "_Y" will replace allinstances of _Y with _length in the names of variables.
A tibble or data.frame with variables that have been renamed.
Vikram B. Baliga
Other data cleaning functions:gather_tunnel_data(),get_full_trajectories(),quick_separate_trajectories(),redefine_tunnel_center(),rename_viewr_characters(),rotate_tunnel(),select_x_percent(),separate_trajectories(),standardize_tunnel(),trim_tunnel_outliers(),visualize_frame_gap_choice()
library(pathviewr)## Import the Motive example data included in the packagemotive_data <- read_motive_csv(system.file("extdata", "pathviewr_motive_example_data.csv", package = 'pathviewr'))## Names of variables are labeled with _x, _y, _z, which we'd like to renamenames(motive_data)## Now use relabel_viewr_axes() to rename these variables using _length,## _width, and _height insteadmotive_data_relabeled <- relabel_viewr_axes(motive_data, tunnel_length = "_z", tunnel_width = "_x", tunnel_height = "_y", real = "_w")## See the resultnames(motive_data_relabeled)library(pathviewr)## Import the Motive example data included in the packagemotive_data<- read_motive_csv(system.file("extdata","pathviewr_motive_example_data.csv", package='pathviewr'))## Names of variables are labeled with _x, _y, _z, which we'd like to renamenames(motive_data)## Now use relabel_viewr_axes() to rename these variables using _length,## _width, and _height insteadmotive_data_relabeled<- relabel_viewr_axes(motive_data, tunnel_length="_z", tunnel_width="_x", tunnel_height="_y", real="_w")## See the resultnames(motive_data_relabeled)
Remove any duplicates or aliased frames within trajectories
remove_duplicate_frames(obj_name)remove_duplicate_frames(obj_name)
obj_name | The input viewr object; a tibble or data.frame with attribute |
The separate_trajectories() and get_full_trajectories() must berun prior to use.
A viewr object (tibble or data.frame with attributepathviewr_steps.
Vikram B. Baliga
Other utility functions:clean_by_span(),insert_treatments(),remove_vel_anomalies(),set_traj_frametime()
Remove any rows which show sharp shifts in velocity that are likely due totracking errors
remove_vel_anomalies( obj_name, target = "velocity", method = "gesd", alpha = 0.05, max_anoms = 0.2)remove_vel_anomalies( obj_name, target="velocity", method="gesd", alpha=0.05, max_anoms=0.2)
obj_name | The input viewr object; a tibble or data.frame with attribute |
target | The column to target; defaults to "velocity" |
method | The anomaly detection method; see anomalize::anomalize() |
alpha | The width of the "normal" range; see anomalize::anomalize() |
max_anoms | The max proportion of anomalies; see anomalize::anomalize() |
This function runs anomalize::anomalize() on a per-trajectory basis.The separate_trajectories() and get_full_trajectories() must be run priorto use.
A viewr object (tibble or data.frame with attributepathviewr_steps. Rows in which large anomalies were detected havebeen removed. No additional columns are created.
Vikram B. Baliga
Other utility functions:clean_by_span(),insert_treatments(),remove_duplicate_frames(),set_traj_frametime()
Quick utility function to use str_replace with mutate(across()) to batch-rename subjects via pattern detection.
rename_viewr_characters( obj_name, target_column = "subject", pattern, replacement = "")rename_viewr_characters( obj_name, target_column="subject", pattern, replacement="")
obj_name | The input viewr object; a tibble or data.frame with attribute |
target_column | The target column; defaults to "subject" |
pattern | The (regex) pattern to be replaced |
replacement | The replacement text. Must be a character |
A tibble or data frame in which subjects have been renamed accordingto thepattern andreplacement supplied by the user.
Vikram B. Baliga
Other data cleaning functions:gather_tunnel_data(),get_full_trajectories(),quick_separate_trajectories(),redefine_tunnel_center(),relabel_viewr_axes(),rotate_tunnel(),select_x_percent(),separate_trajectories(),standardize_tunnel(),trim_tunnel_outliers(),visualize_frame_gap_choice()
## Import the example Motive data included in the packagemotive_data <- read_motive_csv(system.file("extdata", "pathviewr_motive_example_data.csv", package = 'pathviewr'))## Clean the file. It is generally recommended to clean up to the## "gather" step before running rescale_tunnel_data(). motive_gathered <- motive_data %>% relabel_viewr_axes() %>% gather_tunnel_data()## See the subject names unique(motive_gathered$subject)## Now rename the subjects. We'll get rid of "device" and replace it## with "subject"motive_renamed <- motive_gathered %>% rename_viewr_characters(target_column = "subject", pattern = "device", replacement = "subject")## See the new subject namesunique(motive_renamed$subject)## Import the example Motive data included in the packagemotive_data<- read_motive_csv(system.file("extdata","pathviewr_motive_example_data.csv", package='pathviewr'))## Clean the file. It is generally recommended to clean up to the## "gather" step before running rescale_tunnel_data(). motive_gathered<- motive_data%>% relabel_viewr_axes()%>% gather_tunnel_data()## See the subject names unique(motive_gathered$subject)## Now rename the subjects. We'll get rid of "device" and replace it## with "subject"motive_renamed<- motive_gathered%>% rename_viewr_characters(target_column="subject", pattern="device", replacement="subject")## See the new subject namesunique(motive_renamed$subject)
viewr objectShould data have been exported at an incorrect scale, apply an isometrictransformation to the position data and associated mean marker errors (iffound)
rescale_tunnel_data(obj_name, original_scale = 0.5, desired_scale = 1, ...)rescale_tunnel_data(obj_name, original_scale=0.5, desired_scale=1,...)
obj_name | The input viewr object; a tibble or data.frame with attribute |
original_scale | The original scale at which data were exported. SeeDetails if unknown. |
desired_scale | The desired scale |
... | Additional arguments passed to/from other pathviewr functions |
Thedesired_scale is divided by theoriginal_scale todetermine ascale_ratio internally. If theoriginal_scale isnot explicitly known, set it to 1 and then setdesired_scale to bewhatever scaling ratio you have in mind. E.g. settingoriginal_scaleto 1 and thendesired_scale to 0.7 will multiply all position axisvalues by 0.7.
The default arguments oforiginal_scale = 0.5 anddesired_scale = 1 apply a doubling of tunnel size isometrically.
Aviewr object that has position data (andmean_marker_error data, if found) adjusted by the ratio ofdesired_scale/original_scale.
Vikram B. Baliga
## Import the example Motive data included in the packagemotive_data <- read_motive_csv(system.file("extdata", "pathviewr_motive_example_data.csv", package = 'pathviewr'))## Clean the file. It is generally recommended to clean up to the## "gather" step before running rescale_tunnel_data(). motive_gathered <- motive_data %>% relabel_viewr_axes() %>% gather_tunnel_data()## Now rescale the tunnel datamotive_rescaled <- motive_gathered %>% rescale_tunnel_data(original_scale = 0.5, desired_scale = 1)## See the difference in data range e.g. for lengthrange(motive_rescaled$position_length)range(motive_gathered$position_length)## Import the example Motive data included in the packagemotive_data<- read_motive_csv(system.file("extdata","pathviewr_motive_example_data.csv", package='pathviewr'))## Clean the file. It is generally recommended to clean up to the## "gather" step before running rescale_tunnel_data(). motive_gathered<- motive_data%>% relabel_viewr_axes()%>% gather_tunnel_data()## Now rescale the tunnel datamotive_rescaled<- motive_gathered%>% rescale_tunnel_data(original_scale=0.5, desired_scale=1)## See the difference in data range e.g. for lengthrange(motive_rescaled$position_length)range(motive_gathered$position_length)
Specify a minimum number of trajectories that each subject must completeduring a treatment, trial, or session.
rm_by_trajnum( obj_name, trajnum = 5, mirrored = FALSE, treatment1, treatment2, ...)rm_by_trajnum( obj_name, trajnum=5, mirrored=FALSE, treatment1, treatment2,...)
obj_name | The input viewr object; a tibble or data.frame with attribute |
trajnum | Minimum number of trajectories; must be numeric. |
mirrored | Does the data have mirrored treatments? If so, arguments |
treatment1 | The first treatment or session during which the thresholdmust be met. |
treatment2 | A second treatment or session during which the thresholdmust be met. |
... | Additional arguments passed to/from other pathviewr functions. |
Depending on analysis needs, users may want to remove subjects thathave not completed a certain number of trajectories during a treatment,trial, or session. Ifmirrored = FALSE, no treatment information isnecessary and subjects will be removed based on total number of trajectoriesas specified intrajnum. Ifmirrored = TRUE, thetreatment1 andtreatment2 parameters will allow users todefine during which treatments or sessions subjects must reach threshold asspecified in thetrajnum argument. For example, ifmirrored = TRUE, settingtreatment1 = "latA",treatment2 = "latB" andtrajnum = 5 will remove subjects that have fewer than 5 trajectoriesduring the"latA" treatment AND the"latB" treatment.treatment1 andtreatment2 should be levels within a columnnamed"treatment".
A viewr object; a tibble or data.frame with attributepathviewr_steps that includes"viewr" that now has fewerobservations (rows) as a result of removal of subjects with too fewtrajectories according to thetrajnum parameter.
Melissa S. Armstrong
library(pathviewr)## Import the example Motive data included in the packagemotive_data <- read_motive_csv(system.file("extdata", "pathviewr_motive_example_data.csv", package = 'pathviewr'))## Clean, isolate, and label trajectoriesmotive_full <- motive_data %>% clean_viewr(desired_percent = 50, max_frame_gap = "autodetect", span = 0.95)##Remove subjects that have not completed at least 150 trajectories:motive_rm_unmirrored <- motive_full %>% rm_by_trajnum(trajnum = 150)## Add treatment informationmotive_full$treatment <- c(rep("latA", 100), rep("latB", 100), rep("latA", 100), rep("latB", 149))## Remove subjects by that have not completed at least 10 trajectories in## both treatmentsmotive_rm_mirrored <- motive_full %>% rm_by_trajnum( trajnum = 10, mirrored = TRUE, treatment1 = "latA", treatment2 = "latB" )library(pathviewr)## Import the example Motive data included in the packagemotive_data<- read_motive_csv(system.file("extdata","pathviewr_motive_example_data.csv", package='pathviewr'))## Clean, isolate, and label trajectoriesmotive_full<- motive_data%>% clean_viewr(desired_percent=50, max_frame_gap="autodetect", span=0.95)##Remove subjects that have not completed at least 150 trajectories:motive_rm_unmirrored<- motive_full%>% rm_by_trajnum(trajnum=150)## Add treatment informationmotive_full$treatment<- c(rep("latA",100), rep("latB",100), rep("latA",100), rep("latB",149))## Remove subjects by that have not completed at least 10 trajectories in## both treatmentsmotive_rm_mirrored<- motive_full%>% rm_by_trajnum( trajnum=10, mirrored=TRUE, treatment1="latA", treatment2="latB")
The rotation is applied about the height axis and affects tunnel length andwidth only, i.e. no rotation of height.
rotate_tunnel( obj_name, all_heights_min = 0.11, all_heights_max = 0.3, perch1_len_min = -0.06, perch1_len_max = 0.06, perch2_len_min = 2.48, perch2_len_max = 2.6, perch1_wid_min = 0.09, perch1_wid_max = 0.31, perch2_wid_min = 0.13, perch2_wid_max = 0.35, ...)rotate_tunnel( obj_name, all_heights_min=0.11, all_heights_max=0.3, perch1_len_min=-0.06, perch1_len_max=0.06, perch2_len_min=2.48, perch2_len_max=2.6, perch1_wid_min=0.09, perch1_wid_max=0.31, perch2_wid_min=0.13, perch2_wid_max=0.35,...)
obj_name | The input viewr object; a tibble or data.frame with attribute |
all_heights_min | Minimum perch height |
all_heights_max | Maximum perch height |
perch1_len_min | Minimum length value of perch 1 |
perch1_len_max | Maximum length value of perch 1 |
perch2_len_min | Minimum length value of perch 2 |
perch2_len_max | Maximum length value of perch 2 |
perch1_wid_min | Minimum width value of perch 1 |
perch1_wid_max | Maximum width value of perch 1 |
perch2_wid_min | Minimum width value of perch 2 |
perch2_wid_max | Maximum width value of perch 2 |
... | Additional arguments passed to/from other pathviewr functions |
The user first estimates the locations of the perches by specifyingbounds for where each perch is located. The function then computes thecenter of each bounding box and estimates that to be the midpoint of eachperch. Then the center point of the tunnel (center between the perchmidpoints) is estimated. The angle between perch1_center,tunnel_center_point, and arbitrary point along the length axis(tunnel_center_point - 1 on length) is estimated. That angle is then usedto rotate the data, again only in the length and width dimensions. Heightis standardized by (approximate) perch height; values greater than 0 areabove the perch and values less than 0 are below the perch level.
A viewr object (tibble or data.frame with attributepathviewr_steps that includes"viewr") in which data havebeen rotated according to user specifications.
Vikram B. Baliga
Other data cleaning functions:gather_tunnel_data(),get_full_trajectories(),quick_separate_trajectories(),redefine_tunnel_center(),relabel_viewr_axes(),rename_viewr_characters(),select_x_percent(),separate_trajectories(),standardize_tunnel(),trim_tunnel_outliers(),visualize_frame_gap_choice()
Other tunnel standardization functions:redefine_tunnel_center(),standardize_tunnel()
## Import the example Motive data included in the packagemotive_data <- read_motive_csv(system.file("extdata", "pathviewr_motive_example_data.csv", package = 'pathviewr'))## Clean the file. It is generally recommended to clean up to the## "trimmed" step before running rotate_tunnel().motive_trimmed <- motive_data %>% relabel_viewr_axes() %>% gather_tunnel_data() %>% trim_tunnel_outliers()## Now rotate the tunnel using default valuesmotive_rotated <- motive_trimmed %>% rotate_tunnel()## The following attributes store information about## how rotation & translation was appliedattr(motive_rotated, "rotation_degrees")attr(motive_rotated, "rotation_radians")attr(motive_rotated, "perch1_midpoint_original")attr(motive_rotated, "perch1_midpoint_current")attr(motive_rotated, "tunnel_centerpoint_original")attr(motive_rotated, "perch2_midpoint_original")attr(motive_rotated, "perch2_midpoint_current")## Import the example Motive data included in the packagemotive_data<- read_motive_csv(system.file("extdata","pathviewr_motive_example_data.csv", package='pathviewr'))## Clean the file. It is generally recommended to clean up to the## "trimmed" step before running rotate_tunnel().motive_trimmed<- motive_data%>% relabel_viewr_axes()%>% gather_tunnel_data()%>% trim_tunnel_outliers()## Now rotate the tunnel using default valuesmotive_rotated<- motive_trimmed%>% rotate_tunnel()## The following attributes store information about## how rotation & translation was appliedattr(motive_rotated,"rotation_degrees")attr(motive_rotated,"rotation_radians")attr(motive_rotated,"perch1_midpoint_original")attr(motive_rotated,"perch1_midpoint_current")attr(motive_rotated,"tunnel_centerpoint_original")attr(motive_rotated,"perch2_midpoint_original")attr(motive_rotated,"perch2_midpoint_current")
Chop data into X sections (of equal size) along a specified axis
section_tunnel_by(obj_name, axis = "position_length", number_of_sections = 20)section_tunnel_by(obj_name, axis="position_length", number_of_sections=20)
obj_name | The input viewr object; a tibble or data.frame with attribute |
axis | Chosen axis, must match name of column exactly |
number_of_sections | Total number of sections |
The idea is to bin the data along a specified axis, generallyposition_length.
A new column added to the input data object calledsection_id,which is an ordered factor that indicates grouping.
Vikram B. Baliga
## Load data and run section_tunnel_by()test_mat <- read_flydra_mat(system.file("extdata", "pathviewr_flydra_example_data.mat", package = 'pathviewr'), subject_name = "birdie_wooster") %>% redefine_tunnel_center(length_method = "middle", height_method = "user-defined", height_zero = 1.44) %>% select_x_percent(desired_percent = 50) %>% separate_trajectories(max_frame_gap = 1) %>% get_full_trajectories(span = 0.95) %>% section_tunnel_by(number_of_sections = 10)## Plot; color by section IDplot(test_mat$position_length, test_mat$position_width, asp = 1, col = as.factor(test_mat$section_id))## Load data and run section_tunnel_by()test_mat<- read_flydra_mat(system.file("extdata","pathviewr_flydra_example_data.mat", package='pathviewr'), subject_name="birdie_wooster")%>% redefine_tunnel_center(length_method="middle", height_method="user-defined", height_zero=1.44)%>% select_x_percent(desired_percent=50)%>% separate_trajectories(max_frame_gap=1)%>% get_full_trajectories(span=0.95)%>% section_tunnel_by(number_of_sections=10)## Plot; color by section IDplot(test_mat$position_length, test_mat$position_width, asp=1, col= as.factor(test_mat$section_id))
Select data in the middle X percent of the length of the tunnel
select_x_percent(obj_name, desired_percent = 33, ...)select_x_percent(obj_name, desired_percent=33,...)
obj_name | The input viewr object; a tibble or data.frame with attribute |
desired_percent | Numeric, the percent of the total length of the tunnelthat will define the region of interest. Measured from the center outwards. |
... | Additional arguments passed to/from other pathviewr functions |
A viewr object (tibble or data.frame with attributepathviewr_steps that includes"viewr") in which data outsidethe region of interest have been removed.
Vikram B. Baliga
Other data cleaning functions:gather_tunnel_data(),get_full_trajectories(),quick_separate_trajectories(),redefine_tunnel_center(),relabel_viewr_axes(),rename_viewr_characters(),rotate_tunnel(),separate_trajectories(),standardize_tunnel(),trim_tunnel_outliers(),visualize_frame_gap_choice()
motive_data <- read_motive_csv(system.file("extdata", "pathviewr_motive_example_data.csv", package = 'pathviewr'))## Clean the file. It is generally recommended to clean up to the## "trimmed" step before running rotate_tunnel().motive_rotated <- motive_data %>% relabel_viewr_axes() %>% gather_tunnel_data() %>% trim_tunnel_outliers() %>% rotate_tunnel()## Now select the middle 50% of the tunnelmotive_selected <- motive_rotated %>% select_x_percent(desired_percent = 50)## Compare the ranges of lengths to see the effectrange(motive_rotated$position_length)range(motive_selected$position_length)motive_data<- read_motive_csv(system.file("extdata","pathviewr_motive_example_data.csv", package='pathviewr'))## Clean the file. It is generally recommended to clean up to the## "trimmed" step before running rotate_tunnel().motive_rotated<- motive_data%>% relabel_viewr_axes()%>% gather_tunnel_data()%>% trim_tunnel_outliers()%>% rotate_tunnel()## Now select the middle 50% of the tunnelmotive_selected<- motive_rotated%>% select_x_percent(desired_percent=50)## Compare the ranges of lengths to see the effectrange(motive_rotated$position_length)range(motive_selected$position_length)
Separate rows of data into separately labeled trajectories.
separate_trajectories( obj_name, max_frame_gap = 1, frame_rate_proportion = 0.1, frame_gap_messaging = FALSE, frame_gap_plotting = FALSE, ...)separate_trajectories( obj_name, max_frame_gap=1, frame_rate_proportion=0.1, frame_gap_messaging=FALSE, frame_gap_plotting=FALSE,...)
obj_name | The input viewr object; a tibble or data.frame with attribute |
max_frame_gap | Default 1; defines the largest permissible gap in databefore a new trajectory is forced to be defined. Can be either a numericvalue or "autodetect". See Details for more. |
frame_rate_proportion | Default 0.10; if |
frame_gap_messaging | Default FALSE; should frame gaps be reported inthe console? |
frame_gap_plotting | Default FALSE; should frame gap diagnostic plots beshown? |
... | Additional arguments passed to/from other pathviewr functions |
This function is designed to separate rows of data into separatelylabeled trajectories.
Themax_frame_gap parameter determines how trajectories will beseparated. If numeric, the function uses the supplied value as the largestpermissible gap in frames before a new trajectory is defined.
Ifmax_frame_gap = "autodetect" is used, the functionattempts to guesstimate the best value(s) ofmax_frame_gap. This isperformed separately for each subject in the data set, i.e. as manymax_frame_gap values will be estimated as there are unique subjects.The highest possible value of anymax_frame_gap is first set as aproportion of the capture frame rate, as defined by theframe_rate_proportion parameter (default 0.10). For each subject, aplot of total trajectory counts vs. max frame gap values is createdinternally (but can be plotted via settingframe_gap_plotting = TRUE). As larger max frame gaps are allowed,trajectory count will necessarily decrease but may reach a value thatlikely represents the "best" option. The "elbow" of that plot is then usedto find an estimate of the best max frame gap value to use.
A viewr object (tibble or data.frame with attributepathviewr_steps that includes"viewr") in which a new columnfile_sub_traj is added, which labels trajectories within the data byconcatenating file name, subject name, and a trajectory number (allseparated by underscores).
Vikram B. Baliga and Melissa S. Armstrong
Other data cleaning functions:gather_tunnel_data(),get_full_trajectories(),quick_separate_trajectories(),redefine_tunnel_center(),relabel_viewr_axes(),rename_viewr_characters(),rotate_tunnel(),select_x_percent(),standardize_tunnel(),trim_tunnel_outliers(),visualize_frame_gap_choice()
Other functions that define or clean trajectories:get_full_trajectories(),quick_separate_trajectories(),visualize_frame_gap_choice()
## Import the example Motive data included in the packagemotive_data <- read_motive_csv(system.file("extdata", "pathviewr_motive_example_data.csv", package = 'pathviewr'))## Clean the file. It is generally recommended to clean up to the## "select" step before running select_x_percent().motive_selected <- motive_data %>% relabel_viewr_axes() %>% gather_tunnel_data() %>% trim_tunnel_outliers() %>% rotate_tunnel() %>% select_x_percent(desired_percent = 50)## Now separate trajectories using autodetectmotive_separated <- motive_selected %>% separate_trajectories(max_frame_gap = "autodetect", frame_rate_proportion = 0.1)## See new column file_sub_traj for trajectory labelingnames(motive_separated)## Import the example Motive data included in the packagemotive_data<- read_motive_csv(system.file("extdata","pathviewr_motive_example_data.csv", package='pathviewr'))## Clean the file. It is generally recommended to clean up to the## "select" step before running select_x_percent().motive_selected<- motive_data%>% relabel_viewr_axes()%>% gather_tunnel_data()%>% trim_tunnel_outliers()%>% rotate_tunnel()%>% select_x_percent(desired_percent=50)## Now separate trajectories using autodetectmotive_separated<- motive_selected%>% separate_trajectories(max_frame_gap="autodetect", frame_rate_proportion=0.1)## See new column file_sub_traj for trajectory labelingnames(motive_separated)
After a data set has been separated into trajectories, find the earliestframe in each trajectory and set the corresponding time to 0. All subsequenttime_sec stamps are computed according to successive frame numbering.
set_traj_frametime(obj_name)set_traj_frametime(obj_name)
obj_name | The input viewr object; a tibble or data.frame with attribute |
The separate_trajectories() and get_full_trajectories() must berun prior to use. The initial traj_time and traj_frame values are set to 0within each trajectory.
A viewr object (tibble or data.frame with attributepathviewr_steps. New columns include traj_time (thetrajectory-specific time values) and traj_frame (the trajectory-specificframe numbering).
Vikram B. Baliga
Other utility functions:clean_by_span(),insert_treatments(),remove_duplicate_frames(),remove_vel_anomalies()
Similar torotate_tunnel(); rotate and center tunnel data based onlandmarks (specific subjects in the data).
standardize_tunnel( obj_name, landmark_one = "perch1", landmark_two = "perch2", ...)standardize_tunnel( obj_name, landmark_one="perch1", landmark_two="perch2",...)
obj_name | The input viewr object; a tibble or data.frame with attribute |
landmark_one | Subject name of the first landmark |
landmark_two | Subject name of the second landmark |
... | Additional arguments passed to/from other pathviewr functions |
The center point of the tunnel is estimated as the point between thetwo landmarks. It is therefore recommended thatlandmark_one andlandmark_two be objects that are placed on opposite ends of thetunnel (e.g. in an avian flight tunnel, these landmarks may be perches thatare placed at the extreme ends). The angle between landmark_one,tunnel_center_point, and arbitrary point along the length axis(tunnel_center_point - 1 on length) is estimated. That angle is then usedto rotate the data, again only in the length and width dimensions. Heightis standardized by average landmark height; values greater than 0 are abovethe landmarks and values less than 0 are below the landmark level.
A viewr object (tibble or data.frame with attributepathviewr_steps that includes"viewr") in which data havebeen rotated according to the positions of the landmarks in the data.
Theposition_length values of landmark_one MUST be less thantheposition_length values of landmark_two; otherwise,the rotation will apply to a mirror-image of the tunnel
Vikram B. Baliga
Other data cleaning functions:gather_tunnel_data(),get_full_trajectories(),quick_separate_trajectories(),redefine_tunnel_center(),relabel_viewr_axes(),rename_viewr_characters(),rotate_tunnel(),select_x_percent(),separate_trajectories(),trim_tunnel_outliers(),visualize_frame_gap_choice()
Other tunnel standardization functions:redefine_tunnel_center(),rotate_tunnel()
## Example data that would work with this function are## not included in this version of pathviewr. Please## contact the package authors for further guidance## should you need it.## Example data that would work with this function are## not included in this version of pathviewr. Please## contact the package authors for further guidance## should you need it.
The user provides estimates of min and max values of data. This function thentrims out anything beyond these estimates.
trim_tunnel_outliers( obj_name, lengths_min = 0, lengths_max = 3, widths_min = -0.4, widths_max = 0.8, heights_min = -0.2, heights_max = 0.5, ...)trim_tunnel_outliers( obj_name, lengths_min=0, lengths_max=3, widths_min=-0.4, widths_max=0.8, heights_min=-0.2, heights_max=0.5,...)
obj_name | The input viewr object; a tibble or data.frame with attribute |
lengths_min | Minimum length |
lengths_max | Maximum length |
widths_min | Minimum width |
widths_max | Maximum width |
heights_min | Minimum height |
heights_max | Maximum height |
... | Additional arguments passed to/from other pathviewr functions |
Anything supplied to _min or _max arguments should be single numericvalues.
A viewr object (tibble or data.frame with attributepathviewr_steps that includes"viewr") in which data outsidethe specified ranges has been excluded.
Vikram B. Baliga
Other data cleaning functions:gather_tunnel_data(),get_full_trajectories(),quick_separate_trajectories(),redefine_tunnel_center(),relabel_viewr_axes(),rename_viewr_characters(),rotate_tunnel(),select_x_percent(),separate_trajectories(),standardize_tunnel(),visualize_frame_gap_choice()
## Import the example Motive data included in the packagemotive_data <- read_motive_csv(system.file("extdata", "pathviewr_motive_example_data.csv", package = 'pathviewr'))## Clean the file. It is generally recommended to clean up to the## "gather" step before running trim_tunnel_outliers().motive_gathered <- motive_data %>% relabel_viewr_axes() %>% gather_tunnel_data()## Now trim outliers using default valuesmotive_trimmed <- motive_gathered %>% trim_tunnel_outliers(lengths_min = 0, lengths_max = 3, widths_min = -0.4, widths_max = 0.8, heights_min = -0.2, heights_max = 0.5)## Import the example Motive data included in the packagemotive_data<- read_motive_csv(system.file("extdata","pathviewr_motive_example_data.csv", package='pathviewr'))## Clean the file. It is generally recommended to clean up to the## "gather" step before running trim_tunnel_outliers().motive_gathered<- motive_data%>% relabel_viewr_axes()%>% gather_tunnel_data()## Now trim outliers using default valuesmotive_trimmed<- motive_gathered%>% trim_tunnel_outliers(lengths_min=0, lengths_max=3, widths_min=-0.4, widths_max=0.8, heights_min=-0.2, heights_max=0.5)
Run separate_trajectories() with many different frame gaps to help determinewhat value to use
visualize_frame_gap_choice(obj_name, loops = 20, ...)visualize_frame_gap_choice(obj_name, loops=20,...)
obj_name | The input viewr object; a tibble or data.frame with attribute |
loops | How many total frame gap entries to consider. Each loop willincrease the |
... | Additional arguments |
The input viewr object (obj_name) should likely be an objectthat has passed through theselect_x_percent() step.
A plot and a tibble, each of which shows the total number oftrajectories that result from using the specified range ofmax_frame_gap values.
Melissa S. Armstrong and Vikram B. Baliga
Other data cleaning functions:gather_tunnel_data(),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()
Other plotting functions:plot_by_subject(),plot_viewr_trajectories()
Other functions that define or clean trajectories:get_full_trajectories(),quick_separate_trajectories(),separate_trajectories()
library(pathviewr)## Import the example Motive data included in the packagemotive_data <- read_motive_csv(system.file("extdata", "pathviewr_motive_example_data.csv", package = 'pathviewr'))motive_selected <- motive_data %>% relabel_viewr_axes() %>% gather_tunnel_data() %>% trim_tunnel_outliers() %>% rotate_tunnel() %>% get_velocity() %>% select_x_percent(desired_percent = 50)visualize_frame_gap_choice(motive_selected, loops = 10)library(pathviewr)## Import the example Motive data included in the packagemotive_data<- read_motive_csv(system.file("extdata","pathviewr_motive_example_data.csv", package='pathviewr'))motive_selected<- motive_data%>% relabel_viewr_axes()%>% gather_tunnel_data()%>% trim_tunnel_outliers()%>% rotate_tunnel()%>% get_velocity()%>% select_x_percent(desired_percent=50)visualize_frame_gap_choice(motive_selected, loops=10)