Package 'sonicscrewdriver'

Description

PseudoWave scalar subtraction

Usage

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

Arguments

Value

A PseudoWave object with e2 subtracted from its offset.

Description

Check if two annotations overlap or are continuous

Usage

.annotation_check_overlap(annotation1, annotation2, domain = "time")

Arguments

Value

TRUE if the annotations overlap, FALSE otherwise.

Description

Checks a list of annotations for those that are overlapping in the time or frequency domain, and returns a list where overlapping annotations are merged.

Usage

.merge_annotations(annotations, domain = "time")

Arguments

Details

The exported function merge_annotations() handles sanity checks and calls this function.

Value

A list of Annotation objects.

Description

Helper function to convert a Wave-like object to scikit-maad spectrogram

Usage

.spectrogram_maad_power(object)

Arguments

Value

A spectrogram_maad object

Description

Helper function to convert a Wave-like object to scikit-maad spectrum

Usage

.spectrum_maad(object)

Arguments

Value

A spectrum list

Description

Allow subsetting a Wave object with a TimeRegion

Usage

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

Arguments

Value

A Wave object containing only the samples within the time region.

Description

Numeric multiplication by PseudoWave

Usage

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

Arguments

Value

A PseudoWave object with its scale multiplied by e1.

Description

PseudoWave scalar manipulation

Usage

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

Arguments

Value

A PseudoWave object with its scale multiplied by e2.

Description

PseudoWave scalar division

Usage

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

Arguments

Value

A PseudoWave object with its scale divided by e2.

Description

Numeric addition by PseudoWave

Usage

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

Arguments

Value

A PseudoWave object with e1 added to its offset.

Description

PseudoWave scalar addition

Usage

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

Arguments

Value

A PseudoWave object with e2 added to its offset.

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

Value

The traits data frame, with value_min and value_max converted to numeric times of day.

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.

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: 
addSpectra(spec1, spec2)
addSpectra(spec1, spec2, coerceNegative=TRUE)

## End(Not run)

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 with one entry per channel, whatever the class and channel count of the input. Each entry is itself a list.

Description

Create a new Annotation object

Usage

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

Arguments

Value

An Annotation object.

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.

Description

Converts a list of Annotation objects to a data.frame, with one column for each metadata name in the list.

Usage

AnnotationList2DataFrame(x)

Arguments

Value

A data.frame.

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",
  units = "decimal"
)

Arguments

Details

The size is given in bits by default. Setting output.unit to "bytes" gives bytes, and to "human" passes the result through humanBytes(), whose choice of decimal or binary units is taken from units.

Value

The size of the audio file in the specified unit

Examples

# One minute of mono 16-bit audio sampled at 44.1kHz
audio_filesize(samp.rate=44100, bit.depth=16, channels=1, duration=1, duration.unit="minutes")

# One year of stereo 24-bit audio sampled at 96kHz
audio_filesize(samp.rate=96000, bit.depth=24, channels=2, duration=1, duration.unit="years")

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)

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

Value

No return value, called for its side effect of downloading files.

Description

Reads and parses an AudioMoth configuration file.

Usage

audiomothConfig(filename)

Arguments

Value

A data frame of the configuration settings, with columns Key and Value

Examples

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

## End(Not run)

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)

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)

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)

Description

Given the time differences of arrival of a sound between the microphones of an array, and the positions of those microphones, estimates the direction the sound arrived from.

Usage

bearing(delays, positions, speed = NULL, unit = "degrees")

Arguments

Details

The sound is assumed to be far enough away that the wavefront reaching the array is flat, in which case the delay at each microphone depends on the direction the sound came from but not on how far away it was. "Far enough" is relative to the size of the array: a few array widths is usually sufficient. No distance to the source is estimated, and none can be from a single array under this assumption.

The direction is returned as an azimuth measured anticlockwise from the positive x axis of the coordinates the microphone positions were given in. If those coordinates have x pointing east and y pointing north, the compass bearing of the source is (90 - azimuth) %% 360 degrees.

Arrays that cannot give a single answer

Two microphones, or any number of microphones in a straight line, determine only the angle between the direction of the sound and the axis of the array: every direction on a cone around that axis gives the same delays. For an array lying in a line in two dimensions this leaves two possible bearings, mirrored about the array axis, and both are returned. Microphones lying in a plane, with positions given in three dimensions, likewise leave two possible directions mirrored about that plane. For microphones in a line with positions given in three dimensions no bearing can be recovered, and only the angle from the array axis is returned.

