acoupipe.datasets.experimental#

Contains classes for the generation of microphone array datasets with experimentally acquired signals for acoustic testing applications.

Currently, the following dataset generators are available:

DatasetMIRACLE: A microphone array dataset generator, relying on measured spatial room impulse responses from the MIRACLE dataset and synthetic white noise signals.

../../../../_images/msm_miracle.png — Measurement setup R2 from the MIRACLE dataset.#

Module Contents#

class acoupipe.datasets.experimental.DatasetBase(config=None, tasks=1, remote_args=None, logger=None)#

Bases: traits.api.HasPrivateTraits

Base class for generating microphone array datasets with specified features and labels.

config#

Configuration object for dataset generation.

Type:: ConfigBase

tasks#

Number of parallel tasks for data generation. Defaults to 1 (sequential calculation).

Type:: int

get_feature_collection(features, f, num)#

Get the feature collection of the dataset.

Returns:: BaseFeatureCollection object.
Return type:: BaseFeatureCollection

generate(features, size, split='training', f=None, num=0, start_idx=0, progress_bar=True)#

Generate dataset samples iteratively.

Parameters:

features (list) – List of features included in the dataset. The features “seeds” and “idx” are always included.
split (str) – Split name for the dataset (‘training’, ‘validation’ or ‘test’). Defaults to ‘training’.
size (int) – Size of the dataset (number of source cases).
f (float) – The center frequency or list of frequencies of the dataset. If None, all frequencies are included.
num (integer) –
Controls the width of the frequency bands considered; defaults to 0 (single frequency line).

num

frequency band width

0

single frequency line

1

octave band

3

third-octave band

n

1/n-octave band
start_idx (int, optional) – Starting sample index (default is 0).
progress_bar (bool, optional) – Whether to show a progress bar (default is True).

Yields:

data (dict) – Generator that yields dataset samples as dictionaries containing the feature names as keys.

Examples

Generate features iteratively (example below requires a dataset configuration).

from acoupipe.datasets.synthetic import DatasetSynthetic

# define the features
features = ['csm', 'source_strength_analytic', 'loc']
f = 1000
num = 3

# generate the dataset
generator = DatasetSynthetic().generate(f=f, num=num, split='training', size=2, features=features)

# iterate over the dataset
for data in generator:
    print(data)

save_h5(features, size, name, split='training', f=None, num=0, start_idx=0, progress_bar=True)#

Save dataset to a HDF5 file.

Parameters:

features (list) – List of features included in the dataset. The features “seeds” and “idx” are always included.
size (int) – Size of the dataset (number of source cases).
name (str) – Name of the HDF5 file.
split (str) – Split name for the dataset (‘training’, ‘validation’ or ‘test’). Defaults to ‘training’.
f (float) – The center frequency or list of frequencies of the dataset. If None, all frequencies are included.
num (integer) –
Controls the width of the frequency bands considered; defaults to 0 (single frequency line).

num

frequency band width

0

single frequency line

1

octave band

3

third-octave band

n

1/n-octave band
start_idx (int, optional) – Starting sample index (default is 0).
progress_bar (bool, optional) – Whether to show a progress bar (default is True).

Return type:

None

Examples

Save features to a HDF5 file (example requires proper file path).

from acoupipe.datasets.synthetic import DatasetSynthetic

# define the features
features = ['csm', 'source_strength_analytic', 'loc']
f = 1000
num = 3

# save the dataset
dataset = DatasetSynthetic().save_h5(
    f=f, num=num, split='training', size=10, features=features, name='/tmp/example.h5'
)

class acoupipe.datasets.experimental.DatasetSyntheticConfig(**kwargs)#

Bases: acoupipe.datasets.base.ConfigBase

Default Configuration class.

fs#

Sampling frequency in Hz.

Type:: float

signal_length#

Length of the source signals in seconds.

Type:: float

max_nsources#

Maximum number of sources.

Type:: int

min_nsources#

Minimum number of sources.

Type:: int

mode#

Type of CSM calculation method.

Type:: str

mic_pos_noise#

Apply positional noise to microphone geometry.

Type:: bool

mic_sig_noise#

Apply signal noise to microphone signals.

Type:: bool

snap_to_grid#

Snap source locations to grid.

Type:: bool

random_signal_length#

Randomize signal length (Default: uniformly sampled signal length [1s,10s]).

Type:: bool

fft_params#

FFT parameters with default items block_size=128, overlap="50%", window="Hanning" and precision="complex64".

