diveMove-internal: Internal diveMove Functions

In diveMove: Dive Analysis and Calibration

Internal diveMove Functions

Description

Functions used for very particular tasks within larger functions in diveMove

Usage

.depthFilter(depth, k, probs, depth.bounds, na.rm)
.derivStats(x, diveNo)
.diveIndices(diveID, diveNo)
.diveMatches(diveID, diveNo)
.getInterval(time)
.speedStats(x, vdist)
.night(time, sunrise.time, sunset.time)
.rleActivity(time, act, interval)
.speedCol(x)
.zoc(time, depth, method, control)

Arguments

depth	Numeric vector with depth in m.
k	Vector of moving window width integers (coerced to integer by .runquantile) to be applied sequentially.
probs	Vector of quantiles to extract at each step indicated by k (so it must be as long as k).
depth.bounds	Numeric vector of length two, with minimum and maximum depth to bound the search for the surface.
na.rm	Should NA values be removed prior to calculating running quantiles?
diveID	Numeric (or character for .diveMatches) vector of all dive and non dive IDs.
diveNo	Numeric vector of unique dive indices to extract from diveID, or x in the case of .derivStats. For .derivStats any duplicates are ignored.
time	POSIXct object representing time.
x	For .speedStats, a matrix with a dive's section data. A single dive's data: 3-col matrix with time, depth, and speed. For .speedCol, a data.frame where names are searched for strings matching .speedNames (see Details). For .derivStats, a TDRcalibrate object.
vdist	Vertical distance travelled during this time. If vdist is missing, then it's all horizontal movements (no angles).
sunrise.time, sunset.time	Passed from plotTDR.
act	A numeric vector indicating the activity for every element of time.
interval	Sampling interval in seconds.
method	Character string to indicate the method to use for zero offset correction. One of “visual”, “offset”, or “filter” (see ‘Details’).
control	Named list of control parameters to be used for ZOC method filter (k, probs, na.rm, depth.bounds) and offset (offset).

Details

These functions are not meant to be called directly by the user, as he/she could not care less (right?). This may change in the future. Nonetheless, they can be called in the usual way for functions that are not exported: diveMove:::.functionName.

.depthFilter performs the zero-offset correction with method=“filter”. It takes a numeric vector and applies a running quantile to it, and the process is repeated zero or more times on the filtered/smooth vector from the previous process.

.derivStats obtains summary statistics (summary() and sd()) of derivatives for descent, bottom, and ascent phases for each dive. It takes a TDRcalibrate object.

.diveIndices takes a numeric vector with sequences of dive numbers, and selects the indices of dive numbers listed uniquely in the vector given as its second argument.

.diveMatches takes a numeric or character vector with sequences of dive numbers, and selects the indices of dive numbers listed uniquely in the vector given as its first argument. Stops if no matches are found, and warns if some were ignored.

.getInterval takes a POSIXct object and calculates the the most frequent interval between successive elements.

.plotTDR is the underlying plotting function for TDR objects. Arguments are documented in the main S4 method (plotTDR).

.plotZOCfilters and plotZOCtdrs are the underlying plotting functions for visually assessing the ZOC procedure. Arguments are documented in the main S4 methods (plotZOC).

.speedStats takes matrix of time and speed, and an optional vector of vertical distance travelled between segments, and calculates the total vertical distance travelled, mean speed, and angle. Input and output correspond to a single section of a dive.

.night takes a POSIXct object, sunrise and sunset time strings to provide a list of sunrise and sunset times for each day in the POSIXct input.

.rleActivity takes a factor indicating different activity phases, their associated time, and the sampling interval to return a factor uniquely identifying each phase of activity, i.e. labelling them. In addition, it returns the duration of each phase, and their beginning and end times.

.speedNames is a character vector with possible names for a speed vector.

.speedCol takes a data.frame and checks whether there is a column with a name matching one of those in .speedNames.

.zoc is the main workhorse for the zero-offset correction ZOC procedure in calibrateDepth. It takes a POSIXct object, corresponding numeric depth vector, a string representing a method to use for the procedure, and a list of control parameters for the chosen method to perform ZOC.

Value

.diveIndices returns a numeric vector with the indices of dives (and their beginning/end indices) in diveID.

.getInterval returns a scalar, the mode of intervals between time readings.

.speedStats returns a 3-column matrix with total distance, mean speed, and angle for a section of a dive.

.night returns a list with sunrise and sunset times for dates in time.

.speedCol returns column number where speed is located in x.

.rleActivity returns a list with components:

• time.br A factor dividing act into different periods of activity.

• time.peract The duration of each period of activity.

• beg.time, end.time POSIXct objects indicating the beginning and ending times of each period of activity.

.zoc returns a vector with all corrected depths based on ‘method’. Depths < 0 are set to 0.

.depthFilter returns a matrix with the filtered depths at each step, and corrected depth as last column, so it has dimensions length(depth) rows by length(k) + 1 columns.

Author(s)

Sebastian P. Luque [e-mail]

Examples

data(divesTDR)

times <- getTime(divesTDR)
depths <- getDepth(divesTDR)

## This can take too long
## .depthFilter

d.filter <- diveMove:::.depthFilter(depth=depths, k=c(3, 5760),
                                    probs=c(0.5, 0.02), depth.bounds=c(0, 5),
                                    na.rm=TRUE)
## Set negative depths to zero
d.filter[d.filter[, 3] < 0, 3] <- 0

## Plotting

idx <- seq(95, 6000)		# try different slices
idx <- seq(nrow(d.filter))
## Look at the top 10 m only plus a few meters above
ylim <- c(-10, 5)

layout(seq(3))
plot(times[idx], -depths[idx], type="l", col="gray",
     ylab="Depth (m)", ylim=ylim)
abline(h=0, lty=2)
legend("topleft", legend="original", lty=1, col="gray")
plot(times[idx], -d.filter[idx, 1], type="l", col=2,
     ylab="Depth (m)", ylim=ylim)
abline(h=0, lty=2)
lines(times[idx], -d.filter[idx, 2])
legend("topleft", legend=colnames(d.filter)[-3],
       lty=1, col=c(2, 1))
plot(times[idx], -d.filter[idx, 3], type="l", ylim=ylim,
     ylab="Depth (m)"); abline(h=0, lty=2)
legend("topleft", legend=paste("Original -", colnames(d.filter)[2]),
       lty=1)

diveMove documentation built on May 29, 2024, 6:43 a.m.