nvspl_to_ai: Convert NVSPLs data into acoustic indices

In nationalparkservice/NSNSDAcoustics: Streamline National Park Service Bioacoustics Analysis

Convert NVSPLs data into acoustic indices

Description

Convert NVSPL table data into acoustic indices.

Usage

nvspl_to_ai(
  input.directory,
  output.directory,
  project,
  instrum = "SM4",
  start.at.beginning = TRUE,
  fminimum = "H1600",
  fmaximum = "H8000",
  fbinMax = 8,
  BKfminimum = "H31p5",
  BKfmaximum = "H1250",
  timestep = 10,
  startday = 1,
  plt = FALSE
)

Arguments

input.directory	Top-level NVSPL directory from which to ingest data (often named "NVSPL").
output.directory	Where to place output files (often named "ANALYSIS").
project	File name for your project (e.g., 'GLBAPhenology2019').
instrum	Audio recorder used. Default = 'SM4'.
start.at.beginning	Logical flag for where computation should start. Default = TRUE. If TRUE, computation starts at the beginning of recordings on a given day. TRUE is preferred in most cases for NSNSD bioacoustic analyses. When FALSE, indices are calculated only for data that begins at the top of the chosen timestep. For example, if timestep is 10 minutes, then each AI calculation will start at 0, 10, 20, 30, 40, 50 for each hour. If the full ten minute sample is not available, the timestep is skipped. start.at.beginning = FALSE may be desired if the user wishes to break results easily into hours.
fminimum	Lower limit of frequency band of interest (NOTE: HXXXX represents the center frequency of the octave band, eg. H1600 = 1413-1778 Hz). Default = 'H1600'.
fmaximum	Upper limit of frequency band of interest. Default = 'H8000'.
fbinMax	Sets the frequency bins to look across for cluster analysis. Default = 8.
BKfminimum	Lower limit of frequency bands for background noise (NOTE: if NVSPL calculated with PAMGuide, no data below H25). Default = 'H31p5'.
BKfmaximum	Upper limit of frequency bands for background noise. Default = 'H1250'.
timestep	Timestep of computation, in minutes (NOTE: to get daily values, summarizing the timestep values is preferred over running the code for an entire day). Default = 10.
startday	Optional start date if many files or error.
plt	Logical flag for whether to plot NVSPL files. NOTE: this will slow the function down considerably. Default = FALSE.

Details

CSV file contains the following 59 columns:

• Site: Site name.

• Date: Date as YYYY_MM_DD.

• Yr: Year as YYYY.

• Mo: Month of year as integer.

• Day: Day of month.

• Hr: Hour of day.

• Min: Minute of hour

• Sec: Second of minute.

• timestep: In minutes, the time increment over which acoustic indices are calculated.

• SampleLength_sec: Sample length (i.e., timestep) in seconds.

• ACIout: ACI results for each time chunk on a given day - SPLs (link to documentation of how this was computed, or describe here)

• ACIoutI: ACI results for each time chunk on a given day - intensity (unlog)

• ACIoutN: ACI results for each time chunk on a given day - normalized

• BKdB_low: These are all background noise of some kind. Unclear on the details based on the code

• BKdBA_low: tbd.

• BKdB_bird: tbd.

• BKdBA_bird: tbd.

• avgAMP: tbd.

• L10AMP: tbd.

• Hf: tbd.

• Ht: tbd.

• El: tbd.

• BioPh: tbd.

• AthPh: tbd.

• SoundScapeI: tbd.

• AA: Acoustic activity, but unclear to me what each of these means based on the code. Regular AA is average time a noise is above background in each timestep.

• AAc: tbd.

• AAdur: tbd.

• AAanth: tbd.

• AAcanth: tbd.

• AAduranth: tbd.

• Rough: Roughness - change in acoustic energy from one second to the next, summarized over timestep.

• ADI_step: Acoustic diversity index for the timestep (based on vegan::diversity)

• Eveness_step: ineq::Gini

• pk: tbd.

• pkd: tbd.

• pks: tbd.

• Hm: tbd.

• HvPres: tbd.

• HvSPL: tbd.

• unlist(dif_L10L90): tbd. What is this colname?

• Mamp: maybe this is acoustic richness instead, according to the code (though at some point I concluded not based on plots)

• NumCL: tbd.

• SP2: this might be spectral persistence??

• CL1dur: tbd.

• CL1pk: tbd.

• CL1Leq: tbd.

• CL2dur: tbd.

• CL2pk: tbd.

• CL2Leq: tbd.

• CL3dur: tbd.

• CL3pk: tbd.

• CL3Leq: tbd.

• CL4dur: tbd.

• CL4pk: tbd.

• CL4Leq: tbd.

• vers: PAMGUIDE version used for NVSPLs that gets carried over into here? Or is this AI versioning, documentation of which I have yet to locate?

• AR: Acoustic richness - i'm assuming that's what AR stands for?

Value

Returns a CSV file of the acoustic indices to the output directory. For posterity, also saves a "params" file to the output.directory.

See Also

wave_to_nvspl

Examples

## Not run: 

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

# Read in example NVSPL data
data(exampleNVSPL)

# Write example NVSPL data to example input directory
for (i in 1:length(exampleNVSPL)) {
  write.table(
    x = exampleNVSPL[[i]],
    file = paste0('example-input-directory/', names(exampleNVSPL)[i]),
    sep = ',',
    quote = FALSE
  )
}

# Run nvspl_to_ai to generate acoustic indices csv for example NVSPL files
nvspl_to_ai(
  input.directory = 'example-input-directory',
  output.directory = 'example-output-directory',
  project = 'example-project'
)

# View Results
(ai.results <- read.csv(
  list.files(path = 'example-output-directory',
             pattern = '.csv', full.names = TRUE))
)

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


## End(Not run)

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