Checking the result

A set of delays that is consistent with a plane wave has a magnitude of 1 and a residual of 0. A magnitude far from 1, or a residual that is an appreciable fraction of the size of the array, means the delays are not consistent with any single direction and the bearing should not be trusted. Common causes are a correlation peak found on the wrong cycle of a tonal sound, a source too close to the array for the plane wave assumption, and two sounds overlapping in the window correlated.

Neither check is available from every array. The residual is only meaningful where there are more microphones than one more than the number of dimensions the positions are given in, as fewer leave the delays exactly enough to fit a direction to. The magnitude is only meaningful for an array that determines the direction fully, as one that does not fits only the part of the direction it can see. For a pair of microphones neither is available, and delays that are not physically possible are all that can be detected.

The speed of sound

Where the array determines the direction fully the bearing does not depend on the speed of sound, which only scales the delays: getting it wrong moves the magnitude away from 1 but leaves the direction alone. Where the array leaves an ambiguity the bearing does depend on it, so a pair of microphones is worth giving a speed calculated for the conditions of the recording.

Value

A list holding:

• azimuth The direction the sound arrived from, or two directions where the array leaves an ambiguity (see Details), or NA where no direction can be recovered.

• elevation The angle above the horizontal, for positions given in three dimensions. NA otherwise.

• direction A matrix holding the unit vector of each direction in the coordinates the positions were given in.

• cone For microphones in a line with positions given in three dimensions, the angle between the direction of the sound and the axis of the array, measured from the first microphone towards the last. NA otherwise.

• residual The root mean square difference, in metres, between the path length differences the estimate implies and those the delays give.

• magnitude The length of the direction vector the fit produced, before it was scaled to a unit vector, which is 1 for delays that are exactly consistent with a plane wave (see Details). Where the array leaves an ambiguity this is the length of the part of the direction the array can see, which is at most 1.

• speed The speed of sound used.

• unit The unit the angles are given in.

• ambiguous Whether the array leaves more than one possible direction.

See Also

tdoa(), which produces the delays this function takes.

Examples

# Three microphones in a right angled triangle, 1m apart
mics <- rbind(c(0, 0), c(1, 0), c(0, 1))

# A sound arriving from the east reaches the eastern microphone first
bearing(c(0, -1/343, 0), mics)

# A stereo pair leaves two possible bearings
bearing(c(0, -0.5/343), rbind(c(0, 0), c(1, 0)))

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)

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)

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

Value

A list of Annotation objects, or a data frame if output is "data.frame".

References

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

Examples

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

## End(Not run)

Description

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

Usage

channels_se(...)

Arguments

Value

A list containing the value calculated for the left channel.

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

Value

The input vector with its first value appended, so that it closes on itself.

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.

Description

Converts file size measurements into bytes. Both decimal units, which are powers of 1000, and binary units, which are powers of 1024, are accepted.

Usage

convert2bytes(S, input = "bits")

Arguments

Value

The numeric value in bytes

Examples

convert2bytes(8, input="bits")
convert2bytes(1, input="kB")
convert2bytes(1, input="KiB")

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")

Description

Converts angle measurements into degrees

Usage

convert2degrees(A, input = "radians")

Arguments

Value

The numeric value in degrees

Description

Converts pressure measurements into dyne per square centimetre

Usage

convert2dyne_cm2(P, input = "kPa")

Arguments

Value

The numeric value in dyne per square centimetre.

Examples

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

Description

Converts temperature measurements into Fahrenheit

Usage

convert2Fahrenheit(temp, input)

Arguments

Value

No return value, this conversion is not implemented and the function raises an error.

Examples

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

## End(Not run)

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")

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")

Description

Converts angle measurements into radians

Usage

convert2radians(A, input = "degrees")

Arguments

Value

The numeric value in radians

Description

Converts time measurements into seconds

Usage

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

Arguments

Value

The numeric value in seconds

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, cluster = NULL, ...)

Arguments

Details

