spectro_analysis {warbleR} | R Documentation |
Measure acoustic parameters in batches of sound files
Description
spectro_analysis
measures acoustic parameters on acoustic signals for which the start and end times
are provided.
Usage
spectro_analysis(X, bp = "frange", wl = 512, wl.freq = NULL, threshold = 15,
parallel = 1, fast = TRUE, path = NULL, pb = TRUE, ovlp = 50,
wn = "hanning", fsmooth = 0.1, harmonicity = FALSE, nharmonics = 3, ...)
Arguments
X |
'selection_table', 'extended_selection_table' or data frame with the following columns: 1) "sound.files": name of the sound
files, 2) "sel": number of the selections, 3) "start": start time of selections, 4) "end":
end time of selections. The output |
bp |
A numeric vector of length 2 for the lower and upper limits of a frequency bandpass filter (in kHz) or "frange" (default) to indicate that values in bottom.freq and top.freq columns will be used as bandpass limits. Lower limit of bandpass filter is not applied to fundamental frequencies. |
wl |
A numeric vector of length 1 specifying the spectrogram window length. Default is 512. See 'wl.freq' for setting windows length independently in the frequency domain. |
wl.freq |
A numeric vector of length 1 specifying the window length of the spectrogram
for measurements on the frequency spectrum. Default is 512. Higher values would provide
more accurate measurements. Note that this allows to increase measurement precision independently in the time and frequency domain. If |
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). |
fast |
Logical. If |
path |
Character string containing the directory path where the sound files are located.
If |
pb |
Logical argument to control progress bar and messages. Default is |
ovlp |
Numeric vector of length 1 specifying % of overlap between two
consecutive windows, used for fundamental frequency (using |
wn |
Character vector of length 1 specifying window name. Default is hanning'.
See function |
fsmooth |
A numeric vector of length 1 to smooth the frequency spectrum with a mean sliding window (in kHz) used for mean peak frequency detection. This help to average amplitude "hills" to minimize the effect of amplitude modulation. Default is 0.1. |
harmonicity |
Logical. If |
nharmonics |
Numeric vector of length 1 setting the number of harmonics to analyze. |
... |
Additional parameters to be passed to |
Details
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 analyze
from the package soundgen. NAs are produced for fundamental and dominant
frequency measures when there are no amplitude values above the threshold.
Additional parameters can be provided to the internal function analyze
, which measures parameters related to harmonicity.
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 (in kHz). Calculated as the weighted average of the frequency spectrum (i.e. weighted by the amplitude within the supplied band pass). -
sd
: standard deviation of frequency (in kHz). Calculated as the weighted standard deviation of the frequency spectrum (i.e. weighted by the amplitude within the supplied band pass). -
freq.median
: median frequency. The frequency at which the frequency spectrum is divided in two frequency intervals of equal energy (in kHz) -
freq.Q25
: first quartile frequency. The frequency at which the frequency spectrum is divided in two frequency intervals of 25% and 75% energy respectively (in kHz) -
freq.Q75
: third quartile frequency. The frequency at which the frequency spectrum 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 time envelope is divided in two time intervals of equal energy (in s) -
time.Q25
: first quartile time. The time at which the time envelope is divided in two time intervals of 25% and 75% energy respectively (in s). Seeacoustat
-
time.Q75
: third quartile time. The time at which the time envelope is divided in two time intervals of 75% and 25% energy respectively (in s). Seeacoustat
-
time.IQR
: interquartile time range. Time range between 'time.Q25' and 'time.Q75' (in s). Seeacoustat
-
skew
: skewness. Asymmetry of the frequency spectrum (see note inspecprop
description) -
kurt
: kurtosis. Peakedness of the frequency spectrum (see note inspecprop
description) -
sp.ent
: spectral entropy. Energy distribution of the frequency spectrum. Pure tone ~ 0; noisy ~ 1. Seesh
-
time.ent
: time entropy. Energy distribution on the time envelope. ~0 means amplitude concentrated in a specific time point, 1 means amplitude equally distributed across time. Seeth
-
entropy
: spectrographic entropy. Product of time and spectral entropysp.ent * time.ent
. SeeH
-
sfm
: spectral flatness. Similar to sp.ent (Pure tone ~ 0; noisy ~ 1). Seesfm
-
meandom
: average of dominant frequency measured across the spectrogram -
mindom
: minimum of dominant frequency measured across the spectrogram -
maxdom
: maximum of dominant frequency measured across the spectrogram -
dfrange
: range of dominant frequency measured across the spectrogram -
modindx
: modulation index. Calculated as the cumulative absolute difference between adjacent measurements of dominant frequencies divided by the dominant frequency range (measured on the spectrogram). 1 means the signal is not modulated. -
startdom
: dominant frequency measurement at the start of the signal (measured on the spectrogram). -
enddom
: dominant frequency measurement at the end of the signal(measured on the spectrogram). -
dfslope
: slope of the change in dominant frequency (measured on the spectrogram) through time ((enddom-startdom)/duration). Units are kHz/s. -
peakf
: peak frequency. Frequency with the highest energy. This parameter can take a considerable amount of time to measure. It's only generated iffast = FALSE
. It provides a more accurate measure of peak frequency than 'meanpeakf' but can be more easily affected by background noise. Measured on the frequency spectrum. -
meanpeakf
: mean peak frequency. Frequency with highest energy from the mean frequency spectrum (seemeanspec
). Typically more consistent than peakf in the presence of noise. -
meanfun
: average of fundamental frequency measured across the acoustic signal. Only measured ifharmonicity = TRUE
. -
minfun
: minimum fundamental frequency measured across the acoustic signal. Only measured ifharmonicity = TRUE
. -
maxfun
: maximum fundamental frequency measured across the acoustic signal. Only measured ifharmonicity = TRUE
. -
hn_freq
: mean frequency of the 'n' upper harmonics (kHz) (seeanalyze
). Number of harmonics is defined with the argument 'nharmonics'. Only measured ifharmonicity = TRUE
. -
hn_width
: mean bandwidth of the 'n' upper harmonics (kHz) (seeanalyze
). Number of harmonics is defined with the argument 'nharmonics'. Only measured ifharmonicity = TRUE
. -
harmonics
: the amount of energy in upper harmonics, namely the ratio of total spectral power above 1.25 x F0 to the total spectral power below 1.25 x F0 (dB) (seeanalyze
). Number of harmonics is defined with the argument 'nharmonics'. Only measured ifharmonicity = TRUE
. -
HNR
: harmonics-to-noise ratio (dB). A measure of the harmonic content generated bygetPitchAutocor
. Only measured ifharmonicity = TRUE
.
Author(s)
Marcelo Araya-Salas (marcelo.araya@ucr.ac.cr) and Grace Smith Vidaurre
References
Araya-Salas, M., & Smith-Vidaurre, G. (2017). warbleR: An R package to streamline analysis of animal acoustic signals. Methods in Ecology and Evolution, 8(2), 184-191.
Examples
{
data(list = c("Phae.long1", "Phae.long2", "Phae.long3", "lbh_selec_table"))
writeWave(Phae.long1, file.path(tempdir(), "Phae.long1.wav"))
writeWave(Phae.long2, file.path(tempdir(), "Phae.long2.wav"))
writeWave(Phae.long3, file.path(tempdir(), "Phae.long3.wav"))
# measure acoustic parameters
sp_param <- spectro_analysis(X = lbh_selec_table[1:8,], pb = FALSE, path = tempdir())
# measuring peakf
sp_param <- spectro_analysis(X = lbh_selec_table[1:8,], pb = FALSE, fast = FALSE, path = tempdir())
# measuring harmonic-related parameters using progress bar
sp_param <- spectro_analysis(X = lbh_selec_table[1:8,], harmonicity = TRUE,
path = tempdir(), ovlp = 70)
}