acoular 24.7__py3-none-any.whl → 25.1__py3-none-any.whl

acoular/spectra.py

@@ -7,12 +7,11 @@
     :toctree: generated/
 
     BaseSpectra
-    FFTSpectra
     PowerSpectra
-    synthetic
     PowerSpectraImport
 """
 
+from abc import abstractmethod
 from warnings import warn
 
 from numpy import (
@@ -26,52 +25,53 @@ from numpy import (
     hamming,
     hanning,
     imag,
-    isscalar,
     linalg,
     ndarray,
     newaxis,
     ones,
     real,
     searchsorted,
-    sqrt,
-    sum,
+    sum,  # noqa A004
     zeros,
-    zeros_like,
 )
 from scipy import fft
 from traits.api import (
+    ABCHasStrictTraits,
     Bool,
     CArray,
     Delegate,
     Enum,
     Float,
-    HasPrivateTraits,
     Instance,
     Int,
+    Map,
     Property,
-    Trait,
+    Union,
     cached_property,
     property_depends_on,
 )
 
-from .calib import Calib
+# acoular imports
+from .base import SamplesGenerator
 from .configuration import config
+from .deprecation import deprecated_alias
 from .fastFuncs import calcCSM
 from .h5cache import H5cache
 from .h5files import H5CacheFileBase
 from .internal import digest
-from .tprocess import SamplesGenerator, TimeInOut
+from .tools.utils import find_basename
 
 
-class BaseSpectra(HasPrivateTraits):
+@deprecated_alias({'numchannels': 'num_channels'}, read_only=True)
+class BaseSpectra(ABCHasStrictTraits):
     #: Data source; :class:`~acoular.sources.SamplesGenerator` or derived object.
-    source = Trait(SamplesGenerator)
+    source = Instance(SamplesGenerator)
 
     #: Sampling frequency of output signal, as given by :attr:`source`.
     sample_freq = Delegate('source')
 
     #: Number of time data channels
-    numchannels = Delegate('source')
+    num_channels = Delegate('source')
 
     #: Window function for FFT, one of:
     #:   * 'Rectangular' (default)
@@ -79,23 +79,22 @@ class BaseSpectra(HasPrivateTraits):
     #:   * 'Hamming'
     #:   * 'Bartlett'
     #:   * 'Blackman'
-    window = Trait(
-        'Rectangular',
+    window = Map(
         {'Rectangular': ones, 'Hanning': hanning, 'Hamming': hamming, 'Bartlett': bartlett, 'Blackman': blackman},
+        default_value='Rectangular',
         desc='type of window for FFT',
     )
 
     #: Overlap factor for averaging: 'None'(default), '50%', '75%', '87.5%'.
-    overlap = Trait('None', {'None': 1, '50%': 2, '75%': 4, '87.5%': 8}, desc='overlap of FFT blocks')
+    overlap = Map({'None': 1, '50%': 2, '75%': 4, '87.5%': 8}, default_value='None', desc='overlap of FFT blocks')
 
     #: FFT block size, one of: 128, 256, 512, 1024, 2048 ... 65536,
     #: defaults to 1024.
-    block_size = Trait(
+    block_size = Enum(
         1024,
         128,
         256,
         512,
-        1024,
         2048,
         4096,
         8192,
@@ -105,16 +104,16 @@ class BaseSpectra(HasPrivateTraits):
         desc='number of samples per FFT block',
     )
 
-    #: The floating-number-precision of entries of csm, eigenvalues and
-    #: eigenvectors, corresponding to numpy dtypes. Default is 64 bit.
-    precision = Trait('complex128', 'complex64', desc='precision of the fft')
+    #: The floating-number-precision of the resulting spectra, corresponding to numpy dtypes.
+    #: Default is 'complex128'.
+    precision = Enum('complex128', 'complex64', desc='precision of the fft')
 
     # internal identifier
     digest = Property(depends_on=['precision', 'block_size', 'window', 'overlap'])
 
-    @cached_property
+    @abstractmethod
     def _get_digest(self):
-        return digest(self)
+        """Return internal identifier."""
 
     def fftfreq(self):
         """Return the Discrete Fourier Transform sample frequencies.
