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

acoular/calib.py

@@ -10,65 +10,115 @@
 """
 
 # imports from other packages
-from os import path
+import xml.dom.minidom
 
-from numpy import array
-from traits.api import CArray, CLong, File, HasPrivateTraits, Property, cached_property, on_trait_change
+from numpy import array, newaxis
+from traits.api import CArray, CInt, File, List, Property, cached_property, on_trait_change
+
+import acoular as ac
+
+from .base import InOut
 
 # acoular imports
+from .deprecation import deprecated_alias
 from .internal import digest
 
 
-class Calib(HasPrivateTraits):
-    """Container for calibration data in `*.xml` format.
-
+@deprecated_alias({'from_file': 'file'})
+class Calib(InOut):
+    """Processing block for handling calibration data in `*.xml` or NumPy format.
+
+    This class implements the application of calibration factors to the data obtained from its
+    :attr:`source`. The calibrated data can be accessed (e.g. for use in a block chain) via the
+    :meth:`result` generator. Depending on the source type, calibration can be performed in the
+    time or frequency domain.
+
+
+    Examples
+    --------
+    Consider calibrating a time signal by specifying the calibration factors in NumPy format.
+    Assume that the following white noise signal is in Volt and the sensitivity of the virtual
+    sensor is 1e-2 V/Pa. Then, the voltage signal can be converted to a calibrated sound
+    pressure signal by multiplying it with a calibration factor of  100 Pa/V.
+
+    >>> import acoular as ac
+    >>> import numpy as np
+    >>>
+    >>> signal = ac.WNoiseGenerator(sample_freq=51200,# doctest: +SKIP
+    >>>                             num_samples=51200,# doctest: +SKIP
+    >>>                             rms=0.01).signal()# doctest: +SKIP
+    >>> ts = ac.TimeSamples(data=signal[:, np.newaxis], sample_freq=51200)  # doctest: +SKIP
+    >>> calib = ac.Calib(source=ts)  # doctest: +SKIP
+    >>> calib.data = np.array([100])  # doctest: +SKIP
+    >>> print(next(calib.result(num=1)))  # doctest: +SKIP
+    [[1.76405235]]
+
+    The calibrated data can then be further processed, e.g. by calculating the FFT of the
+    calibrated data.
+
+    >>> fft = ac.RFFT(source=calib, block_size=16)  # doctest: +SKIP
+    >>> print(next(fft.result(num=1)))  # doctest: +SKIP
+    [[10.63879909+0.j          3.25957562-1.57652611j -2.27342854-3.39108312j
+    0.07458428+0.49657939j  1.772696  +3.92233098j  3.19543248+0.17988554j
+    0.3379041 -3.93342331j  0.93949242+2.5328611j   2.97352574+0.j        ]]
+
+    One could also apply the calibration after the FFT calculation.
+
+    >>> fft = ac.RFFT(source=ts, block_size=16)  # doctest: +SKIP
+    >>> calib = ac.Calib(source=fft)  # doctest: +SKIP
+    >>> calib.data = 100 * np.ones(ts.num_channels * fft.num_freqs)  # doctest: +SKIP
+    >>> print(next(calib.result(num=1)))  # doctest: +SKIP
+    [[10.63879909+0.j          3.25957562-1.57652611j -2.27342854-3.39108312j
+    0.07458428+0.49657939j  1.772696  +3.92233098j  3.19543248+0.17988554j
+    0.3379041 -3.93342331j  0.93949242+2.5328611j   2.97352574+0.j        ]]
+
+    Deprecated and will be removed in Acoular 25.10:
     This class serves as interface to load calibration data for the used
     microphone array. The calibration factors are stored as [Pa/unit].
     """
 
     #: Name of the .xml file to be imported.
-    from_file = File(filter=['*.xml'], desc='name of the xml file to import')
-
-    #: Basename of the .xml-file. Readonly / is set automatically.
-    basename = Property(depends_on='from_file', desc='basename of xml file')
+    file = File(filter=['*.xml'], exists=True, desc='name of the xml file to import')
 
     #: Number of microphones in the calibration data,
-    #: is set automatically / read from file.
-    num_mics = CLong(0, desc='number of microphones in the geometry')
+    #: is set automatically when read from file or when data is set.
+    num_mics = CInt(0, desc='number of microphones in the geometry')
 
     #: Array of calibration factors,
-    #: is set automatically / read from file.
+    #: is set automatically when read from file.
+    #: Can be set manually by specifying a NumPy array with shape (num_channels, ) if
+    #: :attr:`source` yields time domain signals. For frequency domain signals, the expected
+    #: shape is (num_channels * num_freqs).
     data = CArray(desc='calibration data')
 
