ACIspec: Spectral Acoustic Complexity Index

In Ruido: Soundscape Spectral Metrics

Spectral Acoustic Complexity Index

Description

Calculate the Acoustic Complexity Index values of a single audio using the methodology proposed in Pieretti, et al. 2011

Usage

ACIspec(
  soundfile,
  channel = "stereo",
  timeBin = 60,
  j = 5,
  targetSampRate = NULL,
  wl = 512,
  window = signal::hamming(wl),
  overlap = ceiling(length(window)/2)
)

Arguments

soundfile	wav package numeric matrix, tuneR package Wave object or path to a .wav file
channel	channel where the metric values will be extracted from. Available channels are: "stereo", "mono", "left" or "right". Defaults to "stereo"
timeBin	size (in seconds) of the time bin. Set to NULL to use the entire audio as a single bin. Defaults to 60
j	size (in seconds) of the cluster interval. Set to NULL to use the entire bin as a single cluster. Defaults to 5
targetSampRate	desired sample rate of the audios. This argument is only used to down sample the audio. If NULL, then audio's sample rate remains the same. Defaults to NULL
wl	window length of the spectrogram. Defaults to 512
window	window used to smooth the spectrogram. Switch to signal::hanning(wl) to use hanning instead. Defaults to signal::hamming(wl)
overlap	overlap between the spectrogram windows. Defaults to wl/2 (half the window length)

Details

The Acoustic Complexity Index (ACI) quantifies the average proportional change in spectral amplitude between adjacent time steps across frequency bins. Because biological sounds, particularly bird vocalizations, often exhibit rapid and irregular amplitude fluctuations over time, ACI captures this temporal variability as a proxy for acoustic complexity.

In Ruido, ACI is computed independently within each time bin. Within a time bin, the signal is further subdivided into smaller temporal segments, here referred to as cluster intervals j.

For a given frequency bin f_l, acoustic intensity values I_k are evaluated across consecutive time steps k within each cluster interval j. The absolute differences between adjacent time steps are calculated as:

d_k = |I_k - I_{k+1}|

These differences are summed within each cluster interval:

D_j = \sum_{k = 1}^{N} d_k

where N is the number of time steps \Delta t_k in interval j. The ACI for each cluster interval is then:

ACI_j = \frac{D_j}{\sum_{k = 1}^{N} I_k}

where \sum_{k = 1}^{N} I_k is the total acoustic intensity within the same interval.

For each frequency bin f_l, ACI values are summed across all cluster intervals within the time bin:

ACI_{f_l} = \sum_{j = 1}^{m} ACI_j

where m is the number of cluster intervals in the time bin.

The result is a frequency-resolved representation of ACI for each time bin, rather than a single scalar value for the entire recording.

In the original formulation (Pieretti et al., 2011), ACI is further summed across all frequency bins:

ACI_{tot} = \sum_{l = 1}^{q} ACI_{f_l}

where q is the total number of frequency bins. This final aggregation step is not performed in this package.

Value

This function returns a noise.matrix object.

References

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

See Also

ENTspec() to calculate Spectral Entropy and bgNoise() to calculate Background Noise and Soundscape Power.

Examples

### This is an secondary example using audio from a real soundscape
### These audios are originated from the Escutadô Project, a project
### that records the soundscapes of the brazilian semiarid
# Getting audiofile from the online Zenodo library
dir = paste(tempdir(), "forExample", sep = "/")
dir.create(dir)
rec = paste0("GAL24576_20250401_", sprintf("%06d", 0), ".wav")
recDir = paste(dir, rec , sep = "/")
url = paste0("https://zenodo.org/records/17575795/files/",
              rec,
              "?download=1")

# Downloading the file, might take some time denpending on your internet
download.file(url, destfile = recDir, mode = "wb")

# Running the ACIspec function with all the default arguments
aci = ACIspec(recDir)

# Here's the result
aci

# Plot ACI values
plot(aci)

Ruido documentation built on Sept. 2, 2026, 1:07 a.m.