TimeSamples¶

class acoular.sources.TimeSamples¶

Bases: SamplesGenerator

Container for processing time data in *.h5 or NumPy array format.

The TimeSamples class provides functionality for loading, managing, and accessing time-domain data stored in HDF5 files or directly provided as a NumPy array. This data can be accessed iteratively through the result() method, which returns chunks of the time data for further processing.

See also

acoular.sources.MaskedTimeSamples

Extends the functionality of class TimeSamples by enabling the definition of start and stop samples as well as the specification of invalid channels.

Notes

• If a calibration object is provided, calibrated time-domain data will be returned.

• Metadata from the HDF5 file can be accessed through the metadata attribute.

Examples

Data can be loaded from a HDF5 file as follows:

>>> from acoular import TimeSamples
>>> file = <some_h5_file.h5>
>>> ts = TimeSamples(file=file)
>>> print(f'number of channels: {ts.num_channels}')
number of channels: 56

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.

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

Chunks of the time data can be accessed iteratively via the result() generator. The last block will be shorter than the block size if the number of samples is not a multiple of the block size.

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

file = File(filter=['*.h5'], exists=True, desc='name of data file')¶

Full path to the .h5 file containing time-domain data.

basename = Property(depends_on=['file'], desc='basename of data file')¶

Basename of the .h5 file, set automatically from the file attribute.

calib = Instance(Calib, desc='Calibration data')¶

Calibration data, an instance of the Calib class. (optional; if provided, the time data will be calibrated.)

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

Number of input channels in the time data, set automatically based on the loaded data or specified array.

num_samples = CInt(0, desc='number of samples')¶

Total number of time-domain samples, set automatically based on the loaded data or specified array.

data = Any(transient=True, desc='the actual time data array')¶

A 2D NumPy array containing the time-domain data, shape (num_samples, num_channels).

h5f = Instance(H5FileBase, transient=True)¶

HDF5 file object.

metadata = Dict(desc='metadata contained in .h5 file')¶

Metadata loaded from the HDF5 file, if available.

digest = Property( …¶

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

result(num=128)¶

Generate blocks of time-domain data iteratively.

The result() method is a Python generator that yields blocks of time-domain data of the specified size. Data is either read from an HDF5 file (if file is set) or from a NumPy array (if data is directly provided). If a calibration object is specified, the returned data is calibrated.

Parameters:

numint, optional

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

Yields:

numpy.ndarray

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

Raises:

OSError

If no samples are available (i.e., num_samples is 0).

ValueError

If the calibration data does not match the number of channels.

Warning

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

Examples

Create a generator and access blocks of data:

>>> import numpy as np
>>> from acoular.sources import TimeSamples
>>> ts = TimeSamples(data=np.random.rand(1000, 4), sample_freq=51200)
>>> generator = ts.result(num=256)
>>> for block in generator:
...     print(block.shape)
(256, 4)
(256, 4)
(256, 4)
(232, 4)

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