acoupipe.datasets.synthetic#

Contains classes for the generation of microphone array data from synthesized signals for acoustic testing applications.

Currently, the following dataset generators are available:

DatasetSynthetic: A simple and fast method that relies on synthetic white noise signals and spatially stationary sources radiating under anechoic conditions.

../../../../_images/msm_layout.png — Default measurement setup used in the `acoupipe.datasets.synthetic` module.#

Module Contents#

class acoupipe.datasets.synthetic.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.synthetic.AnalyticNoiseStrengthFeature#

Bases: SpectraFeature

Handles the calculation of features in the frequency domain.

Attributes:

namestr: Name of the feature.
freq_datainstance of class acoular.BaseSpectra: The frequency data to calculate the feature for.
ffloat: the frequency (or center frequency) of interest
numint: the frequency band (0: single frequency line, 1: octave band, 3: third octave band)
fidxlist of tuples: List of tuples containing the start and end indices of the frequency bands to be considered.

get_feature_func()#: Will return a method depending on the class parameters.

class acoupipe.datasets.synthetic.AnalyticSourceStrengthFeature#

Bases: SpectraFeature

Handles the calculation of features in the frequency domain.

Attributes:

namestr: Name of the feature.
freq_datainstance of class acoular.BaseSpectra: The frequency data to calculate the feature for.
ffloat: the frequency (or center frequency) of interest
numint: the frequency band (0: single frequency line, 1: octave band, 3: third octave band)
fidxlist of tuples: List of tuples containing the start and end indices of the frequency bands to be considered.

get_feature_func()#: Will return a method depending on the class parameters.

class acoupipe.datasets.synthetic.BaseFeatureCatalog#

Bases: traits.api.HasPrivateTraits

BaseFeatureCatalog base class for handling feature funcs.

Attributes:

namestr: Name of the feature.
dtypecallable: Numpy dtype of the feature.

get_feature_func()#: Will return a method depending on the class parameters.

class acoupipe.datasets.synthetic.BaseFeatureCollectionBuilder#

Bases: traits.api.HasPrivateTraits

BaseFeatureCollectionBuilder base class for building a BaseFeatureCollection.

Attributes:

feature_collectionBaseFeatureCollection: BaseFeatureCollection object.

add_custom(feature_func)#

Add a custom feature to the BaseFeatureCollection.

The custom feature_func should be a callable that takes a sampler as input and returns a dictionary of feature name and feature data.

Parameters:

feature_funccallable: Feature to be added.

build()#

Build a BaseFeatureCollection.

Returns:

BaseFeatureCollection: BaseFeatureCollection object.

class acoupipe.datasets.synthetic.CSMFeature#

Bases: SpectraFeature

CSMFeature class for handling cross-spectral matrix calculation.

Attributes:

namestr: Name of the feature (default=’csm’).
freq_datainstance of class acoular.PowerSpectra: The object which calculates the cross-spectral matrix.
ffloat: the frequency (or center frequency) of interest
numint: the frequency band (0: single frequency line, 1: octave band, 3: third octave band)
fidxlist of tuples: List of tuples containing the start and end indices of the frequency bands to be considered.

static calc_csm1(sampler, freq_data, name)#

Calculate the cross-spectral matrix (CSM) from time data.

Parameters:

freq_datainstance of class acoular.PowerSpectra: power spectra to calculate the csm feature

Returns:

numpy.array: The complex-valued cross-spectral matrix with shape (numfreq, num_mics, num_mics).

static calc_csm2(sampler, freq_data, fidx, name)#

Calculate the cross-spectral matrix (CSM) from time data.

Parameters:

freq_datainstance of class acoular.PowerSpectra: power spectra to calculate the csm feature
fidxlist of tuples, optional: list of tuples containing the start and end indices of the frequency bands to be considered, by default None

Returns:

numpy.array: The complex-valued cross-spectral matrix with shape (numfreq, num_mics, num_mics) with numfreq depending on the number of frequencies in fidx.

