redefine_tunnel_center {pathviewr}

"Center" the tunnel data, i.e. translation but no rotation

Description

Redefine the center (0, 0, 0,) of the tunnel data via translating positions along axes.

Usage

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,
  ...
)

Arguments

obj_name

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

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

Details

For each _method argument, there are four choices of how centering is handled: 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 the range of data: (min + max) / 2; 3) "median" is the median value of data on that axis. Probably not recommended; and 4) "user-defined" lets the user customize where the (0, 0, 0) point in the tunnel will end up. Each _zero argument is subtracted from its corresponding axis' data.

Value

A viewr object (tibble or data.frame with attribute pathviewr_steps that includes "viewr") in which data have been translated according to the user's inputs, generally with (0, 0, 0,) being relocated to the center of the tunnel.

Author(s)

Vikram B. Baliga

See Also

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()

Examples

## Import the Flydra example data included in
## the package
flydra_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 axis
flydra_centered <-
  flydra_data %>%
  redefine_tunnel_center(length_method = "middle",
                         height_method = "user-defined",
                         height_zero = 1.44)