align {callsync}

align

Description

Aligns multiple recordings (.wav files). It assumes all microphones are within recording range of each other most of the time.

Usage

align(
  chunk_size = 15,
  step_size = 0.5,
  all_files = NULL,
  path_recordings = NULL,
  path_chunks = NULL,
  chunk_seq = NULL,
  keys_id = NULL,
  keys_rec = NULL,
  blank = 15,
  wing = 10,
  ffilter_from = NULL,
  down_sample = NULL,
  save_pdf = FALSE,
  save_log = FALSE,
  quiet = FALSE
)

Arguments

chunk_size

numeric, duration in minutes of the chunks to output. Default is '15'.

step_size

numeric, duration in seconds of the bins for signal compression before cross correlation. Default is '0.5'.

all_files

character vector, paths to all raw recordings to consider. If 'NULL' files are listed based on the argument 'path_recordings'.

path_recordings

character, the path where the raw recordings are stored. Can be nested in folders, in this case provide the top-level folder.

path_chunks

character, the path where aligned chunks should be stored.

chunk_seq

numeric vector or 'NULL'. If supplied only these chunks are rerun.

keys_id

character vector of length 2. The characters before and after the unique ID of the individual or microphone. This can be in the file name or in the folder structure. E.g., if the path to the recording is ‘../data/week_1/recording_mic1.wav' the keys would be 'c(’recording_', '.wav')' and the function would retrieve 'mic1' as individual id.

keys_rec

character vector of length 2. The characters before and after the unique ID of the recording. This can be in the file name or in the folder structure. E.g., if the path to the recording is ‘../data/week_1/recording_mic1.wav' the keys would be 'c(’data/', '/recording')' and the function would retrieve 'week_1' as recording id.

blank

numeric, the duration in minutes to be discarded at the beginning and end of the recording.

wing

numeric, the duration in minutes to load before and after each chunk to improve alignment. This is not saved with the aligned chunk.

ffilter_from

numeric, frequency in Hz for the high-pass filter.

down_sample

numeric, the sample rate for down-sampling. If 'NULL' no down-sampling is done.

save_pdf

logical, if 'TRUE' a pdf is saved with a page per chunk that shows all the aligned recordings.

save_log

logical, if 'TRUE' a csv file with all alignment times is saved in path_chunks.

quiet

logical, if 'TRUE' no messages are printed.

Details

There are two ways to tell the function where the files are. You can either compile a character vector of pathnames yourself and enter this under 'all_files' or you can give a single character path to 'path_recordings'. You need to make sure that there is an identifier by which to group the recordings and an identifier for each individual or microphone in the path. This can either be a in the folder structure or in the file names themselves. The align function will align all individuals per recording id (e.g., date). These identifiers are found using regexp, so mostly you can use the first few characters before and after them (see examples in the argument descriptions). The function loads chunks of the recordings, sums the absolute amplitude per bin and runs cross correlation to find alignment relative to the first recording. The aligned chunks are then saved.

Value

saves all the aligned chunks in the location specific by 'path_chunks'.

Examples

## Not run: 
require(callsync)
require(seewave)
require(tuneR)
path_git = 'https://raw.githubusercontent.com'
path_repo = '/simeonqs/callsync/master/tests/testthat/files'
file_1 = '/chunk@1@1@[e-mail]'
file_2 = '/chunk@2@1@[e-mail]'
url_1 = paste0(path_git, path_repo, file_1)
url_2 = paste0(path_git, path_repo, file_2)
local_file_1 = paste(tempdir(), file_1, sep = '/')
local_file_2 = paste(tempdir(), file_2, sep = '/')
if(!file.exists(local_file_1))
  download.file(url_1, destfile = local_file_1, mode = 'wb',)
if(!file.exists(local_file_2))
  download.file(url_2, destfile = local_file_2, mode = 'wb')
all_files = c(local_file_1, local_file_2)
a = align(chunk_size = 2,
          step_size = 0.1,
          all_files = all_files,
          keys_id = c('c', '@'),
          keys_rec = c('c', '@'),
          blank = 0,
          wing = 0,
          quiet = TRUE)

## End(Not run)