@@ -130,9 +129,9 @@ class BaseSpectra(HasPrivateTraits):
         return None
 
     # generator that yields the time data blocks for every channel (with optional overlap)
-    def get_source_data(self):
+    def _get_source_data(self):
         bs = self.block_size
-        temp = empty((2 * bs, self.numchannels))
+        temp = empty((2 * bs, self.num_channels))
         pos = bs
         posinc = bs / self.overlap_
         for data_block in self.source.result(bs):
@@ -146,52 +145,16 @@ class BaseSpectra(HasPrivateTraits):
                 pos -= bs
 
 
-class FFTSpectra(BaseSpectra, TimeInOut):
-    """Provides the spectra of multichannel time data.
-
-    Returns Spectra per block over a Generator.
-    """
-
-    # internal identifier
-    digest = Property(depends_on=['source.digest', 'precision', 'block_size', 'window', 'overlap'])
-
-    @cached_property
-    def _get_digest(self):
-        return digest(self)
-
-    # generator that yields the fft for every channel
-    def result(self):
-        """Python generator that yields the output block-wise.
-
-        Parameters
-        ----------
-        num : integer
-            This parameter defines the size of the blocks to be yielded
-            (i.e. the number of samples per block).
-
-        Returns
-        -------
-        Samples in blocks of shape (numfreq, :attr:`numchannels`).
-            The last block may be shorter than num.
-
-        """
-        wind = self.window_(self.block_size)
-        weight = sqrt(2) / self.block_size * sqrt(self.block_size / dot(wind, wind)) * wind[:, newaxis]
-        for data in self.get_source_data():
-            ft = fft.rfft(data * weight, None, 0).astype(self.precision)
-            yield ft
-
-
 class PowerSpectra(BaseSpectra):
     """Provides the cross spectral matrix of multichannel time data
      and its eigen-decomposition.
 
     This class includes the efficient calculation of the full cross spectral
-    matrix using the Welch method with windows and overlap. It also contains
+    matrix using the Welch method with windows and overlap (:cite:`Welch1967`). It also contains
     the CSM's eigenvalues and eigenvectors and additional properties.
 
     The result is computed only when needed, that is when the :attr:`csm`,
-    :attr:`eva`, or :attr:`eve` attributes are acturally read.
+    :attr:`eva`, or :attr:`eve` attributes are actually read.
     Any change in the input data or parameters leads to a new calculation,
     again triggered when an attribute is read. The result may be
     cached on disk in HDF5 files and need not to be recomputed during
@@ -200,30 +163,14 @@ class PowerSpectra(BaseSpectra):
     and the same file name in case of that the data is read from a file.
     """
 
-    # Shadow trait, should not be set directly, for internal use.
-    _source = Trait(SamplesGenerator)
-
     #: Data source; :class:`~acoular.sources.SamplesGenerator` or derived object.
-    source = Property(_source, desc='time data object')
-
-    #: The :class:`~acoular.tprocess.SamplesGenerator` object that provides the data.
-    time_data = Property(
-        _source,
-        desc='deprecated attribute holding the time data object. Use PowerSpectra.source instead!',
-    )
-
-    #: The :class:`~acoular.calib.Calib` object that provides the calibration data,
-    #: defaults to no calibration, i.e. the raw time data is used.
-    #:
-    #: **deprecated**:      use :attr:`~acoular.sources.TimeSamples.calib` property of
-    #: :class:`~acoular.sources.TimeSamples` objects
-    calib = Instance(Calib)
+    source = Instance(SamplesGenerator)
 
     # Shadow trait, should not be set directly, for internal use.
     _ind_low = Int(1, desc='index of lowest frequency line')
 
     # Shadow trait, should not be set directly, for internal use.
-    _ind_high = Trait(-1, (Int, None), desc='index of highest frequency line')
+    _ind_high = Union(Int(-1), None, desc='index of highest frequency line')
 
     #: Index of lowest frequency line to compute, integer, defaults to 1,
     #: is used only by objects that fetch the csm, PowerSpectra computes every
