Average¶

class acoular.process.Average¶

Bases: InOut

Calculate the average across consecutive time samples or frequency snapshots.

The average operation is performed differently depending on the source type. If the source is a time domain source (e.g. derived from SamplesGenerator), the average is calculated over a certain number of time samples given by num_per_average. If the source is a frequency domain source (e.g. derived from SpectraGenerator), the average is calculated over a certain number of frequency snapshots given by num_per_average.

See also

acoular.base.InOut

Receive data from any source domain and return signals in the same domain.

Examples

To estimate the RMS of a white noise (time-domain) signal, the average of the squared signal can be calculated:

>>> import acoular as ac
>>> import numpy as np
>>>
>>> signal = ac.WNoiseGenerator(sample_freq=51200, num_samples=51200, rms=2.0).signal()
>>> ts = ac.TimeSamples(data=signal[:, np.newaxis], sample_freq=51200)
>>> tp = ac.TimePower(source=ts)
>>> avg = ac.Average(source=tp, num_per_average=512)
>>> mean_squared_value = next(avg.result(num=1))
>>> rms = np.sqrt(mean_squared_value)[0, 0]
>>> print(rms)
1.9985200025816718

Here, each evaluation of the generator created by the result() method of the Average object via the next() function returns num=1 average across a snapshot of 512 time samples.

If the source is a frequency domain source, the average is calculated over a certain number of frequency snapshots, defined by num_per_average.

>>> fft = ac.RFFT(source=ts, block_size=64)
>>> ps = ac.AutoPowerSpectra(source=fft)
>>> avg = ac.Average(source=ps, num_per_average=16)
>>> mean_power = next(avg.result(num=1))
>>> print(np.sqrt(mean_power.sum()))
2.0024960894399295

Here, the generator created by the result() method of the Average object returns the average across 16 snapshots in the frequency domain.

num_per_average = Int(64, desc='number of samples/snapshots to average over')¶

The number of samples (time domain source) or snapshots (frequency domain source) to average over. Default is 64.

sample_freq = Property(depends_on=['source.sample_freq', 'num_per_average'])¶

The sampling frequency of the output signal. It is set automatically as (sample_freq / num_per_average).

num_samples = Property(depends_on=['source.num_samples', 'num_per_average'])¶

The number of samples (time domain) or snapshots (frequency domain) of the output signal. It is set automatically as (num_samples / num_per_average).

digest = Property(depends_on=['source.digest', 'num_per_average'])¶

A unique identifier based on the class properties.

result(num)¶

Generate averaged output blocks from the source data.

This method implements a Python generator that yields blocks of averaged data from the source. The averaging is performed over num_per_average samples (for time-domain sources) or snapshots (for frequency-domain sources). The size of the blocks yielded is defined by the num parameter.

Parameters:

numint

The number of averaged blocks to yield at a time. Each block contains the average over num_per_average time samples or frequency snapshots. The last block may be shorter than the specified size if the remaining data is insufficient.

Yields:

numpy.ndarray

A 2D NumPy array of shape (num, num_channels), where num is the number of averaged blocks requested, and num_channels corresponds to the number of channels in the source, as specified by num_channels. Each entry in the array is the average over num_per_average samples/snapshots.

Notes

• The averaging operation depends on the source type:

  • For time-domain sources (e.g., derived from SamplesGenerator), the average is calculated over num_per_average time samples.

  • For frequency-domain sources (e.g., derived from SpectraGenerator), the average is calculated over num_per_average frequency snapshots.

• The generator will stop yielding when the source data is exhausted.

• If the source provides fewer than num * num_per_average samples, the final block may be smaller than the requested num size.