API Reference

This section contains a description of all classes and functions.

Acoustics

The acoustics module.

Standards

The acoustics.standards module consists of modules where all code and values are according to the respective standard.

Signal class

class acoustics.Signal[source]

A signal consisting of samples (array) and a sample frequency (float).

amplitude_envelope()[source]

Amplitude envelope.

Returns:Amplitude envelope of signal.
Return type:Signal

See also

acoustics.signal.amplitude_envelope()

angle_spectrum(N=None)[source]

Phase angle spectrum. Wrapped.

Parameters:N – amount of bins.

See also

acoustics.signal.angle_spectrum(), acoustics.signal.phase_spectrum() and phase_spectrum().

bandpass(lowcut, highcut, order=8, zero_phase=False)[source]

Filter signal with band-pass filter.

Parameters:
  • lowcut – Lower cornerfrequency.
  • highcut – Upper cornerfrequency.
  • order – Filter order.
  • zero_phase – Prevent phase error by filtering in both directions (filtfilt).
Returns:

Band-pass filtered signal.
Return type:

Signal.

See also

acoustics.signal.bandpass()

bandpass_frequencies(frequencies, order=8, purge=True, zero_phase=False)[source]

Apply bandpass filters for frequencies.

Parameters:
  • frequencies (Instance of acoustics.signal.Frequencies) – Band-pass filter frequencies.
  • order – Filter order.
  • purge – Discard bands of which the upper corner frequency is above the Nyquist frequency.
  • zero_phase – Prevent phase error by filtering in both directions (filtfilt).
Returns:

Frequencies and band-pass filtered signal.

See also

acoustics.signal.bandpass_frequencies()

bandstop(lowcut, highcut, order=8, zero_phase=False)[source]

Filter signal with band-stop filter.

Parameters:
  • lowcut – Lower cornerfrequency.
  • highcut – Upper cornerfrequency.
  • order – Filter order.
  • zero_phase – Prevent phase error by filtering in both directions (filtfilt).
Returns:

Band-pass filtered signal.
Return type:

Signal.

See also

acoustics.signal.bandstop()

calibrate_to(decibel, inplace=False)[source]

Calibrate signal to value decibel.

Parameters:
  • decibel – Value to calibrate to.
  • inplace – Whether to perform inplace or not.
Returns:

Calibrated signal.
Return type:

Signal

Values of decibel are broadcasted. To set a value per channel, use decibel[…,None].

calibrate_with(other, decibel, inplace=False)[source]

Calibrate signal with other signal.

Parameters:
  • other – Other signal/array.
  • decibel – Signal level of other.
  • inplace – Whether to perform inplace or not.
Returns:

calibrated signal.
Return type:

Signal
channels

Amount of channels.

complex_cepstrum(N=None)[source]

Complex cepstrum.

Parameters:N – Amount of bins.
Returns:Quefrency, complex cepstrum and delay in amount of samples.

See also

acoustics.cepstrum.complex_cepstrum()

correlate(other=None, mode='full')[source]

Correlate signal with other signal. In case other==None this method returns the autocorrelation.

Parameters:
  • other – Other signal.
  • mode – Mode.

See also

np.correlate(), scipy.signal.fftconvolve()

decimate(factor, zero_phase=False, ftype='iir', order=None)[source]

Decimate signal by integer factor. Before downsampling a low-pass filter is applied.

Parameters:
  • factor – Downsampling factor.
  • zero_phase – Prevent phase shift by filtering with filtfilt instead of lfilter.
  • ftype – Filter type.
  • order – Filter order.
Returns:

Decimated signal.
Return type:

Signal

See also

scipy.signal.decimate()

See also

resample()

detrend(**kwargs)[source]

Detrend signal.

Returns:Detrended version of signal.
Return type:Signal

See also

scipy.signal.detrend()

duration

Duration of signal in seconds.

energy()[source]

Signal energy.

