`PowerSpectraImport`#

class acoular.spectra.PowerSpectraImport

Bases: PowerSpectra

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.

csm: The cross-spectral matrix stored in an array of shape (n, m, m) of complex for n frequencies and m channels.

frequencies: The frequencies included in the CSM in ascending order. Accepts list, array, or a single float value.

num_channels: Number of time data channels, inferred from the shape of the CSM.

source: PowerSpectraImport does not consume time data; source is always None.

sample_freq: Sampling frequency of the signal. Default is None

block_size: Block size for FFT, non-functional in this class.

window: Windowing method, non-functional in this class.

overlap: Overlap between blocks, non-functional in this class.

cached: Caching capability, always disabled.

num_blocks: Number of FFT blocks, always None.

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

basename: Name of the cache file without extension. (read-only)

fftfreq()

Return the Discrete Fourier Transform sample frequencies.

The method checks the type of frequencies and returns the corresponding frequency array. If frequencies is not defined, a warning is raised.

Returns:

numpy.ndarray: Array containing the frequencies.

calc_csm()

Calculate the CSM for the given source data.

This method computes the CSM by performing a block-wise Fast Fourier Transform (FFT) on the source data, applying a window function, and averaging the results. Only the upper triangular part of the matrix is computed for efficiency, and the lower triangular part is constructed via transposition and complex conjugation.

Returns:

numpy.ndarray: The computed cross spectral matrix as an array of shape (n, m, m) of complex values for n frequencies and m channels as in num_channels.

Examples

>>> import numpy as np
>>> from acoular import TimeSamples
>>> from acoular.spectra import PowerSpectra
>>>
>>> data = np.random.rand(1000, 4)
>>> ts = TimeSamples(data=data, sample_freq=51200)
>>> print(ts.num_channels, ts.num_samples, ts.sample_freq)
4 1000 51200.0
>>> ps = PowerSpectra(source=ts, block_size=128, window='Blackman')
>>> ps.csm.shape
(65, 4, 4)

calc_ev()

Calculate eigenvalues and eigenvectors of the CSM for each frequency.

The eigenvalues represent the spectral power, and the eigenvectors correspond to the principal components of the matrix. This calculation is performed for all frequency slices of the CSM.

Returns:

tuple of numpy.ndarray

A tuple containing:

eva (numpy.ndarray): Eigenvalues as a 2D array of shape (n, m), where n is the number of frequencies and m is the number of channels. The datatype depends on the precision.
eve (numpy.ndarray): Eigenvectors as a 3D array of shape (n, m, m). The datatype is consistent with the precision of the input data.

Notes

The precision of the eigenvalues is determined by precision ('float64' for complex128 precision and 'float32' for complex64 precision).
This method assumes the CSM is already computed and accessible via csm.

Examples

>>> import numpy as np
>>> from acoular import TimeSamples
>>> from acoular.spectra import PowerSpectra
>>>
>>> data = np.random.rand(1000, 4)
>>> ts = TimeSamples(data=data, sample_freq=51200)
>>> ps = PowerSpectra(source=ts, block_size=128, window='Hanning')
>>> eva, eve = ps.calc_ev()
>>> print(eva.shape, eve.shape)
(65, 4) (65, 4, 4)

calc_eva()

Calculate eigenvalues of the CSM.

This method computes and returns the eigenvalues of the CSM for all frequency slices.

Returns:

numpy.ndarray: A 2D array of shape (n, m) containing the eigenvalues for n frequencies and m channels. The datatype depends on precision ('float64' for complex128 precision and 'float32' for complex64 precision).

Notes

This method internally calls calc_ev() and extracts only the eigenvalues.

calc_eve()

Calculate eigenvectors of the Cross Spectral Matrix (CSM).

This method computes and returns the eigenvectors of the CSM for all frequency slices.

Returns:

numpy.ndarray: A 3D array of shape (n, m, m) containing the eigenvectors for n frequencies and m channels. Each slice eve[f] represents an (m, m) matrix of eigenvectors for frequency f. The datatype matches the precision of the CSM (complex128 or complex64).

Notes

This method internally calls calc_ev() and extracts only the eigenvectors.

synthetic_ev(freq, num=0)

Retrieve synthetic eigenvalues for a specified frequency or frequency range.

This method calculates the eigenvalues of the CSM for a single frequency or a synthetic frequency range. If num is set to 0, it retrieves the eigenvalues at the exact frequency. Otherwise, it averages eigenvalues across a range determined by freq and num.

Parameters:

freqfloat

The target frequency for which the eigenvalues are calculated. This is the center frequency for synthetic averaging.

numint, optional

The number of subdivisions in the logarithmic frequency space around the center frequency freq.

0 (default): Only the eigenvalues for the exact frequency line are returned.
Non-zero:

num	frequency band width
0	single frequency line
1	octave band
3	third-octave band
n	1/n-octave band

Returns:

numpy.ndarray: An array of eigenvalues. If num == 0, the eigenvalues for the single frequency are returned. For num > 0, a summed array of eigenvalues across the synthetic frequency range is returned.

Examples

>>> import numpy as np
>>> from acoular import TimeSamples
>>> from acoular.spectra import PowerSpectra
>>> np.random.seed(0)
>>>
>>> data = np.random.rand(1000, 4)
>>> ts = TimeSamples(data=data, sample_freq=51200)
>>> ps = PowerSpectra(source=ts, block_size=128, window='Hamming')
>>> ps.synthetic_ev(freq=5000, num=5)
array([0.00048803, 0.0010141 , 0.00234248, 0.00457097])
>>> ps.synthetic_ev(freq=5000)
array([0.00022468, 0.0004589 , 0.00088059, 0.00245989])

ind_low: Index of lowest frequency line to compute. Default is 1. Only used by objects that fetch the CSM. PowerSpectra computes every frequency line.

ind_high: Index of highest frequency line to compute. Default is -1 (last possible line for default block_size).

freq_range: 2-element array with the lowest and highest frequency. If the higher frequency is larger than the max frequency, the max frequency will be the upper bound.

indices: The sequence of frequency indices between ind_low and ind_high. (read-only)

eva: The eigenvalues of the CSM, stored as an array of shape (n,) of floats for n frequencies. (read-only)

eve: The eigenvectors of the cross spectral matrix, stored as an array of shape (n, m, m) of floats for n frequencies and m channels as in num_channels. (read-only)

precision: Precision of the FFT, corresponding to NumPy dtypes. Default is 'complex128'.

PowerSpectraImport#

`PowerSpectraImport`#