tdrply: Apply function to subsets of a TDR dataset

In SESman/rbl: Biologging tools for diving predators in R

Description

tdrply is a functional programing utility to apply functions to specific parts and variables of TDR datasets. It is based on a call to mapply.

Usage

tdrply(f, cl = ., ty = "!_/", no = NULL, la = NULL, no_match = "na",
  obj = ind(), ...)

Arguments

f	function(s) to apply. The function has to be written considering that it's first argument will be a subset of the TDR data (columns according to cl, rows according to ty).
cl	character of numeric, the columns to select in the tdr table. Enter cl = NULL or cl = . (default) to keep all columns.
ty	a kind of regular expression to subset diving periods of tdr table. The pattern can be any part of this dive cycle representation '-!_/~': '-' surface preceding the dive '!' descent of the dive '_' bottom of the dive '/' ascent of the dive '~' surface following the dive Several symbols can be juxtaposed to bluid more complex groups e.g. ty = "!_/" (default which represents a dive). tdrply return the result of f for each group. '&' operator can be used to provide several groups in a same ty expression. '|' operator can be used within a group in order to match a group in priority but provide rescue cases (e.g '-|~' matches '-' first but will also match '~' if '-' is not found). '()' are implemented so '(-|~_)' is different from '(-|~)_').
no	the dive numbers to process. Keep default no = NULL for all dives available in the delim table of obj. Negative values can be used to exlude dives; -0 syntax is accepeted to remove the dive number 0.
la	list of additional arguments of f whose values depend on the period involved.
no_match	how to handle no match or partial match. See last example for details.
obj	a "ses" object.Optional if a default individual has been declared with ind.
...	additional arguments to be passed to f. Arguments passed through ... are recycled for each group defined by ty and no.

See Also

tdrexpand

Examples

data(exses)
ind(exses)

## Apply function to each dive
tdrply(function(x) max(x$depth, na.rm = TRUE))
# or, using "cl" to subset columns and "..." to set "na.rm"
tdrply(max, "depth", na.rm = TRUE)
# other examples with "cl" and "..."
bsm <- tdrply(brokenstick, 1:2, npts = 10)
tdrply(plot, 1:2, no = 33) ; plot(bsm[["!_/#33"]], add = TRUE, enumerate = TRUE)

# use "no" to specify what dive numbers should be processed
(tmp <- tdrply(max, "depth", no = 111, na.rm = FALSE)) # dive no 111 only
tdrply(max, "depth", no = -111, na.rm = FALSE) # all dives but no 111
tdrply(max, "depth", no = exses$stat$max_depth == tmp, na.rm = FALSE) # logicals are accepeted

## How to use "ty": few examples
# apply "f" to each group delimited by &
tdrply(max, "light", ty = "!&_&/", no = 50:51)
# apply "f" previous surface or, if not found, next surface 
tdrply(max, "light", ty = "-|~", no = 50:51)
# mix operators and use parentheses as desired
tdrply(max, "light", ty = "_!&_/&_(-|~)", no = 50:51)
# When "ty" syntax is not enought just give a data frame instead
df <- data.frame(start = seq(1, 5000, 1000), 
                 end = seq(1001, 6000, 1000))
tdrply(max, "depth", df) # notice that names start with "cst" as "custom"
# An id for output names can be provided in third column
(df$id <- sample(10:20, 5, replace = FALSE))
tdrply(max, "depth", df)

## Provide different arguments to each group with "la" (List of Arguments)
opar <- par(no.readonly = TRUE); par(mfrow = c(2, 2))
tdrply(plot, 1:2, no = 50:53, la = list(col = 1:4))
par(opar)

## Not run: 
## tdrply is vectorized over "f"
funs <- c(min_depth = min, max_depth = max)
tmp <- tdrply(funs, "depth", "_", no = 50:53, na.rm = TRUE)
as.data.frame(tmp)

## tdrply is vectorized over "ty" as well
tmp <- tdrply(funs, "depth", c("!", "/", surf = "-~"), no = 50:53, na.rm = TRUE)
as.data.frame(unlist(tmp, recursive = FALSE))

## Assuming that some dive bottom could not be properly defined
exses$delim[exses$delim$no_dive == 111, c("btt_st_idx", "btt_ed_idx")] <- c(NA, NA)
# choose how to handle missing periods using "no_match".
# a warning is printed anyway
tdrply(max, "depth", ty = "_", no = 110:112, no_match = "na") # default
tdrply(max, "depth", ty = "_", no = 110:112, no_match = "ignore")
tdrply(max, "depth", ty = "_", no = 110:112, no_match = "error")
# but not if the missing period can be ignored e.g:
tdrply(max, "depth", ty = "!_/", no = 110:112, no_match = "error")

## End(Not run)

SESman/rbl documentation built on May 9, 2019, 11:10 a.m.