pathviewr (version 1.1.8)

standardize_tunnel: Rotate and center a tunnel based on landmarks

Description

Similar to rotate_tunnel(); rotate and center tunnel data based on landmarks (specific subjects in the data).

Usage

standardize_tunnel(
  obj_name,
  landmark_one = "perch1",
  landmark_two = "perch2",
  ...
)

Value

A viewr object (tibble or data.frame with attribute pathviewr_steps that includes "viewr") in which data have been rotated according to the positions of the landmarks in the data.

Arguments

obj_name

The input viewr object; a tibble or data.frame with attribute pathviewr_steps that includes "viewr" that has been passed through relabel_viewr_axes() and gather_tunnel_data() (or is structured as though it has been passed through those functions).

landmark_one

Subject name of the first landmark

landmark_two

Subject name of the second landmark

...

Additional arguments passed to/from other pathviewr functions

Warning

The position_length values of landmark_one MUST be less than the position_length values of landmark_two; otherwise, the rotation will apply to a mirror-image of the tunnel

Author

Vikram B. Baliga

Details

The center point of the tunnel is estimated as the point between the two landmarks. It is therefore recommended that landmark_one and landmark_two be objects that are placed on opposite ends of the tunnel (e.g. in an avian flight tunnel, these landmarks may be perches that are 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 used to rotate the data, again only in the length and width dimensions. Height is standardized by average landmark height; values greater than 0 are above the landmarks and values less than 0 are below the landmark level.

See Also

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

Examples

## 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.