Type:: dict

env#

Instance of acoular.Environment defining the environmental coditions, i.e. the speed of sound.

Type:: ac.Environment

mics#

Instance of acoular.MicGeom defining the microphone array geometry.

Type:: ac.MicGeom

noisy_mics#

a second instance of acoular.MicGeom defining the noisy microphone array geometry.

Type:: ac.MicGeom

obs#

Instance of acoular.MicGeom defining the observation point which is used as the reference position when calculating the source strength.

Type:: ac.MicGeom

grid#

Instance of acoular.RectGrid defining the grid on which the Beamformer calculates the source map and on which the targetmap feature is calculated.

Type:: ac.RectGrid

source_grid#

Instance of acoular.Grid. Only relevant if snap_to_grid is True. Then, the source locations are snapped to this grid. Default is a copy of grid.

Type:: ac.Grid

beamformer#

Instance of acoular.BeamformerBase defining the beamformer used to calculate the sourcemap.

Type:: ac.BeamformerBase

steer#

Instance of acoular.SteeringVector defining the steering vector used to calculate the sourcemap.

Type:: ac.SteeringVector

freq_data#

Instance of acoular.PowerSpectra defining the frequency domain data. Only used if mode is welch. Otherwise, an instance of acoupipe.datasets.spectra_analytic.PowerSpectraAnalytic is used.

Type:: ac.PowerSpectra

fft_spectra#

Instance of acoular.RFFT used to calculate the spectrogram data. Only used if mode is welch.

Type:: ac.RFFT

fft_obs_spectra#

Instance of acoular.PowerSpectra used to calculate the source strength at the observation point given in obs.

Type:: ac.PowerSpectra

signals#

List of signals.

Type:: list

sources#

List of sources.

Type:: list

mic_noise_signal#

Noise signal configuration object.

Type:: ac.SignalGenerator

mic_noise_source#

Noise source configuration object.

Type:: ac.UncorrelatedNoiseSource

micgeom_sampler#

Sampler that applies positional noise to the microphone geometry.

Type:: sp.MicGeomSampler

location_sampler#

Source location sampler that samples the locations of the sound sources.

Type:: sp.LocationSampler

rms_sampler#

Signal RMS sampler that samples the RMS values of the source signals.

Type:: sp.ContainerSampler

nsources_sampler#

Number of sources sampler.

Type:: sp.NumericAttributeSampler

mic_noise_sampler#

Microphone noise sampler that creates random uncorrelated noise at the microphones.

Type:: sp.ContainerSampler

signal_length_sampler#

Signal length sampler that samples the length of the source signals. Only used if random_signal_length is True.

Type:: sp.ContainerSampler

get_sampler()#

Return dictionary containing the sampler objects of type acoupipe.sampler.BaseSampler.

this function has to be manually defined in a dataset subclass. It includes the sampler objects as values. The key defines the idx in the sample order.

Examples

>>> ConfigBase().get_sampler()
{}

e.g.:

sampler = {
    0 : BaseSampler(...),
    1 : BaseSampler(...),
    ...
}

Returns:: dictionary containing the sampler objects
Return type:: dict

acoupipe.datasets.experimental.calc_transfer(ir, fs, blocksize, fftfreq, time_axis=-1)#

Compute one-sided transfer functions H(f) from (measured) impulse responses on a target rFFT bin grid defined by blocksize, returning only fftfreq.

The function enforces that the FFT length is a power-of-two by zero-padding the impulse responses to nfft = 2**ceil(log2(max(L, blocksize))), where L is the IR length.

Parameters:

