added examples to every function

IPS-LMU · Nov 14, 2014 · 0feca6e · 0feca6e
1 parent c62e73c
commit 0feca6e
Show file tree

Hide file tree

Showing 26 changed files with 450 additions and 12 deletions.
diff --git a/R/acfana.R b/R/acfana.R
@@ -9,7 +9,8 @@
 ##' @param listOfFiles vector of file paths to be processed by function
 ##' @param optLogFilePath path to option log file
 ##' @param beginTime = <time>: set begin of analysis interval to <time> seconds (default: 0 = beginning of file)
-##' @param centerTime = <time>: set single-frame analysis with the analysis window centred at <time> seconds; overrules BeginTime, EndTime and WindowShift options
+##' @param centerTime = <time>: set single-frame analysis with the analysis window centred at <time> seconds; 
+##' overrules BeginTime, EndTime and WindowShift options
 ##' @param endTime = <time>: set end of analysis interval to <time> seconds (default: 0 = end of file)
 ##' @param windowShift = <dur>: set analysis window shift to <dur> ms (default: 5.0)
 ##' @param windowSize = <dur>: set analysis window size to <dur> ms; overrules EffectiveLength parameter
@@ -28,6 +29,23 @@
 ##' @author Raphael Winkelmann
 ##' @author Lasse Bombien
 ##' @useDynLib wrassp
