Skip to contents

Estimate the forward speed of a diving animal

Source: R/speed_from_depth.R
speed_from_depth.Rd

This function is used to estimate the forward speed of a diving animal by first computing the depth-rate (i.e., the first differential of the depth) and then correcting for the pitch angle.

Usage

speed_from_depth(
  p,
  A = NULL,
  fs_p = NULL,
  fs_A = NULL,
  fc = 0.2,
  plim = 20/180 * pi
)

Arguments

p

The depth vector (a regularly sampled time series) in meters. sampled at sampling_rate Hz. This can either be an animaltags sensor list, or a vector.

A

(optional) A matrix or animaltags sensor data list containing acceleration data. If A is not provided then only vertical velocity is returned (same output as depth_rate()). Acceleration can be in any consistent unit, e.g., g or m/s^2. Acceleration data must have the same number of rows as p.

fs_p

(optional) The sampling rate of p in Hz (samples per second). Required only if p is vector rather than sensor data list.

fs_A

(optional) The sampling rate of A in Hz (samples per second). Required only if A is vector rather than sensor data list.

fc

(optional) Specifies the cut-off frequency of a low-pass filter to apply to p after computing depth-rate and to A before computing pitch. The filter cut-off frequency is in Hz. The filter length is 4*sampling_rate/fc. Filtering adds no group delay. If fc is empty or not given, the default value of 0.2 Hz (i.e., a 5 second time constant) is used.

plim

(optional) Minimum pitch angle, in radians, at which speed can be computed. Default: 0.3490659 radians = 20 degrees. Errors in speed estimation using this method increase strongly at low pitch angles. To avoid estimates with poor accuracy being used in later analyses, speed estimates at low pitch angles are replaced by NaN (not-a-number). The default threshold for this is 20 degrees.

Value

Either forward speed or vertical speed:

  • s: If both p and A are input, the forward speed estimate in m/s is returned

  • v: If only p is input, the depth-rate (or vertical velocity) in m/s is returned

Note

Output sampling rate is the same as the input sampling rate. If A and p are input and A has a higher sampling rate, then p and the output are interpolated to match A using interp2length .

Frame: This function assumes a [north,east,up] navigation frame and a [forward,right,up] local frame. In these frames, a positive pitch angle is an anti-clockwise rotation around the y-axis. A descending animal will have a negative pitch angle.

Forward velocity for animals could be negative if its vertical velocity is negative and pitch angle is positive, or, its vertical velocity is positive and pitch angle is negative. One could avoid getting negative forward velocity by taking the absolute value of the output.

Examples

s <- speed_from_depth(harbor_seal$P, harbor_seal$A)