Title:	Bioacoustic Analysis and Publication Tools
Version:	0.0.7
Description:	Provides tools for manipulating sound files for bioacoustic analysis, and preparing analyses these for publication. The package validates that values are physically possible wherever feasible.
Depends:	R (≥ 3.4.0)
Imports:	methods, ggplot2, hms, jsonlite, mime, Rdpack, seewave, stringi, suncalc, tuneR
License:	GPL-3
Encoding:	UTF-8
LazyData:	true
RoxygenNote:	7.3.1
Language:	en-GB
Suggests:	av, covr, devtools, googleCloudStorageR, googleLanguageR, knitr, parallel, pbapply, plotrix, reticulate, rmarkdown, soundecology, spelling, testthat (≥ 3.0.0), WaveletComp
VignetteBuilder:	knitr
URL:	https://sonicscrewdriver.ebaker.me.uk, https://github.com/edwbaker/SonicScrewdriveR
Config/testthat/edition:	3
BugReports:	https://github.com/edwbaker/SonicScrewdriveR/issues
RdMacros:	Rdpack
NeedsCompilation:	no
Packaged:	2024-05-11 20:34:31 UTC; edwab
Author:	Ed Baker [aut, cre], Quentin Geissman [ctb]
Maintainer:	Ed Baker <ed@ebaker.me.uk>
Repository:	CRAN
Date/Publication:	2024-05-11 20:50:02 UTC

PseudoWave scalar manipulation

Description

PseudoWave scalar manipulation

Usage

## S4 method for signature 'PseudoWave,numeric'
e1 * e2

Arguments

Numeric multiplication by PseudoWave

Description

Numeric multiplication by PseudoWave

Usage

## S4 method for signature 'numeric,PseudoWave'
e1 * e2

Arguments

PseudoWave scalar addition

Description

PseudoWave scalar addition

Usage

## S4 method for signature 'PseudoWave,numeric'
e1 + e2

Arguments

Numeric addition by PseudoWave

Description

Numeric addition by PseudoWave

Usage

## S4 method for signature 'numeric,PseudoWave'
e1 + e2

Arguments

PseudoWave scalar subtraction

Description

PseudoWave scalar subtraction

Usage

## S4 method for signature 'PseudoWave,numeric'
e1 - e2

Arguments

PseudoWave scalar division

Description

PseudoWave scalar division

Usage

## S4 method for signature 'PseudoWave,numeric'
e1 / e2

Arguments

A S4 class for annotations

Description

The Annotation class is used to store annotations on Wave-like objects.

Slots

file

File being annotated.

metadata

A list for storing metadata.

start

Start time of annotation.

end

End time of annotation.

low

Low frequency of annotation.

high

High frequency of annotation.

source

Source of annotation.

type

Type of annotation.

value

Value of annotation.

An S4 class to represent a PseudoWave object that is converted to a Wave object when operated on.

Description

An S4 class to represent a PseudoWave object that is converted to a Wave object when operated on.

Slots

type

Type of PseudoWave (e.g. "noise")

subtype

Subtype of PseudoWave (e.g. "white" if type is "noise")

scale

The Wave channels are multiplied by this value

offset

This value is added to the Wave channels

seed

Random seed for reproducible output, NA for no seed

scale

Logical. Whether to use the random seed value

params

List of additional parameters to pass to generating function

STP: Standard Temperature and Pressure

Description

Dataset compiled from various sources for differing values of STP.

Usage

STP

Format

An object of class list of length 2.

A S4 class for tagged waves

Description

The TaggedWave class extended the Wave class from the tuneR package so that it can include extended metadata and the results of analyses.

Slots

metadata

A list for storing metadata.

analyses

A list for storing analyses.

A S4 class for tagged multi-channel waves

Description

The TaggedWaveMC class extended the WaveMC class from the tuneR package so that it can include extended metadata and the results of analyses.

Slots

metadata

A list for storing metdata.

analyses

A list for storing analyses.

An S4 class to represent a TimeRegion within a Wave object.

Description

An S4 class to represent a TimeRegion within a Wave object.

Slots

from

Start position

to

End position

unit

Time unit (one of seconds, minutes, hours)

WaveFilter object for audio filters

Description

A WaveFilter object is an object containing information necessary for the filterWave() function to apply the filter to a Wave or TaggedWave object. This is designed to allow a pipe operator (either magrittr or base R) to be used to apply filters to a Wave in a pipeline. If used with a TaggedWave object the function adds information to the processing slot documenting its action.

Slots

description

Description of the filter.

func

Name of function.

params

List of additional parameters to pass to the function.

Allow subsetting a Wave object with a TimeRegion

Description

Allow subsetting a Wave object with a TimeRegion

Usage

## S4 method for signature 'Wave,TimeRegion'
x[i]

Arguments

Convert text times of day in audioblast traits to numeric values

Description

This function takes a traits dataset retrieved from audioblast and converts values such as "day" into a numeric time of day based on the date and location.

Usage

ab_diel_traits(traits, date, lat, lon, overwrite = FALSE)

Arguments

Nearest start time

Description

Search audioBLAST! for recordings with a start time closest to specified date/time which match specified criteria

Usage

ab_seqss_nearestStart(...)

Arguments

Value

A data frame of matching annotations

Examples