get_feature_func()#: Return the callable for calculating the cross-spectral matrix.

class acoupipe.datasets.synthetic.CSMtriuFeature#

Bases: SpectraFeature

Handles the calculation of features in the frequency domain.

Attributes:

namestr: Name of the feature.
freq_datainstance of class acoular.BaseSpectra: The frequency data to calculate the feature for.
ffloat: the frequency (or center frequency) of interest
numint: the frequency band (0: single frequency line, 1: octave band, 3: third octave band)
fidxlist of tuples: List of tuples containing the start and end indices of the frequency bands to be considered.

static calc_csmtriu1(sampler, freq_data, name)#

Calculate the cross-spectral matrix (CSM) from time data.

Parameters:

freq_datainstance of class acoular.PowerSpectra: power spectra to calculate the csm feature

Returns:

numpy.array: The real-valued cross-spectral matrix with shape (numfreq, num_mics, num_mics).

static calc_csmtriu2(sampler, freq_data, fidx, name)#

Calculate the cross-spectral matrix (CSM) from time data.

Parameters:

freq_datainstance of class acoular.PowerSpectra: power spectra to calculate the csm feature
fidxlist of tuples, optional: list of tuples containing the start and end indices of the frequency bands to be considered, by default None

Returns:

numpy.array: The real-valued cross-spectral matrix with shape (numfreq, num_mics, num_mics) with numfreq depending on the number of frequencies in fidx.

get_feature_func()#: Will return a method depending on the class parameters.

class acoupipe.datasets.synthetic.EigmodeFeature#

Bases: SpectraFeature

Handles the calculation of features in the frequency domain.

Attributes:

namestr: Name of the feature.
freq_datainstance of class acoular.BaseSpectra: The frequency data to calculate the feature for.
ffloat: the frequency (or center frequency) of interest
numint: the frequency band (0: single frequency line, 1: octave band, 3: third octave band)
fidxlist of tuples: List of tuples containing the start and end indices of the frequency bands to be considered.

static calc_eigmode1(sampler, freq_data, name)#

Calculate eigenvalue-scaled eigenvectors of the CSM from time data.

Parameters:

freq_datainstance of class acoular.PowerSpectra: power spectra to calculate the csm feature

Returns:

numpy.array: The eigenvalue scaled eigenvectors with shape (numfreq, num_mics, num_mics).

static calc_eigmode2(sampler, freq_data, fidx, name)#

Calculate eigenvalue-scaled eigenvectors of the CSM from time data.

Parameters:

freq_datainstance of class acoular.PowerSpectra: power spectra to calculate the csm feature
fidxlist of tuples, optional: list of tuples containing the start and end indices of the frequency bands to be considered, by default None

Returns:

numpy.array: The eigenvalue scaled eigenvectors with shape (numfreq, num_mics, num_mics) with numfreq depending on the number of frequencies in fidx.

get_feature_func()#: Will return a method depending on the class parameters.

class acoupipe.datasets.synthetic.EstimatedNoiseStrengthFeature#

Bases: SpectraFeature

Handles the calculation of features in the frequency domain.

Attributes:

namestr: Name of the feature.
freq_datainstance of class acoular.BaseSpectra: The frequency data to calculate the feature for.
ffloat: the frequency (or center frequency) of interest
numint: the frequency band (0: single frequency line, 1: octave band, 3: third octave band)
fidxlist of tuples: List of tuples containing the start and end indices of the frequency bands to be considered.

get_feature_func()#: Will return a method depending on the class parameters.

class acoupipe.datasets.synthetic.EstimatedSourceStrengthFeature#

Bases: SpectraFeature

Handles the calculation of features in the frequency domain.

Attributes:

namestr: Name of the feature.
freq_datainstance of class acoular.BaseSpectra: The frequency data to calculate the feature for.
ffloat: the frequency (or center frequency) of interest
numint: the frequency band (0: single frequency line, 1: octave band, 3: third octave band)
fidxlist of tuples: List of tuples containing the start and end indices of the frequency bands to be considered.

