Documentation improvements.

NAMESPACE

@@ -2,6 +2,7 @@
 
 export(addSpectra)
 export(autoBandPass)
+export(beatComplexity)
 export(beatSpectrum)
 export(convert2Celsius)
 export(convert2Fahrenheit)

R/autoBandPass.R

@@ -1,21 +1,29 @@
-#' Automatic Band Pass
+#' Automatic Band Pass Filter
 #'
-#' Creates an automatic bandpass filter based on the strongest frequency. The width of the bandwidth can be an
+#' Creates an automatic bandpass filter based on the strongest frequency. The allowed bandwidth can be an
 #' integer multiple of the bandwidth at either -3dB or -10dB.
-#' 
+#'
 #' @param wave A Wave object
-#' @param bw Either -3dB or -10dB. This is calculated by `frequencyStats`
+#' @param bw Either -3dB or -10dB. This is calculated by \code{frequencyStats}
 #' @param n.bw The number of bandwidths either side of the centre of the centre to keep
 #' @param lowcut High-pass filtering is applied at this frequency before calculating the centre frequency and bandwith
-#' 
+#' @return A band-pass filtered Wave object
+#' @examples
+#' \dontrun{
+#' autoBandPass(sheep)
+#' autoBandPass(sheep, bw="-3dB", n.bw=1, lowcut=1000)
+#' autoBandPass(sheep, bw="-10dB", n.bw=2, lowcut=0)
+#' }
 #' @export
-#' 
+#'
 autoBandPass <- function(
   wave,
   bw="-3dB",
   n.bw=1,
   lowcut=1000
 ) {
+  validateIsWave(wave)
+  if (!is.integer(n.bw)) {stop("n.bw must be an integer.")}
   wave2 <- seewave::ffilter(wave, from=lowcut, output="Wave")
   data <- frequencyStats(wave2)
   rm(wave2)
@@ -34,4 +42,4 @@ autoBandPass <- function(
     output="Wave"
   )
   return(wave)
-}
+}

R/beatComplexity.R

@@ -1,24 +1,39 @@
+#' Beat spectrum complexity
+#'
+#' This function computes a \code{beatSpectrum} and calculates some basic measurements of its complexity.
+#' The complexity value is calculated as the maximum identified repeating period (in seconds) divided by
+#' the number of peaks.
+#'
+#' @param wave A Wave object
+#' @param plot If TRUE a spectorgram overlaid with the peaks is plotted.
+#' @return A list of the complexity, a vector of the peak periods, and the number of peaks.
+#' @examples
+#' \dontrun{
+#' beatComplexity(sheep)
+#' beatComplexity(sheep, plot=TRUE)
+#' }
+#' @export
+#'
+
 beatComplexity <-function(
   wave,
   plot=FALSE
 ) {
-  bs <- beatSpectrum(wave) 
-  #bs$power <- bs$power / max(bs$power)
-
-  e <- c(0,diff(sign(diff(bs$power))),0)
-
+  bs <- beatSpectrum(wave)
 
-
+  e <- c(0,diff(sign(diff(bs$power))),0)
   peaks <- e==-2
-  
+
   if (plot) {
-    plot(bs$period, bs$power, type="l")  
+    plot(bs$period, bs$power, type="l")
     abline(v=bs$period[peaks], col="green")
   }
-
-  c <- max(bs$period[peaks]) / length(peaks)
-
-  #ToDo: return period range, number of peaks as list
-  return(c)
-
-}
+
+  r <- list(
+    "complexity" = max(bs$period[peaks]) / length(bs$period[peaks]),
+    "peak.periods" = bs$period[peaks],
+    "num.peaks" = length(bs$period[peaks])
+  )
+  return(r)
+
+}

R/beatSpectrum.R

@@ -1,29 +1,34 @@
 #' Computes a beat spectrum
-#' 
+#'
 #' Beat spectra represent the periodicity in signal amplitude.
 #' It is computed by performing a continuous wavelet transform on
-#' the envelope of a preprocessed signal, and processing 
+#' the envelope of a preprocessed signal, and processing
 #' the average power per frequency band.
-#' 
+#'
 #' @param wave an R object or path to a wave file
 #' @param min_period the minimal rythmicity period expected, in seconds
 #' @param max_period the maximal rythmicity period expected, in seconds
 #' @param dj the frequency resolution of the cwt (in voices per octave)
 #' @param ... extra arguments passed to \code{analyze.wavelet()}
-#' @return a spectrum as a \code{data.table}. 
-#' It contains two columns: \code{power} and \code{period}. 
+#' @return a spectrum as a data frame.
+#' It contains two columns: \code{power} and \code{period}.
 #' The number of rows depend on the resolution and frequency range.
 #' @importFrom stats approx runmed
 #' @export
 #' @author Quentin Geissmann
-beatSpectrum <- function(wave, 
+#' @examples
+#' \dontrun{
+#' beatSpectrum(sheep)
+#' beatSpectrum(sheep, min_period=0.005, max_period=30, dj=1/32)
+#' }
+beatSpectrum <- function(wave,
                          min_period = 0.005,#s
                          max_period=30, #s,
                          dj=1/32, # 1/nvoices
                          ...
 ){
-  
-  #wave_std <- orthophonia::standardiseWave(wave) 
+
+  #wave_std <- orthophonia::standardiseWave(wave)
   wave_std <- wave
   scaling_ratio <- wave_std@samp.rate / (1/min_period)
   runmed_k <- 2*(floor(scaling_ratio/2))+1
@@ -39,8 +44,8 @@ beatSpectrum <- function(wave,
                         loess.span = 0, dj=dj,
                         lowerPeriod = 2 ^ 1,
                         upperPeriod = 2 ^ upper_period,
-                        make.pval =F, 
+                        make.pval =F,
                         verbose = F,...)
   #data.table(power=wt$Power.avg, period = wt$Period * min_period)
   data.frame(power=wt$Power.avg, period = wt$Period * min_period)
-}
+}