The delays are the offsets corenv() reports, with the sign changed so that a positive delay means the sound arrived at that channel later than it arrived at the first channel, which is the convention tdoa() and bearing() use. corenv() resolves an offset only to a whole sample, and reports any delay of zero or less as one sample greater than it is. tdoa() with method="envelope" measures the same thing without either limitation, and its output can be passed to bearing().

corenv() correlates ranks rather than values unless it is told otherwise, which for a recording with quiet stretches between events can put the largest correlation at no offset at all whatever the offset really is. Pass method="pearson" if the delays look implausible.

Value

A list with one entry per event, each holding the corenv list for every channel in correlations, and the delay of every channel relative to the first in delays (see Details).

See Also

tdoa(), which measures the time differences of arrival between channels, and bearing(), which turns them into a direction.

Description

Extract a section of a Wave or WaveMC object based on sample positions. This function will automatically detect if a Wave object is stereo, and returns the same class of object it was given.

Usage

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

Arguments

Value

A Wave or WaveMC object

Examples

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

## End(Not run)

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)

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

Examples

dayPhase(time=as.POSIXct("2024-06-15 20:00:00", tz="UTC"), duration=40000)

Description

Phases of days

Usage

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

Arguments

Value

A data frame with a row for each day, giving the times of each phase of the day and the state of the moon.

Examples

daysPhases(date=as.Date("2024-06-15"), period="month")

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)

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

Value

The position of the time within the day, in radians or as a fraction of a day.

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),
  rot = tzRot(0)
)

Arguments

Value

A data frame of start and end points of bins.

Description

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

Usage

dielLabels(format = "clock24")

Arguments

Value

A character vector of eight labels, at three hourly intervals.

Examples

dielLabels()
dielLabels("clock12")

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 = FALSE
)

Arguments

Value

Called for its side effect of drawing a plot. The return value is that of the underlying plotting function and should not be relied on.

Description

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

Usage

dielPositions(format = "3hourly")

Arguments

Value

A numeric vector of label positions, in radians.

Examples

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

Description

Plot rings on a diel plot.

Usage

dielRings(
  names,
  starts,
  ends,
  cols = "grey",
  format = "HHMM",
  limits = c(1, 2),
  legend = TRUE,
  rot = tzRot(0)
)

Arguments

Value

Called for its side effect of drawing on the current plot. The return value is that of the underlying plotting function and should not be relied on.

Description

Dolbear (1897) was the first to publish a formula for how the rate of chirping of crickets varies with temperature, using the tree cricket Oecanthus fultoni.

Usage

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

Arguments

Details

Subsequent research by Dolbear and others have published additional formulae for other species: Oecanthus fultoni (Fulton 1925), Oecanthus rileyi (Walker 1962), Oecanthus alexanderi (Walker and Collins 2010), and Oecanthus allardi (Allard 1957).

Value

Data frame with t and n calculated for matching species.

References

Allard HA (1957). “The stridulations of some crickets in the Dominican Republic.” Journal Washington Academy of Sciences, 47, 150–152.

Dolbear AE (1897). “The Cricket as a Thermometer.” The American Naturalist, 31(371), 970–971. ISSN 00030147, 15375323. http://www.jstor.org/stable/2453256.

Fulton BB (1925). “Physiological variation in the snowy tree cricket, Oecanthus fultoni, De Geer.” Annals of the Entomological Society of America, 18, 363–383.

Walker TJ (1962). “The taxonomy and calling songs of United States tree crickets (Orthoptera: Gryllidae: Oecanthinae). I. The genus Neoxabea and the niveus and varicornis groups of the genus Oecanthus.” Annals Entomological Society of America, 55, 303–322. http://entnemdept.ifas.ufl.edu/walker/Buzz/s576lw62.pdf.

Walker TJ, Collins N (2010). “New World thermometer crickets: the Oecanthus rileyi species group and a new species from North America.” Journal of Orthoptera Research, 19(2). ISSN 10826467, 19372426. http://www.jstor.org/stable/25822725.

Examples

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

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). For multi-channel input, a list of such values.

Examples

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

Description

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

Usage

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

Arguments

Value

Called for its side effect of drawing a plot. The return value is that of the underlying plotting function and should not be relied on.

Description

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

Usage

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

Arguments

Value

Called for its side effect of drawing a plot. The return value is that of the underlying plotting function and should not be relied on.

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) https://doi.org/10.1080/09524622.1999.9753408.

