acoular 24.5__py3-none-any.whl → 24.10__py3-none-any.whl

acoular/sources.py

@@ -1,7 +1,7 @@
 # ------------------------------------------------------------------------------
 # Copyright (c) Acoular Development Team.
 # ------------------------------------------------------------------------------
-"""Measured multichannel data managment and simulation of acoustic sources.
+"""Measured multichannel data management and simulation of acoustic sources.
 
 .. autosummary::
     :toctree: generated/
@@ -22,6 +22,7 @@
 
 # imports from other packages
 
+import contextlib
 from os import path
 from warnings import warn
 
@@ -50,7 +51,7 @@ from numpy import (
 )
 from numpy import min as npmin
 from numpy.fft import fft, ifft
-from numpy.linalg import norm
+from scipy.linalg import norm
 from scipy.special import sph_harm, spherical_jn, spherical_yn
 from traits.api import (
     Any,
@@ -75,6 +76,8 @@ from traits.api import (
     on_trait_change,
 )
 
+from .base import SamplesGenerator
+
 # acoular imports
 from .calib import Calib
 from .environments import Environment
@@ -82,7 +85,7 @@ from .h5files import H5FileBase, _get_h5file_class
 from .internal import digest, ldigest
 from .microphones import MicGeom
 from .signals import SignalGenerator
-from .tprocess import SamplesGenerator, TimeConvolve
+from .tprocess import TimeConvolve
 from .trajectory import Trajectory
 
 
@@ -104,7 +107,7 @@ def _fill_mic_signal_block(out, signal, rm, ind, blocksize, numchannels, up, pre
     return out
 
 
-def spherical_hn1(n, z, derivativearccos=False):
+def spherical_hn1(n, z):
     """Spherical Hankel Function of the First Kind."""
     return spherical_jn(n, z, derivative=False) + 1j * spherical_yn(n, z, derivative=False)
 
@@ -146,7 +149,7 @@ def get_radiation_angles(direction, mpos, sourceposition):
     return azi, ele
 
 
-def get_modes(lOrder, direction, mpos, sourceposition=None):
+def get_modes(lOrder, direction, mpos, sourceposition=None):  # noqa: N803
     """Returns Spherical Harmonic Radiation Pattern at the Microphones.
 
     Parameters
@@ -170,9 +173,9 @@ def get_modes(lOrder, direction, mpos, sourceposition=None):
     azi, ele = get_radiation_angles(direction, mpos, sourceposition)  # angles between source and mics
     modes = zeros((azi.shape[0], (lOrder + 1) ** 2), dtype=complex128)
     i = 0
-    for l in range(lOrder + 1):
-        for m in range(-l, l + 1):
-            modes[:, i] = sph_harm(m, l, azi, ele)
+    for lidx in range(lOrder + 1):
+        for m in range(-lidx, lidx + 1):
+            modes[:, i] = sph_harm(m, lidx, azi, ele)
             if m < 0:
                 modes[:, i] = modes[:, i].conj() * 1j
             i += 1
@@ -180,12 +183,44 @@ def get_modes(lOrder, direction, mpos, sourceposition=None):
 
 
 class TimeSamples(SamplesGenerator):
-    """Container for time data in `*.h5` format.
-
-    This class loads measured data from h5 files and
-    and provides information about this data.
-    It also serves as an interface where the data can be accessed
-    (e.g. for use in a block chain) via the :meth:`result` generator.
+    """Container for processing time data in `*.h5` or NumPy array format.
+
+    This class loads measured data from HDF5 files and provides information about this data.
+    It also serves as an interface where the data can be accessed (e.g. for use in a block chain) via the
+    :meth:`result` generator.
+
+    Examples
+    --------
+    Data can be loaded from a HDF5 file as follows:
+
+    >>> from acoular import TimeSamples
+    >>> name = <some_h5_file.h5>  # doctest: +SKIP
+    >>> ts = TimeSamples(name=name)  # doctest: +SKIP
+    >>> print(f'number of channels: {ts.numchannels}')  # doctest: +SKIP
+    number of channels: 56 # doctest: +SKIP
+
+    Alternatively, the time data can be specified directly as a numpy array.
+    In this case, the :attr:`data` and :attr:`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 :meth:`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)
+
+    See Also
+    --------
+    acoular.sources.MaskedTimeSamples :
+        Extends the functionality of class :class:`TimeSamples` by enabling the definition of start and stop samples
+        as well as the specification of invalid channels.
     """
 
     #: Full name of the .h5 file with data.
@@ -219,7 +254,9 @@ class TimeSamples(SamplesGenerator):
     _datachecksum = Property()
 
     # internal identifier
-    digest = Property(depends_on=['basename', 'calib.digest', '_datachecksum'])
+    digest = Property(
+        depends_on=['basename', 'calib.digest', '_datachecksum', 'sample_freq', 'numchannels', 'numsamples']
+    )
 
     def _get__datachecksum(self):
         return self.data[0, :].sum()
@@ -233,31 +270,31 @@ class TimeSamples(SamplesGenerator):
         return path.splitext(path.basename(self.name))[0]
 
     @on_trait_change('basename')
-    def load_data(self):
+    def _load_data(self):
         """Open the .h5 file and set attributes."""
         if not path.isfile(self.name):
-            # no file there
-            self.numsamples = 0
-            self.numchannels = 0
             self.sample_freq = 0
             raise OSError('No such file: %s' % self.name)
         if self.h5f is not None:
-            try:
+            with contextlib.suppress(OSError):
                 self.h5f.close()
-            except OSError:
-                pass
         file = _get_h5file_class()
         self.h5f = file(self.name)
-        self.load_timedata()
-        self.load_metadata()
+        self._load_timedata()
+        self._load_metadata()
 
-    def load_timedata(self):
+    @on_trait_change('data')
+    def _load_shapes(self):
+        """Set numchannels and numsamples from data."""
+        if self.data is not None:
+            self.numsamples, self.numchannels = self.data.shape
+
+    def _load_timedata(self):
         """Loads timedata from .h5 file. Only for internal use."""
         self.data = self.h5f.get_data_by_reference('time_data')
         self.sample_freq = self.h5f.get_node_attribute(self.data, 'sample_freq')
-        (self.numsamples, self.numchannels) = self.data.shape
 
-    def load_metadata(self):
+    def _load_metadata(self):
         """Loads metadata from .h5 file. Only for internal use."""
         self.metadata = {}
         if '/metadata' in self.h5f:
@@ -266,15 +303,20 @@ class TimeSamples(SamplesGenerator):
     def result(self, num=128):
         """Python generator that yields the output block-wise.
 
+        Reads the time data either from a HDF5 file or from a numpy array given
+        by :attr:`data` and iteratively returns a block of size `num` samples.
+        Calibrated data is returned if a calibration object is given by :attr:`calib`.
+
         Parameters
         ----------
         num : integer, defaults to 128
             This parameter defines the size of the blocks to be yielded
-            (i.e. the number of samples per block) .
+            (i.e. the number of samples per block).
 
-        Returns
-        -------
-        Samples in blocks of shape (num, numchannels).
+        Yields
+        ------
+        numpy.ndarray
+            Samples in blocks of shape (num, numchannels).
             The last block may be shorter than num.
 
         """
@@ -298,14 +340,40 @@ class TimeSamples(SamplesGenerator):
 
 
 class MaskedTimeSamples(TimeSamples):
-    """Container for time data in `*.h5` format.
-
-    This class loads measured data from h5 files
-    and provides information about this data.
-    It supports storing information about (in)valid samples and (in)valid channels
-    It also serves as an interface where the data can be accessed
-    (e.g. for use in a block chain) via the :meth:`result` generator.
-
+    """Container for processing time data in `*.h5` or NumPy array format.
+
+    This class loads measured data from HDF5 files and provides information about this data.
+    It supports storing information about (in)valid samples and (in)valid channels and allows
+    to specify a start and stop index for the valid samples.
+    It also serves as an interface where the data can be accessed (e.g. for use in a block chain) via the
+    :meth:`result` generator.
+
+    Examples
+    --------
+    Data can be loaded from a HDF5 file and invalid channels can be specified as follows:
+
+    >>> from acoular import MaskedTimeSamples
+    >>> name = <some_h5_file.h5>  # doctest: +SKIP
+    >>> ts = MaskedTimeSamples(name=name, invalid_channels=[0, 1])  # doctest: +SKIP
+    >>> print(f'number of valid channels: {ts.numchannels}')  # doctest: +SKIP
+    number of valid channels: 54 # doctest: +SKIP
+
+    Alternatively, the time data can be specified directly as a numpy array.
+    In this case, the :attr:`data` and :attr:`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 :meth:`result` generator:
+
+    >>> blocksize = 512
+    >>> generator = ts.result(num=blocksize)
+    >>> for block in generator:
+    ...     print(block.shape)
+    (512, 4)
+    (488, 4)
     """
 
     #: Index of the first sample to be considered valid.
@@ -362,26 +430,28 @@ class MaskedTimeSamples(TimeSamples):
         return sli[1] - sli[0]
 
     @on_trait_change('basename')
-    def load_data(self):
+    def _load_data(self):
         # """ open the .h5 file and set attributes
         # """
         if not path.isfile(self.name):
             # no file there
-            self.numsamples_total = 0
-            self.numchannels_total = 0
             self.sample_freq = 0
             raise OSError('No such file: %s' % self.name)
         if self.h5f is not None:
-            try:
+            with contextlib.suppress(OSError):
                 self.h5f.close()
-            except OSError:
-                pass
         file = _get_h5file_class()
         self.h5f = file(self.name)
-        self.load_timedata()
-        self.load_metadata()
+        self._load_timedata()
+        self._load_metadata()
+
+    @on_trait_change('data')
+    def _load_shapes(self):
+        """Set numchannels and numsamples from data."""
+        if self.data is not None:
+            self.numsamples_total, self.numchannels_total = self.data.shape
 
-    def load_timedata(self):
+    def _load_timedata(self):
         """Loads timedata from .h5 file. Only for internal use."""
         self.data = self.h5f.get_data_by_reference('time_data')
         self.sample_freq = self.h5f.get_node_attribute(self.data, 'sample_freq')
@@ -390,15 +460,20 @@ class MaskedTimeSamples(TimeSamples):
     def result(self, num=128):
         """Python generator that yields the output block-wise.
 
+        Reads the time data either from a HDF5 file or from a numpy array given
+        by :attr:`data` and iteratively returns a block of size `num` samples.
+        Calibrated data is returned if a calibration object is given by :attr:`calib`.
+
         Parameters
         ----------
         num : integer, defaults to 128
             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 (num, numchannels).
+        Yields
+        ------
+        numpy.ndarray
+            Samples in blocks of shape (num, numchannels).
             The last block may be shorter than num.
 
         """
@@ -463,7 +538,11 @@ class PointSource(SamplesGenerator):
         return self.mics
 
     def _set_mpos(self, mpos):
-        warn("Deprecated use of 'mpos' trait. ", Warning, stacklevel=2)
+        msg = (
+            "Deprecated use of 'mpos' trait. Use 'mics' trait instead."
+            "The 'mpos' trait will be removed in version 25.01."
+        )
+        warn(msg, DeprecationWarning, stacklevel=2)
         self.mics = mpos
 
     # The speed of sound.
@@ -475,7 +554,8 @@ class PointSource(SamplesGenerator):
         return self.env.c
 
     def _set_c(self, c):
-        warn("Deprecated use of 'c' trait. ", Warning, stacklevel=2)
+        msg = "Deprecated use of 'c' trait. Use 'env' trait instead." "The 'c' trait will be removed in version 25.01."
+        warn(msg, DeprecationWarning, stacklevel=2)
         self.env.c = c
 
     # --- End of backwards compatibility traits --------------------------------------
@@ -588,7 +668,7 @@ class SphericalHarmonicSource(PointSource):
     """
 
     #: Order of spherical harmonic source
-    lOrder = Int(0, desc='Order of spherical harmonic')
+    lOrder = Int(0, desc='Order of spherical harmonic')  # noqa: N815
 
     alpha = CArray(desc='coefficients of the (lOrder,) spherical harmonic mode')
 
@@ -1302,7 +1382,11 @@ class UncorrelatedNoiseSource(SamplesGenerator):
         return self.mics
 
     def _set_mpos(self, mpos):
-        warn("Deprecated use of 'mpos' trait. ", Warning, stacklevel=2)
+        msg = (
+            "Deprecated use of 'mpos' trait. Use 'mics' trait instead."
+            "The 'mpos' trait will be removed in version 25.01."
+        )
+        warn(msg, DeprecationWarning, stacklevel=2)
         self.mics = mpos
 
     # --- End of backwards compatibility traits --------------------------------------
@@ -1391,7 +1475,7 @@ class UncorrelatedNoiseSource(SamplesGenerator):
 class SourceMixer(SamplesGenerator):
     """Mixes the signals from several sources."""
 
-    #: List of :class:`~acoular.tprocess.SamplesGenerator` objects
+    #: List of :class:`~acoular.base.SamplesGenerator` objects
     #: to be mixed.
     sources = List(Instance(SamplesGenerator, ()))
 

acoular/spectra.py

@@ -7,7 +7,6 @@
     :toctree: generated/
 
     BaseSpectra
-    FFTSpectra
     PowerSpectra
     synthetic
     PowerSpectraImport
@@ -33,7 +32,6 @@ from numpy import (
     ones,
     real,
     searchsorted,
-    sqrt,
     sum,
     zeros,
     zeros_like,
@@ -54,13 +52,13 @@ from traits.api import (
     property_depends_on,
 )
 
+from .base import SamplesGenerator
 from .calib import Calib
 from .configuration import config
 from .fastFuncs import calcCSM
 from .h5cache import H5cache
 from .h5files import H5CacheFileBase
 from .internal import digest
-from .tprocess import SamplesGenerator, TimeInOut
 
 
 class BaseSpectra(HasPrivateTraits):
@@ -105,8 +103,8 @@ 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.
+    #: The floating-number-precision of the resulting spectra, corresponding to numpy dtypes.
+    #: Default is 'complex128'.
     precision = Trait('complex128', 'complex64', desc='precision of the fft')
 
     # internal identifier
@@ -130,7 +128,7 @@ 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))
         pos = bs
@@ -146,48 +144,12 @@ 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`,
@@ -206,7 +168,7 @@ class PowerSpectra(BaseSpectra):
     #: 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.
+    #: The :class:`~acoular.base.SamplesGenerator` object that provides the data.
     time_data = Property(
         _source,
         desc='deprecated attribute holding the time data object. Use PowerSpectra.source instead!',
@@ -215,9 +177,11 @@ class PowerSpectra(BaseSpectra):
     #: 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
+    #: **deprecated, will be removed in version 25.01**: use :attr:`~acoular.sources.TimeSamples.calib` property of
     #: :class:`~acoular.sources.TimeSamples` objects
-    calib = Instance(Calib)
+    calib = Property(desc='calibration object (deprecated, will be removed in version 25.01)')
+
+    _calib = Instance(Calib)
 
     # Shadow trait, should not be set directly, for internal use.
     _ind_low = Int(1, desc='index of lowest frequency line')
@@ -292,6 +256,18 @@ class PowerSpectra(BaseSpectra):
     # hdf5 cache file
     h5f = Instance(H5CacheFileBase, transient=True)
 
+    def _get_calib(self):
+        return self._calib
+
+    def _set_calib(self, calib):
+        msg = (
+            "Using 'calib' attribute is deprecated and will be removed in version 25.01. "
+            'use :attr:`~acoular.sources.TimeSamples.calib` property of '
+            ':class:`~acoular.sources.TimeSamples` object instead.'
+        )
+        warn(msg, DeprecationWarning, stacklevel=2)
+        self._calib = calib
+
     @property_depends_on('_source.numsamples, block_size, overlap')
     def _get_num_blocks(self):
         return self.overlap_ * self._source.numsamples / self.block_size - self.overlap_ + 1
@@ -341,6 +317,11 @@ class PowerSpectra(BaseSpectra):
         self._ind_low = ind_low
 
     def _set_time_data(self, time_data):
+        msg = (
+            "Using 'time_data' attribute is deprecated and will be removed in version 25.01. "
+            "Use 'source' attribute instead."
+        )
+        warn(msg, DeprecationWarning, stacklevel=2)
         self._source = time_data
 
     def _set_source(self, source):
@@ -383,7 +364,7 @@ class PowerSpectra(BaseSpectra):
         wind = wind[newaxis, :].swapaxes(0, 1)
         numfreq = int(self.block_size / 2 + 1)
         csm_shape = (numfreq, t.numchannels, t.numchannels)
-        csmUpper = zeros(csm_shape, dtype=self.precision)
+        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:
@@ -392,13 +373,13 @@ class PowerSpectra(BaseSpectra):
             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(csmUpper, ft)  # only upper triangular part of matrix is calculated (for speed reasons)
+            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.
-        csmLower = csmUpper.conj().transpose(0, 2, 1)
-        [fill_diagonal(csmLower[cntFreq, :, :], 0) for cntFreq in range(csmLower.shape[0])]
-        csm = csmLower + csmUpper
+        csm_lower = csm_upper.conj().transpose(0, 2, 1)
+        [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)
 
@@ -594,7 +575,7 @@ def synthetic(data, freqs, f, num=3):
         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>`
+        the :attr:`sampling frequency<acoular.base.SamplesGenerator.sample_freq>`
         and used :attr:`FFT block size<acoular.spectra.PowerSpectra.block_size>`.
 
     """