Returns:Total energy per channel.
Return type:np.ndarray
\[E = \sum_{n=0}^{N-1} |x_n|^2\]
fractional_octaves(frequencies=None, fraction=1, order=8, purge=True, zero_phase=False)[source]

Apply 1/N-octaves bandpass filters.

Parameters:
  • frequencies (Instance of acoustics.signal.Frequencies) – Band-pass filter frequencies.
  • fraction – Default band-designator of fractional-octaves.
  • order – Filter order.
  • purge – Discard bands of which the upper corner frequency is above the Nyquist frequency.
  • zero_phase – Prevent phase error by filtering in both directions (filtfilt).
Returns:

Frequencies and band-pass filtered signal.

See also

acoustics.signal.bandpass_fractional_octaves()

classmethod from_wav(filename)[source]

Create an instance of Signal from a WAV file.

Parameters:filename – Filename
gain(decibel, inplace=False)[source]

Apply gain of decibel decibels.

Parameters:
  • decibel – Decibels
  • inplace – In place
Returns:

Amplified signal.
Return type:

Signal
highpass(cutoff, order=4, zero_phase=False)[source]

Filter signal with high-pass filter.

Parameters:
  • cutoff – Cornerfrequency.
  • order – Filter order.
  • zero_phase – Prevent phase error by filtering in both directions (filtfilt).
Returns:

High-pass filtered signal.
Return type:

Signal.

See also

acoustics.signal.highpass()

instantaneous_frequency()[source]

Instantaneous frequency.

Returns:Instantaneous frequency of signal.
Return type:Signal

See also

acoustics.signal.instantaneous_frequency()

instantaneous_phase()[source]

Instantaneous phase.

Returns:Instantaneous phase of signal.
Return type:Signal

See also

acoustics.signal.instantaneous_phase()

leq()[source]

Equivalent level. Single-value number.

See also

acoustics.standards.iso_tr_25417_2007.equivalent_sound_pressure_level()

levels(time=0.125, method='average')[source]

Calculate sound pressure level as function of time.

Parameters:
  • time – Averaging time or integration time constant. Default value is 0.125 corresponding to FAST.
  • method – Use time average or time weighting. Default option is average.
Returns:

sound pressure level as function of time.

See also

acoustics.standards.iec_61672_1_2013.time_averaged_sound_level()

See also

acoustics.standards.iec_61672_1_2013.time_weighted_sound_level()

lowpass(cutoff, order=4, zero_phase=False)[source]

Filter signal with low-pass filter.

Parameters:
  • cutoff – Cornerfrequency.
  • order – Filter order.
  • zero_phase – Prevent phase error by filtering in both directions (filtfilt).
Returns:

Low-pass filtered signal.
Return type:

Signal.

See also

acoustics.signal.lowpass()

max(axis=-1)[source]

Return the minimum along a given axis.

Refer to np.amax for full documentation.

max_level(axis=-1)[source]

Maximum sound pressure level.

Parameters:axis – Axis.

See also

acoustics.standards.iso_tr_25417_2007.max_sound_pressure_level()

min(axis=-1)[source]

Return the minimum along a given axis.

Refer to np.amin for full documentation.

ms()[source]

Mean value squared of signal.

See also

acoustics.signal.ms()

normalize(gap=6.0, inplace=False)[source]

Normalize signal.

Parameters:
  • gap – Gap between maximum value and ceiling in decibel.
  • inplace – Normalize signal in place.

The parameter gap can be understood as using gap decibels fewer for the dynamic range. By default a 6 decibel gap is used.

octavepass(center, fraction, order=8, zero_phase=False)[source]

Filter signal with fractional-octave band-pass filter.

Parameters:
  • center – Center frequency. Any value in the band will suffice.
  • fraction – Band designator.
  • order – Filter order.
  • zero_phase – Prevent phase error by filtering in both directions (filtfilt).
Returns:

Band-pass filtered signal.
Return type:

Signal.

See also