## Not run: 
ab_seqss_nearestStart(date="2020-05-15",time="1500")

## End(Not run)

Add a process to a Tagged Wave or WaveMC object

Description

This function takes a TaggedWave or TaggedWaveMC object and adds a process to the processing slot. This is used to keep a record of the processes that have been applied to the object.

Usage

addProcess(object, process, output = NULL, duration = NULL)

## S4 method for signature 'TaggedWave'
addProcess(object, process, output = NULL, duration = NULL)

## S4 method for signature 'TaggedWaveMC'
addProcess(object, process, output = NULL, duration = NULL)

Arguments

Value

The object with the process added.

Add two spectra from seewave

Description

This function takes two spectra from seewave (or equivalent) and adds their values. The spectra must have the same bins.

Usage

addSpectra(s1, s2, coerceNegative = TRUE)

Arguments

Value

A spectrum of s1+s2

Examples

## Not run: 
subtractSpectra(spec1, spec2)

## End(Not run)

Apply a function to all channels of a Wave or WaveMC object

Description

Some functions (e.g. ffilter from seewave) only operate on a single channel at a time. This function applies the function to each channel and returns a list of analyses.

Usage

allChannels(
  w,
  FUN,
  cl = NULL,
  channel.param = "channel",
  output.FUN = NULL,
  ...
)

Arguments

Value

A list of outputs.

Create a new Annotation object

Description

Create a new Annotation object

Usage

annotation(
  file = NA_character_,
  metadata = list(),
  start = 0,
  end = Inf,
  low = 0,
  high = Inf,
  source = NA_character_,
  type = NA_character_,
  value = NA_character_
)

Arguments

Value

An Annotation object.

Calculated size of raw audio files

Description

Calculates the raw size of audio date at set sample rate, bit depth and duration.

Usage

audio_filesize(
  samp.rate = 44100,
  bit.depth = 16,
  channels = 1,
  duration = 1,
  duration.unit = "seconds",
  output.unit = "bits"
)

Arguments

Get data or analyses from audioBlast

Description

Search for data or analyses on audioBlast.

Usage

audioblast(
  type,
  name,
  endpoint = NULL,
  check = TRUE,
  max_pages = NULL,
  page = 1,
  quiet = FALSE,
  on.issue = stop,
  output = "data.frame",
  ...
)

Arguments

Value

A data frame

Examples

## Not run: 
audioblast("data", "recordings", taxon="Gryllotalpa vineae")

## End(Not run)

Download audio files from audioBlast

Description

Downloads audio files associated with a search using the audioBlast() function.

Usage

audioblastDownload(
  d,
  metadata = TRUE,
  skip.existing = TRUE,
  dir = ".",
  quiet = FALSE,
  on.issue = .audioblastIssue
)

Arguments

Read AudioMoth configuration file

Description

Reads and parses an AudioMoth configuration file.

Usage

audiomothConfig(filename)

Arguments

Value

A data frame of matching annotations

Examples

## Not run: 
audiomothConfig("./CONFIG.TXT")

## End(Not run)

Read AudioMoth metadata from a wave file

Description

Reads and parses metadata stored in wave files produced by AudioMoth devices.

Usage

audiomothWave(filename)

Arguments

Value

A list of extracted parameters

Examples

## Not run: 
audiomothWave("./FILENAME.WAV")

## End(Not run)

Automatic Band Pass Filter

Description

Creates an automatic bandpass filter based on the strongest frequency. The allowed bandwidth can be an integer multiple of the bandwidth at either -3dB or -10dB.

Usage

autoBandPass(wave, bw = "-3dB", n.bw = 1, lowcut = 1000)

Arguments

Value

A band-pass filtered Wave object

Examples

## Not run: 
autoBandPass(sheep)
autoBandPass(sheep, bw="-3dB", n.bw=1, lowcut=1000)
autoBandPass(sheep, bw="-10dB", n.bw=2, lowcut=0)

## End(Not run)

Simple bandpass filter

Description

Creates a band pass WaveFilter between values specified to a Wave object.

Usage

bandpass(from, to, ...)

Arguments

Details

This is a simple wrapper function to the seewave ffilter function allowing its use with filterw and pipes.

Value

A WaveFilter object.

Examples

## Not run: 
nwave <- noise("white", duration=44100, samp.rate=44100)

fwave <- filterWave(nwave, bandpass(from=1000, to=2000))
nwave |> filterWave(bandpass(from=1000, to=2000)) -> fwave

## End(Not run)

Beat spectrum complexity

Description

This function computes a beatSpectrum and calculates some basic measurements of its complexity. The complexity value is calculated as the maximum identified repeating period (in seconds) divided by the number of peaks.

Usage

beatComplexity(wave, plot = FALSE)

Arguments

Value

A list of the complexity, a vector of the peak periods, and the number of peaks.

Examples

## Not run: 
  beatComplexity(sheep)
  beatComplexity(sheep, plot=TRUE)

## End(Not run)

Computes a beat spectrum

Description

Beat spectra represent the periodicity in signal amplitude. It is computed by performing a continuous wavelet transform on the envelope of a preprocessed signal, and processing the average power per frequency band.

Usage

beatSpectrum(wave, min_period = 0.005, max_period = 30, dj = 1/32, ...)

Arguments

Value

a spectrum as a data frame. It contains two columns: power and period. The number of rows depend on the resolution and frequency range.

