BioAcoustic EveNT ClassifiER

Description

banter

References

Rankin, S. , Archer, F. , Keating, J. L., Oswald, J. N., Oswald, M. , Curtis, A. and Barlow, J. (2017), Acoustic classification of dolphins in the California Current using whistles, echolocation clicks, and burst pulses. Marine Mammal Science 33:520-540. doi:10.1111/mms.12381

Detector randomForest function

Description

Detector randomForest function

Checks to make sure 'x' contains syntactically valid and unique characters

Checks to make sure 'model' is a valid model name x is a banter_model object

Check that detectors are present x is a banter_model object

Produces a vector of equal sample sizes for balanced Random Forest model. x is a vector of species or table of species frequencies n is desired sample size

Returns matrix of mean species vote percentage by event x is a list of data.frames with species probability assignments

Usage

.rfFuncDetector(params)

.checkValidStrings(x, label)

.checkModelName(x, model)

.stopIfNoDetectors(x)

.getSampsize(x, n, warn.label)

.meanVotes(x)

Add a BANTER Detector Model

Description

Add a detector model to a BANTER classifier.

Usage

addBanterDetector(
  x,
  data,
  name,
  ntree,
  sampsize = 1,
  importance = FALSE,
  num.cores = 1
)

removeBanterDetector(x, name)

Arguments

Value

a banter_model object with the detector model added or removed.

Author(s)

Eric Archer eric.archer@noaa.gov

References

Rankin, S., Archer, F., Keating, J. L., Oswald, J. N., Oswald, M. , Curtis, A. and Barlow, J. (2017), Acoustic classification of dolphins in the California Current using whistles, echolocation clicks, and burst pulses. Marine Mammal Science 33:520-540. doi:10.1111/mms.12381

Examples

data(train.data)
# initialize BANTER model with event data
bant.mdl <- initBanterModel(train.data$events)
# add the 'bp' (burst pulse) detector model
bant.mdl <- addBanterDetector(
  x = bant.mdl, 
  data = train.data$detectors$bp, 
  name = "bp",
  ntree = 50, sampsize = 1, num.cores = 1
)
bant.mdl

# remove the 'bp' detector model
bant.mdl <- removeBanterDetector(bant.mdl, "bp")
bant.mdl

BANTER Guide

Description

Open a browser window displaying "BANTER: A User’s Guide to Acoustic Classification".

Usage

banterGuide()

Author(s)

Eric Archer eric.archer@noaa.gov

References

Rankin, S. , Archer, F. , Keating, J. L., Oswald, J. N., Oswald, M. , Curtis, A. and Barlow, J. (2017), Acoustic classification of dolphins in the California Current using whistles, echolocation clicks, and burst pulses. Marine Mammal Science 33:520-540. doi:10.1111/mms.12381

Detector classification model

Description

Create classification model for a detector

Slots

name

detector name

ids

data.frame of event.ids and call.ids for calls in detector

model

classification model

sampsize

sample size vector used in model

timestamp

start and stop times of model run

Author(s)

Eric Archer eric.archer@noaa.gov

Events classification model

Description

Create classification model for events

Slots

data

data.frame of event.ids and call.ids for calls in detector

detectors

list of detector_model objects

model.data

data used to create classification model

model

classification model

sampsize

sample size vector used in model

timestamp

start and stop times of model run

Author(s)

Eric Archer eric.archer@noaa.gov

Extract Random Forest Model

Description

Extract BANTER event or detector Random Forest model.

Usage

getBanterModel(x, model = "event")

Arguments

Value

a randomForest model object.

Author(s)

Eric Archer eric.archer@noaa.gov

References

Rankin, S. , Archer, F. , Keating, J. L., Oswald, J. N., Oswald, M. , Curtis, A. and Barlow, J. (2017), Acoustic classification of dolphins in the California Current using whistles, echolocation clicks, and burst pulses. Marine Mammal Science 33:520-540. doi:10.1111/mms.12381

Examples

data(train.data)
# initialize BANTER model with event data
bant.mdl <- initBanterModel(train.data$events)
# add all detector models
bant.mdl <- addBanterDetector(
  bant.mdl, train.data$detectors, 
  ntree = 50, sampsize = 1, num.cores = 1
)
# run BANTER event model
bant.mdl <- runBanterModel(bant.mdl, ntree = 1000, sampsize = 1)

# extract the event randomForest model
event.rf <- getBanterModel(bant.mdl)
event.rf

# extract the burst pulse (bp) detector model
bp.rf <- getBanterModel(bant.mdl, "bp")
bp.rf