Usage

entropyStats(wave)

Arguments

Value

A list of spectral entropy types. For multi-channel input, one such list per channel.

Examples

## Not run: 
entropyStats(sheep)

## End(Not run)

Description

Calculates a false-colour index spectrogram, in which three acoustic indices are calculated for each frequency bin of each time window and mapped to the red, green and blue channels of an image. Long recordings can be summarised in a single image, with different sounds appearing as different colours.

Usage

fcis(
  x,
  window.length = NULL,
  indices = c("power", "ACI", "entropy"),
  wl = 256,
  cluster = NULL
)

Arguments

Details

Indices are scaled across the whole of the input, so that colours are comparable between the windows of one spectrogram but not between separate spectrograms. The available indices are described in fcisIndexNames.

Value

An object of class "fcis", being a list of the colours as a character matrix of one entry per frequency bin and window, the matrix of values for each index, the frequencies of the bins in kHz, the duration of a window in seconds, and the names of the indices used.

Examples

## Not run: 
f <- fcis(wave, window.length=44100)
plot(f)

f <- fcis(wave, window.length=44100, indices=c("background", "ACI", "cover"))

## End(Not run)

Description

The indices available as channels of a false-colour index spectrogram. Each is calculated separately for every frequency bin of a spectrogram, giving one value per bin rather than one value for the whole signal.

Usage

fcisIndexNames()

Details

power

Mean of the squared amplitude.

ACI

Acoustic complexity index, the summed absolute difference between consecutive time frames, divided by the total amplitude in the bin.

entropy

Temporal entropy of the amplitude, scaled to between 0 and 1. A bin whose amplitude is constant over time has an entropy of 1.

background

An estimate of the background level, taken as the tenth percentile of the amplitude over time.

cover

The proportion of time frames whose amplitude is more than three times the background level of the bin.

Value

A character vector of index names.

Examples

fcisIndexNames()

Description

The units understood by convert2bytes() and produced by humanBytes(). Decimal units are powers of 1000 and binary units are powers of 1024.

Usage

fileSizeUnits(units = "decimal")

Arguments

Value

A character vector of unit names, from smallest to largest.

Examples

fileSizeUnits()
fileSizeUnits("binary")

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.

Value

A filtered Wave or WaveMC object, or a list of such objects if given a list.

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)

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

Value

A list of frequency statistics, with an entry for each of the -3dB and -10dB thresholds.

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.

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

Value

The Wave or WaveMC object with the time mask applied.

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")

Arguments

Value

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

Description

Imports the scikit-maad object into R. This allows reuse of the same object between function calls.

Usage

getMaad()

Value

The scikit-maad Python module, with its sound and features submodules attached.

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)

Description

Given an input of bytes calculates the result in a sensible output unit (e.g. MB, GB, PB). Decimal units are powers of 1000, and binary units powers of 1024.

Usage

humanBytes(S, units = "decimal", digits = 3)

Arguments

Value

String in human readable format, one for each value of S.

Examples

humanBytes(1500)
humanBytes(1500, units="binary")
humanBytes(c(1, 1024, 1e6))

Description

Given a time calculates the result in a sensible output unit (e.g. minutes, hours).

Usage

humanTime(S, unit = "seconds", digits = 3)

Arguments

Value

String in human readable format, one for each value of S.

Examples

humanTime(90)
humanTime(c(1, 90, 7200))
humanTime(1, unit="hours")

Description

Jitter is a measure of the variability of the length of successive periods in the waveform. Absolute jitter is the mean absolute difference between the lengths of consecutive periods, in samples; relative jitter divides this by the mean period length. A waveform of constant period has a jitter of zero.

Usage

jitter(wave, method = "absolute")

Arguments

Details

Periods are located from zero crossings, so they are measured to the nearest sample. A tone whose period is not a whole number of samples will report a small amount of jitter for this reason.

Value

The jitter, in samples for method "absolute" and as a proportion of the mean period for method "relative"

Examples

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

## End(Not run)

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)

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)

Description

ACI depends on the duration of the spectrogram as the derivation of the signal is normalized by the sum of the signal. Thus, if the background noise is high due to high acoustic activity the normalization by the sum of the signal reduced ACI. So ACI is low when there is no acoustic activity or high acoustic activity with continuous background noise. ACI is high only when acoustic activity is medium, with sounds well above the background noise.