Author(s)

Quentin Geissmann

Examples

## Not run: 
beatSpectrum(sheep)
beatSpectrum(sheep, min_period=0.005, max_period=30, dj=1/32)

## End(Not run)

Analyse sound files using BirdNET-Analyzer

Description

This function takes a list of sound files and analyses them using the BirdNET-Analyzer (Kahl et al. 2021). The function either returns a data frame with the results of the analysis or a list of Annotation objects.

Usage

birdNetAnalyse(
  files,
  lat = NULL,
  lon = NULL,
  date = NULL,
  output = "Annotation"
)

Arguments

References

Kahl S, Wood CM, Eibl M, Klinck H (2021). “BirdNET: A deep learning solution for avian diversity monitoring.” Ecological Informatics, 61, 101236.

Examples

## Not run: 
  birdnetAnalyse(files=c("path/to/file1.wav", "path/to/file2.wav"), output="data.frame")

## End(Not run)

Install the BirdNET environment

Description

This function installs BirdNET in the ssd_birdnet environment using reticulate.

Usage

birdNetInstall(unattended = FALSE)

Arguments

Examples

## Not run: 
birdnetInstall()
birdNetInstall(unattended=TRUE)

## End(Not run)

Channels for sound ecology

Description

Used to process the output of acoustic index functions from the soundecology package when using allChannels.

Usage

channels_se(...)

Arguments

Circularise a dataset

Description

When plotting rings or horizons that are meant to cover the entirety of the time period in a dielPlot() or yearlyPlot() this function append the beginning values to the end to ensure an entire loop is created.

Usage

circularise(values)

Arguments

Concatenate two or more Wave-like objects.

Description

The concat() method is a more flexible version of the bind() method from tuneR package, that allows specifying more advanced types of concatenation. Setting method to "noClick" will remove any click between Wave objects caused by sudden jumps in amplitude by applying tuneR::prepComb() appropriately with default value of zero (this is only effective for the left channel or stereo or multi-channel recordings).

Usage

concat(object, ..., method = "bind")

## S4 method for signature 'Wave'
concat(object, ..., method = "bind")

## S4 method for signature 'WaveMC'
concat(object, ..., method = "bind")

## S4 method for signature 'TaggedWave'
concat(object, ..., method = "bind")

## S4 method for signature 'TaggedWaveMC'
concat(object, ..., method = "bind")

Arguments

Value

A concatenated Wave like object, with type of object.

Convert temperature to Celsius

Description

Converts temperature measurements into Celsius

Usage

convert2Celsius(temp, input = "K")

Arguments

Value

Numeric value in degrees Celsius

Examples

convert2Celsius(15, input="K")
convert2Celsius(15, input="F")

Convert temperature to Fahrenheit

Description

Converts temperature measurements into Fahrenheit

Usage

convert2Fahrenheit(temp, input)

Arguments

Examples

## Not run: 
convert2Fahrenheit(15, input = "C")

## End(Not run)

Convert temperature to Kelvin

Description

Converts temperature measurements into Kelvin

Usage

convert2Kelvin(temp, input = "C")

Arguments

Value

Numeric value in Kelvin

Examples

convert2Kelvin(15, input="C")
convert2Kelvin(15, input="F")

Convert pressure to Pascals

Description

Converts pressure measurements into Pascals

Usage

convert2Pascals(P, input = "kPa")

Arguments

Value

The numeric value in Pascals

Examples

convert2Pascals(1000, input="kPa")
convert2Pascals(10, input="dyne_cm2")

Convert bits to bytes

Description

Converts time measurements into seconds

Usage

convert2bytes(S, input = "bits")

Arguments

Value

The numeric value in seconds

Convert angle to degrees

Description

Converts angle measurements into degrees

Usage

convert2degrees(A, input = "radians")

Arguments

Value

The numeric value in degrees

Convert pressure to dyne per square centimetre

Description

Converts pressure measurements into dyne per square centimetre

Usage

convert2dyne_cm2(P, input = "kPa")

Arguments

Examples

convert2dyne_cm2(1, input="Pa")
convert2dyne_cm2(1, input="kPa")

Convert angle to radians

Description

Converts angle measurements into radians

Usage

convert2radians(A, input = "degrees")

Arguments

Value

The numeric value in radians

Convert time to seconds

Description

Converts time measurements into seconds

Usage

convert2seconds(T, input = "minutes", origin = "day")

Arguments

Value

The numeric value in seconds

Correlate channels in a WaveMC object

Description

Uses the corenv function from seewave to calculate the envelope correlation for timed events between the channels of a WaveMC object

Usage

corWaveMC(wave, times, window, temp = 25, cluster = NULL)

Arguments

Value

List of corenv lists for events, and a list of the time differences between channels

Cut wave by samples

Description

Extract a section of a Wave object based on sample positions. This function will automatically detect if a Wave object is stereo.

Usage

cutws(wave, from = 1, to = Inf, plot = FALSE)

Arguments

Value

A Wave object

Examples

## Not run: 
cutws(sheep, 1, 20)
cutws(sheep, 1, 20, plot=TRUE)

## End(Not run)

Convert data into a Wave object

Description

Make a sequence of data into a normalised Wave object.

Usage

