MaskedTimeSamples¶

class acoular.sources.MaskedTimeSamples¶

Bases: TimeSamples

Container to process and manage time-domain data with support for masking samples and channels.

The MaskedTimeSamples class extends the functionality of TimeSamples by allowing the definition of start and stop indices for valid samples and by supporting invalidation of specific channels. This makes it suitable for use cases where only a subset of the data is of interest, such as analyzing specific time segments or excluding faulty sensor channels.

See also

acoular.sources.TimeSamples

The parent class for managing unmasked time-domain data.

Notes

Channels specified in invalid_channels are excluded from processing and not included in the generator output.

Examples

Data can be loaded from a HDF5 file and invalid channels can be specified as follows:

>>> from acoular import MaskedTimeSamples
>>> file = <some_h5_file.h5>
>>> ts = MaskedTimeSamples(file=file, invalid_channels=[0, 1])
>>> print(f'number of valid channels: {ts.num_channels}')
number of valid channels: 54

Alternatively, the time data can be specified directly as a numpy array. In this case, the data and sample_freq attributes must be set manually.

>>> from acoular import MaskedTimeSamples
>>> import numpy as np
>>> data = np.random.rand(1000, 4)
>>> ts = MaskedTimeSamples(data=data, sample_freq=51200)

Chunks of the time data can be accessed iteratively via the result() generator:

>>> block_size = 512
>>> generator = ts.result(num=block_size)
>>> for block in generator:
...     print(block.shape)
(512, 4)
(488, 4)

start = CInt(0, desc='start of valid samples')¶

Index of the first sample to be considered valid. Default is 0.

stop = Union(None, CInt, desc='stop of valid samples')¶

Index of the last sample to be considered valid. If None, all remaining samples from the start index onward are considered valid. Default is None.

invalid_channels = List(int, desc='list of invalid channels')¶

List of channel indices to be excluded from processing. Default is [].

channels = Property(depends_on=['invalid_channels', 'num_channels_total'], desc='channel mask')¶

A mask or index array representing valid channels. Automatically updated based on the invalid_channels and num_channels_total attributes.

num_channels_total = CInt(0, desc='total number of input channels')¶

Total number of input channels, including invalid channels. (read-only).

num_samples_total = CInt(0, desc='total number of samples per channel')¶

Total number of samples, including invalid samples. (read-only).

num_channels = Property( …¶

Number of valid input channels after excluding invalid_channels. (read-only)

num_samples = Property( …¶

Number of valid time-domain samples, based on start and stop indices. (read-only)

digest = Property(depends_on=['basename', 'start', 'stop', 'calib.digest', 'invalid_channels', '_datachecksum'])¶

A unique identifier for the samples, based on its properties. (read-only)

result(num=128)¶

Generate blocks of valid time-domain data iteratively.

The result() method is a Python generator that yields blocks of valid time-domain data based on the specified start and stop indices and the valid channels. Data can be calibrated if a calibration object, given by calib, is provided.

Parameters:

numint, optional

The size of each block to be yielded, representing the number of time-domain samples per block. Default is 128.

Yields:

numpy.ndarray

A 2D array of shape (num, num_channels) representing a block of valid time-domain data. The last block may have fewer than num samples if the number of valid samples is not a multiple of num.

Raises:

OSError

If no valid samples are available (i.e., start and stop indices result in an empty range).

ValueError

If the calibration data is incompatible with the number of valid channels.

Warning

A deprecation warning is raised if the calibration functionality is used directly in MaskedTimeSamples. Instead, the acoular.calib.Calib class should be used as a separate processing block.

Examples

Access valid data in blocks:

>>> import numpy as np
>>> from acoular.sources import MaskedTimeSamples
>>>
>>> data = np.random.rand(1000, 4)
>>> ts = MaskedTimeSamples(data=data, start=100, stop=900)
>>>
>>> generator = ts.result(num=256)
>>> for block in generator:
...     print(block.shape)
(256, 4)
(256, 4)
(256, 4)
(32, 4)

Note that the last block may have fewer that num samples.