mt_align {mousetrap}

Align trajectories.

Description

mt_align aligns trajectories to a common start point, end point, and / or coordinate system.

Usage

mt_align(
  data,
  use = "trajectories",
  save_as = use,
  dimensions = c("xpos", "ypos"),
  coordinates = "isotropic",
  align_start = FALSE,
  align_end = FALSE,
  align_side = "no",
  verbose = FALSE
)

Arguments

data

a mousetrap data object created using one of the mt_import functions (see mt_example for details). Alternatively, a trajectory array can be provided directly (in this case use will be ignored).

use

a character string specifying which trajectory data should be used.

save_as

a character string specifying where the resulting trajectory data should be stored.

dimensions

a character string specifying which trajectory variables should be used. Can be of length 2 or 3 for two-dimensional or three-dimensional alignment respectively.

coordinates

either a numeric vector of length 4 specifying the xstart, ystart, xend, yend coordinates of the trajectory start and end points. Can also be isotropic (the default) to preserve the coordinates of dim1 and dim2, isotropic-norm to set the coordinates to c(0,0,-1,x) where x is chosen to preserve the aspect ratio of dim1 and dim2, mt to set coordinates to c(0,0,-1,1.5), norm to set coordinates to c(0,0,-1,1), and wide to set coordinates to c(0,0,-1,1.2). In the three-dimensional case, coordinates is a vector of length 6.

align_start

boolean specifying whether the start points of all trajectories should be aligned to the position specified in coordinates. See Details.

align_end

boolean specifying whether the end points of all trajectories should be aligned to the position specified in coordinates. See Details.

align_side

character string specifying whether all trajectories should be flipped to the left side (left), the right side (right), or not at all (no). Assumes that first entry in dimensions are the x positions.

verbose

logical indicating whether function should report its progress.

Details

If align_start / align_end is FALSE, coordinates define the position of the average start / end point across all trajectories.

Note that if the end points of trajectories are not aligned, coordinates refer to the hypothetical case where all trajectories are mapped to one side.

If align_start / align_end is TRUE, the start / end point of each trajectory is set to the exact position specified in coordinates. align_start and align_end can be set completely independently of one another, i.e., one can align only end points, only start points, none, or both.

If align_start is set to "left" or "right" trajectories will be flipped to the lower or upper spectrum of the first dimensions, respectively. If the first dimension is the x-coordinate this is equivalent to flipping the trajectories to the left and right side, respectively.

Value

A mousetrap data object (see mt_example) with aligned trajectories. Per default, the dimensions in the original trajectory array will be replaced. If a different trajectory array is specified using save_as, a new trajectory array will be created (including only the aligned dimensions). If a trajectory array was provided directly as data, only the aligned trajectories will be returned.

Author(s)

Dirk U. Wulff

See Also

mt_align_start for aligning all trajectories to a common start position.

mt_align_start_end for aligning all trajectories so that they share a common initial and final coordinate.

mt_remap_symmetric for remapping trajectories to one side (or one quadrant) of the coordinate system.

Examples

mt_example <- mt_align(mt_example,
  align_start = TRUE, align_end = TRUE,
  coordinates = 'mt')