acoustics.signal.octavepass()

octaves(frequencies=array([ 16., 31.5, 63., 125., 250., 500., 1000., 2000., 4000., 8000., 16000. ]), order=8, purge=True, zero_phase=False)[source]

Apply 1/1-octaves bandpass filters.

Parameters:
  • frequencies (np.ndarray with (approximate) center-frequencies or an instance of acoustics.signal.Frequencies) – Band-pass filter frequencies.
  • order – Filter order.
  • purge – Discard bands of which the upper corner frequency is above the Nyquist frequency.
  • zero_phase – Prevent phase error by filtering in both directions (filtfilt).
Returns:

Frequencies and band-pass filtered signal.

See also

acoustics.signal.bandpass_octaves()

peak(axis=-1)[source]

Peak sound pressure.

Parameters:axis – Axis.

See also

acoustic.standards.iso_tr_25417_2007.peak_sound_pressure()

peak_level(axis=-1)[source]

Peak sound pressure level.

Parameters:axis – Axis.

See also

acoustics.standards.iso_tr_25417_2007.peak_sound_pressure_level()

phase_spectrum(N=None)[source]

Phase spectrum. Unwrapped.

Parameters:N – Amount of bins.

See also

acoustics.signal.phase_spectrum(), acoustics.signal.angle_spectrum() and angle_spectrum().

pick(start=0.0, stop=None)[source]

Get signal from start time to stop time.

Parameters:
  • start (float) – Start time.
  • stop (float) – End time.
Returns:

Selected part of the signal.
Return type:

Signal
plot(**kwargs)[source]

Plot signal as function of time. By default the entire signal is plotted.

Parameters:
  • filename – Name of file.
  • start (Start time in seconds from start of signal.) – First sample index.
  • stop (Stop time in seconds. from stop of signal.) – Last sample index.
plot_angle_spectrum(N=None, **kwargs)[source]

Plot phase angle spectrum of signal. Wrapped.

Valid kwargs:

  • xscale
  • yscale
  • xlim
  • ylim
  • reference: Reference power
plot_complex_cepstrum(N=None, **kwargs)[source]

Plot complex cepstrum of signal.

Valid kwargs:

  • xscale
  • yscale
  • xlim
  • ylim
  • frequency: Boolean indicating whether the x-axis should show time in seconds or quefrency
  • xlabel_frequency: Label in case frequency is shown.
plot_fractional_octaves(frequencies=None, fraction=1, order=8, purge=True, zero_phase=False, **kwargs)[source]

Plot fractional octaves.

plot_levels(**kwargs)[source]

Plot sound pressure level as function of time.

See also

levels()

plot_octaves(**kwargs)[source]

Plot octaves.

See also

octaves()

plot_phase_spectrum(N=None, **kwargs)[source]

Plot phase spectrum of signal. Unwrapped.

Valid kwargs:

  • xscale
  • yscale
  • xlim
  • ylim
  • reference: Reference power
plot_power_spectrum(N=None, **kwargs)[source]

Plot spectrum of signal.

Valid kwargs:

  • xscale
  • yscale
  • xlim
  • ylim
  • reference: Reference power

See also

power_spectrum()

plot_real_cepstrum(N=None, **kwargs)[source]

Plot real cepstrum of signal.

Valid kwargs:

  • xscale
  • yscale
  • xlim
  • ylim
  • frequency: Boolean indicating whether the x-axis should show time in seconds or quefrency
  • xlabel_frequency: Label in case frequency is shown.
plot_spectrogram(**kwargs)[source]

Plot spectrogram of the signal.

Valid kwargs:

  • xlim
  • ylim
  • clim

Note

This method only works for a single channel.

plot_third_octaves(**kwargs)[source]

Plot 1/3-octaves.

See also

third_octaves()

power()[source]

Signal power.

\[P = \frac{1}{N} \sum_{n=0}^{N-1} |x_n|^2\]
power_spectrum(N=None)[source]

