acoular 25.7__py3-none-any.whl → 26.1__py3-none-any.whl

acoular/spectra.py

@@ -3,6 +3,12 @@
 # ------------------------------------------------------------------------------
 """Estimation of power spectra and related tools.
 
+.. inheritance-diagram::
+                acoular.spectra
+    :top-classes:
+                acoular.spectra.BaseSpectra
+    :parts: 1
+
 .. autosummary::
     :toctree: generated/
 
@@ -13,26 +19,7 @@
 
 from abc import abstractmethod
 
-from numpy import (
-    arange,
-    array,
-    bartlett,
-    blackman,
-    dot,
-    empty,
-    fill_diagonal,
-    hamming,
-    hanning,
-    imag,
-    linalg,
-    ndarray,
-    newaxis,
-    ones,
-    real,
-    searchsorted,
-    sum,  # noqa A004
-    zeros,
-)
+import numpy as np
 from scipy import fft
 from traits.api import (
     ABCHasStrictTraits,
@@ -53,7 +40,6 @@ from traits.api import (
 # 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
@@ -61,9 +47,6 @@ from .internal import digest
 from .tools.utils import find_basename
 
 
-@deprecated_alias(
-    {'numchannels': 'num_channels', 'time_data': 'source'}, read_only=['numchannels'], removal_version='25.10'
-)
 class BaseSpectra(ABCHasStrictTraits):
     """
     Base class for handling spectral data in Acoular.
@@ -94,9 +77,14 @@ class BaseSpectra(ABCHasStrictTraits):
     #:
     #: - ``'Blackman'``
     window = Map(
-        {'Rectangular': ones, 'Hanning': hanning, 'Hamming': hamming, 'Bartlett': bartlett, 'Blackman': blackman},
+        {
+            'Rectangular': np.ones,
+            'Hanning': np.hanning,
+            'Hamming': np.hamming,
+            'Bartlett': np.bartlett,
+            'Blackman': np.blackman,
+        },
         default_value='Rectangular',
-        desc='type of window for FFT',
     )
 
     #: Overlap factor for FFT block averaging. One of:
@@ -108,7 +96,7 @@ class BaseSpectra(ABCHasStrictTraits):
     #: - ``'75%'``
     #:
     #: - ``'87.5%'``
-    overlap = Map({'None': 1, '50%': 2, '75%': 4, '87.5%': 8}, default_value='None', desc='overlap of FFT blocks')
+    overlap = Map({'None': 1, '50%': 2, '75%': 4, '87.5%': 8}, default_value='None')
 
     #: FFT block size. Must be one of: ``128``, ``256``, ``512``, ``1024``, ... ``65536``.
     #: Default is ``1024``.
@@ -123,11 +111,10 @@ class BaseSpectra(ABCHasStrictTraits):
         16384,
         32768,
         65536,
-        desc='number of samples per FFT block',
     )
 
     #: Precision of the FFT, corresponding to NumPy dtypes. Default is ``'complex128'``.
-    precision = Enum('complex128', 'complex64', desc='precision of the fft')
+    precision = Enum('complex128', 'complex64')
 
     #: A unique identifier for the spectra, based on its properties. (read-only)
     digest = Property(depends_on=['precision', 'block_size', 'window', 'overlap'])
@@ -181,7 +168,7 @@ class BaseSpectra(ABCHasStrictTraits):
     # generator that yields the time data blocks for every channel (with optional overlap)
     def _get_source_data(self):
         bs = self.block_size
-        temp = empty((2 * bs, self.num_channels))
+        temp = np.empty((2 * bs, self.num_channels))
         pos = bs
         posinc = bs / self.overlap_
         for data_block in self.source.result(bs):
@@ -218,19 +205,16 @@ class PowerSpectra(BaseSpectra):
     #: :class:`SamplesGenerator<acoular.base.SamplesGenerator>` or a derived class.
     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 = Union(Int(-1), None, desc='index of highest frequency line')
+    _ind_low = Int(1)
+    _ind_high = Union(Int(-1), None)
 
     #: Index of lowest frequency line to compute. Default is ``1``. Only used by objects that fetch
     #: the CSM. PowerSpectra computes every frequency line.
-    ind_low = Property(_ind_low, desc='index of lowest frequency line')
+    ind_low = Property(_ind_low)
 
     #: Index of highest frequency line to compute. Default is ``-1``
     #: (last possible line for default :attr:`~BaseSpectra.block_size`).
-    ind_high = Property(_ind_high, desc='index of lowest frequency line')
+    ind_high = Property(_ind_high)
 
     # Stores the set lower frequency, for internal use, should not be set directly.
     _freqlc = Float(0)
@@ -244,37 +228,37 @@ class PowerSpectra(BaseSpectra):
     _index_set_last = Bool(True)
 
     #: A flag indicating whether the result should be cached in HDF5 files. Default is ``True``.
-    cached = Bool(True, desc='cached flag')
+    cached = Bool(True)
 
     #: The number of FFT blocks used for averaging. This is derived from the
     #: :attr:`~BaseSpectra.block_size` and :attr:`~BaseSpectra.overlap` parameters. (read-only)