data2Wave(
  left,
  samp.rate = 44100,
  bit = 16,
  unit = NULL,
  remove.offset = TRUE,
  normalise = TRUE
)

Arguments

Value

A mono Wave object.

Examples

pattern <- seq(from=-1, to=1, length.out=100)
data <- rep.int(pattern, 100)
w <- data2Wave(data)

Phase of day

Description

Given a start time and (optionally) a duration returns the phase of day at a given location. This is primarily used to calculate phase of day information for soundscape recording projects.

Usage

dayPhase(
  time = Sys.time(),
  duration = 40000,
  lat = 50.1,
  lon = 1.83,
  tz = "UTC"
)

Arguments

Value

Data frame of day phases with absolute timestamps and relative times within file

Phases of day

Description

Wrapper for suncalc::getSunlightTimes that formats output for this package.

Usage

dayPhases(time = as.Date(Sys.time()), lat = 50.1, lon = 1.83, tz = "UTC")

Arguments

Phases of days

Description

Phases of days

Usage

daysPhases(
  date = Sys.Date(),
  period = "year",
  plot = FALSE,
  lat = 50.1,
  lon = 1.83,
  tz = "UTC"
)

Arguments

Create Default Cluster for Windowing

Description

Creates a default cluster using one less than the total cores available on the system. By default this uses forking, which is not be available on Windows. Hence, the fork parameter has no effect on Windows.

Usage

defaultCluster(fork = TRUE)

Arguments

Value

A cluster object for parallel processing

Examples

## Not run: 
cl <- defaultCluster()
stopCluster(cl)
cl <- defaultCluster(FALSE)
stopCluster(cl)

## End(Not run)

Calculate the fraction of a day given by a value

Description

Given an object that can be coerced to POSIXlt or is in a supported string format, return the fraction of a day represented by the object.

Usage

dielFraction(t, input = "POSIX", unit = "radians")

Arguments

Diel Histogram

Description

Draws a histogram on a dielPlot() using pre-defined bins related to time of day.

Usage

dielHistogram(
  times,
  by = "hour",
  col = "grey",
  maxval = NA,
  presence.only = FALSE,
  limits = c(1, 2)
)

Arguments

Value

A data frame of start and end points of bins.

Generate labels for a diel plot

Description

Generates labels for a dielPlot() in 12- or 24-hour format. Labels are generated at three hourly intervals.

Usage

dielLabels(format = "clock24")

Arguments

Examples

dielLabels()
dielLabels("clock12")

Create a diel plot

Description

A diel plot shows the times of night, twilight and the maximum altitude of the sun for a given date.

Usage

dielPlot(
  date,
  lat,
  lon,
  limits = c(0, 2),
  plot = NULL,
  rot = tzRot(0),
  method = "plotrix",
  legend = F
)

Arguments

Generate positions of labels for a diel plot

Description

Generates positions for three-hourly labels of a dielPlot() in radians.

Usage

dielPositions(format = "3hourly")

Arguments

Examples

dielPositions()
dielPositions("hours")
dielPositions("minutes")

Plot rings on a diel plot

Description

Plot rings on a diel plot.

Usage

dielRings(
  names,
  starts,
  ends,
  cols = "grey",
  format = "HHMM",
  limits = c(1, 2),
  legend = T
)

Arguments

Dolbear's law

Description

Calculates either chirps per minute based on temperature or vice versa using Dolbear's law (or equivalent laws for other species)

Usage

dolbear(n = NULL, t = NULL, species = "Oecanthus fultoni")

Arguments

Value

Missing value of n or t

Examples

dolbear(n=6)
dolbear(t=25)

Calculate the duty cycle of a wave

Description

Proportion of a wave with signal above the limit

Usage

dutyCycle(wave, limit = 0.1, output = "unit", normalise = TRUE)

Arguments

Value

A numerical value for the duty cycle between 0 and 1 (or 0 and 100% if percentage output).

Examples

wave <- tuneR::sine(2000)
dc <- dutyCycle(wave)
pc <- dutyCycle(wave, output="percent")

Create an empty diel plot

Description

Create a diel plot with labels but without sun altitude or times of day plotted.

Usage

emptyDiel(method = "plotrix", rot = pi)

Arguments

Create an empty yearly plot

Description

Create a yearly plot with labels but without sun or night duration plotted.

Usage

emptyYearly(year = 2022, method = "plotix", rot = pi)

Arguments

Various measurements of frequency values for a Wave object

Description

Calculates the peak, centre, bandwidth and quality factor. The quality factor (Q) is calculated at both -3dB and -10dB as discussed by Bennett-Clark (1999) doi:10.1080/09524622.1999.9753408.

Usage

entropyStats(wave)

Arguments

Value

A list of spectral entropy types.

Examples

## Not run: 
entropyStats(sheep)

## End(Not run)

Apply a WaveFilter object to a Wave object

Description

A WaveFilter object is an object containing information necessary for the filterw function to apply the filter to a Wave object. This is designed to allow a pipe operator (either magrittr or base R) to be used to apply filters to a Wave in a pipeline.

Usage

filterWave(w, filt, cl = NULL)

Arguments

Details

Supported filters include those from the seewave package.

Get the frequency from wavelength and speed of sound

Description

Calculates the frequency of a sound wave given the wavelength and speed of sound in that medium.

Usage