Power spectrum.

Parameters:N – Amount of bins.

See also

acoustics.signal.power_spectrum()

real_cepstrum(N=None)[source]

Real cepstrum.

Parameters:N – Amount of bins.
Returns:Quefrency and real cepstrum.

See also

acoustics.cepstrum.real_cepstrum()

resample(nsamples, times=None, axis=-1, window=None)[source]

Resample signal.

Parameters:
  • samples – New amount of samples.
  • times – Times corresponding to samples.
  • axis – Axis.
  • window – Window.

See also

scipy.signal.resample()

See also

decimate()

You might want to low-pass filter this signal before resampling.

rms()[source]

Root mean squared of signal.

See also

acoustics.signal.rms()

samples

Amount of samples in signal.

sound_exposure(axis=-1)[source]

Sound exposure.

Parameters:axis – Axis.

See also

acoustics.standards.iso_tr_25417_2007.sound_exposure()

sound_exposure_level(axis=-1)[source]

Sound exposure level.

Parameters:axis – Axis.

See also

acoustics.standards.iso_tr_25417_2007.sound_exposure_level()

spectrogram(**kwargs)[source]

Spectrogram of signal.

Returns:Spectrogram.

See scipy.signal.spectrogram(). Some of the default values have been changed. The generated spectrogram consists by default of complex values.

third_octaves(frequencies=array([1.00e+01, 1.25e+01, 1.60e+01, 2.00e+01, 2.50e+01, 3.15e+01, 4.00e+01, 5.00e+01, 6.30e+01, 8.00e+01, 1.00e+02, 1.25e+02, 1.60e+02, 2.00e+02, 2.50e+02, 3.15e+02, 4.00e+02, 5.00e+02, 6.30e+02, 8.00e+02, 1.00e+03, 1.25e+03, 1.60e+03, 2.00e+03, 2.50e+03, 3.15e+03, 4.00e+03, 5.00e+03, 6.30e+03, 8.00e+03, 1.00e+04, 1.25e+04, 1.60e+04, 2.00e+04]), order=8, purge=True, zero_phase=False)[source]

Apply 1/3-octaves bandpass filters.

Parameters:
  • frequencies (np.ndarray with (approximate) center-frequencies or an instance of acoustics.signal.Frequencies) – Band-pass filter frequencies.
  • order – Filter order.
  • purge – Discard bands of which the upper corner frequency is above the Nyquist frequency.
  • zero_phase – Prevent phase error by filtering in both directions (filtfilt).
Returns:

Frequencies and band-pass filtered signal.

See also

acoustics.signal.bandpass_third_octaves()

times()[source]

Time vector.

Returns:A vector with a timestamp for each sample.
Return type:np.ndarray
to_wav(filename, depth=16)[source]

Save signal as WAV file.

Parameters:
  • filename – Name of file to save to.
  • depth – If given, convert to integer with specified depth. Else, try to store using the original data type.

By default, this function saves a normalized 16-bit version of the signal with at least 6 dB range till clipping occurs.

unwrap()[source]

Unwrap signal in case the signal represents wrapped phase.

Returns:Unwrapped signal.
Return type:Signal

See also

np.unwrap()

upsample(factor, axis=-1)[source]

Upsample signal with integer factor.

Parameters:
  • factor – Upsample factor.
  • axis – Axis.

See also

resample()

values

Return the values of this signal as an instance of np.ndarray.

weigh(weighting='A', zero_phase=False)[source]

Apply frequency-weighting. By default ‘A’-weighting is applied.

Parameters:weighting – Frequency-weighting filter to apply. Valid options are ‘A’, ‘C’ and ‘Z’. Default weighting is ‘A’.
Returns:Weighted signal.
Return type:Signal.

By default the weighting filter is applied using scipy.signal.lfilter() causing a frequency-dependent delay. In case a delay is undesired, the filter can applied using scipy.signal.filtfilt() by settings zero_phase=True.