Usage

maad_acoustic_complexity_index(object, maad = NULL)

Arguments

Details

For addition documentation see https://scikit-maad.github.io/generated/maad.features.temporal_acoustic_complexity_index.html (Pieretti et al. 2011).

Value

List comprising:

References

Pieretti N, Farina A, Morri D, Gage SH (2011). “A new methodology to infer the singing activity of an avian community: the Acoustic Complexity Index (ACI).” Ecological Indicators, 11, 868–873. doi:10.1016/j.ecolind.2010.11.005.

Description

The spectral entropy of a signal measures the energy dispersion along frequencies. Low values indicates a concentration of energy around a narrow frequency band. If the DC value is not removed before processing the large peak at f=0Hz will lower the entropy of the signal.

Usage

maad_frequency_entropy(object, compatibility = "QUT", maad = NULL)

Arguments

Details

For addition documentation see https://scikit-maad.github.io/generated/maad.features.frequency_entropy.html

Value

List comprising:

References

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

Towsey M, Truskinger A, Cottman-Fields M, Roe P (2018). “Ecoacoustics Audio Analysis Software.” https://github.com/QutEcoacoustics/audio-analysis.

Description

Count the number of frequency peaks on a mean spectrum. This function was adapted from the function fpeaks of the R package Seewave (Sueur et al. 2008).

Usage

maad_number_of_peaks(
  object,
  mode = "dB",
  min_peak_val = NULL,
  min_freq_dist = 200,
  slopes = c(1, 1),
  prominence = 0,
  maad = NULL
)

Arguments

Details

For addition documentation see https://scikit-maad.github.io/generated/maad.features.number_of_peaks.html

Value

Numeric number of peaks

Description

Acoustic activity corresponds to the portion of the spectrogram above a threshold frequency per frequency along time axis (Towsey 2017).

Usage

maad_spectral_activity(object, dB_threshold = 6, maad = NULL)

Arguments

Value

The function computes for each frequency bin:

References

Towsey M (2017). “The calculation of acoustic indices derived from long-duration recordings of the natural environment.” Queensland University of Technology. https://eprints.qut.edu.au/110634/1/QUTePrints110634_TechReport_Towsey2017August_AcousticIndices%20v3.pdf.

Description

Compute different entropies based on the average spectrum, its variance, and its maxima.

Usage

maad_spectral_entropy(object, flim = NULL, maad = NULL)

Arguments

Details

For addition documentation see https://scikit-maad.github.io/generated/maad.features.spectral_entropy.html

Value

List comprising:

Description

This is a wrapper function for the maad.sound.spectrogram function from the scikit-maad package for Python. It computes the spectrogram of a sound wave. Further usage details are provided at https://maad.readthedocs.io/en/latest/maad.sound.html#maad.sound.spectrogram.

Usage

maad_spectrogram(wave, mode = "power", ..., maad = NULL)

Arguments

Value

Generically a spectrogram_maad object.

Description

This is a wrapper function for the maad.sound.spectrum function. It computes the spectrum of a sound wave. Further usage details are provided at https://maad.readthedocs.io/en/latest/maad.sound.html#maad.sound.spectrum.

Usage

maad_spectrum(wave, ..., maad = NULL)

Arguments

Value

A list comprising:

Description

For addition documentation see https://scikit-maad.github.io/generated/maad.features.temporal_activity.html (Towsey 2013).

Usage

maad_temporal_activity(
  wave,
  dB_threshold = 3,
  mode = "fast",
  Nt = 512,
  maad = NULL
)

Arguments

Value

List of calculated values, comprising:

References

Towsey M (2013). “Noise Removal from Waveforms and Spectrograms Derived from Natural Recordings of the Environment.” Queensland University of Technology. https://eprints.qut.edu.au/216373/.

Description

For addition documentation see https://scikit-maad.github.io/generated/maad.features.temporal_entropy.html.

Usage

maad_temporal_entropy(
  wave,
  compatibility = "QUT",
  mode = "fast",
  Nt = 512,
  maad = NULL
)

Arguments

Value

Numeric entropy of the envelope.

References

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

Towsey M, Truskinger A, Cottman-Fields M, Roe P (2018). “Ecoacoustics Audio Analysis Software.” https://github.com/QutEcoacoustics/audio-analysis.