get_feature_func()#: Will return a method depending on the class parameters.

class acoupipe.datasets.synthetic.LocFeature#

Bases: BaseFeatureCatalog

BaseFeatureCatalog base class for handling feature funcs.

Attributes:

namestr: Name of the feature.
dtypecallable: Numpy dtype of the feature.

get_feature_func()#: Will return a method depending on the class parameters.

class acoupipe.datasets.synthetic.SourcemapFeature#

Bases: BaseFeatureCatalog

Handle the generation of sourcemaps obtained with microphone array methods.

Attributes:

namestr

Name of the feature (default=’sourcemap’).

beamformerinstance of class acoular.BeamformerBase

The beamformer to calculate the sourcemap.

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

fidxlist of tuples

List of tuples containing the start and end indices of the frequency bands to be considered. Is determined automatically from attr:f and attr:num.

set_freq_limits()#: Set the beamformer frequency limits to calculate only the necessary frequencies.

get_feature_func()#: Return the callable for calculating the sourcemap.

class acoupipe.datasets.synthetic.SpectrogramFeature#

Bases: SpectraFeature

SpectrogramFeature class for handling spectrogram features.

Attributes:

namestr: Name of the feature (default=’spectrogram’).
freq_datainstance of class acoular.RFFT: The object which calculates the spectrogram data.
ffloat: the frequency (or center frequency) of interest
numint: the frequency band (0: single frequency line, 1: octave band, 3: third octave band)
fidxlist of tuples: List of tuples containing the start and end indices of the frequency bands to be considered.

get_feature_func()#: Will return a method depending on the class parameters.

class acoupipe.datasets.synthetic.TargetmapFeature#

Bases: BaseFeatureCatalog

BaseFeatureCatalog base class for handling feature funcs.

Attributes:

namestr: Name of the feature.
dtypecallable: Numpy dtype of the feature.

get_feature_func()#: Will return a method depending on the class parameters.

class acoupipe.datasets.synthetic.TimeDataFeature#

Bases: BaseFeatureCatalog

TimeDataFeature class for handling time data.

Attributes:

namestr: Name of the feature (default=’time_data’).
time_datainstance of class acoular.SamplesGenerator: The source delivering the time data.

get_feature_func()#: Return the callable for calculating the time data.

acoupipe.datasets.synthetic.create_feature(feature_func, name, shape, dtype)#

acoupipe.datasets.synthetic.get_ir(sample_freq, room_dim, mloc, sloc, rt60, c=343.0, **kwargs)#: Get impulse responses for the unsupported developer-only synthetic IR dataset.

acoupipe.datasets.synthetic.require_ir_support()#: Validate that the unsupported developer-only IR dataset support is installed.

class acoupipe.datasets.synthetic.PowerSpectraAnalytic#

Bases: acoular.PowerSpectraImport

Provides a dummy class for using pre-calculated CSMs.

This class does not calculate the CSM. Instead, the user can inject one or multiple existing CSMs by setting the csm attribute. This can be useful when algorithms shall be evaluated with existing CSMs. The frequency or frequencies contained by the CSM must be set via the frequencies attribute. The attr:num_channels attributes is determined on the basis of the CSM shape. In contrast to the PowerSpectra object, the attributes sample_freq, source, block_size, window, overlap, cached, and num_blocks have no functionality.

fftfreq()#

Return the Discrete Fourier Transform sample frequencies.

Returns:

fndarray: Array of length block_size/2+1 containing the sample frequencies.

acoupipe.datasets.synthetic.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).

acoupipe.datasets.synthetic.get_all_source_signals(source_list)#

Get all signals from a list of acoular.SamplesGenerator derived objects.

Parameters:

source_listlist: list of acoular.SamplesGenerator derived objects

Returns:

list: list of all acoular.SignalGenerator derived objects

acoupipe.datasets.synthetic.get_uncorrelated_noise_source_recursively(source)#