Extract Random Forest Model Data

Description

Extract BANTER event data used for the Random Forest model.

Usage

getBanterModelData(x)

Arguments

Value

the event data frame used to build the input model x.

Author(s)

Eric Archer eric.archer@noaa.gov

References

Rankin, S. , Archer, F. , Keating, J. L., Oswald, J. N., Oswald, M. , Curtis, A. and Barlow, J. (2017), Acoustic classification of dolphins in the California Current using whistles, echolocation clicks, and burst pulses. Marine Mammal Science 33:520-540. doi:10.1111/mms.12381

Examples

data(train.data)
# initialize BANTER model with event data
bant.mdl <- initBanterModel(train.data$events)
# add all detector models
bant.mdl <- addBanterDetector(
  bant.mdl, train.data$detectors, 
  ntree = 50, sampsize = 1, num.cores = 1
)
# run BANTER event model
bant.mdl <- runBanterModel(bant.mdl, ntree = 1000, sampsize = 1)

event.df <- getBanterModelData(bant.mdl)
head(event.df)

Detector Names

Description

Return names of detectors loaded in BANTER model.

Usage

getDetectorNames(x)

Arguments

Value

a vector of names.

Author(s)

Eric Archer eric.archer@noaa.gov

References

Rankin, S. , Archer, F. , Keating, J. L., Oswald, J. N., Oswald, M. , Curtis, A. and Barlow, J. (2017), Acoustic classification of dolphins in the California Current using whistles, echolocation clicks, and burst pulses. Marine Mammal Science 33:520-540. doi:10.1111/mms.12381

Examples

data(train.data)
# initialize BANTER model with event data
bant.mdl <- initBanterModel(train.data$events)
# add all detector models
bant.mdl <- addBanterDetector(
  bant.mdl, train.data$detectors, 
  ntree = 50, sampsize = 1, num.cores = 1
)
getDetectorNames(bant.mdl)

Sample Size

Description

Return sample sizes used for a BANTER model.

Usage

getSampSize(x, model = "event")

Arguments

Value

a vector of sample sizes.

Author(s)

Eric Archer eric.archer@noaa.gov

References

Rankin, S. , Archer, F. , Keating, J. L., Oswald, J. N., Oswald, M. , Curtis, A. and Barlow, J. (2017), Acoustic classification of dolphins in the California Current using whistles, echolocation clicks, and burst pulses. Marine Mammal Science 33:520-540. doi:10.1111/mms.12381

Examples

data(train.data)
# initialize BANTER model with event data
bant.mdl <- initBanterModel(train.data$events)
# add all detector models
bant.mdl <- addBanterDetector(
  bant.mdl, train.data$detectors, 
  ntree = 50, sampsize = 2, num.cores = 1
)
# run BANTER event model
bant.mdl <- runBanterModel(bant.mdl, ntree = 1000, sampsize = 1)

# sample size for the event model
getSampSize(bant.mdl)

# sample size for the burst pulse (bp) detector model
getSampSize(bant.mdl, "bp")

Initialize BANTER model

Description

Initialize a BANTER model with event data.

Usage

initBanterModel(x)

Arguments

Value

a banter_model object without any detector models.

Note

Values in the column species are passed through the make.names function on creation to ensure they don't include invalid characters.

Author(s)

Eric Archer eric.archer@noaa.gov

References

Rankin, S. , Archer, F. , Keating, J. L., Oswald, J. N., Oswald, M. , Curtis, A. and Barlow, J. (2017), Acoustic classification of dolphins in the California Current using whistles, echolocation clicks, and burst pulses. Marine Mammal Science 33:520-540. doi:10.1111/mms.12381

Examples

data(train.data)
# initialize BANTER model with event data
bant.mdl <- initBanterModel(train.data$events)
bant.mdl

Model Percent Correct

Description

Extract percent correctly classified by species for detector and event models.

Usage

modelPctCorrect(x)

Arguments

Value

a data.frame with the percent correctly classified for each model in x.

Author(s)

Eric Archer eric.archer@noaa.gov

References

Rankin, S. , Archer, F. , Keating, J. L., Oswald, J. N., Oswald, M. , Curtis, A. and Barlow, J. (2017), Acoustic classification of dolphins in the California Current using whistles, echolocation clicks, and burst pulses. Marine Mammal Science 33:520-540. doi:10.1111/mms.12381

Examples

