acfana: Analysis of short-term autocorrelation function of signals
In humlab-speech/superassp: A speech signal processing using various framworks using a wrassp-like interface

acfana

R Documentation

Analysis of short-term autocorrelation function of signals

Description

Applies the autocorrelation function to windows of the input signals listed in listOfFiles. Input signals not in a file format natively supported will be converted before the autocorrelation functions are computed. The conversion process will display warnings about input files that are not in known losslessly encoded formats.

The results will be will be written to an SSFF formated file with the base name of the input file and extension .acf in a track ACF.

Usage

acfana(
  listOfFiles = NULL,
  beginTime = 0,
  centerTime = FALSE,
  endTime = 0,
  windowShift = 5,
  windowSize = 20,
  effectiveLength = TRUE,
  window = "BLACKMAN",
  analysisOrder = 0,
  energyNormalization = FALSE,
  lengthNormalization = FALSE,
  toFile = TRUE,
  explicitExt = "acf",
  outputDirectory = NULL,
  assertLossless = NULL,
  logToFile = FALSE,
  keepConverted = FALSE,
  verbose = TRUE
)

Arguments

`listOfFiles`	vector of file paths to be processed by function
`beginTime`	the time point (in seconds) of the start of the analysed interval. A NULL or 0 is interpreted as the start of the signal file. If a vector of time points is supplied, the length of that vector needs to correspond with the length of `listOfFiles`.
`centerTime`	sets a single-frame analysis time point (in seconds). Overrides `beginTime`, `endTime` and `windowShift` parameters.
`endTime`	the time point (in seconds) of the end of the analysed interval. A NULL or 0 is interpreted as the end of the signal file. If a vector of time points is supplied, the length of that vector needs to correspond with the length of `listOfFiles`.
`windowShift`	the amount of time (in ms) that the analysis window will be shifted between analysis frames
`windowSize`	the analysis window size (in ms); overrides the effect of the `effectiveLength` parameter
`effectiveLength`	make window size effective rather than exact
`window`	= the analysis window function type ("BLACKMAN" by default). See AsspWindowTypes for a list of supported window types.
`analysisOrder`	the analysis order. The `NULL` or `0` sets the analysis order to the sample rate (in kHz) + 3, so that a signal with a 16000 Hz sampling rate will be analysed using an `analysisOrder` of 19.
`energyNormalization`	calculate energy-normalized autocorrelation
`lengthNormalization`	calculate length-normalized autocorrelation
`toFile`	Should the function write the results to a file, with the (default) file extension (`TRUE`) or returned as a list of AsspDataObj objects (`FALSE`)?
`explicitExt`	the file extension will be used when result files are written (`toFile=TRUE`), but the file extension can be set to something else using this function argument.
`outputDirectory`	directory in which output files are stored. Defaults to NULL which means that the result file will be stored in the same directory as the input file.
`assertLossless`	an optional list of file extensions that the user wants to assert contains losslessly encoded signals data.
`logToFile`	whether to log commands to a separate logfile in the `outputDirectory`. Logging will otherwise be in the function-specific logging namespace of logger and will be put wherever this namespace is defined to place its output. See logger::log_appender for details.
`verbose`	display verbose information about processing steps taken, as well as progress bars.

Details

The function is a re-write of the wrassp::acfana function, but with media pre-conversion, better checking of preconditions such as the input file existance, structured logging, and the use of a more modern framework for user feedback.

The native file type of this function is "wav" files (in "pcm_s16le" format), SUNs "au", NIST, or CSL formats (kay or NSP extension). Input signal conversion, when needed, is done by libavcodec and the excellent av::av_audio_convert wrapper function

Value

The number of successfully written files (if toFile=TRUE), or a vector of AsspDataObj objects (if toFile=FALSE).

Note

This function is not considered computationally expensive enough to require caching of results if applied to many signals. However, if the number of signals it will be applied to is very large, then caching of results may be warranted.

Please note the unit reported is Hz², which may be accurate depending on whether the signal is normalized or not.

References

\insertAllCited

Examples

# get path to audio file
path2wav <- list.files(system.file("samples","sustained", package = "superassp"), pattern = glob2rx("a1.wav"), full.names = TRUE)

# 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 (Hz²)')

humlab-speech/superassp documentation built on May 8, 2024, 2:27 p.m.