frequencySound(wl, s = soundSpeed(medium = "air"))

Arguments

Value

Frequency of the sound in Hertz

Examples

f <- frequencySound(wl=100, s=343)

Various measurements of frequency values for a Wave object

Description

Calculates the peak, centre, bandwidth and quality factor. The quality factor (Q) is calculated at both -3dB and -10dB as discussed by Bennett-Clark (1999) <doi: 10.1080/09524622.1999.9753408>.

Usage

frequencyStats(wave, wave_spec = NULL, warn = TRUE, lowcut = 1, plot = FALSE)

Arguments

Add noise to a Wave like object

Description

Adding noise to a Wave like object allows for testing of the robustness of automated identification algorithms to noise.

Usage

generateNoise(
  wave,
  noise = c("white"),
  noise.add = FALSE,
  noise.ratio = 0.5,
  noise.ref = "file",
  output = "list"
)

Arguments

Value

A list of Wave objects with the required noise added.

Generate time masked Wave-like objects

Description

Given a Wave-like object (or a list of Wave-like objects), generate new Wave-like objects with time masking.

Usage

generateTimeMask(wave, method = "squarewave", dutyCycle = 0.95, n.periods = 10)

Arguments

Generated time-shifted versions of a Wave-like object

Description

Given a Wave-like object (or list of Wave-like objects), this function generates time-shifted versions of the object. The time-shifted versions are generated by adding a constant amount of time to the start or end of the object. This is achieved by either inserting silence and truncating the object to the original length, or by rotating the audio within the object.

Usage

generateTimeShift(
  wave,
  type = "silent",
  amount = c(1, 2),
  where = "start",
  output = "list"
)

Arguments

Value

A Wave-like object or list of Wave-like objects.

Google Speech API Transcribe

Description

Wrapper around various Google packages to simplify speech transcription.

Usage

gs_transcribe(filename, bucket = NULL, ...)

Arguments

Value

A gs_transcribe object containing details of the transcription

Examples

## Not run: 
gs_transcribe("demo.wav")

## End(Not run)

Converts bytes in human readable form

Description

Given an input of bytes calculates the result in a sensible output unit (e.g. MB, GB, PB).

Usage

humanBytes(S)

Arguments

Value

String in human readable format

Converts time to human readable form

Description

Given an input of bytes calculates the result in a sensible output unit (e.g. minutes, hours).

Usage

humanTime(S, unit = "seconds")

Arguments

Value

String in human readable format

Calculate the jitter in a Wave object

Description

Jitter is a measure of the variability of periods in the waveform. Relative jitter is scaled by the jitter in the analysed waveform.

Usage

jitter(wave, method = "absolute")

Arguments

Value

A vector of zero crossing locations

Examples

## Not run: 
jitter(sheep, method="absolute")
jitter(sheep, method="relative")

## End(Not run)

Pad labels with interval

Description

Takes labels from Google Speech API transcript and pads the time by a specified number of seconds.

Usage

labelPadding(t, pad = 0.5, max_t = NULL)

Arguments

Value

A modified Google Speech API transcript object

Examples

## Not run: 
labelPadding(t, pad=2, max_t=duration(wave))

## End(Not run)

Combines labels which overlap into single continuous regions

Description

Takes labels from Google Speech API transcript and combines overlapping labels.

Usage

labelReduction(t)

Arguments

Value

A list containing start and end times of speech containing regions

Examples

## Not run: 
labelReduction(t)

## End(Not run)

Map three vectors to RGB

Description

Maps three vectors of equal length to RGB for use in false-colour index spectrograms

Usage

map2RGB(red, green, blue)

Arguments

Value

A vector of RGB values

Calculate the natural frequency

Description

Calculates the natural frequency given the inductance, capacitance and resistance. In the acoustic case the inductance is inertia or mass, the capacitance is elasticity (bulk modulus) and resistance is composed of air resistance and related quantities. All units are SI.

Usage

naturalFrequency(L, C = "default", R)

Arguments

Details

For isothermal compression, the bulk modulus is equal to the pressure. The default value of C therefore is the IUPAC standard pressure.

Examples

naturalFrequency(L=20,R=0.5)
naturalFrequency(L=20,C=1/4,R=0.5)

Normalise a Wave object

Description

Similar to normalize() from the tuneR package but automatically identifies the unit parameter.

Usage

normalise(wave, unit = NULL, ...)

Arguments

Value

Normalised Wave or WaveMC object

Natural Time Domain

Description

Runs a function on the wave and outputs values in the Natural Time Domain (see Varotsos, Sarlis & Skordas(2011) doi:10.1007/978-3-642-16449-1).

Usage

ntd(wave, events, FUN, normalise = FALSE, argument = "wave", ...)

Arguments

Value

A list of outputs form the applied function

Parse a filename

Description

Attempts to extract meaningful information from a filename, typically the date and time a recording started.

Usage

parseFilename(file, format = NULL, timezone = NULL)

Arguments

Details

Determining the format

It is sometimes impossible to accurately determine the format of a filename, e.g. when an eight-digit 'AudioMoth HEX' only contains numbers it could be confused with a YYYYMMDD format. If a list of filenames is given and the "match" format is specified then an effort will be made to determine the most likely format that applies to all filenames.

Supported formats

