Skip to contents

Temporal and Spectral Statistics of LQ (Broad-band) Songs.

Source: R/song_stats_lq.R
song_stats_lq.Rd

This function detects temporal peaks in the envelope of a Wave, groups them into hierarchical structures (i.e., trains, 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_lq(
  wave,
  specimen_id = "",
  ssmooth = 100,
  peakfinder_ws = 50,
  peakfinder_threshold = 0.005,
  min_peaks_train = 3,
  max_peak_gap = 0.01,
  max_peak_diff = NULL,
  max_train_gap = 0.3,
  motif_seq = TRUE,
  max_motif_gap = 0.8,
  detection_threshold = 0.15,
  norm_env = TRUE,
  db_threshold = 20
)

Arguments

wave

A Wave object.

specimen_id

A character string representing the specimen identifier.

ssmooth

Numeric. Smoothing window size (in samples) for the amplitude envelope.

peakfinder_ws

Numeric. Window size (in samples) for the peak detection algorithm.

peakfinder_threshold

Numeric. Amplitude threshold for peak detection, as a proportion of the maximum amplitude.

max_peak_gap

Numeric. Maximum allowed gap (in seconds) between peaks to consider them part of the same train.

max_peak_diff

Numeric. Maximum allowed difference (in % amplitude) between consecutive peaks to be considered in the same train.

max_train_gap

Numeric. Maximum allowed gap (in seconds) between trains to consider them part of the same motif.

motif_seq

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

max_motif_gap

Numeric. Maximum allowed gap (in seconds) between motifs to consider them part of the same group.

detection_threshold

Numeric. Minimum amplitude for a peak to be considered valid.

norm_env

Logical. Whether to normalize the amplitude envelope between 0 and 1. Defaults to TRUE.

db_threshold

Numeric. Decibel threshold below the peak amplitude for calculating low and high frequencies. Defaults to 20 dB.

min_peak_train

Numeric. Minimum number of peaks per train. If a train is found to have less than this number, it will be dropped.

Value

A list containing the following components:

plot

An interactive plotly object showing the waveform envelope, detected peaks, trains, and motifs.

summary_data

A tibble with summary statistics for the analyzed waveform.

motif_seq_data

A tibble summarizing motif sequences. Only produced when motif_seq = TRUE.

motif_data

A tibble summarizing motifs, including motif duration, train counts, and spectral properties.

train_data

A tibble detailing detected trains, including start and end times, durations, peak frequencies, and bandwidths.

peak_data

A tibble containing detected peaks, including their times, periods, and amplitudes.

params

A tibble summarizing input parameters for the function.

Examples

if (FALSE) { # \dontrun{
data(coryphoda)
# Perform analysis on the coryphoda sample
results <- call_stats_lq(
  wave = coryphoda,
  specimen_id = "Coryphoda_Sample",
  ssmooth = 100,
  peakfinder_ws = 50,
  peakfinder_threshold = 0.01,
  max_train_gap = 0.5,
  max_peak_gap = 0.05,
  detection_threshold = 0.2,
  norm_env = TRUE,
  db_threshold = 20
)
results$plot
} # }