data(train.data)
# initialize BANTER model with event data
bant.mdl <- initBanterModel(train.data$events)
# add all detector models
bant.mdl <- addBanterDetector(
  bant.mdl, train.data$detectors, 
  ntree = 50, sampsize = 1, num.cores = 1
)
# run BANTER event model
bant.mdl <- runBanterModel(bant.mdl, ntree = 1000, sampsize = 1)
modelPctCorrect(bant.mdl)

Number and Proportion of Calls

Description

Return the number and proportion of calls in BANTER detector models.

Usage

numCalls(x, by = c("species", "event"))

propCalls(x, by = c("species", "event"))

Arguments

Author(s)

Eric Archer eric.archer@noaa.gov

References

Rankin, S. , Archer, F. , Keating, J. L., Oswald, J. N., Oswald, M. , Curtis, A. and Barlow, J. (2017), Acoustic classification of dolphins in the California Current using whistles, echolocation clicks, and burst pulses. Marine Mammal Science 33:520-540. doi:10.1111/mms.12381

Examples

data(train.data)
# initialize BANTER model with event data
bant.mdl <- initBanterModel(train.data$events)
# add all detector models
bant.mdl <- addBanterDetector(
  bant.mdl, train.data$detectors, 
  ntree = 50, sampsize = 1, num.cores = 1
)
# run BANTER event model
bant.mdl <- runBanterModel(bant.mdl, ntree = 1000, sampsize = 1)

# number of calls by species and event
numCalls(bant.mdl, "species")
numCalls(bant.mdl, "event")

# proportion of calls by species and event
propCalls(bant.mdl, "species")
propCalls(bant.mdl, "event")

Number of Events

Description

Return the number of events in a BANTER model by species.

Usage

numEvents(x, model = "event")

Arguments

Value

a data.frame giving the number of events available for each species.

Author(s)

Eric Archer eric.archer@noaa.gov

References

Rankin, S. , Archer, F. , Keating, J. L., Oswald, J. N., Oswald, M. , Curtis, A. and Barlow, J. (2017), Acoustic classification of dolphins in the California Current using whistles, echolocation clicks, and burst pulses. Marine Mammal Science 33:520-540. doi:10.1111/mms.12381

Examples

data(train.data)
# initialize BANTER model with event data
bant.mdl <- initBanterModel(train.data$events)
# add all detector models
bant.mdl <- addBanterDetector(
  bant.mdl, train.data$detectors, 
  ntree = 50, sampsize = 1, num.cores = 1
)
# run BANTER event model
bant.mdl <- runBanterModel(bant.mdl, ntree = 1000, sampsize = 1)

# number of events in event model
numEvents(bant.mdl)

# number of events in burst pulse (bp) detector model
numEvents(bant.mdl, "bp")

Plot BANTER Detector Traces

Description

Plot traces of OOB error rates for detector Random Forest models.

Usage

plotDetectorTrace(x, detector = NULL)

Arguments

Author(s)

Eric Archer eric.archer@noaa.gov

References

Rankin, S. , Archer, F. , Keating, J. L., Oswald, J. N., Oswald, M. , Curtis, A. and Barlow, J. (2017), Acoustic classification of dolphins in the California Current using whistles, echolocation clicks, and burst pulses. Marine Mammal Science 33:520-540. doi:10.1111/mms.12381

See Also

plotTrace

Examples

data(train.data)
# initialize BANTER model with event data
bant.mdl <- initBanterModel(train.data$events)
# add all detector models
bant.mdl <- addBanterDetector(
  bant.mdl, train.data$detectors, 
  ntree = 50, sampsize = 1, num.cores = 1
)

plotDetectorTrace(bant.mdl)

Predict BANTER events

Description

Predict species of events for novel data from a BANTER model.

Usage

predict(object, ...)

## S3 method for class 'banter_model'
predict(object, new.data, ...)

## S4 method for signature 'banter_model'
predict(object, new.data, ...)

Arguments

Value

A list with the following elements:

events

the data frame used in the event model for predictions.

predict.df

data.frame of predicted species and assignment probabilities for each event.

detector.freq

data.frame giving the number of events available for each detector.

validation.matrix

if species is a column in new.data, a table giving the classification rate for each event

Note

At least one detector in the model must be present in new.data. Any detectors in the training model that are absent will have all species proportions and the the detector propoprtion set to 0. If a column called species is in new.data, columns for the original species designation and if that matches predicted (correct) will be added to the predict.df data.frame of the output.

Author(s)

Eric Archer eric.archer@noaa.gov

References