• AudioMoth - The newer format for AudioMoth devices consists of a standard YYYYMMDD_HHMMSS.wav format. Specifying 'AudioMoth' forces a call to the audiomoth() function from the seewave package (Sueur et al. 2008).

• AudioMoth HEX - Older format for AudioMoth devices consisting of eight hexadecimal characters. Conversion is handled by a call to seewave::audiomoth().

• timestamp - A standard date-time format. Uses the R standard origin of 1970-01-01 00:00:00 UTC.

• Wildlife Acoustics SM2 - Can also be used for Wildlife Acoustics SM4 devices. Conversion is handled by a call to seewave::songmeter().

• Wildlife Acoustics SM3 - Conversion is handled by a call to seewave::songmeter().

• YYYYMMDD_HHMMSS - A standard date-time format.

Value

A list of file, type of match, datetime.

It is possible to determine additional properties from some files, these will be added to the list.

References

Sueur J, Aubin T, Simonis C (2008). “Seewave, a free modular tool for sound analysis and synthesis.” Bioacoustics, 18(2), 213–226.

Examples

parseFilename("5E90A4D4.wav")

Pulse detection using Dietrich (2004)

Description

Detects pulses in a Wave using the method described in Dietrich et al (2004) doi:10.1016/j.patcog.2004.04.004.

Usage

pd_dietrich2004(
  wave,
  U = 120,
  gamma = 0.05,
  alpha = 1.4,
  scaling = 32,
  V = 480,
  psi = 1
)

Arguments

Value

A list of input values plus the onset and offset times of pulses

Simplified pulse detection using Dietrich (2004)

Description

Detects pulses in a Wave.

Usage

pd_simple(
  wave,
  U = 120,
  gamma = 0.05,
  alpha = 1.4,
  scaling = 32,
  V = 480,
  psi = 1
)

Arguments

Create a PseudoWave object

Description

This function is used to create a PseudoWave object that can be used to generate a Wave object when operated on.

Usage

pseudoWave(
  type = NA_character_,
  subtype = NA_character_,
  scale = 1,
  offset = 0,
  seed = 1,
  params = list()
)

Arguments

Value

A PseudoWave object.

Examples

pw <- pseudoWave("noise", "white")

pw <- pseudoWave("sine", params=list("f0"=440))

Generate a single pulse

Description

Generate a single pulse, either a Dirac pulse (Dirac delta) or a square pulse.

Usage

pulse(
  type = "dirac",
  leading = 22050,
  pulse.length = 1,
  duration = samp.rate,
  samp.rate = 44100,
  bit = 1,
  pcm = FALSE,
  stereo = FALSE,
  output = "Wave",
  invert = FALSE
)

Arguments

Value

Specified by output.

Pulse detection

Description

Detects pulses in a Wave, defaults to using Dietrich (2004).

Usage

pulseDetection(wave, method = "simple", ...)

Arguments

Pulse intervals

Description

Used to locate area of no pulses from the results of pulseDetection().

Usage

pulseIntervals(pulses, nsd = 2)

Arguments

Value

A list of onset and offset times for pulses

The radar equation

Description

Calculates the power returned from an echolocation pulse

Usage

radarPower(P_t, r, area, G_t = 1, G_r = 1, wl = 1)

Arguments

Value

The received power

Examples

radarPower(12, 20, 0.05)
radarPower(12, 20, 0.05, G_t=1.2, G_r=1.5, wl=0.045)

Radar range

Description

Calculates the distance of an object based on the round trip time of an echolocation pulse

Usage

radarRange(t, c = soundSpeed(medium = "air"))

Arguments

Value

Distance to object

Examples

radarRange(2)
radarRange(2, c=343)
radarRange(2, c=soundSpeed(medium = "sea water"))

Plot a radial polygon

Description

Used to plot sectors, annuli and horizons on a dielPlot() or yearlyPlot(). The polygon has an inner and outer horizon - which can be set to a fixed radius or a vector.

Usage

radialPolygon(
  angle1,
  angle2,
  radius1,
  radius2,
  col = "grey",
  border = NA,
  rot = -pi,
  angleinc = 0.01,
  reverse = TRUE,
  ...
)

Arguments

Rainfall detection

Description

Detects rainfall in a Wave. An uncalibrated version of Bedoya et al (2017) doi:10.1016/j.ecolind.2016.12.018 is available in this package. The hardRain package can also be accessed via this wrapper.

Usage

rainfallDetection(wave, method = "bedoya2017", ...)

Arguments

Value

Numeric value from the rainfall detection algorithm chosen.

Examples

## Not run: 
rainfallDetection(sheep, method="bedoya2017")

## End(Not run)

Read an Audacity label file

Description

Reads an Audacity label file and returns either a list of Annotation objects or a data frame.

Usage

readAudacityLabels(file, output = "annotations")

Arguments

Read an audio file

Description

This file is used to read an audio file and return a Wave object, it is an abstraction function for various specific audio reading functions. If no existing method can be identified an attempt is made to use the av package to read the audio.

Usage

readAudio(file, mime = "auto", from = 0, to = Inf, units = "seconds")

Arguments

Value

A Wave object

Read output files from BirdNet Analyser

Description

Reads a single file, or directory of files, output by BirdNet Analyser.

Usage

readBirdNet(file, filename_parsing = "none")

Arguments

Value

A data frame.

