Package 'sonicscrewdriver'

Description

PseudoWave scalar subtraction

Usage

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

Arguments

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

Description

Numeric multiplication by PseudoWave

Usage

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

Arguments

Description

PseudoWave scalar manipulation

Usage

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

Arguments

Description

PseudoWave scalar division

Usage

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

Arguments

Description

Numeric addition by PseudoWave

Usage

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

Arguments

Description

PseudoWave scalar addition

Usage

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

Arguments

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

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: 
subtractSpectra(spec1, spec2)

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

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

Arguments

Details

By default humanBytes() is used to convert the output to human readable format, however this can be changed by setting output.unit to "bits" or "bytes".

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

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)

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

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

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

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

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 time measurements into seconds

Usage

convert2bytes(S, input = "bits")

Arguments

Value

The numeric value in seconds

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

Examples

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

Description

Converts temperature measurements into Fahrenheit

Usage

convert2Fahrenheit(temp, input)

Arguments

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

Arguments

Value

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

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)

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

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

Description

Phases of days

Usage

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

Arguments

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

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.

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

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

Description

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

Usage

dielPositions(format = "3hourly")

Arguments

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

Arguments

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

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

Description

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

Usage

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

Arguments

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)

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.

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

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

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.

Description

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

Usage

getMaad()

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

Usage

humanBytes(S)

Arguments

Value

String in human readable format

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

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)

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

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

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

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

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

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

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

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, defaults to using Dietrich (2004).

Usage

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

Arguments

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

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

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)

Description

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

Usage

readAudacityLabels(file, output = "annotations")

Arguments

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

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

Examples

ri <- referenceIntensity()

Description

Provides the standard reference pressure level.

Usage

referencePressure(unit = "Pa")

Arguments

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

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

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)

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

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

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

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

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

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

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

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

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)

Description

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

Usage

writeAnnotationWave(annotation, wave = NULL)

Arguments

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.

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

Description

Generates monthly labels for a yearlyPlot()..

Usage

yearlyLabels()

Description

ToDO......

Usage

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

Arguments

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.

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)

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)