tag2animal {tagtools}

Tag-frame to animal-frame conversion

Description

Convert tag frame measurements to animal frame using pre-determined tag orientation(s) on the animal.

Usage

tag2animal(X, sampling_rate, OTAB, Ya = NULL)

Arguments

X

Data from a triaxial sensor such as an accelerometer, magnetometer or a gyroscope. X can be a three column matrix or a sensor structure (not a data frame or tbl). In either case, X is in the tag frame, i.e., expressed in the canonical axes of the tag, not the animal. X can have any unit and any regular sampling rate (i.e., measurements are regularly sampled; equally spaced in time).

sampling_rate

(optional) The sampling rate of the sensor data in Hz (samples per second). This is only needed if X is not a sensor structure. If X is a sensor data list, sampling_rate is obtained from its metadata (X$sampling_rate).

OTAB

is a matrix defining the orientation of the tag on the animal as a function of time. Each row of OTAB is: cue1, cue2, pitch, roll, heading. (See Details.)

Ya

is an optional sensor structure in which the sensor data has already been converted to the animal frame. The OTAB is extracted from this structure. This is useful, for example, to replicate tag-to-animal conversions at different sampling rates.

Details

This function uses the OTAB matrix to convert sensor data X from tag frame of reference to whale frame of reference. Each row of OTAB is: cue1, cue2, pitch, roll, heading where cue1 is the start time of a move in seconds with respect to the start of X. cue2 is the end time of the move. If cue1 and cue2 are the same, the move is instantaneous, otherwise a gradual move will be implemented in which the orientation of the tag is linearly interpolated between the previous and the new orientation. The pitch, roll and heading angles describe the tag orientation on the animal at the end of the move (angles are in radians). The first row of OTAB must have cue1 and cue2 equal to 0 as this is the initial orientation of the tag on the animal. Subsequent rows (if any) of OTAB describe

Value

Xa,the sensor data in the animal frame, i.e., rotated to correct for the tag orientation on the animal. If X is a sensor structure, Xa will also be one. In this case the structure elements 'frame' and 'name' will be changed. The OTAB will also be added to the structure.

See Also

[prh_predictor1], [prh_predictor2]

Examples

Aw <- tag2animal(beaked_whale$A, OTAB = matrix(c(0,0,0.1, 0.04, -0.2), nrow = 1))