R: Internal diveMove Functions

diveMove-internal {diveMove} | R Documentation

## 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 spluque@gmail.com

### 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)

[Package diveMove version 1.5.2 Index]