+##' @examples
+##' # get path to audio file
+##' path2wav <- list.files(system.file("extdata", package = "wrassp"), 
+##'                        pattern = glob2rx("*.wav"), 
+##'                        full.names = TRUE)[1]
+##' 
+##' # calculate short-term autocorrelation
+##' res <- acfana(path2wav, toFile=FALSE)
+##' 
+##' # plot short-term autocorrelation values
+##' matplot(seq(0,numRecs.AsspDataObj(res) - 1) / rate.AsspDataObj(res) + 
+##'         attr(res, 'startTime'), 
+##'         res$acf, 
+##'         type='l', 
+##'         xlab='time (s)', 
+##'         ylab='short-term autocorrelation values')
+##'         
 ##' @export
 'acfana' <- function(listOfFiles = NULL, optLogFilePath = NULL, 
                      beginTime = 0.0, centerTime = FALSE, 

diff --git a/R/afdiff.R b/R/afdiff.R
@@ -27,6 +27,23 @@
 ##' @author Raphael Winkelmann
 ##' @author Lasse Bombien
 ##' @useDynLib wrassp
+##' @examples
+##' # get path to audio file
+##' path2wav <- list.files(system.file("extdata", package = "wrassp"), 
+##'                        pattern = glob2rx("*.wav"), 
+##'                        full.names = TRUE)[1]
+##' 
+##' # compute the first forward difference of the signal
+##' res <- afdiff(path2wav, toFile=FALSE)
+##' 
+##' # plot samples
+##' # (only plot every 10th element to accelerate plotting)
+##' plot(seq(0,numRecs.AsspDataObj(res) - 1, 10) / rate.AsspDataObj(res), 
+##'      res$audio[c(TRUE, rep(FALSE,9))], 
+##'      type='l', 
+##'      xlab='time (s)', 
+##'      ylab='Audio samples')
+##'      
 ##' @export
 'afdiff' <- function(listOfFiles = NULL, optLogFilePath = NULL, 
                      computeBackwardDifference = FALSE, computeCentralDifference = FALSE, 

diff --git a/R/affilter.R b/R/affilter.R
@@ -26,7 +26,8 @@
 ##' @param stopBand = <num>: set the stop-band attenuation to <num> dB (default: 93.0 dB, minimum: 21.0 dB)
 ##' @param transition = <num>: set the width of the transition band to <num> Hz (default: 250.0 Hz)
 ##' @param useIIR switch from the default FIR to IIR filter 
-##' @param numIIRsections = <num>: set the number of 2nd order sections to <num> (default: 4) where each section adds 12dB/oct to the slope of the filter 
+##' @param numIIRsections = <num>: set the number of 2nd order sections to <num> (default: 4) where each section 
+##' adds 12dB/oct to the slope of the filter 
 ##' @param toFile write results to file (for default extension see details section))
 ##' @param explicitExt set if you wish to overwride the default extension
 ##' @param outputDirectory directory in which output files are stored. Defaults to NULL, i.e. 
@@ -37,6 +38,23 @@
 ##' @author Raphael Winkelmann
 ##' @author Lasse Bombien
 ##' @useDynLib wrassp
+##' @examples
+##' # get path to audio file
+##' path2wav <- list.files(system.file("extdata", package = "wrassp"), 
+##'                        pattern = glob2rx("*.wav"), 
+##'                        full.names = TRUE)[1]
+##' 
+##' # band-pass filter signal between 4000 and 5000 Hz
+##' res <- affilter(path2wav, highPass=4000, lowPass=5000, toFile=FALSE)
+##' 
+##' # plot samples
+##' # (only plot every 10th element to accelerate plotting)
+##' plot(seq(0,numRecs.AsspDataObj(res) - 1, 10) / rate.AsspDataObj(res), 
+##'      res$audio[c(TRUE, rep(FALSE,9))], 
+##'      type='l', 
+##'      xlab='time (s)', 
+##'      ylab='Audio samples')
+##'      
 ##' @export
 'affilter' <- function(listOfFiles = NULL, optLogFilePath = NULL, 
                        highPass = 4000, lowPass = 0, 

diff --git a/R/cepstrum.R b/R/cepstrum.R
@@ -36,8 +36,24 @@
 ##' AsspDataObj of that file
 ##' @author Raphael Winkelmann
 ##' @author Lasse Bombien
-##' @seealso \code{\link{dftSpectrum}}, \code{\link{cssSpectrum}}, \code{\link{lpsSpectrum}}; all derived from libassp's spectrum function
+##' @seealso \code{\link{dftSpectrum}}, \code{\link{cssSpectrum}}, \code{\link{lpsSpectrum}}; 
+##' all derived from libassp's spectrum function
 ##' @useDynLib wrassp
+##' @examples
+##' # get path to audio file
+##' path2wav <- list.files(system.file("extdata", package = "wrassp"), 
+##'                        pattern = glob2rx("*.wav"), 
+##'                        full.names = TRUE)[1]
+##' 
+##' # calulate cepstrum
+##' res <- cepstrum(path2wav, toFile=FALSE)
+##' 
+##' # plot cepstral values at midpoint of signal
+##' plot(res$cep[dim(res$cep)[1]/2,], 
+##'      type='l', 
+##'      xlab='cepstral value index', 
+##'      ylab='cepstral value')
+##'      
 ##' @export
 'cepstrum' <- function(listOfFiles = NULL, optLogFilePath = NULL,
                        beginTime = 0.0, centerTime = FALSE,

diff --git a/R/cssSpectrum.R b/R/cssSpectrum.R
@@ -36,8 +36,24 @@
 ##' AsspDataObj of that file
 ##' @author Raphael Winkelmann
 ##' @author Lasse Bombien
-##' @seealso \code{\link{dftSpectrum}}, \code{\link{lpsSpectrum}}, \code{\link{cepstrum}}; all derived from libassp's spectrum function.
+##' @seealso \code{\link{dftSpectrum}}, \code{\link{lpsSpectrum}}, \code{\link{cepstrum}}; 
+##' all derived from libassp's spectrum function.
 ##' @useDynLib wrassp
+##' @examples
+##' # get path to audio file
+##' path2wav <- list.files(system.file("extdata", package = "wrassp"), 
+##'                        pattern = glob2rx("*.wav"), 
+##'                        full.names = TRUE)[1]
+##' 
+##' # calculate cepstrally smoothed spectrum
+##' res <- cssSpectrum(path2wav, toFile=FALSE)
+##' 
+##' # plot spectral values at midpoint of signal
+##' plot(res$css[dim(res$css)[1]/2,], 
+##'      type='l', 
+##'      xlab='spectral value index', 
+##'      ylab='spectral value')
+##'      
 ##' @export
 'cssSpectrum' <- function(listOfFiles = NULL, optLogFilePath = NULL,
                           beginTime = 0.0, centerTime = FALSE,

diff --git a/R/dftSpectrum.R b/R/dftSpectrum.R
@@ -43,8 +43,24 @@
 ##' AsspDataObj of that file
 ##' @author Raphael Winkelmann
 ##' @author Lasse Bombien
-##' @seealso \code{\link{cssSpectrum}}, \code{\link{lpsSpectrum}}, \code{\link{cepstrum}}; all derived from libassp's spectrum function.
+##' @seealso \code{\link{cssSpectrum}}, \code{\link{lpsSpectrum}}, \code{\link{cepstrum}}; 
+##' all derived from libassp's spectrum function.
 ##' @useDynLib wrassp
+##' @examples
+##' # get path to audio file
+##' path2wav <- list.files(system.file("extdata", package = "wrassp"), 
+##'                        pattern = glob2rx("*.wav"), 
+##'                        full.names = TRUE)[1]
+##' 
+##' # calculate dft spectrum
+##' res <- dftSpectrum(path2wav, toFile=FALSE)
+##' 
+##' # plot spectral values at midpoint of signal
+##' plot(res$dft[dim(res$dft)[1]/2,], 
+##'      type='l', 
+##'      xlab='spectral value index', 
+##'      ylab='spectral value')
+##'      
 ##' @export
 'dftSpectrum' <- function(listOfFiles = NULL, optLogFilePath = NULL,
                           beginTime = 0.0, centerTime = FALSE,

diff --git a/R/forest.R b/R/forest.R
@@ -42,6 +42,23 @@
 ##' @author Raphael Winkelmann
 ##' @author Lasse Bombien
 ##' @useDynLib wrassp
+##' @examples
+##' # get path to audio file
+##' path2wav <- list.files(system.file("extdata", package = "wrassp"), 
+##'                        pattern = glob2rx("*.wav"), 
+##'                        full.names = TRUE)[1]
+##' 
+##' # calculate formant values
+##' res <- forest(path2wav, toFile=FALSE)
+##' 
+##' # plot formant values
+##' matplot(seq(0,numRecs.AsspDataObj(res) - 1) / rate.AsspDataObj(res) + 
+##'           attr(res, 'startTime'), 
+##'         res$fm, 
+##'         type='l', 
+##'         xlab='time (s)', 
+##'         ylab='Formant frequency (Hz)')
+##' 
 ##' @export
 'forest' <- function(listOfFiles = NULL, optLogFilePath = NULL,
                      beginTime = 0.0, endTime = 0.0, 

diff --git a/R/ksvF0.R b/R/ksvF0.R
@@ -35,6 +35,23 @@
 ##' @aliases f0ana f0_ksv
 ##' @seealso \code{\link{mhsF0}} for an alternative pitch tracker
 ##' @useDynLib wrassp
+##' @examples
+##' # get path to audio file
+##' path2wav <- list.files(system.file("extdata", package = "wrassp"), 
+##'                        pattern = glob2rx("*.wav"), 
+##'                        full.names = TRUE)[1]
+##' 
+##' # calculate fundamental frequency contour
+##' res <- ksvF0(path2wav, toFile=FALSE)
+##' 
+##' # plot the fundamental frequency contour
+##' plot(seq(0,numRecs.AsspDataObj(res) - 1) / rate.AsspDataObj(res) +
+##'        attr(res, 'startTime'),
+##'      res$F0, 
+##'      type='l', 
+##'      xlab='time (s)', 
+##'      ylab='F0 frequency (Hz)')
+##'      
 ##' @export
 'ksvF0' <- 'f0ana' <- 'f0_ksv' <- function(listOfFiles = NULL, optLogFilePath = NULL, 
                                            beginTime = 0.0, endTime = 0.0, 

diff --git a/R/lpsSpectrum.R b/R/lpsSpectrum.R
@@ -42,8 +42,24 @@
 ##' AsspDataObj of that file
 ##' @author Raphael Winkelmann
 ##' @author Lasse Bombien
-##' @seealso \code{\link{dftSpectrum}}, \code{\link{cssSpectrum}}, \code{\link{cepstrum}}; all derived from libassp's spectrum function.
+##' @seealso \code{\link{dftSpectrum}}, \code{\link{cssSpectrum}}, \code{\link{cepstrum}}; 
+##' all derived from libassp's spectrum function.
 ##' @useDynLib wrassp
+##' @examples
+##' # get path to audio file
+##' path2wav <- list.files(system.file("extdata", package = "wrassp"), 
+##'                        pattern = glob2rx("*.wav"), 
+##'                        full.names = TRUE)[1]
+##' 
+##' # calculate lps spectrum
+##' res <- lpsSpectrum(path2wav, toFile=FALSE)
+##' 
+##' # plot spectral values at midpoint of signal
+##' plot(res$lps[dim(res$lps)[1]/2,], 
+##'      type='l', 
+##'      xlab='spectral value index', 
+##'      ylab='spectral value')
+##' 
 ##' @export
 'lpsSpectrum' <- function(listOfFiles = NULL, optLogFilePath = NULL,
                           beginTime = 0.0, centerTime = FALSE,

diff --git a/R/mhsF0.R b/R/mhsF0.R
@@ -37,6 +37,23 @@
 ##' @aliases mhspitch f0_mhs
 ##' @seealso \code{\link{ksvF0}} for an tracking the fundamental frequency
 ##' @useDynLib wrassp
+##' @examples
+##' # get path to audio file
+##' path2wav <- list.files(system.file("extdata", package = "wrassp"), 
+##'                        pattern = glob2rx("*.wav"), 
+##'                        full.names = TRUE)[1]
+##' 
+##' # calculate fundamental frequency contour
+##' res <- mhsF0(path2wav, toFile=FALSE)
+##' 
+##' # plot fundamental frequency contour
+##' plot(seq(0,numRecs.AsspDataObj(res) - 1) / rate.AsspDataObj(res) +
+##'        attr(res, 'startTime'),
+##'      res$pitch, 
+##'      type='l', 
+##'      xlab='time (s)', 
+##'      ylab='F0 frequency (Hz)')
+##' 
 ##' @export
 'mhsF0' <- 'mhspitch' <- 'f0_mhs' <-function(listOfFiles = NULL, optLogFilePath = NULL,
                                              beginTime = 0.0, centerTime = FALSE, 

diff --git a/R/rfcana.R b/R/rfcana.R
@@ -38,6 +38,23 @@
 ##' @author Raphael Winkelmann
 ##' @author Lasse Bombien
 ##' @useDynLib wrassp
+##' @examples
+##' # get path to audio file
+##' path2wav <- list.files(system.file("extdata", package = "wrassp"), 
+##'                        pattern = glob2rx("*.wav"), 
+##'                        full.names = TRUE)[1]
+##' 
+##' # perform linear prediction analysis
+##' res <- rfcana(path2wav, toFile=FALSE)
+##' 
+##' # plot reflection coefficients
+##' matplot(seq(0,numRecs.AsspDataObj(res) - 1) / rate.AsspDataObj(res) + 
+##'           attr(res, 'startTime'), 
+##'         res$rfc, 
+##'         type='l', 
+##'         xlab='time (s)', 
+##'         ylab='reflection coefficient values')
+##'         
 ##' @export
 'rfcana' <- function(listOfFiles = NULL, optLogFilePath = NULL, 
                      beginTime = 0.0, centerTime = FALSE, 

diff --git a/R/rmsana.R b/R/rmsana.R
@@ -29,6 +29,23 @@
 ##' @author Raphael Winkelmann
 ##' @author Lasse Bombien
 ##' @useDynLib wrassp
+##' @examples
+##' # get path to audio file
+##' path2wav <- list.files(system.file("extdata", package = "wrassp"), 
+##'                        pattern = glob2rx("*.wav"), 
+##'                        full.names = TRUE)[1]
+##' 
+##' # calculate rms values
+##' res <- rmsana(path2wav, toFile=FALSE)
+##' 
+##' # plot rms values
+##' plot(seq(0,numRecs.AsspDataObj(res) - 1) / rate.AsspDataObj(res) +
+##'        attr(res, 'startTime'),
+##'      res$rms, 
+##'      type='l', 
+##'      xlab='time (s)', 
+##'      ylab='RMS energy (dB)')
+##' 
 ##' @export
 'rmsana' <- function(listOfFiles = NULL, optLogFilePath = NULL,
                      beginTime = 0.0, centerTime = FALSE, 

diff --git a/R/zcrana.R b/R/zcrana.R
@@ -24,6 +24,23 @@
 ##' @author Raphael Winkelmann
 ##' @author Lasse Bombien
 ##' @useDynLib wrassp
+##' @examples
+##' # get path to audio file
+##' path2wav <- list.files(system.file("extdata", package = "wrassp"), 
+##'                        pattern = glob2rx("*.wav"), 
+##'                        full.names = TRUE)[1]
+##' 
+##' # calculate zcr values
+##' res <- zcrana(path2wav, toFile=FALSE)
+##' 
+##' # plot rms values
+##' plot(seq(0,numRecs.AsspDataObj(res) - 1) / rate.AsspDataObj(res) +
+##'        attr(res, 'startTime'),
+##'      res$zcr, 
+##'      type='l', 
+##'      xlab='time (s)', 
+##'      ylab='ZCR values')
+##' 
 ##' @export
 'zcrana' <- function(listOfFiles = NULL, optLogFilePath = NULL, 
                      beginTime = 0.0, centerTime = FALSE, 

diff --git a/man/acfana.Rd b/man/acfana.Rd
@@ -17,7 +17,8 @@ acfana(listOfFiles = NULL, optLogFilePath = NULL, beginTime = 0,
 
 \item{beginTime}{= <time>: set begin of analysis interval to <time> seconds (default: 0 = beginning of file)}
 
-\item{centerTime}{= <time>: set single-frame analysis with the analysis window centred at <time> seconds; overrules BeginTime, EndTime and WindowShift options}
+\item{centerTime}{= <time>: set single-frame analysis with the analysis window centred at <time> seconds;
+overrules BeginTime, EndTime and WindowShift options}
 
 \item{endTime}{= <time>: set end of analysis interval to <time> seconds (default: 0 = end of file)}
 
@@ -58,6 +59,23 @@ Analysis results will be written to a file with the
 base name of the input file and extension '.acf'.
 Default output is in SSFF binary format (track 'acf').
 }
+\examples{
+# get path to audio file
+path2wav <- list.files(system.file("extdata", package = "wrassp"),
+                       pattern = glob2rx("*.wav"),
+                       full.names = TRUE)[1]
+
+# calculate short-term autocorrelation
+res <- acfana(path2wav, toFile=FALSE)
+
+# plot short-term autocorrelation values
+matplot(seq(0,numRecs.AsspDataObj(res) - 1) / rate.AsspDataObj(res) +
+        attr(res, 'startTime'),
+        res$acf,
+        type='l',
+        xlab='time (s)',
+        ylab='short-term autocorrelation values')
+}
 \author{
 Raphael Winkelmann
 

diff --git a/man/afdiff.Rd b/man/afdiff.Rd
@@ -48,6 +48,23 @@ very low frequency components - and in the case of central
 differentiation also very high ones - and enhances the
 moment of glottal closure.
 }
+\examples{
+# get path to audio file
+path2wav <- list.files(system.file("extdata", package = "wrassp"),
+                       pattern = glob2rx("*.wav"),
+                       full.names = TRUE)[1]
+
+# compute the first forward difference of the signal
+res <- afdiff(path2wav, toFile=FALSE)
+
+# plot samples
+# (only plot every 10th element to accelerate plotting)
+plot(seq(0,numRecs.AsspDataObj(res) - 1, 10) / rate.AsspDataObj(res),
+     res$audio[c(TRUE, rep(FALSE,9))],
+     type='l',
+     xlab='time (s)',
+     ylab='Audio samples')
+}
 \author{
 Raphael Winkelmann