Description

An acoustic event corresponds to the period of the signal above a threshold. An acoustic event could be short (at list one point if rejectDuration is None) or very long (the duration of the entire audio). Two acoustic events are separated by a period with low audio signal (i.e. below the threshold).

Usage

maad_temporal_events(
  wave,
  dB_threshold = 3,
  rejectDuration = 0.1,
  mode = "fast",
  Nt = 512,
  maad = NULL
)

Arguments

Details

For addition documentation see https://scikit-maad.github.io/generated/maad.features.temporal_events.html (Towsey 2013) (Towsey et al. 2018).

Value

List of calculated values, comprising:

References

Towsey M (2013). “Noise Removal from Waveforms and Spectrograms Derived from Natural Recordings of the Environment.” Queensland University of Technology. https://eprints.qut.edu.au/216373/.

Towsey M, Truskinger A, Cottman-Fields M, Roe P (2018). “Ecoacoustics Audio Analysis Software.” https://github.com/QutEcoacoustics/audio-analysis.

Description

For addition documentation see https://scikit-maad.github.io/generated/maad.features.temporal_median.html.

Usage

maad_temporal_median(wave, mode = "fast", Nt = 512, maad = NULL)

Arguments

Value

Numeric median of the envelope.

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

Description

Checks a list of annotations for those that are overlapping in the time or frequency domain, and returns a list where overlapping annotations are merged. Annotation objects must have the same file, type and value to be merged.

Usage

merge_annotations(annotations, domain = "time", same.source = TRUE)

Arguments

Value

A list of Annotation objects.

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 = NULL, 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.

Value

The natural frequency, in Hertz.

Examples

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

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

Description

Runs a function on the wave and outputs values in the Natural Time Domain (see Varotsos, Sarlis & Skordas(2011) https://doi.org/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

Description

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

Usage

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

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.

Timezones

Most supported formats write a wall clock (e.g. 20200609_191730) into the filename, with no indication of the timezone the clock of the recorder was set to. The timezone argument states which timezone that wall clock belongs to, and defaults to UTC, which is what AudioMoth devices use unless they are configured otherwise. The datetime returned is therefore the same instant whatever timezone the machine running the analysis is set to.

The 'AudioMoth HEX' and 'timestamp' formats are exceptions: these encode an instant rather than a wall clock, so for them timezone only sets the timezone the datetime is displayed in.

Supported formats

• AudioMoth - The newer format for AudioMoth devices consists of a standard YYYYMMDD_HHMMSS.wav format. An eight character hexadecimal filename given this format is treated as 'AudioMoth HEX'.

• AudioMoth HEX - Older format for AudioMoth devices consisting of eight hexadecimal characters giving the number of seconds since 1970-01-01 00:00:00 UTC. Conversion is handled by a call to the audiomoth() function from the seewave package (Sueur et al. 2008).

• 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. The filename is split by a call to seewave::songmeter().

• Wildlife Acoustics SM3 - The filename is split by a call to seewave::songmeter().

• YYYYMMDD_HHMMSS - A standard date-time format.

• YYYYMMDD - A standard date format, the time is taken to be midnight.

Value

A list of file, type of match, datetime. If a list of filenames is given then a list of such lists is returned.

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")

Description

Detects pulses in a Wave using the method described in Dietrich et al (2004) https://doi.org/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

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

Value

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

Description

Plot a false-colour index spectrogram

Usage

## S3 method for class 'fcis'
plot(
  x,
  xlab = NULL,
  ylab = "Frequency (kHz)",
  main = "False-colour index spectrogram",
  ...
)

Arguments

Value

No return value, called for its side effect of drawing a plot.

Examples

## Not run: 
plot(fcis(wave, window.length=44100))

## End(Not run)

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

## Not run: 
pw <- pseudoWave("file", "myfile.wav")

## End(Not run)

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, so that the same PseudoWave gives the same samples every time. NA draws a fresh sequence on each use.

params

List of additional parameters to pass to generating function

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.

Description

Detects pulses in a Wave. Stereo and multi-channel waves are analysed one channel at a time, giving one result per channel.

Usage

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

Arguments

Value

The output of the pulse detection method used.

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

Description

This function installs scikit-maad in the sonicscrewdriver environment using reticulate.

Usage

pythonInstall(unattended = FALSE)

Arguments

Value

No return value, called for its side effect of creating the Python environment.

Examples

## Not run: 
pythonInstall()
pythonInstall(unattended=TRUE)

## End(Not run)

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)

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"))

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

