Temporal and Spectral Statistics for HQ (Narrow-band) Songs

This function detects trains in the envelope of a Wave, groups them into hierarchical structures (i.e. motifs, motif sequences), and saves a suite of temporal and spectral metrics for each detection into several tables. An interactive plot visualizes the results, showing the envelope of the signal, detected trains, motifs, and key statistics. The plot can be downloaded as an HTML (interactive) or PNG (static) file.

Usage

song_stats_hq(
  wave,
  specimen_id = "",
  msmooth_window = 100,
  msmooth_overlap = 50,
  upper_detection_threshold = 0.2,
  lower_detection_threshold = 0.15,
  min_train_dur = 0.002,
  max_train_gap = 0.3,
  motif_seq = TRUE,
  max_motif_gap = 0.8,
  norm_env = TRUE,
  db_threshold = 20
)

Arguments

wave

A Wave object.

specimen_id

A character string representing the specimen identifier.

msmooth_window

An integer specifying the window size (in milliseconds) for smoothing the envelope (default: 100).

msmooth_overlap

An integer specifying the overlap (in %) for smoothing the envelope. Default = 50.

upper_detection_threshold

A numeric value representing the upper amplitude detection threshold Default = 0.2.

lower_detection_threshold

A numeric value representing the lower amplitude detection threshold Default = 0.1.

min_train_dur

A numeric value specifying the minimum duration (in seconds) of a valid amplitude train. Default = 0.002.

max_train_gap

A numeric value representing the maximum gap (in seconds) allowed between two trains before considering them part of different motifs. Default = 0.08.

motif_seq

Logical. If TRUE, add an first-order aggregation of motifs. Default value is FALSE.

max_motif_gap

Numeric. Maximum allowed gap (in seconds) between motifs to consider them part of the same sequence. @param norm_env A logical indicating whether to normalize the envelope Default = TRUE.

Value

A list with the following components:

plot

An interactive plotly plot showing the signal envelope, detected trains, and motifs.

summary_data

A tibble with summary statistics of the acoustic motifs.

train_data

A tibble with details about the detected trains.

motif_data

A tibble with details about the detected motifs.

params

A tibble containing the input parameters.

Examples

if (FALSE) { # \dontrun{
data(gryllus)
# result <- temporal_stats_hq(gryllus)
# result$plot
} # }