+    #: Channels that are to be treated as invalid.
+    invalid_channels = List(int, desc='list of invalid channels')
+
+    #: Channel mask to serve as an index for all valid channels, is set automatically.
+    channels = Property(depends_on=['invalid_channels', 'num_mics'], desc='channel mask')
+
     # Internal identifier
-    digest = Property(depends_on=['basename'])
+    digest = Property(depends_on=['source.digest', 'data'])
+
+    @on_trait_change('data')
+    def set_num_mics(self):
+        self.num_mics = self.data.shape[0]
 
     @cached_property
-    def _get_digest(self):
-        return digest(self)
+    def _get_channels(self):
+        if len(self.invalid_channels) == 0:
+            return slice(0, None, None)
+        allr = [i for i in range(self.num_mics) if i not in self.invalid_channels]
+        return array(allr)
 
     @cached_property
-    def _get_basename(self):
-        if not path.isfile(self.from_file):
-            return ''
-        return path.splitext(path.basename(self.from_file))[0]
+    def _get_digest(self):
+        return digest(self)
 
-    @on_trait_change('basename')
+    @on_trait_change('file')
     def import_data(self):
         """Loads the calibration data from `*.xml` file ."""
-        if not path.isfile(self.from_file):
-            # empty calibration
-            if self.basename == '':
-                self.data = None
-                self.num_mics = 0
-            # no file there
-            else:
-                self.data = array([1.0], 'd')
-                self.num_mics = 1
-            return
-        import xml.dom.minidom
-
-        doc = xml.dom.minidom.parse(self.from_file)
+        doc = xml.dom.minidom.parse(self.file)
         names = []
         data = []
         for element in doc.getElementsByTagName('pos'):
@@ -76,3 +126,48 @@ class Calib(HasPrivateTraits):
             data.append(float(element.getAttribute('factor')))
         self.data = array(data, 'd')
         self.num_mics = self.data.shape[0]
+
+    def __validate_data(self):
+        """Validates the calibration data."""
+        if self.data is None:
+            msg = 'No calibration data available.'
+            raise ValueError(msg)
+        if self.source is None:
+            msg = 'No source data available.'
+            raise ValueError(msg)
+        tobj = self.source
+        while isinstance(tobj, ac.InOut):
+            tobj = tobj.source
+        if isinstance(tobj, ac.SamplesGenerator) and (self.data[self.channels].shape[0] != tobj.num_channels):
+            msg = f'calibration data shape {self.data[self.channels].shape[0]} does not match \
+                source data shape {tobj.num_channels}'
+            raise ValueError(msg)
+        if isinstance(tobj, ac.SpectraGenerator) and (
+            self.data[self.channels].shape[0] != tobj.num_channels * tobj.num_freqs
+        ):
+            msg = f'calibration data shape {self.data[self.channels].shape[0]} does not match \
+                source data shape {tobj.num_channels * tobj.num_freqs}'
+            raise ValueError(msg)
+
+    def result(self, num):
+        """Python generator that processes the source data and yields the time-signal block-wise.
+
+        This method needs to be implemented by the derived classes.
+
+        Parameters
+        ----------
+        num : int
+            This parameter defines the size of the blocks to be yielded
+            (i.e. the number of samples per block)
+
+        Yields
+        ------
+        numpy.ndarray
+            Two-dimensional output data block of shape (num, sourcechannels)
+            where sourcechannels is num_channels if the source data is in the time domain
+            or sourcechannels is num_channels*num_freqs if the source data is in the frequency
+            domain.
+        """
+        self.__validate_data()
+        for block in self.source.result(num):
+            yield block * self.data[self.channels][newaxis]

acoular/configuration.py

@@ -15,6 +15,8 @@ import sys
 from os import environ, mkdir, path
 from warnings import warn
 
+# WARNING: DO NOT ADD ANY IMPORTS HERE THAT MIGHT IMPORT NUMPY
+
 # When numpy is using OpenBLAS then it runs with OPENBLAS_NUM_THREADS which may lead to
 # overcommittment when called from within numba jitted function that run on
 # NUMBA_NUM_THREADS. If overcommitted, things get extremely! slow. Therefore we make an
@@ -50,11 +52,11 @@ if 'numpy' in sys.modules:
             stacklevel=2,
         )
 else:
-    # numpy is not loaded
+    # numpy is not loaded, make sure that OpenBLAS runs single threaded
     environ['OPENBLAS_NUM_THREADS'] = '1'
 
 # this loads numpy, so we have to defer loading until OpenBLAS check is done
-from traits.api import Bool, Enum, HasStrictTraits, Property, Str, Trait, cached_property
+from traits.api import Bool, Enum, HasStrictTraits, File, Property, cached_property  # noqa: I001
 
 
 class Config(HasStrictTraits):
@@ -90,11 +92,11 @@ class Config(HasStrictTraits):
     #: * 'overwrite': Acoular classes replace existing cachefile content with new data.
     global_caching = Property()
 