Read a file from Seeed Studio Respeaker 6 mic array

Description

The Seeed Studio Respeaker-6 when used as described in the documentation saves an eight channel audio file with channels 7 and 8 not containing input audio. This function reads such a file and saves it as a six channel file.

Usage

readRespeaker6(filename, from = 1, to = Inf, units = "samples", header = FALSE)

Arguments

Value

A WaveMC object.

Reference intensity

Description

Provides the standard reference intensity level.

Usage

referenceIntensity(unit = "watt_cm2")

Arguments

Examples

ri <- referenceIntensity()

Reference pressure

Description

Provides the standard reference pressure level.

Usage

referencePressure(unit = "Pa")

Arguments

Examples

rp <- referencePressure()
rp <- referencePressure(unit="dyne_cm2")

Specify a region with a file to analyse

Description

Specifies a time-bounded region to analyse.

Usage

region(unit, from = 0, to = Inf)

Arguments

Value

A TimeRegion object.

Calculate the resonant frequency

Description

Calculates the resonant frequency given the inductance and capacitance. In the acoustic case the inductance is inertia or mass, the capacitance is elasticity (bulk modulus) and resistance is composed of air resistance and related quantities. All units are SI.

Usage

resonantFrequency(L, C = "default")

Arguments

Details

For isothermal compression, the bulk modulus is equal to the pressure. The default value of C therefore is the IUPAC standard pressure.

Examples

f <- resonantFrequency(L=1)

Sample duration

Description

Calculates the time represented by n samples in a Wave.

Usage

sDuration(n = 1, wave = NULL, samp.rate = NULL)

Arguments

Value

A numeric value in seconds

Examples

sDuration(n=20, samp.rate=44100)
## Not run: 
sDuration(n=20, wave=sheep)#'

## End(Not run)

Sheep frequencyStats

Description

The frequencyStats of the sheep data file from the seewave package.

Usage

sheepFrequencyStats

Format

An object of class list of length 3.

Calculate the shimmer in a Wave object

Description

Jitter is a measure of the variability of amplitudes within periods in the waveform. Relative shimmer is scaled by the shimmer in the analysed waveform.

Usage

shimmer(wave)

Arguments

Value

A vector of zero crossing locations

Examples

## Not run: 
shimmer(sheep)

## End(Not run)

Calculate the speed of sound in a medium

Description

Given sufficient parameters (i.e. wavelength and frequency, bulk modulus and density) this function calculates the speed of sound.

Usage

soundSpeed(
  medium = NULL,
  method = NULL,
  wl = NULL,
  f = NULL,
  bulkModulus = NULL,
  density = NULL,
  ...
)

Arguments

Details

The speed of sound can be calculated using the following methods:

• cramer Uses the method described in Cramer (1993). Additional parameters are:

  • temp Temperature

  • temp.unit Temperature unit

  • pressure Pressure

  • pressure.unit Pressure unit

  • RH Relative humidity

  • MoleFracCO2 Mole fraction of CO2

• seewave Delegates the calculation of the speed of sound in air to the package seewave (Sueur et al. 2008). This calculation is . performed as \text{speed} = 331.4 + 0.6 \times \text{temp}. Additional parameters are:

  • temp Temperature

References

Cramer O (1993). “The variation of the specific heat ratio and the speed of sound in air with temperature, pressure, humidity, and CO2 concentration.” The Journal of the Acoustical Society of America, 93(5), 2510-2516. ISSN 0001-4966, doi:10.1121/1.405827.

Sueur J, Aubin T, Simonis C (2008). “Seewave, a free modular tool for sound analysis and synthesis.” Bioacoustics, 18(2), 213–226.

Examples

soundSpeed(medium="air")
soundSpeed(medium="sea water")

soundSpeed(method="cramer", temp=14, pressure=3, RH=10)
soundSpeed(method="cramer", temp=14, temp.unit="C", pressure=3, pressure.unit="kPa", RH=10)

t <- 1:30
s <- lapply(t, \(x){soundSpeed(method="cramer", temp=x)})

Calculate and plot statistics on a frequency spectrum

Description

Given a list of outputs from meanspec generates a plot with the mean shown by a line, and either the minimum/maximum values or one standard deviation shown by a ribbon.

Usage

specStats(spectra, stats = "minMax", line.col = "black", ribbon.col = "grey70")

Arguments

Value

A ggplot2 object

Short term energy

Description

Computes the short term energy of a Wave.

Usage

ste(wave, method = "dietrich2004", ...)

Arguments

Value

A vector of short term energy values

References

Dietrich C, Palm G, Riede K, Schwenker F (2004). “Classification of bioacoustic time series based on the combination of global and local decisions.” Pattern Recognition, 37(12), 2293–2305.

Examples

## Not run: 
ste(sheep, method="dietrich2004")

## End(Not run)

Subtract two spectra from seewave

Description

This function takes two spectra from seewave (or equivalent) and subtracts their values. The spectra must have the same bins.

Usage

subtractSpectra(s1, s2, coerceNegative = TRUE)

Arguments

Value

A spectrum of s1 - s2

Examples

## Not run: 
subtractSpectra(spec1, spec2)
subtractSpectra(spec1, spec2, coerceNegative=TRUE)

## End(Not run)

Generate a sine sweep

Description