-    num_blocks = Property(desc='overall number of FFT blocks')
+    num_blocks = Property()
 
     #: 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.
-    freq_range = Property(desc='frequency range')
+    freq_range = Property()
     # If set, will overwrite :attr:`_freqlc`  and :attr:`_freqhc` according to the range. The
     # freq_range interval will be the smallest discrete frequency inside the half-open interval
     # [_freqlc, _freqhc[ and the smallest upper frequency outside of the interval.
 
     #: The sequence of frequency indices between :attr:`ind_low` and :attr:`ind_high`. (read-only)
-    indices = Property(desc='index range')
+    indices = Property()
 
     #: The name of the cache file (without the file extension) used for storing results. (read-only)
-    basename = Property(depends_on=['source.digest'], desc='basename for cache file')
+    basename = Property(depends_on=['source.digest'])
 
     #: The cross-spectral matrix, represented as an array of shape ``(n, m, m)`` of complex values
     #: for ``n`` frequencies and ``m`` channels as in :attr:`~BaseSpectra.num_channels`. (read-only)
-    csm = Property(desc='cross spectral matrix')
+    csm = Property()
 
     #: The eigenvalues of the CSM, stored as an array of shape ``(n,)`` of floats for ``n``
     #: frequencies. (read-only)
-    eva = Property(desc='eigenvalues of cross spectral matrix')
+    eva = Property()
 
     #: 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 :attr:`~BaseSpectra.num_channels`.
     #: (read-only)
