song_param calculates descriptive statistics of songs or other higher levels of organization in the signals.
song_param(X = NULL, song_colm = "song",mean_colm = NULL, min_colm = NULL, max_colm = NULL, elm_colm = NULL, elm_fun = NULL, sd = FALSE, parallel = 1, pb = TRUE, na.rm = FALSE, weight = NULL)
| X | 'selection_table', 'extended_selection_table' (created 'by.song') or data frame with the following columns: 1) "sound.files": name of the .wav
files, 2) "selec": number of the selections, 3) "start": start time of selections, 4) "end":
end time of selections. The output of |
|---|---|
| song_colm | Character string with the column name containing song labels. It can be used to label any hierarchical level at which parameters need to be calculated (e.g. syllables, phrases). Note that the function assumes that song labels are not repeated within a sound file. |
| mean_colm | Numeric vector with the index of the columns that will be averaged. If |
| min_colm | Character vector with the name(s) of the columns for which the minimum
value is needed. Default is |
| max_colm | Character vector with the name(s) of the columns for which the maximum
value is needed. Default is |
| elm_colm | Character vector with the name(s) of the columns identifying the element labels (i.e. element types). If supplied 'unq.elms' and 'mean.elm.count' are returned. Default is |
| elm_fun | Function to be applied to the sequence of elements composing a song. Default is |
| sd | Logical value indicating whether standard deviation is also returned for
variables in which averages are reported. Default is |
| 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). |
| pb | Logical argument to control progress bar and messages. Default is |
| na.rm | Logical value indicating whether 'NA' values should be ignored for calculations. |
| weight | Character vector defining 1 or more numeric vectors to weight average
measurements (i.e. song parameters). Names of numeric columns in 'X' can also be used. See |
A data frame similar to the input 'X' data frame, but in this case each row corresponds to a single song. The data frame contains the mean or extreme values for numeric columns for each song. Columns that will be averaged can be defined with 'mean_colm' (otherwise all numeric columns are used). Columns can be weighted by other columns in the data set (e.g. duration, frequency range). In addition, the function returns the following song level parameters:
elm.duration: mean length of elements (in s)
song.duration: length of song (in s)
num.elms: number of elements (or song units)
start: start time of song (in s)
end: end time of song (in s)
bottom.freq: lowest 'bottom.freq' from all song elements (in kHz)
top.freq: highest 'top.freq' from all song elements (in kHz)
freq.range: difference between song's 'top.freq' and 'bottom.freq' (in kHz)
song.rate: number of elements per second (NA if only 1 element)
gap.duration: average length of gaps (i.e. silences) in between elements
(in s, NA if only 1 element)
elm.types: number of element types (i.e. number of unique types, only if 'elm_colm' is supplied)
mean.elm.count: mean number of times element types are found (only if 'elm_colm' is supplied)
This function assumes that song labels are not repeated within a sound file.
The function calculates average or extreme values of acoustic parameters of elements in a song or other level of organization in the signals.
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.
{ # get warbleR sound file examples data(list = c("Phae.long1", "Phae.long2", "Phae.long3", "Phae.long4", "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")) # add a 'song' column lbh_selec_table$song <- rep(1:4, each = 3)[1:11] # measure acoustic parameters sp <- specan(lbh_selec_table[1:8, ], bp = c(1, 11), 300, fast = TRUE, path = tempdir()) # add song data sp <- merge(sp, lbh_selec_table[1:8, ], by = c("sound.files", "selec")) # caculate song-level parameters for all numeric parameters song_param(X = sp, song_colm = "song", parallel = 1, pb = TRUE) # caculate song-level parameters selecting parameters with mean_colm song_param(X = sp, song_colm = "song",mean_colm = c("dfrange", "duration"), parallel = 1, pb = TRUE) # caculate song-level parameters for selecting parameters with mean_colm, max_colm # and min_colm and weighted by duration song_param(X = sp, weight = "duration", song_colm = "song", mean_colm = c("dfrange", "duration"), min_colm = "mindom", max_colm = "maxdom", parallel = 1, pb = TRUE) # with two weights song_param(X = sp, weight = c("duration", "dfrange"), song_colm = "song", mean_colm = c("kurt", "sp.ent"), parallel = 1, pb = TRUE) # with two weights no progress bar song_param(X = sp, weight = c("duration", "dfrange"), song_colm = "song", mean_colm = c("kurt", "sp.ent"), parallel = 1, pb = FALSE) }#> | | 0 % ~calculating |+++++++ | 12% ~00s |+++++++++++++ | 25% ~00s |+++++++++++++++++++ | 38% ~00s |+++++++++++++++++++++++++ | 50% ~00s |++++++++++++++++++++++++++++++++ | 62% ~00s |++++++++++++++++++++++++++++++++++++++ | 75% ~00s |++++++++++++++++++++++++++++++++++++++++++++ | 88% ~00s |++++++++++++++++++++++++++++++++++++++++++++++++++| 100% elapsed=00s #> | | 0 % ~calculating |+++++++++++++ | 25% ~00s |+++++++++++++++++++++++++ | 50% ~00s |++++++++++++++++++++++++++++++++++++++ | 75% ~00s |++++++++++++++++++++++++++++++++++++++++++++++++++| 100% elapsed=00s #> | | 0 % ~calculating |+++++++++++++ | 25% ~00s |+++++++++++++++++++++++++ | 50% ~00s |++++++++++++++++++++++++++++++++++++++ | 75% ~00s |++++++++++++++++++++++++++++++++++++++++++++++++++| 100% elapsed=00s #> | | 0 % ~calculating |+++++++++++++ | 25% ~00s |+++++++++++++++++++++++++ | 50% ~00s |++++++++++++++++++++++++++++++++++++++ | 75% ~00s |++++++++++++++++++++++++++++++++++++++++++++++++++| 100% elapsed=00s #> | | 0 % ~calculating |+++++++++++++ | 25% ~00s |+++++++++++++++++++++++++ | 50% ~00s |++++++++++++++++++++++++++++++++++++++ | 75% ~00s |++++++++++++++++++++++++++++++++++++++++++++++++++| 100% elapsed=00s#> sound.files selec start end top.freq bottom.freq song kurt #> 1 Phae.long1.wav 1 0.34334 2.32146 8.8071 2.1694 1 11.8872 #> 2 Phae.long2.wav 1 0.15960 1.58321 8.8880 2.2840 2 12.2151 #> 3 Phae.long3.wav 1 0.62655 0.75777 8.8223 3.0068 2 10.4118 #> 4 Phae.long3.wav 1 0.12336 2.10439 9.3152 2.3169 3 8.1652 #> sp.ent num.elms elm.duration freq.range song.duration song.rate gap.duration #> 1 0.93123 3 0.17033 6.6376 1.97812 1.5166 -0.58105 #> 2 0.92571 2 0.12936 6.6040 1.42361 1.4049 1.16489 #> 3 0.91059 1 0.13122 5.8155 0.13122 NA NA #> 4 0.90695 2 0.13070 6.9983 1.98103 1.0096 -1.98103