@@ -238,7 +185,7 @@ class PowerSpectra(BaseSpectra):
     _freqlc = Float(0)
 
     # Stores the set higher frequency, for internal use, should not be set directly.
-    _freqhc = Trait(0, (Float, None))
+    _freqhc = Union(Float(0), None)
 
     # Saves whether the user set indices or frequencies last, for internal use only,
     # not to be set directly, if True (default), indices are used for setting
@@ -268,10 +215,10 @@ class PowerSpectra(BaseSpectra):
     indices = Property(desc='index range')
 
     #: Name of the cache file without extension, readonly.
-    basename = Property(depends_on='_source.digest', desc='basename for cache file')
+    basename = Property(depends_on=['source.digest'], desc='basename for cache file')
 
     #: The cross spectral matrix,
-    #: (number of frequencies, numchannels, numchannels) array of complex;
+    #: (number of frequencies, num_channels, num_channels) array of complex;
     #: readonly.
     csm = Property(desc='cross spectral matrix')
 
@@ -280,23 +227,23 @@ class PowerSpectra(BaseSpectra):
     eva = Property(desc='eigenvalues of cross spectral matrix')
 
     #: Eigenvectors of the cross spectral matrix as an
-    #: (number of frequencies, numchannels, numchannels) array of floats,
+    #: (number of frequencies, num_channels, num_channels) array of floats,
     #: readonly.
     eve = Property(desc='eigenvectors of cross spectral matrix')
 
     # internal identifier
     digest = Property(
-        depends_on=['_source.digest', 'calib.digest', 'block_size', 'window', 'overlap', 'precision'],
+        depends_on=['source.digest', 'block_size', 'window', 'overlap', 'precision'],
     )
 
     # hdf5 cache file
     h5f = Instance(H5CacheFileBase, transient=True)
 
-    @property_depends_on('_source.numsamples, block_size, overlap')
+    @property_depends_on(['source.num_samples', 'block_size', 'overlap'])
     def _get_num_blocks(self):
-        return self.overlap_ * self._source.numsamples / self.block_size - self.overlap_ + 1
+        return self.overlap_ * self.source.num_samples / self.block_size - self.overlap_ + 1
 
-    @property_depends_on('_source.sample_freq, block_size, ind_low, ind_high')
+    @property_depends_on(['source.sample_freq', 'block_size', 'ind_low', 'ind_high'])
     def _get_freq_range(self):
         fftfreq = self.fftfreq()
         if fftfreq is not None:
@@ -310,7 +257,7 @@ class PowerSpectra(BaseSpectra):
         self._freqlc = freq_range[0]
         self._freqhc = freq_range[1]
 
-    @property_depends_on('_source.sample_freq, block_size, _ind_low, _freqlc')
+    @property_depends_on(['source.sample_freq', 'block_size', '_ind_low', '_freqlc'])
     def _get_ind_low(self):
         fftfreq = self.fftfreq()
         if fftfreq is not None:
@@ -319,7 +266,7 @@ class PowerSpectra(BaseSpectra):
             return searchsorted(fftfreq[:-1], self._freqlc)
         return None
 
-    @property_depends_on('_source.sample_freq, block_size, _ind_high, _freqhc')
+    @property_depends_on(['source.sample_freq', 'block_size', '_ind_high', '_freqhc'])
     def _get_ind_high(self):
         fftfreq = self.fftfreq()
         if fftfreq is not None:
@@ -340,19 +287,7 @@ class PowerSpectra(BaseSpectra):
         self._index_set_last = True
         self._ind_low = ind_low
 
-    def _set_time_data(self, time_data):
-        self._source = time_data
-
-    def _set_source(self, source):
-        self._source = source
-
-    def _get_time_data(self):
-        return self._source
-
-    def _get_source(self):
-        return self._source
-
-    @property_depends_on('block_size, ind_low, ind_high')
+    @property_depends_on(['block_size', 'ind_low', 'ind_high'])
     def _get_indices(self):
         fftfreq = self.fftfreq()
         if fftfreq is not None:
@@ -371,9 +306,7 @@ class PowerSpectra(BaseSpectra):
 
     @cached_property
     def _get_basename(self):
-        if 'basename' in self._source.all_trait_names():
-            return self._source.basename
-        return self._source.__class__.__name__ + self._source.digest
+        return find_basename(self.source, alternative_basename=self.source.__class__.__name__ + self.source.digest)
 
     def calc_csm(self):
         """Csm calculation."""
@@ -382,17 +315,10 @@ class PowerSpectra(BaseSpectra):
         weight = dot(wind, wind)
         wind = wind[newaxis, :].swapaxes(0, 1)
         numfreq = int(self.block_size / 2 + 1)
-        csm_shape = (numfreq, t.numchannels, t.numchannels)
+        csm_shape = (numfreq, t.num_channels, t.num_channels)
         csm_upper = zeros(csm_shape, dtype=self.precision)
-        # print "num blocks", self.num_blocks
-        # for backward compatibility
-        if self.calib and self.calib.num_mics > 0:
-            if self.calib.num_mics == t.numchannels:
-                wind = wind * self.calib.data[newaxis, :]
-            else:
-                raise ValueError('Calibration data not compatible: %i, %i' % (self.calib.num_mics, t.numchannels))
         # get time data blockwise
-        for data in self.get_source_data():
+        for data in self._get_source_data():
             ft = fft.rfft(data * wind, None, 0).astype(self.precision)
             calcCSM(csm_upper, ft)  # only upper triangular part of matrix is calculated (for speed reasons)
         # create the full csm matrix via transposing and complex conj.
@@ -424,23 +350,6 @@ class PowerSpectra(BaseSpectra):
         """Calculates eigenvectors of csm."""
         return self.calc_ev()[1]
 
-    def _handle_dual_calibration(self):
-        obj = self.source  # start with time_data obj
-        while obj:
-            if 'calib' in obj.all_trait_names():  # at original source?
-                if obj.calib and self.calib:
-                    if obj.calib.digest == self.calib.digest:
-                        self.calib = None  # ignore it silently
-                    else:
-                        msg = 'Non-identical dual calibration for both TimeSamples and PowerSpectra object'
-                        raise ValueError(msg)
-                obj = None
-            else:
-                try:
-                    obj = obj.source  # traverse down until original data source
-                except AttributeError:
-                    obj = None
-
     def _get_filecache(self, traitname):
         """Function handles result caching of csm, eigenvectors and eigenvalues
         calculation depending on global/local caching behaviour.
@@ -448,7 +357,7 @@ class PowerSpectra(BaseSpectra):
         if traitname == 'csm':
             func = self.calc_csm
             numfreq = int(self.block_size / 2 + 1)
-            shape = (numfreq, self._source.numchannels, self._source.numchannels)
+            shape = (numfreq, self.source.num_channels, self.source.num_channels)
             precision = self.precision
         elif traitname == 'eva':
             func = self.calc_eva
@@ -484,18 +393,17 @@ class PowerSpectra(BaseSpectra):
             self.h5f.flush()
         return ac
 
-    @property_depends_on('digest')
+    @property_depends_on(['digest'])
     def _get_csm(self):
         """Main work is done here:
         Cross spectral matrix is either loaded from cache file or
         calculated and then additionally stored into cache.
         """
-        self._handle_dual_calibration()
         if config.global_caching == 'none' or (config.global_caching == 'individual' and self.cached is False):
             return self.calc_csm()
         return self._get_filecache('csm')
 
-    @property_depends_on('digest')
+    @property_depends_on(['digest'])
     def _get_eva(self):
         """Eigenvalues of cross spectral matrix are either loaded from cache file or
         calculated and then additionally stored into cache.
@@ -504,7 +412,7 @@ class PowerSpectra(BaseSpectra):
             return self.calc_eva()
         return self._get_filecache('eva')
 