-    eve = Property(desc='eigenvectors of cross spectral matrix')
+    eve = Property()
 
     #: A unique identifier for the spectra, based on its properties.  (read-only)
     digest = Property(
@@ -293,7 +277,7 @@ class PowerSpectra(BaseSpectra):
         fftfreq = self.fftfreq()
         if fftfreq is not None:
             if self._ind_high is None:
-                return array([fftfreq[self.ind_low], None])
+                return np.array([fftfreq[self.ind_low], None])
             return fftfreq[[self.ind_low, self.ind_high]]
         return None
 
@@ -309,7 +293,7 @@ class PowerSpectra(BaseSpectra):
         if fftfreq is not None:
             if self._index_set_last:
                 return min(self._ind_low, fftfreq.shape[0] - 1)
-            return searchsorted(fftfreq[:-1], self._freqlc)
+            return np.searchsorted(fftfreq[:-1], self._freqlc)
         return 0
 
     @property_depends_on(['source.sample_freq', 'block_size', '_ind_high', '_freqhc'])
@@ -322,7 +306,7 @@ class PowerSpectra(BaseSpectra):
                 return min(self._ind_high, fftfreq.shape[0] - 1)
             if self._freqhc is None:
                 return None
-            return searchsorted(fftfreq[:-1], self._freqhc)
+            return np.searchsorted(fftfreq[:-1], self._freqhc)
         return None
 
     def _set_ind_high(self, ind_high):  # by setting this the user sets the lower index
@@ -338,7 +322,7 @@ class PowerSpectra(BaseSpectra):
         fftfreq = self.fftfreq()
         if fftfreq is not None:
             try:
-                indices = arange(fftfreq.shape[0], dtype=int)
+                indices = np.arange(fftfreq.shape[0], dtype=int)
                 if self.ind_high is None:
                     return indices[self.ind_low :]
                 return indices[self.ind_low : self.ind_high]
@@ -385,18 +369,18 @@ class PowerSpectra(BaseSpectra):
         """
         t = self.source
         wind = self.window_(self.block_size)
-        weight = dot(wind, wind)
-        wind = wind[newaxis, :].swapaxes(0, 1)
+        weight = np.dot(wind, wind)
+        wind = wind[np.newaxis, :].swapaxes(0, 1)
         numfreq = int(self.block_size / 2 + 1)
         csm_shape = (numfreq, t.num_channels, t.num_channels)
-        csm_upper = zeros(csm_shape, dtype=self.precision)
+        csm_upper = np.zeros(csm_shape, dtype=self.precision)
         # get time data blockwise
         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.
         csm_lower = csm_upper.conj().transpose(0, 2, 1)
-        [fill_diagonal(csm_lower[cntFreq, :, :], 0) for cntFreq in range(csm_lower.shape[0])]
+        [np.fill_diagonal(csm_lower[cntFreq, :, :], 0) for cntFreq in range(csm_lower.shape[0])]
         csm = csm_lower + csm_upper
         # onesided spectrum: multiplication by 2.0=sqrt(2)^2
         return csm * (2.0 / self.block_size / weight / self.num_blocks)
@@ -445,10 +429,10 @@ class PowerSpectra(BaseSpectra):
             eva_dtype = 'float32'
         #        csm = self.csm #trigger calculation
         csm_shape = self.csm.shape
-        eva = empty(csm_shape[0:2], dtype=eva_dtype)
-        eve = empty(csm_shape, dtype=self.precision)
+        eva = np.empty(csm_shape[0:2], dtype=eva_dtype)
+        eve = np.empty(csm_shape, dtype=self.precision)
         for i in range(csm_shape[0]):
-            (eva[i], eve[i]) = linalg.eigh(self.csm[i])
+            (eva[i], eve[i]) = np.linalg.eigh(self.csm[i])
         return (eva, eve)
 
     def calc_eva(self):
@@ -605,12 +589,12 @@ class PowerSpectra(BaseSpectra):
         f = self.fftfreq()
         if num == 0:
             # single frequency line
-            return self.eva[searchsorted(f, freq)]
-        f1 = searchsorted(f, freq * 2.0 ** (-0.5 / num))
-        f2 = searchsorted(f, freq * 2.0 ** (0.5 / num))
+            return self.eva[np.searchsorted(f, freq)]
+        f1 = np.searchsorted(f, freq * 2.0 ** (-0.5 / num))
+        f2 = np.searchsorted(f, freq * 2.0 ** (0.5 / num))
         if f1 == f2:
             return self.eva[f1]
-        return sum(self.eva[f1:f2], 0)
+        return np.sum(self.eva[f1:f2], 0)
 
 
 class PowerSpectraImport(PowerSpectra):
@@ -628,50 +612,46 @@ class PowerSpectraImport(PowerSpectra):
 
     #: The cross-spectral matrix stored in an array of shape ``(n, m, m)`` of complex for ``n``
     #: frequencies and ``m`` channels.
-    csm = Property(desc='cross spectral matrix')
+    csm = Property()
 
     #: The frequencies included in the CSM in ascending order. Accepts list, array, or a single
     #: float value.
-    frequencies = Union(None, CArray, Float, desc='frequencies included in the cross-spectral matrix')
+    frequencies = Union(None, CArray, Float)
 
     #: Number of time data channels, inferred from the shape of the CSM.
     num_channels = Property(depends_on=['digest'])
 
     #: :class:`PowerSpectraImport` does not consume time data; source is always ``None``.
-    source = Enum(None, desc='PowerSpectraImport cannot consume time data')
+    source = Enum(None)
 
     #: Sampling frequency of the signal. Default is ``None``
-    sample_freq = Enum(None, desc='sampling frequency')
+    sample_freq = Enum(None)
 
     #: Block size for FFT, non-functional in this class.
-    block_size = Enum(None, desc='PowerSpectraImport does not operate on blocks of time data')
+    block_size = Enum(None)
 
     #: Windowing method, non-functional in this class.
-    window = Enum(None, desc='PowerSpectraImport does not perform windowing')
+    window = Enum(None)
 
     #: Overlap between blocks, non-functional in this class.
-    overlap = Enum(None, desc='PowerSpectraImport does not consume time data')
+    overlap = Enum(None)
 
     #: Caching capability, always disabled.
-    cached = Enum(False, desc='PowerSpectraImport has no caching capabilities')
+    cached = Enum(False)
 
     #: Number of FFT blocks, always ``None``.
-    num_blocks = Enum(None, desc='PowerSpectraImport cannot determine the number of blocks')
-
-    # Shadow trait, should not be set directly, for internal use.
-    _ind_low = Int(0, desc='index of lowest frequency line')
+    num_blocks = Enum(None)
 
-    # Shadow trait, should not be set directly, for internal use.
-    _ind_high = Union(None, Int, desc='index of highest frequency line')
+    _ind_low = Int(0)
+    _ind_high = Union(None, Int)
 
     #: A unique identifier for the spectra, based on its properties. (read-only)
     digest = Property(depends_on=['_csmsum'])
 
     #: Name of the cache file without extension. (read-only)
-    basename = Property(depends_on=['digest'], desc='basename for cache file')
+    basename = Property(depends_on=['digest'])
 
-    # Shadow trait for storing the CSM, for internal use only.
-    _csm = Union(None, CArray(shape=(None, None, None)), desc='cross spectral matrix')
+    _csm = Union(None, CArray(shape=(None, None, None)))
 
     # Checksum for the CSM to trigger digest calculation, for internal use only.
     _csmsum = Float()
@@ -696,7 +676,7 @@ class PowerSpectraImport(PowerSpectra):
                 (number of frequencies, num_channels, num_channels)!'
                 raise ValueError(msg)
             self._csm = csm
-            self._csmsum = real(self._csm).sum() + (imag(self._csm) ** 2).sum()  # to trigger new digest creation
+            self._csmsum = np.real(self._csm).sum() + (np.imag(self._csm) ** 2).sum()  # to trigger new digest creation
 
     @property_depends_on(['digest'])
     def _get_eva(self):
@@ -719,7 +699,7 @@ class PowerSpectraImport(PowerSpectra):
             Array containing the frequencies.
         """
         if isinstance(self.frequencies, float):
-            return array([self.frequencies])
-        if isinstance(self.frequencies, ndarray):
+            return np.array([self.frequencies])
+        if isinstance(self.frequencies, np.ndarray):
             return self.frequencies
         return self.frequencies