-    _global_caching = Trait('individual', 'all', 'none', 'readonly', 'overwrite')
+    _global_caching = Enum('individual', 'all', 'none', 'readonly', 'overwrite')
 
     #: Flag that globally defines package used to read and write .h5 files
-    #: defaults to 'pytables'. It is also possible to set it to 'tables', which is an alias for 'pytables'.
-    #: If 'pytables' can not be imported, 'h5py' is used.
+    #: defaults to 'pytables'. It is also possible to set it to 'tables', which is an alias for
+    #: 'pytables'. If pytables cannot be imported, 'h5py' is used.
     h5library = Property()
 
     _h5library = Enum('pytables', 'tables', 'h5py')
@@ -104,14 +106,14 @@ class Config(HasStrictTraits):
     #: it will be created. :attr:`cache_dir` defaults to current session path.
     cache_dir = Property()
 
-    _cache_dir = Str('')
+    _cache_dir = File()
 
     #: Defines the working directory containing data files. Used only by
     #: :class:`~acoular.tprocess.WriteH5` class.
     #: Defaults to current session path.
     td_dir = Property()
 
-    _td_dir = Str(path.curdir)
+    _td_dir = File(path.curdir)
 
     #: Boolean Flag that determines whether user has access to traitsui features.
     #: Defaults to False.
@@ -232,8 +234,8 @@ by :attr:`h5library`:
 Some Acoular classes support GUI elements for usage with tools from the TraitsUI package.
 If desired, this package has to be installed manually, as it is not a prerequisite for
 installing Acoular.
-To enable the functionality, the flag attribute :attr:`use_traitsui` has to be set to True (default: False).
-Note: this is independent from the GUI tools implemented in the spectAcoular package.
+To enable the functionality, the flag attribute :attr:`use_traitsui` has to be set to True (default:
+False). Note: this is independent from the GUI tools implemented in the spectAcoular package.
 
 
 Example:

acoular/demo/__init__.py

@@ -11,3 +11,4 @@
 """
 
 from . import acoular_demo
+from .acoular_demo import create_three_sources

acoular/demo/acoular_demo.py

@@ -32,6 +32,29 @@ Source Location        RMS
 """
 
 
+def create_three_sources(mg, h5savefile='three_sources.h5'):
+    """Create three noise sources and return them as Mixer."""
+    import acoular as ac
+
+    # set up the parameters
+
+    sfreq = 51200
+    duration = 1
+    nsamples = duration * sfreq
+
+    n1 = ac.WNoiseGenerator(sample_freq=sfreq, num_samples=nsamples, seed=1)
+    n2 = ac.WNoiseGenerator(sample_freq=sfreq, num_samples=nsamples, seed=2, rms=0.7)
+    n3 = ac.WNoiseGenerator(sample_freq=sfreq, num_samples=nsamples, seed=3, rms=0.5)
+    p1 = ac.PointSource(signal=n1, mics=mg, loc=(-0.1, -0.1, -0.3))
+    p2 = ac.PointSource(signal=n2, mics=mg, loc=(0.15, 0, -0.3))
+    p3 = ac.PointSource(signal=n3, mics=mg, loc=(0, 0.1, -0.3))
+    pa = ac.Mixer(source=p1, sources=[p2, p3])
+    if h5savefile:
+        wh5 = ac.WriteH5(source=pa, file=h5savefile)
+        wh5.save()
+    return pa
+
+
 def run():
     """Run the Acoular demo."""
     from pathlib import Path
@@ -40,30 +63,20 @@ def run():
 
     ac.config.global_caching = 'none'
 
-    # set up the parameters
-    sfreq = 51200
-    duration = 1
-    nsamples = duration * sfreq
+    # set up microphone geometry
+
     micgeofile = Path(ac.__file__).parent / 'xml' / 'array_64.xml'
-    h5savefile = 'three_sources.h5'
+    mg = ac.MicGeom(file=micgeofile)
 
     # generate test data, in real life this would come from an array measurement
-    mg = ac.MicGeom(from_file=micgeofile)
-    n1 = ac.WNoiseGenerator(sample_freq=sfreq, numsamples=nsamples, seed=1)
-    n2 = ac.WNoiseGenerator(sample_freq=sfreq, numsamples=nsamples, seed=2, rms=0.7)
-    n3 = ac.WNoiseGenerator(sample_freq=sfreq, numsamples=nsamples, seed=3, rms=0.5)
-    p1 = ac.PointSource(signal=n1, mics=mg, loc=(-0.1, -0.1, 0.3))
-    p2 = ac.PointSource(signal=n2, mics=mg, loc=(0.15, 0, 0.3))
-    p3 = ac.PointSource(signal=n3, mics=mg, loc=(0, 0.1, 0.3))
-    pa = ac.Mixer(source=p1, sources=[p2, p3])
-    wh5 = ac.WriteH5(source=pa, name=h5savefile)
-    wh5.save()
+
+    pa = create_three_sources(mg)
 
     # analyze the data and generate map
 
     ps = ac.PowerSpectra(source=pa, block_size=128, window='Hanning')
 