-    @property_depends_on('digest')
+    @property_depends_on(['digest'])
     def _get_eve(self):
         """Eigenvectors of cross spectral matrix are either loaded from cache file or
         calculated and then additionally stored into cache.
@@ -551,101 +459,6 @@ class PowerSpectra(BaseSpectra):
         return sum(self.eva[f1:f2], 0)
 
 
-def synthetic(data, freqs, f, num=3):
-    """Returns synthesized frequency band values of spectral data.
-
-    If used with :meth:`Beamformer.result()<acoular.fbeamform.BeamformerBase.result>`
-    and only one frequency band, the output is identical to the result of the intrinsic
-    :meth:`Beamformer.synthetic<acoular.fbeamform.BeamformerBase.synthetic>` method.
-    It can, however, also be used with the
-    :meth:`Beamformer.integrate<acoular.fbeamform.BeamformerBase.integrate>`
-    output and more frequency bands.
-
-    Parameters
-    ----------
-    data : array of floats
-        The spectral data (squared sound pressures in Pa^2) in an array with one value
-        per frequency line.
-        The number of entries must be identical to the number of
-        grid points.
-    freq : array of floats
-        The frequencies that correspon to the input *data* (as yielded by
-        the :meth:`PowerSpectra.fftfreq<acoular.spectra.PowerSpectra.fftfreq>`
-        method).
-    f : float or list of floats
-        Band center frequency/frequencies for which to return the results.
-    num : integer
-        Controls the width of the frequency bands considered; defaults to
-        3 (third-octave band).
-
-        ===  =====================
-        num  frequency band width
-        ===  =====================
-        0    single frequency line
-        1    octave band
-        3    third-octave band
-        n    1/n-octave band
-        ===  =====================
-
-    Returns
-    -------
-    array of floats
-        Synthesized frequency band values of the beamforming result at
-        each grid point (the sum of all values that are contained in the band).
-        Note that the frequency resolution and therefore the bandwidth
-        represented by a single frequency line depends on
-        the :attr:`sampling frequency<acoular.tprocess.SamplesGenerator.sample_freq>`
-        and used :attr:`FFT block size<acoular.spectra.PowerSpectra.block_size>`.
-
-    """
-    if isscalar(f):
-        f = (f,)
-    if num == 0:
-        # single frequency lines
-        res = []
-        for i in f:
-            ind = searchsorted(freqs, i)
-            if ind >= len(freqs):
-                warn(
-                    'Queried frequency (%g Hz) not in resolved frequency range. Returning zeros.' % i,
-                    Warning,
-                    stacklevel=2,
-                )
-                h = zeros_like(data[0])
-            else:
-                if freqs[ind] != i:
-                    warn(
-                        f'Queried frequency ({i:g} Hz) not in set of '
-                        'discrete FFT sample frequencies. '
-                        f'Using frequency {freqs[ind]:g} Hz instead.',
-                        Warning,
-                        stacklevel=2,
-                    )
-                h = data[ind]
-            res += [h]
-    else:
-        # fractional octave bands
-        res = []
-        for i in f:
-            f1 = i * 2.0 ** (-0.5 / num)
-            f2 = i * 2.0 ** (+0.5 / num)
-            ind1 = searchsorted(freqs, f1)
-            ind2 = searchsorted(freqs, f2)
-            if ind1 == ind2:
-                warn(
-                    f'Queried frequency band ({f1:g} to {f2:g} Hz) does not '
-                    'include any discrete FFT sample frequencies. '
-                    'Returning zeros.',
-                    Warning,
-                    stacklevel=2,
-                )
-                h = zeros_like(data[0])
-            else:
-                h = sum(data[ind1:ind2], 0)
-            res += [h]
-    return array(res)
-
-
 class PowerSpectraImport(PowerSpectra):
     """Provides a dummy class for using pre-calculated cross-spectral
     matrices.
@@ -655,27 +468,24 @@ class PowerSpectraImport(PowerSpectra):
     :attr:`csm` attribute. This can be useful when algorithms shall be
     evaluated with existing CSM matrices.
     The frequency or frequencies contained by the CSM must be set via the
