plot_audio_summary: Plot barcharts of daily and hourly total recordings across a...

In nationalparkservice/NSNSDAcoustics: Streamline National Park Service Bioacoustics Analysis

Plot barcharts of daily and hourly total recordings across a park bioacoustics dataset.

Description

Exploratory summary function that creates ggplots of total number of hours of audio collected by date, and total number of hours of audio collected by hour, across a yearly season for 1 or more locations in a park bioacoustic monitoring project. This function helps provide overviews to the user of when recordings were taken, and where gaps in the dataset may have occurred. Summaries may be generated either from a directory that points to raw audio files, or from an acoustic index file like that generated by nvspl_to_ai. Using the acoustic.index.fp is desired over using the audio.directory path, particularly for projects that have spanned many years and may have used varied audio recorder parameter settings. See Details.

Usage

plot_audio_summary(
  audio.directory,
  acoustic.index.fp,
  max.x = 20,
  nrow,
  ncol,
  tz.recorder,
  tz.local,
  sample.rate.hz = 44100,
  bit.depth = 16,
  bit.rate = 1024,
  channels = 2
)

Arguments

audio.directory	OPTIONAL. Path to audio files to be processed. Files are expected to have the naming convention SITEID_YYYYMMDD_HHMMSS. User must invoke either the audio.directory OR the acoustic.index.fp argument.
acoustic.index.fp	OPTIONAL. Path an acoustic index file like that generated by nvspl_to_ai. User must invoke either the audio.directory OR the acoustic.index.fp argument.
max.x	Maximum number of labels to include on the x axis of the date plot. Default = 20. Adjust as needed based on output.
nrow	If plotting data that includes multiple locations and/or years, specify the number of rows the plot should have. Adjust as needed based on output.
ncol	If plotting data that includes multiple locations and/or years, specify the number of columns the plot should have. Adjust as needed based on output.
tz.recorder	If using audio.directory argument, specify the timezone setting used in the audio recorder using an Olson-names-formatted character timezone for the location (e.g., 'UTC', 'America/Los_Angeles').
tz.local	Specify an Olson-names-formatted character timezone for the monitoring location.
sample.rate.hz	If using audio.directory argument, specify the sample rate in Hz used by the audio recorder for this dataset. Default = 44100.
bit.depth	If using audio.directory argument, specify the bit depth used by the audio recorder for this dataset. Default = 16.
bit.rate	If using audio.directory argument, specify the bit rate used by the audio recorder for this dataset. Default = 1024.
channels	If using audio.directory argument, specify the number of channels used by the audio recorder for this dataset. Default = 2.

Details

This function was developed by the National Park Service Natural Sounds and Night Skies Division. It is intended to provide exploratory plotting that summarizes the total number of hours collected by date and by season in a park bioacoustics project.

Using the acoustic.index.fp is desired over the audio.directory path. If computing audio hour totals directly from the audio.directory argument, totals are estimated based on the sample.rate.hz, bit.rate, bit.depth, and channels provided by the user or in the defaults for these arguments; thus, if an audio directory contains data with varying sample rates used over the years, the estimate provided from the audio directory may not be accurate. The function does NOT read every audio file to compute total values because this would be computationally prohibitive; instead, if using audio.directory, it assumes the user has done their due diligence inputting values for sample.rate.hz, bit.rate, bit.depth, and channels. If recordings occur over multiple hours and audio.directory is used, the plot.hours graphic will only display that data were collected over the hour specified in the file name, which may not give a correct estimate.

Value

Length 2 list of ggplot2 objects named plot.dates and plot.hours.

See Also

wave_to_nvspl, nvspl_to_ai

Examples

## Not run: 


############################################
#
#  Example using acoustic.index.fp argument
#
############################################

# Read in example acoustic index data
data(exampleAI)

# Write sample data to working directory
write.csv(x = exampleAI, file = 'ai.csv')

gg <- plot_audio_summary(
 acoustic.index.fp = 'ai.csv',
 tz.local = 'America/Anchorage',
 max.x = 10,
 nrow = 4,
 ncol = 3
 )

# View plots
gg$plot.dates
gg$plot.hours

# Delete all temporary example files when finished
unlink(x = 'ai.csv')

############################################
#
#  Example using audio.directory argument
#
############################################


# 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')

gg <- plot_audio_summary(
 audio.directory = 'example-input-directory',
 tz.recorder = 'UTC',
 tz.local = 'America/Los_Angeles',
 sample.rate.hz = 22050,
 bit.depth = 16,
 bit.rate = 1024,
 channels = 2
)

# View plots
gg$plot.dates
gg$plot.hours

# 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.