pyrato

Top-level package for pyrato.

Functions:

air_attenuation_coefficient(frequency[, ...])	Calculate the attenuation coefficient m for the absorption caused
center_frequencies_octaves()	Return the octave center frequencies according to the IEC 61260:1:2014 standard.
center_frequencies_third_octaves()	Return the third octave center frequencies according to the ICE 61260:1:2014 standard.
energy_decay_curve_analytic(surfaces, ...[, ...])	Calculate the energy decay curve analytically by using Eyring's or Sabine's equation 1.
energy_decay_curve_chu(data, sampling_rate)	Implementation of the "subtraction of noise"-method after Chu [#] The noise level is estimated and subtracted from the impulse response before backward integration.
energy_decay_curve_chu_lundeby(data, ...[, ...])	This function combines Chu's and Lundeby's methods: The estimated noise level is subtracted before backward integration, the impulse response is truncated at the intersection time, and the correction for the truncation is applied 4, 5, 6
energy_decay_curve_lundeby(data, sampling_rate)	Lundeby et al. 2 proposed a correction term to prevent the truncation error.
energy_decay_curve_truncation(data, ...[, ...])	This function truncates a given room impulse response by the intersection time after Lundeby and calculates the energy decay curve.
estimate_noise_energy(data[, interval, ...])	This function estimates the noise energy level of a given room impulse response.
filter_fractional_octave_bands(signal, ...)	Apply a fractional octave filter to a signal.
find_impulse_response_maximum(impulse_response)	Find the maximum of an impulse response as argmax(h(t)).
find_impulse_response_start(impulse_response)	Find the first sample of an impulse response in a accordance with the ISO standard ISO 3382 3.
intersection_time_lundeby(data, sampling_rate)	This function uses the algorithm after Lundeby et al. 7 to calculate the intersection time, lundeby reverberation time, and noise level estimation.
preprocess_rir(data[, is_energy, ...])	Preprocess the room impulse response for further processing:
reverberation_time_energy_decay_curve(...[, ...])	Estimate the reverberation time from a given energy decay curve according to the ISO standard 3382 8.
schroeder_integration(impulse_response[, ...])	Calculate the Schroeder integral of a room impulse response 9.
time_shift(signal, n_samples_shift[, ...])	Shift a signal in the time domain by n samples.

pyrato.air_attenuation_coefficient(frequency, temperature=20, humidity=50, atmospheric_pressure=101325)

Calculate the attenuation coefficient m for the absorption caused

by friction with the surrounding air.

Parameters

• frequency (double) – The frequency for which the attenuation coefficient is calculated. When processing in fractional octave bands use the center frequency.

• temperature (double) – Temperature in degrees Celsius.

• humidity (double) – Humidity in percent.

• atmospheric_pressure (double) – Atmospheric pressure.

Returns

attenuation_coefficient – The resulting attenuation coefficient.

Return type

double

pyrato.center_frequencies_octaves()

Return the octave center frequencies according to the IEC 61260:1:2014 standard.

Returns

frequencies – Octave center frequencies

Return type

ndarray, float

pyrato.center_frequencies_third_octaves()

Return the third octave center frequencies according to the ICE 61260:1:2014 standard.

Returns

frequencies – third octave center frequencies

Return type

ndarray, float

pyrato.energy_decay_curve_analytic(surfaces, alphas, volume, times, source=None, receiver=None, method='eyring', c=343.4, frequency=None, air_absorption=True)

Calculate the energy decay curve analytically by using Eyring’s or Sabine’s equation 10.

Parameters

• surfaces (ndarray, double) – Surface areas of all surfaces in the room

• alphas (ndarray, double) – Absorption coefficients corresponding to each surface

• volume (double) – Room volume

• times (ndarray, double) – Time vector for which the decay curve is calculated

• source (Coordinates) – Coordinate object with the source coordinates

• receiver (Coordinates) – Coordinate object with the receiver coordinates

• method ('eyring', 'sabine') – Use either Eyring’s or Sabine’s equation

• c (double) – Speed of sound

• frequency (double, optional) – Center frequency of the respective octave band. This is only used for the air absorption calculation.

Returns

energy_decay_curve – The energy decay curve

Return type

ndarray, double

References

1

8. Kuttruff, Room acoustics, 4th Ed. Taylor & Francis, 2009.

pyrato.energy_decay_curve_chu(data, sampling_rate, freq='broadband', noise_level='auto', is_energy=False, time_shift=True, channel_independent=False, normalize=True, plot=False)

Implementation of the “subtraction of noise”-method after Chu [#] The noise level is estimated and subtracted from the impulse response before backward integration.

Parameters

• data (ndarray, double) – The room impulse response with dimension […, n_samples]

• sampling_rate (integer) – The sampling rate of the room impulse response.

• freq (integer OR string) – The frequency band. If set to ‘broadband’, the time window of the Lundeby-algorithm will not be set in dependence of frequency.

• noise_level (ndarray, double OR string) – If not specified, the noise level is calculated based on the last 10 percent of the RIR. Otherwise specify manually for each channel as array.

• is_energy (boolean) – Defines, if the data is already squared.

• time_shift (boolean) – Defines, if the silence at beginning of the RIR should be removed.

• channel_independent (boolean) – Defines, if the time shift and normalizsation is done channel-independently or not.

• normalize (boolean) – Defines, if the energy decay curve should be normalized in the end or not.

• plot (Boolean) – Specifies, whether the results should be visualized or not.

Returns

energy_decay_curve – Returns the noise handeled edc.

Return type

ndarray, double

References

2

W. T. Chu. “Comparison of reverberation measurements using Schroeder’s impulse method and decay-curve averaging method”. In: Journal of the Acoustical Society of America 63.5 (1978), pp. 1444–1450.

pyrato.energy_decay_curve_chu_lundeby(data, sampling_rate, freq='broadband', noise_level='auto', is_energy=False, time_shift=True, channel_independent=False, normalize=True, plot=False)

This function combines Chu’s and Lundeby’s methods: The estimated noise level is subtracted before backward integration, the impulse response is truncated at the intersection time, and the correction for the truncation is applied 4, 5, 6

Parameters

• data (ndarray, double) – The room impulse response with dimension […, n_samples]

• sampling_rate (integer) – The sampling rate of the room impulse response.

• freq (integer OR string) – The frequency band. If set to ‘broadband’, the time window of the Lundeby-algorithm will not be set in dependence of frequency.

• noise_level (ndarray, double OR string) – If not specified, the noise level is calculated based on the last 10 percent of the RIR. Otherwise specify manually for each channel as array.

• is_energy (boolean) – Defines, if the data is already squared.

• time_shift (boolean) – Defines, if the silence at beginning of the RIR should be removed.

• channel_independent (boolean) – Defines, if the time shift and normalizsation is done channel-independently or not.

• normalize (boolean) – Defines, if the energy decay curve should be normalized in the end or not.

• plot (Boolean) – Specifies, whether the results should be visualized or not.

Returns

energy_decay_curve – Returns the noise handeled edc.

Return type

ndarray, double

References

4(1,2)

Lundeby, Virgran, Bietz and Vorlaender - Uncertainties of Measurements in Room Acoustics - ACUSTICA Vol. 81 (1995)

5(1,2)

W. T. Chu. “Comparison of reverberation measurements using Schroeder’s impulse method and decay-curve averaging method”. In: Journal of the Acoustical Society of America 63.5 (1978), pp. 1444–1450.

6(1,2)

M. Guski, “Influences of external error sources on measurements of room acoustic parameters,” 2015.

pyrato.energy_decay_curve_lundeby(data, sampling_rate, freq='broadband', noise_level='auto', is_energy=False, time_shift=True, channel_independent=False, normalize=True, plot=False)

Lundeby et al. [#]_ proposed a correction term to prevent the truncation error. The missing signal energy from truncation time to infinity is estimated and added to the truncated integral.

Parameters

• data (ndarray, double) – The room impulse response with dimension […, n_samples]

• sampling_rate (integer) – The sampling rate of the room impulse response.

• freq (integer OR string) – The frequency band. If set to ‘broadband’, the time window of the Lundeby-algorithm will not be set in dependence of frequency.

• noise_level (ndarray, double OR string) – If not specified, the noise level is calculated based on the last 10 percent of the RIR. Otherwise specify manually for each channel as array.

• is_energy (boolean) – Defines, if the data is already squared.

• time_shift (boolean) – Defines, if the silence at beginning of the RIR should be removed.

• channel_independent (boolean) – Defines, if the time shift and normalizsation is done channel-independently or not.

• normalize (boolean) – Defines, if the energy decay curve should be normalized in the end or not.

• plot (Boolean) – Specifies, whether the results should be visualized or not.

Returns

energy_decay_curve – Returns the noise handeled edc.

Return type

ndarray, double

References

3

Lundeby, Virgran, Bietz and Vorlaender - Uncertainties of Measurements in Room Acoustics - ACUSTICA Vol. 81 (1995)

pyrato.energy_decay_curve_truncation(data, sampling_rate, freq='broadband', noise_level='auto', is_energy=False, time_shift=True, channel_independent=False, normalize=True, plot=False)

This function truncates a given room impulse response by the intersection time after Lundeby and calculates the energy decay curve.

Parameters

• data (ndarray, double) – The room impulse response with dimension […, n_samples]

• sampling_rate (integer) – The sampling rate of the room impulse response.

• freq (integer OR string) – The frequency band. If set to ‘broadband’, the time window of the Lundeby-algorithm will not be set in dependence of frequency.

• noise_level (ndarray, double OR string) – If not specified, the noise level is calculated based on the last 10 percent of the RIR. Otherwise specify manually for each channel as array.

• is_energy (boolean) – Defines, if the data is already squared.

• time_shift (boolean) – Defines, if the silence at beginning of the RIR should be removed.

• channel_independent (boolean) – Defines, if the time shift and normalization is done channel-independently or not.

• normalize (boolean) – Defines, if the energy decay curve should be normalized in the end or not.

• plot (Boolean) – Specifies, whether the results should be visualized or not.

Returns

energy_decay_curve – Returns the noise handeled edc.

Return type

ndarray, double

pyrato.estimate_noise_energy(data, interval=[0.9, 1.0], is_energy=False)

This function estimates the noise energy level of a given room impulse response. The noise is assumed to be Gaussian.

Parameters

• data (np.array) – The room impulse response with dimension […, n_samples]

• interval (tuple, float, [0.9, 1.]) – Defines the interval of the RIR to be evaluated for the estimation. The interval is relative to the length of the RIR [0 = 0%, 1=100%)]

• is_energy (Boolean) – Defines if the data is already squared.

Returns

noise_energy – The energy of the background noise.

Return type

float

pyrato.filter_fractional_octave_bands(signal, samplingrate, num_fractions, freq_range=(20.0, 20000.0), order=6)

Apply a fractional octave filter to a signal. Filter bank implementation using second order sections of butterworth filters for increased numeric accuracy and stability.

Parameters

• signal (ndarray) – input signal to be filtered

• samplingrate (integer) – samplingrate of the signal

• num_fractions (integer) – number of octave fractions

• order (integer, optional) – order of the butterworth filter

Returns

signal_filtered – Signal filtered into fractional octave bands. The array has a new axis with dimension corresponding to the number of frequency bands: [num_fractions, *signal.shape]

Return type

ndarray

pyrato.find_impulse_response_maximum(impulse_response, threshold=20, noise_energy='auto')

Find the maximum of an impulse response as argmax(h(t)). Performs an initial SNR check according to a defined threshold level in dB.

Parameters

• impulse_response (ndarray, double) – The impulse response

• threshold (double, optional) – Threshold SNR value in dB

Returns

max_sample – Sample at which the impulse response starts

Return type

int

Note

The function tries to estimate the SNR in the IR based on the signal energy in the last 10 percent of the IR.

pyrato.find_impulse_response_start(impulse_response, threshold=20, noise_energy='auto')

Find the first sample of an impulse response in a accordance with the ISO standard ISO 3382 [#]_. The start sample is identified as the first sample that varies significantly from the noise floor but still has a level of at least 20 dB below the maximum of the impulse response. The function further tries to consider oscillations before the time below the threshold value.

Parameters

• impulse_response (ndarray, double) – The impulse response

• threshold (double, optional) – Threshold according to ISO3382 in dB

Returns

start_sample – Sample at which the impulse response starts

Return type

int

Note

The function tries to estimate the SNR in the IR based on the signal energy in the last 10 percent of the IR.

References

7

ISO 3382-1:2009-10, Acoustics - Measurement of the reverberation time of rooms with reference to other acoustical parameters. pp. 22

pyrato.intersection_time_lundeby(data, sampling_rate, freq='broadband', initial_noise_power='auto', is_energy=False, time_shift=False, channel_independent=False, plot=False)

This function uses the algorithm after Lundeby et al. [#]_ to calculate the intersection time, lundeby reverberation time, and noise level estimation.

Parameters

• data (ndarray, double) – The room impulse response with dimension […, n_samples]

• sampling_rate (integer) – The sampling rate of the room impulse response.

• freq (integer OR string) – The frequency band. If set to ‘broadband’, the time window of the Lundeby-algorithm will not be set in dependence of frequency.

• noise_level (ndarray, double OR string) – If not specified, the noise level is calculated based on the last 10 percent of the RIR. Otherwise specify manually for each channel as array.

• is_energy (boolean) – Defines, if the data is already squared.

• time_shift (boolean) – Defines, if the silence at beginning of the RIR should be removed.

• channel_independent (boolean) – Defines, if the time shift and normalizsation is done channel-independently or not.

• plot (Boolean) – Specifies, whether the results should be visualized or not.

Returns

• intersection_time (ndarray, float) – Returns the Lundeby intersection time for each channel.

• reverberation_time (ndarray, float) – Returns the Lundeby reverberation time for each channel.

• noise_level (ndarray, float) – Returns the noise level estimation for each channel.

References

8

Lundeby, Virgran, Bietz and Vorlaender - Uncertainties of Measurements in Room Acoustics - ACUSTICA Vol. 81 (1995)

pyrato.preprocess_rir(data, is_energy=False, time_shift=False, channel_independent=False)

Preprocess the room impulse response for further processing:

• Square data

• Shift the RIR to the first sample of the array, compensating for the delay of the time of arrival of the direct sound. The time shift is performed as a non-cyclic shift, adding numpy.nan values in the end of the RIR corresponding to the number of samples the data is shifted by.

• The time shift can be done channel-independent or not.

Parameters

• data (ndarray, double) – The room impulse response with dimension […, n_samples]

• is_energy (boolean) – Defines, if the data is already squared.

• time_shift (boolean) – Defines, if the silence at beginning of the RIR should be removed.

• channel_independent (boolean) – Defines, if the time shift is done channel-independent or not.

Returns

• energy_data (ndarray, double) – The preprocessed RIR

• n_channels (integer) – The number of channels of the RIR

• data_shape (list, integer) – The original data shape.

pyrato.reverberation_time_energy_decay_curve(energy_decay_curve, times, T='T20', normalize=True, plot=False)

Estimate the reverberation time from a given energy decay curve according to the ISO standard 3382 [#]_.

Parameters

• energy_decay_curve (ndarray, double) – Energy decay curve. The time needs to be the arrays last dimension.

• times (ndarray, double) – Time vector corresponding to each sample of the EDC.

• T ('T20', 'T30', 'T40', 'T50', 'T60', 'EDT', 'LDT') – Decay interval to be used for the reverberation time extrapolation. EDT corresponds to the early decay time extrapolated from the interval [0, -10] dB, LDT corresponds to the late decay time extrapolated from the interval [-25, -35] dB.

• normalize (bool, True) – Normalize the EDC to the steady state energy level

• plot (bool, False) – Plot the estimated extrapolation line for visual inspection of the results.

Returns

reverberation_time – The reverberation time

Return type

double

References

9

ISO 3382, Acoustics - Measurement of the reverberation time of rooms with reference to other acoustical parameters.

pyrato.schroeder_integration(impulse_response, is_energy=False)

Calculate the Schroeder integral of a room impulse response [#]_. The result is the energy decay curve for the given room impulse response.

Parameters

• impulse_response (ndarray, double) – Room impulse response as array

• is_energy (boolean, optional) – Whether the input represents energy data or sound pressure values.

Returns

energy_decay_curve – The energy decay curve

Return type

ndarray, double

References

10

M. R. Schroeder, “New Method of Measuring Reverberation Time,” The Journal of the Acoustical Society of America, vol. 37, no. 6, pp. 1187–1187, 1965.

pyrato.time_shift(signal, n_samples_shift, circular_shift=True, keepdims=False)

Shift a signal in the time domain by n samples. This function will perform a circular shift by default, inherently assuming that the signal is periodic. Use the option circular_shift=False to pad with nan values instead.

Notes

This function is primarily intended to be used when processing impulse responses.

Parameters

• signal (ndarray, float) – Signal to be shifted

• n_samples_shift (integer) – Number of samples by which the signal should be shifted. A negative number of samples will result in a left-shift, while a positive number of samples will result in a right shift of the signal.

• circular_shift (bool, True) – Perform a circular or non-circular shift. If a non-circular shift is performed, the data will be padded with nan values at the respective beginning or ending of the data, corresponding to the number of samples the data is shifted.

• keepdims (bool, False) – Do not squeeze the data before returning.

Returns

shifted_signal – Shifted input signal

Return type

ndarray, float