Value

No return value, called for its side effect of drawing a polygon on the current plot.

Description

Detects rainfall in a Wave. An uncalibrated version of Bedoya et al (2017) https://doi.org/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. For multi-channel input, a list of such values.

Examples

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

## End(Not run)

Description

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

Usage

readAudacityLabels(file, output = "annotations")

Arguments

Value

A list of Annotation objects, or a data frame if output is "data.frame".

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

Details

Files read through the av package (which is everything that is not WAVE or MP3, e.g. FLAC) are returned at the bit depth the file was stored at, so that the same audio compares equal however it was read. The av package does not report a bit depth of 24, and returns 24bit audio as 32bit, so the samples of a 24bit file are 256 times those tuneR::readWave() would give for the same audio stored as WAVE. Audio stored as floating point is returned as 32bit.

Value

A Wave object

Description

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

Usage

readBirdNet(file, filename_parsing = "none")

Arguments

Value

A data frame.

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.

Description

Provides the standard reference intensity level.

Usage

referenceIntensity(unit = "watt_cm2")

Arguments

Value

The reference sound intensity, in the unit specified.

Examples

ri <- referenceIntensity()

Description

Provides the standard reference pressure level.

Usage

referencePressure(unit = "Pa")

Arguments

Value

The reference sound pressure, in the unit specified.

Examples

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

Description

Specifies a time-bounded region to analyse.

Usage

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

Arguments

Value

A TimeRegion object.

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 = NULL)

Arguments

Details

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

Value

The resonant frequency, in Hertz.

Examples

f <- resonantFrequency(L=1)

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)

Description

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

Usage

sheepFrequencyStats

Format

An object of class list of length 3.

Description

Shimmer is a measure of the variability of amplitude between successive periods in the waveform. It is returned in decibels, as the mean absolute difference in level between the peak amplitudes of consecutive periods. A waveform of constant amplitude has a shimmer of zero.

Usage

shimmer(wave)

Arguments

Value

The shimmer in decibels

Examples

## Not run: 
shimmer(sheep)

## End(Not run)

Description

Sorts a list of annotations by either start time, frequency, or both.

Usage

sort_annotations(annotations, domain = "time", decreasing = FALSE)

Arguments

Value

A list of Annotation objects.

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

Value

The speed of sound in the medium, in metres per second.

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, function(x){soundSpeed(method="cramer", temp=x)})

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

Description

An S4 class to represent a spectrogram from scikit-maad.

Slots

Sxx

The spectrogram matrix

tn

The time vector

fn

The frequency vector

extents

The extents of the spectrogram. A list of tmin, tmax, fmin, fmax.

Description

Computes the short term energy of a Wave.

Usage

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

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)

Description

Dataset compiled from various sources for differing values of STP.

Usage

STP

Format

An object of class list of length 2.

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)

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")

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.

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

analyses

A list for storing analyses.

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

Description

Estimates the time difference of arrival (TDOA) of a sound between the channels of a multichannel recording, by generalised cross-correlation of each channel against a reference channel.

Usage

tdoa(
  wave,
  ref = 1,
  from = NULL,
  to = NULL,
  units = "seconds",
  method = "phat",
  max.delay = NULL,
  interpolate = TRUE
)

Arguments

Details

A positive delay means the sound arrived at that channel later than it arrived at the reference channel, so the reference channel is the closer of the two to the source. The delay of the reference channel against itself is zero.

Cross-correlation is performed over the whole recording unless from and to are given, and a single delay is returned for each channel. Recordings holding more than one event should be cut to each event in turn (see Examples), as a correlation over several events with different directions of arrival has no single peak to find. Cutting is also much the faster way to work, as the whole of whatever is given is transformed at once.

The following methods are available:

• phat (the default) - the phase transform, in which each frequency contributes to the correlation according to its phase alone (Knapp and Carter 1976). Discarding the magnitudes sharpens the correlation peak and makes the estimate more robust to reverberation, at the cost of weighting quiet frequencies (which are mostly noise) as heavily as loud ones.

