wave_to_nvspl: Calibrate and convert wave files into NVSPL formatted table

In nationalparkservice/NSNSDAcoustics: Streamline National Park Service Bioacoustics Analysis

Calibrate and convert wave files into NVSPL formatted table

Description

This function uses PAMGuide code to convert wave files into an NVSPL formatted table. These are hourly files comprised of 1/3 octave data in 1-sec LEQ increments. PAMGuide was developed by Merchant et al. 2015. The suggested workflow for this function is to first set test.file = TRUE to test that your workflow has been accurately parameterized. Next, to batch process NVSPLs, run with test.file = FALSE.

Usage

wave_to_nvspl(
  input.directory,
  results.directory,
  data.directory = TRUE,
  test.file = FALSE,
  project,
  instrum = "SM4",
  filext = "_%Y%m%d_%H%M%S.wav",
  filpat = ".+\\d{8}_\\d{6}.wav",
  mhset = -35,
  Gset = 16,
  vADCset = 1,
  enviset = "Air",
  rescWat = 0,
  timezone
)

Arguments

input.directory	Top-level input directory path to audio files to be processed. e.g. E:/AUDIO. Audio files are expected to have the naming convention SITEID_YYYYMMDD_HHMMSS.wav. For nonstandard file patterns, use the filext and filpat arguments (NOT TESTED).
results.directory	OPTIONAL character path stating where NVSPL .txt files should be placed. If omitted, NVSPL directory will be created automatically within input directory.
data.directory	Logical flag to specify whether audio files are housed in 'Data' subdirectories
test.file	Logical flag for whether to test a file. If TRUE, tests a single file and produces plots and diagnostic outputs. If FALSE, processes entire audio dataset indicated by input.directory.
project	File name for your project (e.g., 'GLBAPhenology2019').
instrum	Audio recorder used. Default = 'SM4'.
filext	File extension pattern. Default = '%Y%m%d%H%M%S.wav'. If using split files, '0%Y%m%d_%H%M%S_000.wav'.
filpat	File pattern. Default = '.+\d8_\d6.wav'.
mhset	Microphone sensitivity (dBV/Pa). Default = -35.
Gset	Gain setting. Default = 16.
vADCset	Zero-peak. Default = 1.
enviset	Use 'Air' or 'Wat' to indicate whether audio recordings occurred in a terrestrial or underwater environment, respectively. Default = 'Air'.
rescWat	Use 1 if you want to re-scale underwater values to be able to plot using AMT, 0 if not. Default = 0.
timezone	Specify timezone setting used in the audio recorder (e.g, 'GMT'). If recordings were taken in local time at your study site, specify an Olson-names-formatted character timezone for the location (e.g., 'America/Los_Angeles'). This is extremely important to foster clarity in data analysis through the years, as some projects have varied year to year in whether recordings were taken in GMT vs. local time.

Details

This function was developed by the National Park Service Natural Sounds and Night Skies Division to act as a wrapper to PAMGuide that would support NSNSD data processing workflows.

For more information on function arguments such as mhset, Gset, and vADCset, NSNSD staff should see this tutorial.

PAMGuide was published as supplementary material to the following Open Access journal article:

Merchant, N.D., Fristrup, K.M., Johnson, M.P., Tyack, P.L., Witt, M.J., Blondel, P., Parks, S.E. (2015). Measuring acoustic habitats. Methods in Ecology and Evolution.

• View accompanying PAMGuide tutorial

• Download original PAMGuide code

Value

If test.file = TRUE, returns diagnostics. If test.file = FALSE, returns NVSPL txt files in NVSPL folder generated by the function.

Output NVSPL txt file contains the following columns. Note that many of these columns (e.g. Voltage, WindSpeed, INVID) will not be filled in if processing wave files; however, columns are retained here for compatibility with other NPS workflows.

• SiteID: Site name.

• STime: Date time.

• H12p5 through H20000: ISO standard 1/3 octave band with energy centered around the specified frequency. See ANSI S1.11.

• dbA: A-weighted noise measurement.

• dbC: C-weighted noise measurement. Not applied in this function.

• dbZ: Z-weighted noise measurement.

• Voltage: Voltage.

• WindSpeed: WindSpeed.

• WindDir: WindDir.

• TempIns: Internal temperature of the measurement instrument.

• TempOut: External temperature.

• Humidity: Humidity.

• INVID: Investigator ID.

• INSID: Instrument ID.

• GChar1: General character placeholder.

• PAMGuideVersion: Version of NSNSD PAMGuide code used.

• timezone: Indicates the timezone reflected in the audio filename. 'GMT' indicates that audio recordings were taken with no timezone adjustment. If recordings were taken in local time at a study site, please specify an Olson-names-formatted character timezone for the location (e.g., 'America/Los_Angeles'). This is extremely important to foster clarity in data analysis through the years, as some projects vary across time and space in terms of whether recordings are taken in GMT vs. local time.

• AdjustmentsApplied: Used for gain or windscreen corrections.

• CalibrationAdjustment: Calibration ID (often not used).

• GPSTimeAdjustment: GPS-based time adjustment.

See Also

nvspl_to_ai

Examples

## Not run: 

# Create an input directory for this example
dir.create('example-input-directory')

# Read in example wave files
data(exampleAudio1)
data(exampleAudio2)

# Write example waves to example input directory
tuneR::writeWave(
  object = exampleAudio1,
  filename = 'example-input-directory/Rivendell_20210623_113602.wav'
)

tuneR::writeWave(
  object = exampleAudio2,
  filename = 'example-input-directory/Rivendell_20210623_114602.wav'
)

# Perform wave_to_nvspl in test mode (test.file = TRUE)
wave_to_nvspl(
 input.directory = 'example-input-directory',
 data.directory = FALSE,
 test.file = TRUE,
 project = 'testproject',
 timezone = 'GMT'
)

# Perform wave_to_nvspl in batch mode (test.file = FALSE)
wave_to_nvspl(
 input.directory = 'example-input-directory',
 data.directory = FALSE,
 test.file = FALSE,
 project = 'testproject',
 timezone = 'GMT'
)

# Verify that NVSPL outputs have been created
nvspls <- list.files('example-input-directory/NVSPL', full.names = TRUE)

# View one of the NVSPL outputs
one.nvspl <- read.delim(file = nvspls[1], sep = ',')

# Delete all temporary example files when finished
unlink(x = 'example-input-directory', recursive = TRUE)


## End(Not run)

nationalparkservice/NSNSDAcoustics documentation built on March 4, 2025, 10:24 p.m.