matchTimeData {PAMpal}

Match time-based data to PAMpal objects

Description

Match any time-based data (dataframe with a UTC column) to an AcousticStudy or AcousticEvent object

Usage

matchTimeData(
  x,
  data,
  mode = c("event", "detection"),
  thresh = Inf,
  interpolate = TRUE,
  replace = FALSE,
  keepDiff = FALSE
)

timeJoin(x, y, thresh = Inf, interpolate = TRUE, replace = FALSE)

Arguments

x

AcousticStudy or AcousticEvent object to match data to, or a dataframe for timeJoin

data

a data frame to match to data to x. Must have column UTC, and optionally a column db if subsets of data should be matched only to parts of x with that database. All other columns will be considered variables to add to x

mode

one of "event" or "detection". "event" will match one set of variables per event, stored in the "measures" for that event. "detection" will match variables to every detection.

thresh

maximum time apart in seconds for matching to data, if the closest value is more than thresh apart then the variable values will be set to NA

interpolate

logical flag whether or not to interpolate between points in data or just matched to nearest time

replace

one of TRUE, FALSE, or NA. If TRUE, all existing values with the same name as columns in data will be replaced. If FALSE no replacement occurs. If NA only values which are NA will be replaced with new values

keepDiff

logical flag to keep time difference data

y

dataframe to join to x

Details

This function lets you match any arbitrary data to a PAMpal object as long as it has a time associated with it. Data will be attached to detector dataframes for mode='detection' or to the event "measures" location for mode='event' (this is where calculateICI and matchEnvData,AcousticStudy-method store their event data). These can be accessed with the getMeasures function and are also exported in the various "getXXX" functions (getClickData etc.) if measures=TRUE (default).

All columns in the provided data object will be treated as variables to add, with a few exceptions. There are a few reserved column names used by PAMpal that cannot be overridden (e.g. UID, eventId, species). Also any columns already existing in the PAMpal data will not be overridden unless replace is not FALSE. The column names in data will be used as the names for the added variables, so care should be taken to ensure these are informative enough for future use.

Value

the same data as x, with data added from data

Author(s)

Taiki Sakai [e-mail]

Examples

data(exStudy)
addData <- data.frame(UTC = as.POSIXct('2018-03-20 15:25:10', tz='UTC'),
                      newVariable = 26)
data <- matchTimeData(exStudy, addData, mode='detection')
getClickData(data)
data <- matchTimeData(exStudy, addData, mode='event')
getMeasures(data)