templateMatching: Calculate Spectrogram Template Matching Scores
In monitoR: Acoustic Template Detection in R

Description Usage Arguments Details Value Note Note Author(s) References See Also

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).

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

binMatch(survey, templates, parallel = FALSE, show.prog = FALSE, time.source = "filename",
         rec.tz = NA, write.wav = FALSE, report.amp = FALSE, quiet = FALSE, ...)

`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`).
`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 from the file modification information. See details.
`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.
`quiet`	Use `TRUE` to suppress status updates to the console. Does not suppress messages or warnings.
`...`	Additional arguments to the `spectro` function.

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.

An S4 object of class templateScores, with the following slots:

`survey.name`	The file path to the survey that the scores apply to.
`survey`	The actual survey as a `Wave` object.
`survey.data`	A named list with one element per template. Each element is a named list with time-domain results for the survey.
`templates`	The templates (an S4 object of class `corTemplateList` or `binTemplateList`) used to calculate the scores.
`scores`	A named list with an element for each template. Each element contains the scores for an individual template.
`time`	A character vector containing information on the run time.

Cross-correlation values are not normalized.

For examples, see findPeaks and getDetections.

Sasha D. Hafner and Jon Katz

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.

makeCorTemplate, makeBinTemplate, findPeaks, getDetections, getPeaks, fileCopyRename, mp3Subsamp