templateMatching: Calculate Spectrogram Template Matching Scores

Description

These functions are used to calculate spectrogram template matching scores between a set of templates and an acoustic survey using spectrogram cross correlation (corMatch) or binary point matching (binMatch).

Usage

corMatch(survey, templates, parallel = FALSE, show.prog = FALSE, cor.method = "pearson", 
         warn = TRUE, time.source = "filename", rec.tz = NA, write.wav = FALSE, ...)
binMatch(survey, templates, parallel = FALSE, show.prog = FALSE, warn = TRUE, 
         time.source = "filename", rec.tz = NA, write.wav = FALSE, report.amp = FALSE, 
         ...)

Arguments

survey

A file path to a wav or mp3 recording, or a Wave object. The survey is the acoustic survey that you want to make detections within.

templates

A template list--a corTemplateList object for corMatch or a binTemplateList object for binMatch.

parallel

If TRUE, mclapply is used for calculation of scores across all time bins for each template. This option is not available for Windows operating systems.

show.prog

If TRUE, progress will be reported during the score calculations.

cor.method

For corMatch, the method used to calculate correlation coefficients (see ?cor).

warn

Set to FALSE to suppress warnings about time bin duration and frequency bin span mismatches.

time.source

The source of date and time information. filename will look in the name of the survey file (survey argument) for a date and time with format YYYY-MM-DD_HHMMSS_TimeZone. "fileinfo" will take the date and time

rec.tz

Time zone for which the recordings were made (optional). Needed if different from the time zone setting of the operating system, when times will be adjusted to the correct time zone. See details.

write.wav

If survey is a Wave object, should it be written to file? If FALSE, functions will return an error.

report.amp

If TRUE, binMatch will return the mean ``on'' and ``off'' amplitudes as well as their difference (the score). See details.

...

Additional arguments to the spectro function.

Value

An S4 object of class templateScores, with the following slots:
survey.nameThe file path to the survey that the scores apply to.
surveyThe actual survey as a Wave object.
survey.dataA named list with one element per template. Each element is a named list with time-domain results for the survey.
templatesThe templates (an S4 object of class corTemplateList or binTemplateList) used to calculate the scores.
scoresA named list with an element for each template. Each element contains the scores for an individual template.
timeA character vector containing information on the run time.

Details

Scores are refereced by both the time elapsed since the beginning of the recording and the time of day on the date the recording was made. For times derived from the date modified of the recording file (time.source = "fileinfo") to be accurate the sound file must not have been edited (no samples added or removed) since its original creation. File copying and duplication (as from removeable media to a storage drive) should not affect the date modified, although the creation date will be reset. Date modified values are stored in the time zone when they were recorded but will be translated to the current time zone when read, which may result in errors due to daylight savings changes or when recorded surveys are shared across time zones. Time zone management is tricky; if recordings were made in a different time zone than the operating system running fileCopyRename, you can specify the correct time zone for the recordings with the rec.tz argument. Unexpected results are possible, as time zone abbreviations in general use may not match those in the Internet Assigned Numbers Authority tz database. The most reliable way to specify time zone is to use the full name, most quickly seen using OlsonNames, and also found on Wikipedia: http://en.wikipedia.org/wiki/List_of_tz_database_time_zones. Times derived from a date-time value encoded in the file name (time.source = "filename") are more stable in regard, and are automatically created with either fileCopyRename or mp3Subsamp. Binary point matching scores each time frame by computing the difference between the mean amplitude in the ``on'' cells and the mean amplitude in the ``off'' cells. The resulting score can be a rough estimate of signal:noise.

References

Mellinger, D. K. and C. W. Clark. 1997. Methods for automatic detection of mysticete sounds. Marine and Freshwater Behaviour and Physiology. 29, 163-181.

Towsey, M., B. Planitz, A. Nantes, J. Wimmer, and P. Roe. 2012. A toolbox for animal call recognition. Bioacoustics-the International Journal of Animal Sound and Its Recording 21, 107-125.