Recursively get all uncorrelated noise sources from a acoular.TimeInOut object.

Parameters:

sourceinstance of class acoular.TimeInOut: the source object

Returns:

list: list of all uncorrelated noise sources

class acoupipe.datasets.synthetic.DatasetSynthetic(mode='welch', mic_pos_noise=True, mic_sig_noise=True, snap_to_grid=False, random_signal_length=False, signal_length=5, fs=13720.0, min_nsources=1, max_nsources=10, tasks=1, remote_args=None, logger=None, config=None)#

Bases: acoupipe.datasets.base.DatasetBase

DatasetSynthetic is a purely synthetic microphone array source case generator.

DatasetSynthetic relies on synthetic source signals from which the features are extracted and has been used in different publications, e.g. [KHS19], [KS22], [FZHX22]. The default virtual simulation setup consideres a 64 channel microphone array and a planar observation area, as shown in the default measurement setup figure.

Default environmental properties

Default Environmental Characteristics#
Environment	Anechoic, Resting, Homogeneous Fluid
Speed of sound	343 m/s
Microphone Array	Vogel’s spiral, \(M=64\), Aperture Size 1 m
Observation Area	x,y in [-0.5,0.5], z=0.5
Source Type	Monopole
Source Signals	Uncorrelated White Noise (\(T=5\,s\))

Default FFT parameters

The underlying default FFT parameters are:

FFT Parameters#
Sampling Rate	He = 40, fs=13720 Hz
Block size	128 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. Their respective distributions, are closely related to [HS17]. As such, the the microphone positions are spatially disturbed to account for uncertainties in the microphone placement. The number of sources, their positions, and strength is randomly chosen. Uncorrelated white noise is added to the microphone channels by default.

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

Example#

from acoupipe.datasets.synthetic import DatasetSynthetic

dataset = DatasetSynthetic()
dataset_generator = dataset.generate_dataset(
    features=['sourcemap', 'loc', 'f', 'num'],  # choose the features to extract
    f=[1000, 2000, 3000],  # choose the frequencies to extract
    split='training',  # choose the split of the dataset
    size=10,  # choose the size of the dataset
)

# get the first data sample
data = next(dataset_generator)

# print the keys of the dataset
print(data.keys())

Initialization Parameters

Initialize the DatasetSynthetic object.

The input parameters are passed to the DatasetSyntheticConfig object, which creates all necessary objects for the simulation of microphone array data.

Parameters:

modestr: Type of calculation method. Can be either welch, analytic or wishart. Defaults to welch.
mic_pos_noisebool: Apply positional noise to microphone geometry. Defaults to True.
mic_sig_noisebool: Apply additional uncorrelated white noise to microphone signals. Defaults to True.
snap_to_gridbool: Snap source locations to grid. The grid is defined in the config object as config.grid. Defaults to False.
random_signal_lengthbool: Randomize signal length. Defaults to False. If True, the signal length is uniformly sampled from the interval [1s,10s].
signal_lengthfloat: Length of the signal in seconds. Defaults to 5 seconds.
fsfloat: Sampling frequency in Hz. Defaults to 13720 Hz.
min_nsourcesint: Minimum number of sources in the dataset. Defaults to 1.
max_nsourcesint: Maximum number of sources in the dataset. Defaults to 10.
tasksint: Number of parallel tasks. Defaults to 1.
remote_argsdict: Dictionary of keyword arguments passed to the remote actors when using Ray for parallelization. Defaults to None.
loggerlogging.Logger: Logger object. Defaults to None.
configDatasetSyntheticConfig: Configuration object. Defaults to None. If None, a default configuration object is created.

get_feature_collection(features, f, num)#

Get the feature collection of the dataset.

Returns:

BaseFeatureCollection: BaseFeatureCollection object.

acoupipe.datasets.synthetic.sample_signal_length(rng)#

class acoupipe.datasets.synthetic.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(...),
    ...
}