diveMove (version 1.1)

calibrateDepth: Calibrate Depth and Generate a "TDRcalibrate" object

Description

Detect periods of major activities in a TDR record, calibrate depth readings, and generate a TDRcalibrate object essential for subsequent summaries of diving behaviour.

Usage

calibrateDepth(x, dry.thr=70, wet.thr=3610, dive.thr=4,
               zoc.method=c("visual", "offset", "filter"), ...,
               interp.wet=FALSE, descent.crit.q=0.1,
               ascent.crit.q=0.1, wiggle.tol=0.8)

Arguments

x

An object of class TDR for calibrateDepth or an object of class TDRcalibrate for

dry.thr

Dry error threshold in seconds. Dry phases shorter than this threshold will be considered as wet.

wet.thr

Wet threshold in seconds. At-sea phases shorter than this threshold will be considered as trivial wet.

dive.thr

Threshold depth below which an underwater phase should be considered a dive.

zoc.method

Character string to indicate the method to use for zero offset correction. One of visual, offset, or filter (see Details).

...

Arguments required for ZOC methods filter (k, probs, depth.bounds (defaults to range), na.rm (defaults to TRUE)) and offset (offset).

interp.wet

Logical. If TRUE (default is FALSE), then an interpolating spline function is used to impute NA depths in wet periods (after ZOC). Use with caution: it may only be useful in cases where the missing data pattern in wet periods is

descent.crit.q

Critical quantile of rates of descent below which descent is deemed to have ended.

ascent.crit.q

Critical quantile of rates of ascent above which ascent is deemed to have started.

wiggle.tol

Proportion of maximum depth above which wiggles should not be allowed to define the end of descent. It's also the proportion of maximum depth below which wiggles should be considered part of bottom phase.

Value

• An object of class TDRcalibrate.

ZOC

This procedure is required to correct drifts in the pressure transducer of TDR records and noise in depth measurements. Three methods are available to perform this correction.

Method visual calls plotTD, which plots depth and, optionally, speed vs. time with the ability of zooming in and out on time, changing maximum depths displayed, and panning through time. The button to zero-offset correct sections of the record allows for the collection of x and y coordinates for two points, obtained by clicking on the plot region. The first point clicked represents the offset and beginning time of section to correct, and the second one represents the ending time of the section to correct. Multiple sections of the record can be corrected in this manner, by panning through the time and repeating the procedure. In case there's overlap between zero offset corrected windows, the last one prevails.

Method offset can be used when the offset is known in advance, and this value is used to correct the entire time series. Therefore, offset=0 specifies no correction.

Method filter implements a smoothing/filtering mechanism where running quantiles can be applied to depth measurements in a recursive manner, using .depth.filter. It relies on function runquantile from the caTools package. The method calculates the first running quantile defined by probs[1] on a moving window of size k[1]. The next running quantile, defined by probs[2] and k[2], is applied to the smoothed/filtered depth measurements from the previous step, and so on. The corrected depth measurements (d) are calculated as:

$$d=d_{0} - d_{n}$$

where $d_{0}$ is original depth and $d_{n}$ is the last smoothed/filtered depth. This method is under development, but reasonable results can be achieved by applying two filters (see Examples). The default na.rm=TRUE works well when there are no level shifts between non-NA phases in the data, but na.rm=FALSE is better in the presence of such shifts. In other words, there is no reason to pollute the moving window with NAs when non-NA phases can be regarded as a continuum, so splicing non-NA phases makes sense. Conversely, if there are level shifts between non-NA phases, then it is better to retain NA phases to help the algorithm recognize the shifts while sliding the window(s). The search for the surface can be limited to specified bounds during smoothing/filtering, so that observations outside these bounds are interpolated using the bounded smoothed/filtered series.

Once the whole record has been zero-offset corrected, remaining depths below zero, are set to zero, as these are assumed to indicate values at the surface.

Details

This function is really a wrapper around .detPhase, .detDive, and .zoc which perform the work on simplified objects. It performs wet/dry phase detection, zero-offset correction of depth, and detection of dives, as well as proper labelling of the latter.

The procedure starts by first creating a factor with value L (dry) for rows with NAs for depth and value W (wet) otherwise. It subsequently calculates the duration of each of these phases of activity. If the duration of a dry phase (L) is less than dry.thr, then the values in the factor for that phase are changed to W (wet). The duration of phases is then recalculated, and if the duration of a phase of wet activity is less than wet.thr, then the corresponding value for the factor is changed to Z (trivial wet). The durations of all phases are recalculated a third time to provide final phase durations.

Zero-offset correction of depth is performed at this stage (see ZOC below).

Some instruments produce a peculiar pattern of missing data near the surface, at the beginning and/or end of dives. The argument interp.wet may help to rectify this problem by using an interpolating spline function to impute the missing data, constraining the result to a minimum depth of zero. Please note that this optional step is performed after ZOC and before identifying dives, so that interpolation is performed through dry phases coded as wet because their duration was briefer than dry.thr. Therefore, dry.thr must be chosen carefully to avoid interpolation through legitimate dry periods. The next step is to detect dives whenever the zero-offset corrected depth in an underwater phase is below the specified dive threshold. A new factor with finer levels of activity is thus generated, including U (underwater), and D (diving) in addition to the ones described above.

Once dives have been detected and assigned to a period of wet activity, phases within dives are identified using the descent, ascent and wiggle criteria (see Detection of dive phases below). This procedure generates a factor with levels D, DB, B, BA, A, DA, and X, breaking the input into descent, descent/bottom, bottom, bottom/ascent, ascent, and non-dive, respectively.

References

Luque, S.P. and Fried, R. (Submitted) Recursive filtering for zero offset correction of diving depth time series.

See Also

TDRcalibrate, .zoc, .depthFilter .detPhase, .detDive.

Examples

data(divesTDR)
divesTDR

## Consider a 3 m offset, and a dive threshold of 3 m
dcalib <- calibrateDepth(divesTDR, dive.thr=3, zoc.method="offset",
                         offset=3)
## Or ZOC algorithmically with method="filter":
## This can take a while due to large window needed for 2nd
## filter in this dataset
dcalib <- calibrateDepth(divesTDR, dive.thr=3, zoc.method="filter",
                         k=c(3, 5760), probs=c(0.5, 0.02), na.rm=TRUE)
if (dev.interactive(orNone=TRUE)) {
    plotTDR(dcalib, labels="dive.phase", surface=TRUE)
}