addGps {PAMpal}

Add GPS Locations to an AcousticStudy

Description

Add GPS Lat / Long to an AcousticStudy or AcousticEvent. If GPS data is not present in any of the databases, user will interactively be asked to provide GPS data to add

Usage

addGps(x, gps = NULL, thresh = 3600, ...)

## S4 method for signature 'data.frame'
addGps(x, gps, thresh = 3600, keepDiff = FALSE, ...)

## S4 method for signature 'AcousticEvent'
addGps(x, gps = NULL, thresh = 3600, ...)

## S4 method for signature 'list'
addGps(x, gps = NULL, thresh = 3600, ...)

## S4 method for signature 'AcousticStudy'
addGps(x, gps = NULL, thresh = 3600, ...)

## S4 method for signature 'ANY'
addGps(x, gps = NULL, thresh = 3600, ...)

Arguments

x

data to add GPS coordinates to. Must have a column UTC, and can also have an optional column Channel

gps

a data frame of GPS coordinates to match to data from x. Must have columns UTC, Latitude, Longitude, and optionally Channel. If not provided and x is an AcousticEvent or AcousticStudy object, then the gps data will be read from the databases contained in the files slot of x

thresh

maximum time apart in seconds for matching GPS coordinates to data, if the closest coordinate is more than thresh apart then the Latitude and Longitude values will be set to NA

...

additional arguments for other methods

keepDiff

logical flag to keep time difference column (between GPS time and data time)

Details

Latitude and Longitude coordinates will be matched to the data by interpolating between points in the provided GPS data. After the interpolating is done, the time difference between the matched rows is checked and any that are greater than the set threshold are set to NA. This is done to prevent accidentally matching weird things if an incomplete set of GPS data is provided. An approximate distance between the interpolated points and the closest known GPS point is provided as a "gpsUncertainty" column (distance in meters).

If x is an AcousticEvent or AcousticStudy, then gps can be omitted and will be read from the databases contained in the files slot of x. If x is an AcousticStudy, then the gps data will also be saved to the gps slot of the object, and an additional argument bounds can be provided. This is a length two vector of POSIXct class times that will bound the times of gps data to store, gps data outside this range will not be stored (to reduce the potentially very large amount of data stored in the gps slot)

Value

the same data as x, with Lat/Long data added. AcousticStudy objects will have all GPS data used added to the "gps" slot, and all AcousticEvents will have Latitude and Longitude added to all detector dataframes

Author(s)

Taiki Sakai [e-mail]

Examples

data(exStudy)
# need to update database file to local directory
db <- system.file('extdata', 'Example.sqlite3', package='PAMpal')
exStudy <- updateFiles(exStudy, db=db, bin=NA, verbose=FALSE)
exStudy <- addGps(exStudy)
head(gps(exStudy))