Generates a frequency swept sine wave (either linear or logarithmic) and returns it as a Wave object or vector.

Usage

sweptsine(
  f0 = 100,
  f1 = 2500,
  mode = "linear",
  sweep.time = 1,
  time.unit = "seconds",
  samp.rate = 44100,
  output = "wave",
  ...
)

Arguments

Value

A swept wave object of the type specified in output.

Examples

#Generate a swept sine wave between 0Hz and 10kHz.
w <- sweptsine(0, 10e3)

#Generate a swept sine wave between 0Hz and 10kHz and normalise it.
w <- normalise(sweptsine(0, 10e3))

#Generate a stereo swept sine wave between 100Hz and 1KHz.
w <- tuneR::stereo(sweptsine(100, 1e3))

#Generate an exponentially swept sine wave between 100Hz and 1KHz.
w <- sweptsine(100, 1e3, mode="log")

Samples per time period

Description

Calculates the number of samples for a given duration of a wave

Usage

tSamples(time = 1, wave = NULL, samp.rate = NULL)

Arguments

Value

Number of samples

Examples

tSamples(10, samp.rate=44100)
## Not run: 
tSamples(10, wave=sheep)

## End(Not run)

Tag a Wave or WaveMC object

Description

This function takes a Wave/WaveMC object (or a list of such objects) and returns a corresponding tagged version (TaggedWave or TaggedWaveMC).

Usage

tagWave(w, origin = "user")

Arguments

Value

A TaggedWave or TaggedWaveMC object (or list of such objects).

Typical volumes

Description

Typical volumes of everyday things.

Usage

typicalVolume(thing = NA_character_)

Arguments

Value

Typical volume of thing in dBA, or if no thing parameter a data frame of all volumes

Examples

typicalVolume()
typicalVolume("rocket launch")

Converts a timezone offset into a rotation

Description

Given a timezone offset in hours returns a rotation in radians to apply to values for a diel plot.

Usage

tzRot(tz, init = pi)

Arguments

Untag a TaggedWave or TaggedWaveMC object

Description

This function takes a TaggedWave/TaggedWaveMC object (or a list of such objects) and returns a corresponding Wave/WaveMC object (or list of such objects).

Usage

untagWave(w)

Arguments

Value

A Wave or WaveMC object.

Examples

## Not run: 
w <- noise("white")
tw <- tagWave(w)
w2 <- untagWave(tw)

## End(Not run)

Upsample a wave

Description

Used to upsample a Wave object. The upsampled sample rate must be an natural multiple of the current sample rate.

Usage

upsample(wave, upsample.rate, method = "basic")

Arguments

Value

A resampled Wave object

Examples

wave <- tuneR::sine(4000, samp.rate=44100)
wave2 <- upsample(wave, 88200)

Check an object is a Wave object

Description

Helper function to test that the input is a Wave object. Will create an error if not.

Usage

validateIsWave(wave)

Arguments

Windowing Function for Wave Objects

Description

Separates a Wave object into windows of a defined length and runs a function on the window section. Windows may overlap, and the function can make use of 'parallel' package for multi-core processing. It will also show a progress bar if the 'pbapply' package is installed.

Usage

windowing(
  wave,
  window.length = 1000,
  FUN,
  window.overlap = 0,
  bind.wave = FALSE,
  complete.windows = TRUE,
  cluster = NULL,
  ...
)

Arguments

Examples

## Not run: 
windowing(wave, window.length=1000, FUN=duration, window.overlap=0, bind.wave=TRUE)

## End(Not run)

Write an Audacity label file

Description

Writes a list of Annotation objects to an Audacity label file.

Internally this uses the write.audacity() function from the seewave package (Sueur et al. 2008).

Usage

writeAudacityLabels(annotations, file)

Arguments

References

Sueur J, Aubin T, Simonis C (2008). “Seewave, a free modular tool for sound analysis and synthesis.” Bioacoustics, 18(2), 213–226.

Calculate the fraction of a year given by a value

Description

Given an object that can be coerced to POSIXlt, return the fraction of a year represented by the object.

Usage

yearlyFraction(t, year = 2022, input = "POSIX", unit = "radians")

Arguments

Generate labels for a yearly plot

Description

Generates monthly labels for a yearlyPlot()..

Usage

yearlyLabels()

Create a yearly plot

Description

ToDO......

Usage

yearlyPlot(
  year = 2022,
  lat,
  lon,
  limits = c(0, 2),
  plot = NULL,
  method = "plotrix",
  legend = F
)

Arguments

Generate positions of labels for a yearly plot

Description

Generates positions for monthly labels of a dielPlot() in radians. The positions can either be for the start of the month, or middle of the month.

Usage

yearlyPositions(year = 2022, format = "months")

Arguments

Details

The function allows for leap years if the year parameter is provided.

Zero spectrum

Description

This function takes a spectrum from seewave and creates a new zero-valued spectrum with the same structure.

Usage

zeroSpectrum(s1)

Arguments

Value

A zero-valued spectrum.

Examples

## Not run: 
zeroSpectrum(spec)

## End(Not run)

Identify zero crossings in a Wave object

Description

Returns a vector of the position (in samples) of zero crossings in a Wave object

Usage

zerocross(wave)

Arguments

Value

A vector of zero crossing locations

Examples

## Not run: 
zerocross(sheep)

## End(Not run)