-    attr:`frequencies` attribute. The attr:`numchannels` attributes
+    attr:`frequencies` attribute. The attr:`num_channels` attributes
     is determined on the basis of the CSM shape.
     In contrast to the PowerSpectra object, the attributes
-    :attr:`sample_freq`, :attr:`time_data`, :attr:`source`,
-    :attr:`block_size`, :attr:`calib`, :attr:`window`,
+    :attr:`sample_freq`, :attr:`source`, :attr:`block_size`, :attr:`window`,
     :attr:`overlap`, :attr:`cached`, and :attr:`num_blocks`
     have no functionality.
     """
 
     #: The cross spectral matrix,
-    #: (number of frequencies, numchannels, numchannels) array of complex;
+    #: (number of frequencies, num_channels, num_channels) array of complex;
     csm = Property(desc='cross spectral matrix')
 
     #: frequencies included in the cross-spectral matrix in ascending order.
     #: Compound trait that accepts arguments of type list, array, and float
-    frequencies = Trait(None, (CArray, Float), desc='frequencies included in the cross-spectral matrix')
+    frequencies = Union(CArray, Float, desc='frequencies included in the cross-spectral matrix')
 
     #: Number of time data channels
-    numchannels = Property(depends_on=['digest'])
-
-    time_data = Enum(None, desc='PowerSpectraImport cannot consume time data')
+    num_channels = Property(depends_on=['digest'])
 
     source = Enum(None, desc='PowerSpectraImport cannot consume time data')
 
@@ -684,8 +494,6 @@ class PowerSpectraImport(PowerSpectra):
 
     block_size = Enum(None, desc='PowerSpectraImport does not operate on blocks of time data')
 
-    calib = Enum(None, desc='PowerSpectraImport cannot calibrate the time data')
-
     window = Enum(None, desc='PowerSpectraImport does not perform windowing')
 
     overlap = Enum(None, desc='PowerSpectraImport does not consume time data')
@@ -698,17 +506,13 @@ class PowerSpectraImport(PowerSpectra):
     _ind_low = Int(0, desc='index of lowest frequency line')
 
     # Shadow trait, should not be set directly, for internal use.
-    _ind_high = Trait(None, (Int, None), desc='index of highest frequency line')
+    _ind_high = Union(None, Int, desc='index of highest frequency line')
 
     # internal identifier
-    digest = Property(
-        depends_on=[
-            '_csmsum',
-        ],
-    )
+    digest = Property(depends_on=['_csmsum'])
 
     #: Name of the cache file without extension, readonly.
-    basename = Property(depends_on='digest', desc='basename for cache file')
+    basename = Property(depends_on=['digest'], desc='basename for cache file')
 
     # csm shadow trait, only for internal use.
     _csm = CArray()
@@ -723,7 +527,7 @@ class PowerSpectraImport(PowerSpectra):
     def _get_digest(self):
         return digest(self)
 
-    def _get_numchannels(self):
+    def _get_num_channels(self):
         return self.csm.shape[1]
 
     def _get_csm(self):
@@ -731,19 +535,20 @@ class PowerSpectraImport(PowerSpectra):
 
     def _set_csm(self, csm):
         if (len(csm.shape) != 3) or (csm.shape[1] != csm.shape[2]):
-            msg = 'The cross spectral matrix must have the following shape: (number of frequencies, numchannels, numchannels)!'
+            msg = 'The cross spectral matrix must have the following shape: \
+            (number of frequencies, num_channels, num_channels)!'
             raise ValueError(msg)
         self._csmsum = real(self._csm).sum() + (imag(self._csm) ** 2).sum()  # to trigger new digest creation
         self._csm = csm
 
-    @property_depends_on('digest')
+    @property_depends_on(['digest'])
     def _get_eva(self):
         """Eigenvalues of cross spectral matrix are either loaded from cache file or
         calculated and then additionally stored into cache.
         """
         return self.calc_eva()
 
-    @property_depends_on('digest')
+    @property_depends_on(['digest'])
     def _get_eve(self):
         """Eigenvectors of cross spectral matrix are either loaded from cache file or
         calculated and then additionally stored into cache.