manualoc: Interactive view of spectrograms

Description

manualoc produces an interactive spectrographic view in which the start and end times of acoustic signals can be measured.

Usage

manualoc(wl = 512, flim = c(0,12), seltime = 1, tdisp = NULL, reccomm = FALSE, wn = "hanning", title = TRUE, selcomm = FALSE, osci = FALSE, player = NULL, pal = reverse.gray.colors.2, path = NULL)

Arguments

A numeric vector of length 1 specifying the spectrogram window length. Default is 512.

flim

A numeric vector of length 2 specifying the frequency limit (in kHz) of the spectrogram, as in the function spectro. Default is c(0,12).

seltime

A numeric vector of length 1 indicating the time interval in seconds at which the spectrograms are produced with higher resolution (ovlp = 70) and oscilograms (if osci = TRUE). Default is 1 second.

tdisp

A numeric vector of length 1 specifying the length in seconds of the total sound file to be displayed. Default is NULL which displays the full sound file.

reccomm

Logical argument. If TRUE pops up a comment window at the end of each sound file. The comment needs to be quoted. Default is FALSE.

A character vector of length 1 specifying the window function (by default "hanning"). See function ftwindow for more options.

title

Logical argument. If TRUE the name of the sound file will be printed as the main title of the spectrogram window. Default is TRUE

selcomm

Logical argument. If TRUE pops up a comment window after each selection. The comment is printed as a label on the selected unit. The comment must be quoted. Default is FALSE

osci

Logical argument. If TRUE adds a oscillogram whenever the spectrograms are produced with higher resolution (see seltime). Default is FALSE.

player

Path to or name of a program capable of playing a wave file by invocation from the command line. If under Windows and no player is given, windows player will be chosen as the default. "vlc" works in Linux if vlc player is installed. The external program must be closed before resuming analysis. Default is NULL.

pal

A color palette function to be used to assign colors in the plot, as in spectro. Default is reverse.gray.colors.2. See Details.

path

Character string containing the directory path where the sound files are located. If NULL (default) then the current working directory is used.

Value

.csv file saved in the working directory with start and end time of selections.

Details

Users can zoom-in a specific sound file segment by clicking at the start and end (left side and right side) of the segment. To select the start and end of a vocalization unit the users need to click at the end and then at the start (right side and left side) of the unit. In addition, 6 "buttons" are provided at the upper right side of the spectrogram that allow to display a full view of the spectrogram ("Full view"), go back to the previous view ("Previous view"), stop the analysis ("Stop"), go to the next sound file ("Next rec"), play the current view using external software ("Play", see "player" argument), or delete the last manual selection in the current sound file ("Del-sel"). When a unit has been selected, the function plots a red circle with the selection number in the middle point of the selection in the spectrogram. It also plots vertical dotted lines at the start and end of the selection. The circle and lines "disappear" when the selection is deleted ("Del-sel" button). Only the last selection can be deleted. The function produces a .csv file (manualoc_output.csv) with information about the .wav file name, selection number, start and end time, selection comment (selcomm), and sound file comment (reccomm). The file is saved in the working directory and is updated every time the user moves into the next sound file (Next rec "button") or stop the process (Stop "button"). When resuming the process (after "stop" and re-running the function in the same working directory), the function will keep the previous selections and will only pick up .wav files that are not present in the .csv file (not previously analyzed). When users go to the next sound file (Next rec "button") without making any selection the file is still included in the .csv file, with NA's in the "end", "time" and "selec" field. Windows length (wl) controls the temporal and frequency precision of the spectrogram. A high "wl" value increases the frequency resolution but reduces the temporal resolution, and vice versa. Any color palette that comes with the seewave package can be used: temp.colors, reverse.gray.colors.1, reverse.gray.colors.2, reverse.heat.colors, reverse.terrain.colors, reverse.topo.colors, reverse.cm.colors, heat.colors, terrain.colors, topo.colors, cm.colors. The function is slow when working on files of length > 5min. In most cases other sound analysis softwares for manually selecting acoustic signals (e.g. Raven, Syrinx) should be prefered.

Examples

Run this code

## Not run: 
# #First create empty folder
# setwd(tempdir())
# 
# # save wav file examples
# data(list = c("Phae.long1", "Phae.long2", "Phae.long3", "Phae.long4"))
# writeWave(Phae.long1,"Phae.long1.wav")
# writeWave(Phae.long2,"Phae.long2.wav")
# writeWave(Phae.long3,"Phae.long3.wav")
# writeWave(Phae.long4,"Phae.long4.wav")
# 
# manualoc(wl = 300)
# # need to use the buttoms to manipulate function
# # check working directory for .csv file after stopping function
# #check here:
# getwd()
# ## End(Not run)