warbleR (version 1.1.7)

specan: Measure acoustic parameters in batches of sound files

Description

specan measures acoustic parameters on acoustic signals for which the start and end times are provided.

Usage

specan(X, bp = c(0,22), wl = 512, threshold = 15, parallel = 1, fast = TRUE, path = NULL, 
pb = TRUE, ovlp = 50, ff.method = "seewave", wn = "hanning")

Arguments

X

Data frame with the following columns: 1) "sound.files": name of the .wav files, 2) "sel": number of the selections, 3) "start": start time of selections, 4) "end": end time of selections. The ouptut of manualoc or autodetec can be used as the input data frame.

bp

A numeric vector of length 2 for the lower and upper limits of a frequency bandpass filter (in kHz) or "frange" to indicate that values in low.f and high.f columns will be used as bandpass limits. Default is c(0, 22). Lower limit of bandpass is not applied to fundamental frequencies.

wl

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

threshold

amplitude threshold (%) for fundamental frequency and dominant frequency detection. Default is 15.

parallel

Numeric. Controls whether parallel computing is applied. It specifies the number of cores to be used. Default is 1 (i.e. no parallel computing). For windows OS the parallelsugar package should be installed.

fast

Logical. If TRUE (default) then the peakf acoustic parameter (see below) is not computed, which substantially increases performance (~9 times faster).

path

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

pb

Logical argument to control progress bar and messages. Default is TRUE. Note that progress bar is only used when parallel = 1.

ovlp

Numeric vector of length 1 specifying % of overlap between two consecutive windows, used for fundamental frequency (using fund or FF) and dominant frequency (using dfreq). Default is 50.

ff.method

Character. Selects the method used to calculate the fundamental frequency. Either 'tuneR' (using FF) or 'seewave' (using fund). Default is 'seewave'. Use trackfreqs to decide which method works the best. 'tuneR' performs faster (and seems to be more accurate) than 'seewave'.

wn

Character vector of length 1 specifying window name. Default is hanning'. See function ftwindow for more options.

Value

Data frame with 'sound.files' and 'selec' as in the input data frame, plus the following acoustic parameters:

• duration: length of signal (in s)
• meanfreq: mean frequency. Weighted average of frequency by amplitude (in kHz)
• sd: standard deviation of frequency weighted by amplitude
• freq.median: median frequency. The frequency at which the signal is divided in two frequency intervals of equal energy (in kHz)
• freq.Q25: first quartile frequency. The frequency at which the signal is divided in two frequency intervals of 25% and 75% energy respectively (in kHz)
• freq.Q75: third quartile frequency. The frequency at which the signal is divided in two frequency intervals of 75% and 25% energy respectively (in kHz)
• freq.IQR: interquartile frequency range. Frequency range between 'freq.Q25' and 'freq.Q75' (in kHz)
• time.median: median time. The time at which the signal is divided in two time intervals of equal energy (in s)
• time.Q25: first quartile time. The time at which the signal is divided in two time intervals of 25% and 75% energy respectively (in s). See acoustat
• time.Q75: third quartile time. The time at which the signal is divided in two time intervals of 75% and 25% energy respectively (in s). See acoustat
• time.IQR: interquartile time range. Time range between 'time.Q25' and 'time.Q75' (in s). See acoustat
• skew: skewness. Asymmetry of the spectrum (see note in specprop description)
• kurt: kurtosis. Peakedness of the spectrum (see note in specprop description)
• sp.ent: spectral entropy. Energy distribution of the frequency spectrum. Pure tone ~ 0; noisy ~ 1. See sh
• time.ent: time entropy. Energy distribution on the time envelope. Pure tone ~ 0; noisy ~ 1. See th
• entropy: spectral entropy. Product of time and spectral entropy sp.ent * time.ent. See H
• sfm: spectral flatness. Similar to sp.ent (Pure tone ~ 0; noisy ~ 1). See sfm
• peakf: peak frequency. Frequency with highest energy
• meanfun: average of fundamental frequency measured across the acoustic signal
• minfun: minimum fundamental frequency measured across the acoustic signal
• maxfun: maximum fundamental frequency measured across the acoustic signal
• meandom: average of dominant frequency measured across the acoustic signal
• mindom: minimum of dominant frequency measured across the acoustic signal
• maxdom: maximum of dominant frequency measured across the acoustic signal
• dfrange: range of dominant frequency measured across the acoustic signal
• modindx: modulation index. Calculated as the cumulative absolute difference between adjacent measurements of dominant frequencies divided by the dominant frequency range. 1 means the signals is not modulated.
• startdom: dominant frequency measurement at the start of the signal
• enddom: dominant frequency measurement at the end of the signal
• dfslope: slope of the change in dominant through time ((enddom-startdom)/duration). Units are kHz/s.

Details

The ouptut of manualoc or autodetec can be used directly without any additional modification. The function measures 29 acoustic parameters (if fast = TRUE) on each selection in the data frame. Most parameters are produced internally by specprop, fpeaks, fund, and dfreq from the package seewave and FF from the package tuneR. NAs are produced for fundamental and dominant frequency measures when there are no amplitude values above the threshold.

Examples

## Not run: ------------------------------------
# # First set temporary folder
# setwd(tempdir())
# 
# data(list = c("Phae.long1", "Phae.long2", "Phae.long3", "Phae.long4", "selec.table"))
# writeWave(Phae.long1,"Phae.long1.wav")
# writeWave(Phae.long2,"Phae.long2.wav")
# writeWave(Phae.long3,"Phae.long3.wav")
# writeWave(Phae.long4,"Phae.long4.wav")
# 
# a <- specan(X = selec.table, bp = c(0, 22))
# 
# # using a diferent threshold
# a <- specan(X = selec.table, bp = c(0, 22), threshold = 20)
# # View(a)
# 
## ---------------------------------------------