Rankin, S. , Archer, F. , Keating, J. L., Oswald, J. N., Oswald, M. , Curtis, A. and Barlow, J. (2017), Acoustic classification of dolphins in the California Current using whistles, echolocation clicks, and burst pulses. Marine Mammal Science 33:520-540. doi:10.1111/mms.12381

Examples

data(train.data)
# initialize BANTER model with event data
bant.mdl <- initBanterModel(train.data$events)
# add all detector models
bant.mdl <- addBanterDetector(
  bant.mdl, train.data$detectors, 
  ntree = 50, sampsize = 2, num.cores = 1
)
# run BANTER event model
bant.mdl <- runBanterModel(bant.mdl, ntree = 1000, sampsize = 1)

# predict test data
data(test.data)
test.pred <- predict(bant.mdl, test.data)
test.pred

Run BANTER Model

Description

Build full event classifier model

Usage

runBanterModel(x, ntree, sampsize = 1)

Arguments

Value

a banter_model object with the complete BANTER model.

Author(s)

Eric Archer eric.archer@noaa.gov

References

Rankin, S., Archer, F., Keating, J. L., Oswald, J. N., Oswald, M. , Curtis, A. and Barlow, J. (2017), Acoustic classification of dolphins in the California Current using whistles, echolocation clicks, and burst pulses. Marine Mammal Science 33:520-540. doi:10.1111/mms.12381

Examples

data(train.data)
# initialize BANTER model with event data
bant.mdl <- initBanterModel(train.data$events)
# add all detector models
bant.mdl <- addBanterDetector(
  bant.mdl, train.data$detectors, 
  ntree = 50, sampsize = 1, num.cores = 1
)
# run BANTER event model
bant.mdl <- runBanterModel(bant.mdl, ntree = 1000, sampsize = 1)
summary(bant.mdl)

Subsample Detections

Description

Extract a random subsample of detections for each event and detector.

Usage

subsampleDetections(data, n)

Arguments

Value

a detector data.frame or list of detector data.frames with no more than n detections per event per detector.

Author(s)

Eric Archer eric.archer@noaa.gov

References

Rankin, S., Archer, F., Keating, J. L., Oswald, J. N., Oswald, M. , Curtis, A. and Barlow, J. (2017), Acoustic classification of dolphins in the California Current using whistles, echolocation clicks, and burst pulses. Marine Mammal Science 33:520-540. doi:10.1111/mms.12381

Examples

data(train.data)

# initial number of detections per event per detector
sapply(train.data$detectors, function(x) table(x$event.id))

# select half of all detectors
detect.half <- subsampleDetections(train.data$detectors, 0.5)
sapply(detect.half, function(x) table(x$event.id))

# select 20 detections
detect.20 <- subsampleDetections(train.data$detectors, 20)
sapply(detect.20, function(x) table(x$event.id))

# select 10 detections fro 'ec' detector
ec.10 <- subsampleDetections(train.data$detectors$ec, 10)
table(ec.10$event.id)

BANTER Classifier Model Summary

Description

Display summaries for event and detector models

Usage

summary(object, ...)

## S3 method for class 'banter_model'
summary(object, model = "event", n = 0.5, bins = 20, ...)

## S4 method for signature 'banter_model'
summary(object, model = "event", n = 0.5, bins = 20, ...)

Arguments

Value

In the plot that is created, the upper panel shows the trace of the Random Forest model OOB rate across sequential trees in the forest. The lower plot shows a frequency histogram of the number of times each sample was inbag (used as training data in a tree in the forest). The vertical red lines indicate the expected inbag rate for samples of each species.

Author(s)

Eric Archer eric.archer@noaa.gov

References

Rankin, S. , Archer, F. , Keating, J. L., Oswald, J. N., Oswald, M. , Curtis, A. and Barlow, J. (2017), Acoustic classification of dolphins in the California Current using whistles, echolocation clicks, and burst pulses. Marine Mammal Science 33:520-540. doi:10.1111/mms.12381

Examples

data(train.data)
# initialize BANTER model with event data
bant.mdl <- initBanterModel(train.data$events)
# add all detector models
bant.mdl <- addBanterDetector(
  bant.mdl, train.data$detectors, 
  ntree = 50, sampsize = 1, num.cores = 1
)
# run BANTER event model
bant.mdl <- runBanterModel(bant.mdl, ntree = 1000, sampsize = 1)
summary(bant.mdl)

Testing events and detectors

Description

A list of events and call data from detectors for testing BANTER model

Usage

data(test.data)

Format

list

Training events and detectors

Description

A list of events and call data from detectors for training BANTER model

Usage

data(train.data)

Format

list