processPgDetections {PAMpal}

Load and Process Detections from Pamguard

Description

Loads and processes acoustic detection data that has been run through Pamguard. Uses the binary files and database(s) contained in pps, and will group your data into events by the grouping present in the 'OfflineEvents' and 'Detection Group Localiser' tables (mode = 'db') or by the grouping specified by start and end times in the supplied grouping (mode = 'time'), or by start and end of recording files (mode = 'recording'). Will apply all processing functions in pps to the appropriate modules

Usage

processPgDetections(
  pps,
  mode = c("db", "time", "recording"),
  id = NULL,
  grouping = NULL,
  format = c("%m/%d/%Y %H:%M:%OS", "%m-%d-%Y %H:%M:%OS",
    "%Y/%m/%d %H:%M:%OS", "%Y-%m-%d %H:%M:%OS"),
  progress = TRUE,
  verbose = TRUE,
  ...
)

Arguments

pps

a PAMpalSettings object containing the databases, binaries, and functions to use for processing data. See PAMpalSettings. Can also be an AcousticStudy object, in which case the pps slot will be used.

mode

selector for how to organize your data in to events. db will organize by events based on tables in the databases. time will organize into events based on timestamps provided in grouping. recording will organize events by the start and end times of recording files found in the database. For time and recording, ALL detections between the start and end times are included, for db only selected detections are included.

id

an event name or id for this study, will default to today's date if not supplied (recommended to supply your own informative id)

grouping

For mode = 'db', the table to group events by. Either event to use the OfflineEvents table, or detGroup to use the detection group localiser module groups.

For mode = 'time', this should be a data frame with three mandatory columns and 1 row for each separate event. The mandatory columns are start, end, and id. start and end should specify the start and end time of the event and must be in UTC. id should specify a unique id for each event. There are also optional columns species, db, and sr. species should provide a species ID if it is available. db and sr are the corresponding database and sample rate to associate with a particular event, these typically do not need to be specified as the function will attempt to automatically match them based on the times of the events and the databases. Note that db must be the full filepath to the database. If a clear match is not found then the user will be prompted to either select from a list or input the proper sample rate.

grouping can be supplied either as a data frame or as a filepath to a csv file.

format

the date format for the start and end columns in grouping if it is a csv. Times are assumed to be UTC. See details section of strptime for more information on how to properly format this

progress

logical flog to show progress bars

verbose

logical flag to show messages

...

additional arguments to pass onto to different methods

Details

If mode is not specified, it will try to be automatically determined in the following order. 1) if a grouping data.frame or CSV is provided, then mode='time' will be used. 2) If there are labelled events present in the database, mode='db' will be used. 3) mode='recording' will be used, which should be equivalent to loading all possible data.

Value

an AcousticStudy object with one AcousticEvent for each event in the events slot, and the PAMpalSettings object used stored in the pps slot.

Author(s)

Taiki Sakai [e-mail]

Examples

exPps <- new('PAMpalSettings')
exPps <- addDatabase(exPps, system.file('extdata', 'Example.sqlite3', package='PAMpal'))
exPps <- addBinaries(exPps, system.file('extdata', 'Binaries', package='PAMpal'))
exClick <- function(data) {
    standardClickCalcs(data, calibration=NULL, filterfrom_khz = 0)
}
exPps <- addFunction(exPps, exClick, module = 'ClickDetector')
exPps <- addFunction(exPps, roccaWhistleCalcs, module='WhistlesMoans')
exPps <- addFunction(exPps, standardCepstrumCalcs, module = 'Cepstrum')
# process events labelled within the Pamguard database
exStudyDb <- processPgDetections(exPps, mode='db', id='Example')
# can also give an AcousticStudy as input and it will use same functions and data
reprocess <- processPgDetections(exStudyDb, mode='db', id='Reprocess')
# process events with manually set start/end times
grp <- data.frame(start = as.POSIXct('2018-03-20 15:25:10', tz='UTC'),
                  end = as.POSIXct('2018-03-20 15:25:11', tz='UTC'),
                  id = 'GroupExample')
exStudyTime <- processPgDetections(exPps, mode='time', grouping=grp, id='Time')
# process events by recording event
exStudyRecording <- processPgDetections(exPps, mode='recording', id='Recording')