• cc - unweighted cross-correlation, normalised so that the returned correlation is between -1 and 1. Better suited to recordings with a poor signal to noise ratio, and to narrowband sounds.

• envelope - cross-correlation of the Hilbert amplitude envelopes of the channels rather than of the waveforms themselves, as seewave::corenv() does. The only method of the three that works on a sound whose waveform does not stay coherent between microphones, which is the usual situation for the broadband pulses of insects and for microphones far enough apart that the path to each differs. Delays are resolved only to the width of a feature of the envelope, so it is the least precise of the three where the others work at all.

The delay found is a whole number of samples, which at the sample rates used for field recording is a coarse measure of direction. interpolate fits a parabola to the correlation peak and its two neighbours to estimate the delay to a fraction of a sample.

Value

A data frame with one row per channel, holding the channel number, the channel name (NA if the channels are not named), the delay in seconds, the delay in samples, and the height of the correlation peak.

References

Knapp C, Carter GC (1976). “The generalized correlation method for estimation of time delay.” IEEE Transactions on Acoustics, Speech, and Signal Processing, 24(4), 320–327.

See Also

bearing(), which turns the delays into a direction.

Examples

# A noise reaching the second channel of a recording 20 samples after
# it reaches the first.
n <- tuneR::noise(kind="white", duration=5000, samp.rate=48000)
w <- tuneR::WaveMC(
  cbind(n@left[101:4900], n@left[81:4880]),
  samp.rate = 48000,
  bit = 32,
  pcm = FALSE
)
tdoa(w)

# Only the middle of the recording, and only delays that an array 1m across
# could produce.
tdoa(w, from=0.02, to=0.08, max.delay=1/soundSpeed())

## Not run: 
# Delays for each of several events in a recording, each 100ms long
w <- readAudio("array.wav")
events <- c(3.2, 8.7, 12.1)
lapply(events, function(t) tdoa(w, from=t, to=t+0.1))

## End(Not run)

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)

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)

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")

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

Value

The rotation of the plot, in radians.

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)

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)

Description

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

Usage

validateIsWave(wave)

Arguments

Value

The Wave object unchanged. An error is raised if it is not a Wave object.

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.

Description

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

Usage

wavelength(frequency, speed = soundSpeed(medium = "air"), unit = "m")

Arguments

Value

Wavelength of the sound in the unit specified

Examples

wl <- wavelength(1000)
wl <- wavelength(1000, speed=soundSpeed(medium="steel"))
wl <- wavelength(1000, unit="cm")

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

Value

A list of the results of FUN for each window, or a single Wave object if bind.wave is TRUE.

Examples

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

## End(Not run)

Description

Save a time region defined by an Annotation object as a Wave file

Usage

writeAnnotationWave(annotation, wave = NULL)

Arguments

Value

No return value, called for its side effect of writing a Wave 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

Value

No return value, called for its side effect of writing a label file.

References

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

Description

This function writes a Wave or WaveMC object to a file, it is an abstraction function for various specific audio writing functions and is the counterpart of readAudio(). WAVE files are written directly, other formats are written by converting a temporary WAVE file using the av package. If the av package is not available FLAC files can also be written using the flac program via the seewave package (Sueur et al. 2008).

Usage

writeAudio(wave, file, mime = "auto", ...)

Arguments

Details

The MIME type of the file to write is determined from the file extension, unless it is given in the mime argument. Any format supported by the encoders available to the av package can be written, commonly used types include:

• audio/x-wav (.wav) - written by tuneR::writeWave().

• audio/flac (.flac)

• audio/mpeg (.mp3)

• audio/mp4 (.m4a)

Which other formats can be written depends on the encoders available to the av package, and some encoders accept only certain sample rates (e.g. Opus requires 48kHz or one of its divisors).

Audio written to a lossy format (e.g. MP3) will not be identical to the audio held in the object, and audio written to a format that does not support the bit depth or channel count of the object will be converted by the encoder.

Value

The path of the file written, invisibly.

References

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

Examples

w <- tuneR::sine(440, duration=1000)
f <- tempfile(fileext=".wav")
writeAudio(w, f)
file.remove(f)

## Not run: 
# Requires the av package
writeAudio(w, "tone.mp3")
writeAudio(w, "tone.flac")

## End(Not run)

Description