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.

Attributes:

configConfigBase: Configuration object for dataset generation.
tasksint: Number of parallel tasks for data generation. Defaults to 1 (sequential calculation).

get_feature_collection(features, f, num)#

Get the feature collection of the dataset.

Returns:

BaseFeatureCollection: BaseFeatureCollection object.

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

Generate dataset samples iteratively.

Parameters:

featureslist

List of features included in the dataset. The features “seeds” and “idx” are always included.

splitstr

Split name for the dataset (‘training’, ‘validation’ or ‘test’). Defaults to ‘training’.

sizeint

Size of the dataset (number of source cases).

ffloat

The center frequency or list of frequencies of the dataset. If None, all frequencies are included.

numinteger

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_idxint, optional

Starting sample index (default is 0).

progress_barbool, optional

Whether to show a progress bar (default is True).

Yields:

datadict: 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:

featureslist

List of features included in the dataset. The features “seeds” and “idx” are always included.

sizeint

Size of the dataset (number of source cases).

namestr

Name of the HDF5 file.

splitstr

Split name for the dataset (‘training’, ‘validation’ or ‘test’). Defaults to ‘training’.

ffloat

The center frequency or list of frequencies of the dataset. If None, all frequencies are included.

numinteger

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_idxint, optional

Starting sample index (default is 0).

progress_barbool, optional

Whether to show a progress bar (default is True).

Returns:

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.

Attributes:

fsfloat: Sampling frequency in Hz.
signal_lengthfloat: Length of the source signals in seconds.
max_nsourcesint: Maximum number of sources.
min_nsourcesint: Minimum number of sources.
modestr: Type of CSM calculation method.
mic_pos_noisebool: Apply positional noise to microphone geometry.
mic_sig_noisebool: Apply signal noise to microphone signals.
snap_to_gridbool: Snap source locations to grid.
random_signal_lengthbool: Randomize signal length (Default: uniformly sampled signal length [1s,10s]).
fft_paramsdict: FFT parameters with default items block_size=128, overlap="50%", window="Hanning" and precision="complex64".
envac.Environment: Instance of acoular.Environment defining the environmental coditions, i.e. the speed of sound.
micsac.MicGeom: Instance of acoular.MicGeom defining the microphone array geometry.
noisy_micsac.MicGeom: a second instance of acoular.MicGeom defining the noisy microphone array geometry.
obsac.MicGeom: Instance of acoular.MicGeom defining the observation point which is used as the reference position when calculating the source strength.
gridac.RectGrid: Instance of acoular.RectGrid defining the grid on which the Beamformer calculates the source map and on which the targetmap feature is calculated.
source_gridac.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.
beamformerac.BeamformerBase: Instance of acoular.BeamformerBase defining the beamformer used to calculate the sourcemap.
steerac.SteeringVector: Instance of acoular.SteeringVector defining the steering vector used to calculate the sourcemap.
freq_dataac.PowerSpectra: 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.
fft_spectraac.RFFT: Instance of acoular.RFFT used to calculate the spectrogram data. Only used if mode is welch.
fft_obs_spectraac.PowerSpectra: Instance of acoular.PowerSpectra used to calculate the source strength at the observation point given in obs.
signalslist: List of signals.
sourceslist: List of sources.
mic_noise_signalac.SignalGenerator: Noise signal configuration object.
mic_noise_sourceac.UncorrelatedNoiseSource: Noise source configuration object.
micgeom_samplersp.MicGeomSampler: Sampler that applies positional noise to the microphone geometry.
location_samplersp.LocationSampler: Source location sampler that samples the locations of the sound sources.
rms_samplersp.ContainerSampler: Signal RMS sampler that samples the RMS values of the source signals.
nsources_samplersp.NumericAttributeSampler: Number of sources sampler.
mic_noise_samplersp.ContainerSampler: Microphone noise sampler that creates random uncorrelated noise at the microphones.
signal_length_samplersp.ContainerSampler: Signal length sampler that samples the length of the source signals. Only used if random_signal_length is True.

get_sampler()#

Return a dict of the sampler objects of type acoupipe.base.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.

Returns:

dict: dictionary containing the sampler objects

Examples

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

e.g.:

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

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:

irndarray

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.

fsfloat

Sampling frequency in Hz.

blocksizeint

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.

fftfreqarray_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_axisint, optional

Axis of ir corresponding to time samples. Default: -1.

Returns:

H_selndarray (complex): 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).

class acoupipe.datasets.experimental.DatasetMIRACLE(srir_dir=None, scenario='A1', dataset_split=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, 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 irdl 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_dirstr, optional: Path to the directory where the SRIR files are stored. Default is None, which sets the path to the irdl cache directory (overridable via the IRDL_DATA_DIR environment

variable). The SRIR files are downloaded from the MIRACLE dataset if not already present.
scenariostr, optional: Scenario of the dataset. One of ‘A1’, ‘A2’, ‘D1’, ‘R2’.
dataset_splitstr or None, optional: Artificial dataset split. One of “C1”, “C2”, “C3”, “C4”, or None (full dataset). Not allowed in combination with scenario “D1”. Default is None.
ref_mic_indexint, optional: Index of the microphone that is used as reference observation point. Default is 63, which is the index of the centermost microphone.
modestr, optional: Mode of the dataset. Possible values are “analytic”, “welch”, “wishart”. Default is “welch”.
mic_sig_noisebool, optional: Add uncorrelated noise to the microphone signals. Default is True.
signal_lengthfloat, optional: Length of the signal in seconds. Default is 5.
min_nsourcesint, optional: Minimum number of sources per sample. Default is 1.
max_nsourcesint, optional: Maximum number of sources per sample. Default is 10.
tasksint, optional: Number of parallel processes. Default is 1.
remote_argsdict, optional: Dictionary of keyword arguments passed to the remote actors when using Ray for parallelization. Defaults to None.
configDatasetMIRACLEConfig, 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()#: Resolve the SRIR file path, downloading via irdl if necessary.

get_sampler()#

Return a dict of the sampler objects of type acoupipe.base.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.

Returns:

dict: dictionary containing the sampler objects

Examples

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

e.g.:

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

class acoupipe.datasets.experimental.DatasetSRIRACHA(srir_dir=None, scenario='SR1-D', dataset_split=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 DatasetSRIRACHA object.

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

Parameters:

srir_dirstr, optional: Path to the directory where the SRIR files are stored. Default is None, which uses the default cache directory. The SRIR files are downloaded from the SRIRACHA dataset if they are not found in the directory.
scenariostr, optional: Scenario of the dataset. One of ‘SR1’, ‘SRA1’, ‘SR1-D’, ‘SRA1-D’, ‘SR2’, ‘SRA2’, ‘SR2-D’, ‘SRA2-D’. Default is ‘SR1-D’.
ref_mic_indexint, optional: Index of the microphone that is used as reference observation point. Default is 63, which is the index of the centermost microphone.
modestr, optional: Mode of the dataset. Possible values are “analytic”, “welch”, “wishart”. Default is “welch”.
mic_sig_noisebool, optional: Add uncorrelated noise to the microphone signals. Default is True.
signal_lengthfloat, optional: Length of the signal in seconds. Default is 5.
min_nsourcesint, optional: Minimum number of sources per sample. Default is 1.
max_nsourcesint, optional: Maximum number of sources per sample. Default is 10.
tasksint, optional: Number of parallel processes. Default is 1.
configDatasetMIRACLEConfig, 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.

set_filename()#: Resolve the SRIR file path, downloading via irdl if necessary.