evaluateDeployment: Evaluate deployment of recording files for potential problems

In PAMscapes: Tools for Summarising and Analysing Soundscape Data

Evaluate deployment of recording files for potential problems

Description

Runs a number of quality assurance / quality control (QAQC) checks on a folder of recording files to identify potential problems. These include checking the start and end times of files for consistency to identify potential data gaps, measuring sound levels in each file to identify potential recorder issues, and (if applicable) checking battery and temperature data to identify potential instrument failure. Can also create spectrogram images throughout the deployment to aid in visually checking for problems or noise.

Usage

evaluateDeployment(
  dir,
  excludeDirs = c("Post_Retrieval_Data", "Pre_Deployment_Data"),
  sampleWindow = c(60, 120),
  channel = 1,
  sensitivity = NA,
  calibration = NULL,
  timeRange = NULL,
  name = NULL,
  subDirPattern = NULL,
  outDir = NULL,
  nSpectrograms = 0,
  specLength = 1800,
  panelLength = 300,
  log = FALSE,
  progress = TRUE,
  verbose = TRUE
)

Arguments

dir	folder or folders containing recordings and optionally Soundtrap .log.xml files. All .wav and .log.xml files within dir will be analysed, as well as all files in each subfolder of dir (only going down one level).
excludeDirs	the names of any subfolders within dir that should be excluded (e.g. if dir contains folders "Recordings" and "Clips" then excludeDirs="Clips" would result in only the "Recordings" folder being analysed
sampleWindow	start and end (in seconds) of the time window to use for analysis, e.g. c(40, 100) will use a 60 second window starting 40 seconds into the file
channel	channel number of recording files to use for analysis
sensitivity	the sensitivity of the recording device in dB, this is typically a large negative number
calibration	if not NULL, the frequency dependent calibration to apply. Must have "frequency" and "gain" (in dB), can either be a .tf file, a CSV file with columns for frequency and gain, or a dataframe with columns frequency and gain
timeRange	if not NULL, a vector of two POSIXct times identifying the expected start and end times of the deployment. If the actual start and end times of of the recording files are earlier or later than these, then a warning will be issued and no calculations will be done, returning NULL
name	a name to assign for this deployment, used for plot labeling, logging, and stored as projectName with the output dataframe. If left as NULL, then the basename of dir will be used.
subDirPattern	if not NULL, a pattern to use for selecting which subfolders of dir to use for analysis. E.g. if folders "Site1_Recordings" and "Site2_Recordings" both exist in dir, then subDirPattern="^Site1" would result in analysing only the first folder of recordings
outDir	if not NULL, a directory to store outputs. Outputs include plots, a CSV of the calculated metrics, and a .txt log file if log=TRUE
nSpectrograms	number of spectrogram images to generate. Recording files for creating the spectrograms will be approximately evenly spaced throughout the deployment - if nSpectrograms=5, then the first recording will be randomly chosen from the first 20% of files, the second from the second 20%, etc.
specLength	length of spectrograms to create, in seconds
panelLength	length of each panel of the spectrogram plot, in seconds. This must be less than specLength, and is used to avoid creating awkwardly long plots. If specLength=360 and panelLength=60, then the result will be a 6 panel plot where each section is 60 seconds long
log	if TRUE and outDir is not NULL, then a text file named "(name)_EvaluateRecorder_LogFile.txt" will be created in outDir logging progress and warning messages
progress	logical flag to show a progress bar
verbose	logical flag to show some messages

Value

a dataframe of the QAQC metric outputs for each recording file

PAMscapes documentation built on April 4, 2025, 2:17 a.m.