-    rg = ac.RectGrid(x_min=-0.2, x_max=0.2, y_min=-0.2, y_max=0.2, z=0.3, increment=0.01)
+    rg = ac.RectGrid(x_min=-0.2, x_max=0.2, y_min=-0.2, y_max=0.2, z=-0.3, increment=0.01)
     st = ac.SteeringVector(grid=rg, mics=mg)
 
     bb = ac.BeamformerBase(freq_data=ps, steer=st)
@@ -71,7 +84,7 @@ def run():
     spl = ac.L_p(pm)
 
     if ac.config.have_matplotlib:
-        from pylab import axis, colorbar, figure, imshow, plot, show
+        from matplotlib.pyplot import axis, colorbar, figure, imshow, plot, show
 
         # show map
         imshow(spl.T, origin='lower', vmin=spl.max() - 10, extent=rg.extend(), interpolation='bicubic')
@@ -79,7 +92,7 @@ def run():
 
         # plot microphone geometry
         figure(2)
-        plot(mg.mpos[0], mg.mpos[1], 'o')
+        plot(mg.pos[0], mg.pos[1], 'o')
         axis('equal')
 
         show()

acoular/deprecation.py

@@ -0,0 +1,85 @@
+# ------------------------------------------------------------------------------
+# Copyright (c) Acoular Development Team.
+# ------------------------------------------------------------------------------
+
+from warnings import warn
+
+from traits.api import Property
+
+
+def deprecated_alias(old2new, read_only=False, removal_version=''):
+    """Decorator function for deprecating renamed class traits.
+    Replaced traits should no longer be part of the class definition
+    and only mentioned in this decorator's parameter list.
+    The replacement trait has to be defined in the updated class and
+    will be mapped to the deprecated name via this function.
+
+    Parameters
+    ----------
+    old2new: dict
+        Dictionary containing the deprecated trait names as keys and
+        their new names as values.
+    read_only: bool or list
+        If True, all deprecated traits will be "read only".
+        If False (default), all deprecated traits can be read and set.
+        If list, traits whose names are in list will be "read only".
+    removal_version: string or dict
+        Adds the acoular version of trait removal to the deprecation message.
+        If a non-empty string, it will be interpreted as the acoular version when
+        all traits in the list will be deprecated.
+        If a dictionary, the keys are expected to be trait names and the values
+        are the removal version as strings.
+    """
+
+    def decorator(cls):
+        """Decorator function that gets applied to the class `cls`."""
+
+        def _alias_accessor_factory(old, new, trait_read_only=False, trait_removal_version=''):
+            """Function to define setter and getter routines for alias property trait."""
+            if trait_removal_version:
+                trait_removal_version = f' (will be removed in version {trait_removal_version})'
+            msg = f"Deprecated use of '{old}' trait{trait_removal_version}. Please use the '{new}' trait instead."
+
+            def getter(cls):
+                warn(msg, DeprecationWarning, stacklevel=2)
+                return getattr(cls, new)
+
+            if trait_read_only:
+                return (getter,)
+
+            def setter(cls, value):
+                warn(msg, DeprecationWarning, stacklevel=2)
+                setattr(cls, new, value)
+
+            return (getter, setter)
+
+        # Add deprecated traits to class traits and link them to
+        # the new ones with a deprecation warning.
+        for old, new in old2new.items():
+            # Set "read only" status depending on global read_only argument
+            current_read_only = (old in read_only) if isinstance(read_only, list) else read_only
+            # If version for trait removal is given, pass info to accessors
+            if isinstance(removal_version, str) and (len(removal_version) > 0):
+                current_removal_version = removal_version
+            elif isinstance(removal_version, dict) and (old in removal_version):
+                current_removal_version = removal_version[old]
+            else:
+                current_removal_version = ''
+            # Define Trait Property type
+            trait_type = Property(*_alias_accessor_factory(old, new, current_read_only, current_removal_version))
+
+            # If the new trait exists, set or update alias
+            if new in cls.class_traits():
+                if old not in cls.class_traits():
+                    cls.add_class_trait(old, trait_type)
+                else:
+                    # Access class dictionary to change trait
+                    cls.__dict__['__class_traits__'][old] = trait_type
+
+            else:
+                error_msg = f"Cannot create trait '{old}' because its replacement trait '{new}' does not exist."
+                raise ValueError(error_msg)
+
+        return cls
+
+    return decorator