ir (ndarray) – Impulse responses. The time axis is given by time_axis. Common shapes are (n_channels, n_samples) with time_axis=1, or (n_samples, n_channels) with time_axis=0.
fs (float) – Sampling frequency in Hz.
blocksize (int) – Target block size defining the desired rFFT bin grid (power-of-two). The associated bin centers are f_k = k*fs/blocksize, k=0..blocksize//2.
fftfreq (array_like of int or float, optional) –
Desired frequency bins to return.
- If integer dtype: interpreted as rFFT bin indices on the blocksize grid, i.e., k in [0, blocksize//2]. This case is exact because both blocksize and nfft are powers-of-two, hence nfft/blocksize is integer and mapping is exact.
- If float dtype: interpreted as frequencies in Hz. Values are mapped to the nearest rFFT bin of the computed FFT grid; a ValueError is raised if the frequency is not (approximately) on the grid.
If None, all one-sided bins of the computed FFT are returned.
time_axis (int, optional) – Axis of ir corresponding to time samples. Default: -1.

Returns:

H_sel – One-sided transfer function values at the requested bins. The returned array has the same shape as ir, except the time axis is replaced by a frequency axis. If fftfreq is None, this frequency axis has length nfft//2+1. Otherwise, it has length len(fftfreq).

Return type:

ndarray (complex)

class acoupipe.datasets.experimental.DatasetMIRACLE(srir_dir=None, scenario='A1', ref_mic_index=63, mode='welch', mic_sig_noise=True, random_signal_length=False, signal_length=5, min_nsources=1, max_nsources=10, tasks=1, remote_args=None, config=None)#

Bases: acoupipe.datasets.base.DatasetBase

A microphone array dataset generator using experimentally measured data.

DatasetSynthetic relies on measured spatial room impulse responses (SRIRs) from the MIRACLE dataset.

MIRACLE is a SRIR dataset explicitly designed for acoustic testing applications using a planar microphone array focused on a rectangular observation area. It consists of a total of 856, 128 captured spatial room impulse responses and dense spatial sampling of the observation area.

The data generation process is similar to acoupipe.datasets.synthetic.DatasetSynthetic, but uses measured transfer functions / impulse responses instead of analytic ones. Multi-source scenarios with possibly closing neighboring sources are realized by superimposing signals that have been convolved with the provided SRIRs.

Scenarios

The MIRACLE dataset provides SRIRs from different measurement setups with the same microphone array, which can be selected by the scenario parameter. The underlying measurement setup for scenario="R2" is shown in the measurement setup figure.

Available scenarios#
Scenario	Download Size	Environment	c0	# SRIRs	Source-plane dist.	Spatial sampling
A1	1.1 GB	Anechoic	344.7 m/s	4096	73.4 cm	23.3 mm
D1	300 MB	Anechoic	344.8 m/s	4096	73.4 cm	5.0 mm
A2	1.1 GB	Anechoic	345.0 m/s	4096	146.7 cm	23.3 mm
R2	1.1 GB	Reflective Ground	345.2 m/s	4096	146.7 cm	23.3 mm

Default FFT parameters

The underlying default FFT parameters are:

FFT Parameters#
Sampling Rate	fs=32,000 Hz
Block size	256 Samples
Block overlap	50 %
Windowing	von Hann / Hanning

Default randomized properties

Several properties of the dataset are randomized for each source case when generating the data. This includes the number of sources, their positions, and strength. Their respective distributions, are closely related to [HS17]. Uncorrelated white noise is added to the microphone channels by default. Note that the source positions are sampled from a grid according to the spatial sampling of the MIRACLE dataset.

Randomized properties#
No. of Sources	Poisson distributed (\(\lambda=3\))
Source Positions [m]	Bivariate normal distributed (\(\sigma = 0.1688 d_a\))
Source Strength (\([{Pa}^2]\) at reference position)	Rayleigh distributed (\(\sigma_{R}=5\))
Relative Noise Variance	Uniform distributed (\(10^{-6}\), \(0.1\))

Example

This is a quick example on how to use the acoupipe.datasets.experimental.DatasetMIRACLE dataset for generation of source cases with multiple sources. First, import the class and instantiate. One can either specify the path, where the SRIR files from the MIRACLE project are stored, or one can set srir_dir=None. The latter will download the corresponding SRIR dataset into a pre-defined cache directory determined by the pooch library.

from acoupipe.datasets.experimental import DatasetMIRACLE

srir_dir = None
# srir_dir = <local path to the MIRACLE dataset>

dataset = DatasetMIRACLE(scenario='A1', mode='wishart')

Now, extract the sourcmap feature iteratively with:

dataset_generator = dataset.generate(size=10, f=2000, features=['sourcemap', 'loc', 'f'], split='training')

data_sample = next(dataset_generator)

And finally, plot the results:

import acoular as ac
import matplotlib.pyplot as plt
import numpy as np

extent = dataset.config.grid.extent

# sound pressure level
Lm = ac.L_p(data_sample['sourcemap']).T
Lm_max = Lm.max()
Lm_min = Lm.max() - 20

# plot sourcemap
plt.figure()
plt.title(f'Beamforming Map (f={data_sample["f"][0]} Hz, scenario={dataset.config.scenario})')
plt.imshow(Lm, vmax=Lm_max, vmin=Lm_min, extent=extent, origin='lower')
plt.colorbar(label='Sound Pressure Level (dB)')
# plot source locations
for loc in data_sample['loc'].T:
    plt.scatter(loc[0], loc[1])
plt.xlabel('x (m)')
plt.ylabel('y (m)')
plt.show()

The resulting plot for the different scenarios should look like this:

Initialization Parameters

Initialize the DatasetMIRACLE object.

Input parameters are passed to the DatasetMIRACLEConfig object, which creates all necessary objects for the simulation of microphone array data.

Parameters:

srir_dir (str, optional) – Path to the directory where the SRIR files are stored. Default is None, which sets the path to the pooch.os_cache directory. The SRIR files are downloaded from the MIRACLE dataset if they are not found in the directory.
scenario (str, optional) – Scenario of the dataset. Possible values are “A1”, “D1”, “A2”, “R2”.
ref_mic_index (int, optional) – Index of the microphone that is used as reference observation point. Default is 63, which is the index of the centermost microphone.
mode (str, optional) – Mode of the dataset. Possible values are “analytic”, “welch”, “wishart”. Default is “welch”.
mic_sig_noise (bool, optional) – Add uncorrelated noise to the microphone signals. Default is True.
signal_length (float, optional) – Length of the signal in seconds. Default is 5.
min_nsources (int, optional) – Minimum number of sources per sample. Default is 1.
max_nsources (int, optional) – Maximum number of sources per sample. Default is 10.
tasks (int, optional) – Number of parallel processes. Default is 1.
remote_args (dict, optional) – Dictionary of keyword arguments passed to the remote actors when using Ray for parallelization. Defaults to None.
config (DatasetMIRACLEConfig, optional) – DatasetMIRACLEConfig object. Default is None, which creates a new DatasetMIRACLEConfig object.

class acoupipe.datasets.experimental.DatasetMIRACLEConfig(**kwargs)#

Bases: acoupipe.datasets.synthetic.DatasetSyntheticConfig

Configuration class for the DatasetMIRACLE dataset.

set_filename()#: Set the filename of the SRIR file according to the scenario and srir_dir.

get_sampler()#

Return dictionary containing the sampler objects of type acoupipe.sampler.BaseSampler.

this function has to be manually defined in a dataset subclass. It includes the sampler objects as values. The key defines the idx in the sample order.

Examples

>>> ConfigBase().get_sampler()
{}

e.g.:

sampler = {
    0 : BaseSampler(...),
    1 : BaseSampler(...),
    ...
}

Returns:: dictionary containing the sampler objects
Return type:: dict

class acoupipe.datasets.experimental.DatasetSRIRACHA(scenario, srir_dir=None, ref_mic_index=63, mode='welch', mic_sig_noise=True, random_signal_length=False, signal_length=5, min_nsources=1, max_nsources=10, tasks=1, config=None)#

Bases: DatasetMIRACLE

A microphone array dataset generator using experimentally measured data from the SRIRACHA dataset.

Initialize the DatasetMIRACLE object.

Input parameters are passed to the DatasetMIRACLEConfig object, which creates all necessary objects for the simulation of microphone array data.

Parameters:

srir_dir (str, optional) – Path to the directory where the SRIR files are stored. Default is None, which sets the path to the pooch.os_cache directory. The SRIR files are downloaded from the MIRACLE dataset if they are not found in the directory.
scenario (str, optional) – Scenario of the dataset. Possible values are “A1”, “D1”, “A2”, “R2”.
ref_mic_index (int, optional) – Index of the microphone that is used as reference observation point. Default is 63, which is the index of the centermost microphone.
mode (str, optional) – Mode of the dataset. Possible values are “analytic”, “welch”, “wishart”. Default is “welch”.
mic_sig_noise (bool, optional) – Add uncorrelated noise to the microphone signals. Default is True.
signal_length (float, optional) – Length of the signal in seconds. Default is 5.
min_nsources (int, optional) – Minimum number of sources per sample. Default is 1.
max_nsources (int, optional) – Maximum number of sources per sample. Default is 10.
tasks (int, optional) – Number of parallel processes. Default is 1.
config (DatasetMIRACLEConfig, optional) – DatasetMIRACLEConfig object. Default is None, which creates a new DatasetMIRACLEConfig object.

class acoupipe.datasets.experimental.DatasetSRIRACHAConfig(**kwargs)#

Bases: DatasetMIRACLEConfig

Configuration class for the DatasetSRIRACHA dataset.

num	frequency band width
0	single frequency line
1	octave band
3	third-octave band
n	1/n-octave band