acoular 25.1__py3-none-any.whl → 25.3.post1__py3-none-any.whl

acoular/signals.py

@@ -1,7 +1,8 @@
 # ------------------------------------------------------------------------------
 # Copyright (c) Acoular Development Team.
 # ------------------------------------------------------------------------------
-"""Implements signal generators for the simulation of acoustic sources.
+"""
+Implements signal generators for the simulation of acoustic sources.
 
 .. autosummary::
     :toctree: generated/
@@ -14,7 +15,6 @@
     FiltWNoiseGenerator
     SineGenerator
     GenericSignalGenerator
-
 """
 
 # imports from other packages
@@ -45,45 +45,78 @@ from .internal import digest
 
 @deprecated_alias({'numsamples': 'num_samples'})
 class SignalGenerator(ABCHasStrictTraits):
-    """Virtual base class for a simple one-channel signal generator.
+    """
+    ABC for a simple one-channel signal generator.
+
+    This ABC defines the common interface and attributes for all signal generator implementations.
+    It provides a template for generating one-channel signals with specified amplitude,
+    sampling frequency, and duration. Subclasses should implement the core functionality,
+    including signal generation and computation of the internal identifier.
+
+    See Also
+    --------
+    :func:`scipy.signal.resample` : Used for resampling signals in the :meth:`usignal` method.
 
-    Defines the common interface for all SignalGenerator classes. This class
-    may be used as a base for specialized SignalGenerator implementations. It
-    should not be used directly as it contains no real functionality.
+    Notes
+    -----
+    This class should not be instantiated directly. Instead, use a subclass that
+    implements the required methods for signal generation.
     """
 
-    #: Sampling frequency of the signal.
+    #: Sampling frequency of the signal in Hz. Default is ``1.0``.
     sample_freq = Float(1.0, desc='sampling frequency')
 
-    #: Number of samples to generate.
+    #: The number of samples to generate for the signal.
     num_samples = CInt
 
-    # internal identifier
+    #: A unique checksum identifier based on the object properties. (read-only)
     digest = Property(depends_on=['sample_freq', 'num_samples'])
 
     @abstractmethod
     def _get_digest(self):
-        """Returns the internal identifier."""
+        """Return the internal identifier."""
 
     @abstractmethod
     def signal(self):
-        """Deliver the signal."""
+        """
+        Generate and return the signal.
+
+        This method must be implemented by subclasses to provide the generated signal
+        as a 1D array of samples.
+        """
 
     def usignal(self, factor):
-        """Delivers the signal resampled with a multiple of the sampling freq.
+        """
+        Resample the signal at a higher sampling frequency.
 
-        Uses fourier transform method for resampling (from scipy.signal).
+        This method uses Fourier transform-based resampling to deliver the signal at a
+        sampling frequency that is a multiple of the original :attr:`sample_freq`.
+        The resampled signal has a length of ``factor * num_samples``.
 
         Parameters
         ----------
-        factor : integer
-            The factor defines how many times the new sampling frequency is
-            larger than :attr:`sample_freq`.
+        factor : int
+            The resampling factor. Defines how many times larger the new sampling frequency is
+            compared to the original :attr:`sample_freq`.
 
         Returns
         -------
-        array of floats
-            The resulting signal of length `factor` * :attr:`num_samples`.
+        :class:`numpy.ndarray`
+            The resampled signal as a 1D array of floats.
+
+        Notes
+        -----
+        This method relies on the :func:`scipy.signal.resample` function for resampling.
+
+        Examples
+        --------
+        Resample a signal by a factor of 4:
+
+        >>> from acoular import SineGenerator  # Class extending SignalGenerator
+        >>> sg = SineGenerator(sample_freq=100.0, num_samples=1000)
+        >>> resampled_signal = sg.usignal(4)
+        >>> len(resampled_signal)
+        4000
         """
         return resample(self.signal(), factor * self.num_samples)
 
@@ -92,27 +125,33 @@ class PeriodicSignalGenerator(SignalGenerator):
     """
     Abstract base class for periodic signal generators.
 
-    Defines the common interface for all :class:`SignalGenerator`-derived classes with periodic
-    signals. This class may be used as a base for class handling periodic signals that can be
-    characterized by their frequency, phase and amplitude. It should not be used directly as it
-    contains no real functionality.
+    The :class:`PeriodicSignalGenerator` class defines the common interface
+    for all :class:`SignalGenerator`-derived classes with periodic signals.
+    This class may be used as a base for class handling periodic signals
+    that can be characterized by their frequency, phase and amplitude.
+
+    It should not be used directly as it contains no real functionality.
+
+    See Also
+    --------
+    SineGenerator : Generate a sine signal.
     """
 
-    #: Frequency of the signal, float, defaults to 1000.0.
+    #: The frequency of the signal. Default is ``1000.0``.
     freq = Float(1000.0, desc='Frequency')
 
-    #: Phase of the signal (in radians), float, defaults to 0.0.
+    #: The phase of the signal (in radians). Default is ``0.0``.
     phase = Float(0.0, desc='Phase')
 
-    #: Amplitude of the signal. Defaults to 1.0.
+    #: The amplitude of the signal. Default is ``1.0``.
     amplitude = Float(1.0)
 
-    # internal identifier
+    #: Internal identifier based on generator properties. (read-only)
     digest = Property(depends_on=['amplitude', 'num_samples', 'sample_freq', 'freq', 'phase'])
 
     @abstractmethod
     def _get_digest(self):
-        """Returns the internal identifier."""
+        """Return the internal identifier."""
 
     @abstractmethod
     def signal(self):
@@ -120,35 +159,86 @@ class PeriodicSignalGenerator(SignalGenerator):
 
 
 class NoiseGenerator(SignalGenerator):
-    """Abstract base class for noise signal generators.
+    """
+    Abstract base class for noise signal generators.
 
-    Defines the common interface for all :class:`SignalGenerator` classes with noise signals. This
-    class may be used as a base for class handling noise signals that can be characterized by their
-    RMS amplitude. It should not be used directly as it contains no real functionality.
+    The :class:`NoiseGenerator` class defines the common interface for all :class:`SignalGenerator`
+    classes with noise signals. This class may be used as a base for class handling noise signals
+    that can be characterized by their RMS amplitude.
+
+    It should not be used directly as it contains no real functionality.
+
+    See Also
+    --------
+    :class:`acoular.signals.PNoiseGenerator` : For pink noise generation.
+    :class:`acoular.signals.WNoiseGenerator` : For pink white generation.
+    :class:`acoular.sources.UncorrelatedNoiseSource` : For per-channel noise generation.
     """
 
-    #: RMS amplitude of the signal.
+    #: Root mean square (RMS) amplitude of the signal. For a point source,
+    #: this corresponds to the RMS amplitude at a distance of 1 meter. Default is ``1.0``.
     rms = Float(1.0, desc='rms amplitude')
 
-    #: Seed for random number generator, defaults to 0.
+    #: Seed for random number generator. Default is ``0``.
     #: This parameter should be set differently for different instances
     #: to guarantee statistically independent (non-correlated) outputs.
     seed = Int(0, desc='random seed value')
 
-    # internal identifier
+    #: Internal identifier based on generator properties. (read-only)
     digest = Property(depends_on=['rms', 'seed', 'sample_freq', 'num_samples'])
 
     @abstractmethod
     def _get_digest(self):
-        """Returns the internal identifier."""
+        """Return the internal identifier."""
 
     @abstractmethod
     def signal(self):
-        """Deliver the signal."""
+        """Generate and deliver the periodic signal."""
 
 
 class WNoiseGenerator(NoiseGenerator):
-    """White noise signal generator."""
+    """
+    White noise signal generator.
+
+    This class generates white noise signals with a specified
+    :attr:`root mean square (RMS)<SignalGenerator.rms>` amplitude,
+    :attr:`number of samples<SignalGenerator.num_samples>`, and
+    :attr:`sampling frequency<SignalGenerator.sample_freq>`. The white noise is generated using a
+    :obj:`random number generator<numpy.random.RandomState.standard_normal>` initialized with a
+    :attr:`user-defined seed<seed>` for reproducibility.
+
+    See Also
+    --------
+    :obj:`numpy.random.RandomState.standard_normal` :
+        Used here to generate normally distributed noise.
+    :class:`acoular.signals.PNoiseGenerator` : For pink noise generation.
+    :class:`acoular.sources.UncorrelatedNoiseSource` : For per-channel noise generation.
+
+    Examples
+    --------
+    Generate white noise with an RMS amplitude of 1.0 and 0.5:
+
+    >>> from acoular import WNoiseGenerator
+    >>> from numpy import mean
+    >>>
+    >>> # White noise with RMS of 1.0
+    >>> gen1 = WNoiseGenerator(rms=1.0, num_samples=1000, seed=42)
+    >>> signal1 = gen1.signal()
+    >>>
+    >>> # White noise with RMS of 0.5
+    >>> gen2 = WNoiseGenerator(rms=0.5, num_samples=1000, seed=24)
+    >>> signal2 = gen2.signal()
+    >>>
+    >>> mean(signal1) > mean(signal2)
+    np.True_
+
+    Ensure different outputs with different seeds:
+
+    >>> gen1 = WNoiseGenerator(num_samples=3, seed=42)
+    >>> gen2 = WNoiseGenerator(num_samples=3, seed=73)
+    >>> gen1.signal() == gen2.signal()
+    array([False, False, False])
+    """
 
     # internal identifier
     digest = Property(depends_on=['rms', 'seed', 'sample_freq', 'num_samples'])
@@ -158,35 +248,52 @@ class WNoiseGenerator(NoiseGenerator):
         return digest(self)
 
     def signal(self):
-        """Deliver the signal.
+        """
+        Generate and deliver the white noise signal.
+
+        The signal is created using a Gaussian distribution with mean 0 and variance 1,
+        scaled by the :attr:`RMS<SignalGenerator.rms>` amplitude of the object.
 
         Returns
         -------
-        Array of floats
-            The resulting signal as an array of length :attr:`~SignalGenerator.num_samples`.
+        :class:`numpy.ndarray`
+            A 1D array of floats containing the generated white noise signal.
+            The length of the array is equal to :attr:`~SignalGenerator.num_samples`.
         """
         rnd_gen = RandomState(self.seed)
         return self.rms * rnd_gen.standard_normal(self.num_samples)
 
 
 class PNoiseGenerator(NoiseGenerator):
-    """Pink noise signal generator.
+    """
+    Generate pink noise signal.
 
-    Simulation of pink noise is based on the Voss-McCartney algorithm.
-    Ref.:
+    The :class:`PNoiseGenerator` class generates pink noise signals,
+    which exhibit a :math:`1/f` power spectral density. Pink noise is characterized by
+    equal energy per octave, making it useful in various applications such as audio testing,
+    sound synthesis, and environmental noise simulations.
 
-      * S.J. Orfanidis: Signal Processing (2010), pp. 729-733
-      * online discussion: http://www.firstpr.com.au/dsp/pink-noise/
+    The pink noise simulation is based on the Voss-McCartney algorithm, which iteratively adds
+    noise with increasing wavelength to achieve the desired :math:`1/f` characteristic.
 
-    The idea is to iteratively add larger-wavelength noise to get 1/f
-    characteristic.
+    See Also
+    --------
+    :class:`acoular.signals.WNoiseGenerator` : For white noise generation.
+    :class:`acoular.sources.UncorrelatedNoiseSource` : For per-channel noise generation.
+
+    References
+    ----------
+    - S.J. Orfanidis: Signal Processing (2010), pp. 729-733 :cite:`Orfanidis2010`
+    - Online discussion: http://www.firstpr.com.au/dsp/pink-noise/
     """
 
-    #: "Octave depth" -- higher values for 1/f spectrum at low frequencies,
-    #: but longer calculation, defaults to 16.
+    #: "Octave depth" of the pink noise generation. Higher values result in a better approximation
+    #: of the :math:`1/f` spectrum at low frequencies but increase computation time. The  maximum
+    #: allowable value depends on the :attr:`number of samples<SignalGenerator.num_samples>`.
+    #: Default is ``16``.
     depth = Int(16, desc='octave depth')
 
-    # internal identifier
+    #: A unique checksum identifier based on the object properties. (read-only)
     digest = Property(depends_on=['rms', 'seed', 'sample_freq', 'num_samples', 'depth'])
 
     @cached_property
@@ -194,6 +301,27 @@ class PNoiseGenerator(NoiseGenerator):
         return digest(self)
 
     def signal(self):
+        """
+        Generate and deliver the pink noise signal.
+
+        The signal is computed using the Voss-McCartney algorithm, which generates noise
+        with a :math:`1/f` power spectral density. The method ensures that the output has the
+        desired :attr:`RMS<SignalGenerator.rms>` amplitude and spectrum.
+
+        Returns
+        -------
+        :class:`numpy.ndarray`
+            A 1D array of floats containing the generated pink noise signal. The length
+            of the array is equal to :attr:`~SignalGenerator.num_samples`.
+
+        Notes
+        -----
+        - The "depth" parameter controls the number of octaves included in the pink noise
+          simulation. If the specified depth exceeds the maximum possible value based on
+          the number of samples, it is automatically adjusted, and a warning is printed.
+        - The output signal is scaled to have the same overall level as white noise by dividing
+          the result by ``sqrt(depth + 1.5)``.
+        """
         nums = self.num_samples
         depth = self.depth
         # maximum depth depending on number of samples
@@ -215,22 +343,69 @@ class PNoiseGenerator(NoiseGenerator):
 
 
 class FiltWNoiseGenerator(WNoiseGenerator):
-    """Filtered white noise signal following an autoregressive (AR), moving-average
-    (MA) or autoregressive moving-average (ARMA) process.
-
-    The desired frequency response of the filter can be defined by specifying
-    the filter coefficients :attr:`ar` and :attr:`ma`.
-    The RMS value specified via the :attr:`rms` attribute belongs to the white noise
-    signal and differs from the RMS value of the filtered signal.
-    For numerical stability at high orders, the filter is a combination of second order
-    sections (sos).
+    """
+    Generate filtered white noise using an **AR**, **MA**, or **ARMA** process.
+
+        - **AR:** autoregressive (:attr:`ar`)
+        - **MA:** moving-average (:attr:`ma`)
+        - **ARMA:** autoregressive moving-average
+
+    This class extends the :class:`WNoiseGenerator` class to apply a digital filter to white noise,
+    producing a signal with specific characteristics based on the provided filter coefficients.
+    The desired filter is defined using the autoregressive coefficients (:attr:`ar`) and
+    moving-average coefficients (:attr:`ma`).
+
+    The filter is implemented as a series of second-order sections (sos) for numerical stability,
+    especially at high filter orders.
+
+    See Also
+    --------
+    :class:`WNoiseGenerator` : For white noise generation.
+
+    Notes
+    -----
+    - The output signal is adjusted for the group delay introduced by the filter, ensuring
+      proper alignment of the filtered signal.
+    - The RMS value specified in the :attr:`~NoiseGenerator.rms` attribute corresponds to the
+      original white noise signal and not the filtered output.
+
+    Examples
+    --------
+    Generate filtered white noise using :attr:`AR<ar>` and :attr:`MA<ma>` coefficients:
+
+    >>> import acoular as ac
+    >>> import numpy as np
+    >>>
+    >>> # Define AR and MA coefficients
+    >>> ar = np.array([1.0, -0.5])
+    >>> ma = np.array([0.5, 0.5])
+    >>>
+    >>> # Create generator
+    >>> gen = ac.FiltWNoiseGenerator(
+    ...     rms=1.0,
+    ...     seed=42,
+    ...     sample_freq=1000,
+    ...     num_samples=10000,
+    ...     ar=ar,
+    ...     ma=ma,
+    ... )
+    >>>
+    >>> # Generate signal
+    >>> signal = gen.signal()
+    >>> print(signal[:10])  # Print the first 10 samples
+    [0.24835708 0.30340346 0.40641385 1.28856612 1.2887213  0.41021549
+     0.87764567 1.61214661 0.95505348 0.51406957]
     """
 
+    #: A :class:`numpy.ndarray` of autoregressive coefficients (denominator). Default is ``[]``,
+    #: which results in no AR filtering (i.e., all-pole filter is ``[1.0]``).
     ar = CArray(value=array([]), dtype=float, desc='autoregressive coefficients (coefficients of the denominator)')
 
+    #: A :class:`numpy.ndarray` of moving-average coefficients (numerator). Default is ``[]``,
+    #: which results in no MA filtering (i.e., all-zero filter is ``[1.0]``).
     ma = CArray(value=array([]), dtype=float, desc='moving-average coefficients (coefficients of the numerator)')
 
-    # internal identifier
+    #: A unique checksum identifier based on the object properties. (read-only)
     digest = Property(depends_on=['rms', 'seed', 'sample_freq', 'num_samples', 'ar', 'ma'])
 
     @cached_property
@@ -238,17 +413,42 @@ class FiltWNoiseGenerator(WNoiseGenerator):
         return digest(self)
 
     def handle_empty_coefficients(self, coefficients):
+        """
+        Handle empty filter coefficient arrays by returning a default value.
+
+        This method ensures that both the autoregressive (:attr:`ar`) and moving-average
+        (:attr:`ma`) coefficients are non-empty before filtering. If a coefficient array is empty,
+        it is replaced with a default array containing a single value of ``1.0``.
+
+        Parameters
+        ----------
+        coefficients : :class:`numpy.ndarray`
+            Array of filter coefficients to check.
+
+        Returns
+        -------
+        :class:`numpy.ndarray`
+            The original array if it is non-empty, or a default array containing ``[1.0]``
+            if the input array is empty.
+        """
         if coefficients.size == 0:
             return array([1.0])
         return coefficients
 
     def signal(self):
-        """Deliver the signal.
+        """
+        Generate and return the filtered white noise signal.
+
+        This method creates a white noise signal with the specified
+        :attr:`RMS value<NoiseGenerator.rms>` and :attr:`~NoiseGenerator.seed`, then filters it
+        using the autoregressive (:attr:`ar`) and moving-average (:attr:`ma`) coefficients.
+        The filtering process compensates for group delay introduced by the filter.
 
         Returns
         -------
-        Array of floats
-            The resulting signal as an array of length :attr:`~SignalGenerator.num_samples`.
+        :class:`numpy.ndarray` of :class:`floats<float>`
+            An array representing the filtered white noise signal. The length of the returned array
+            is equal to :attr:`the number of samples<SignalGenerator.num_samples>`.
         """
         rnd_gen = RandomState(self.seed)
         ma = self.handle_empty_coefficients(self.ma)
@@ -263,9 +463,68 @@ class FiltWNoiseGenerator(WNoiseGenerator):
 
 
 class SineGenerator(PeriodicSignalGenerator):
-    """Sine signal generator with adjustable amplitude, frequency and phase."""
+    r"""
+    Generate a sine signal.
 
-    # internal identifier
+    The :class:`SineGenerator` class extends the :class:`PeriodicSignalGenerator` class and
+    generates a sinusoidal signal based on specified :attr:`~PeriodicSignalGenerator.amplitude`,
+    :attr:`frequency<PeriodicSignalGenerator.freq>`, and :attr:`~PeriodicSignalGenerator.phase`.
+
+    This generator is commonly used for creating test signals in signal processing, acoustics,
+    and control systems.
+
+    The signal is defined as
+
+    .. math::
+
+        s(t) = A \sin(2 \pi f t + \phi)
+
+    where:
+        - :math:`A` is the amplitude,
+        - :math:`f` is the frequency,
+        - :math:`\phi` is the phase,
+        - :math:`t` is the time (computed from the
+          :attr:`sampling frequency<SignalGenerator.sample_freq>` and the
+          :attr:`number of samples<SignalGenerator.num_samples>`).
+
+    See Also
+    --------
+    PeriodicSignalGenerator : Base class for periodic signal generators.
+
+    Examples
+    --------
+    Generate a sine wave signal:
+
+    >>> import acoular as ac
+    >>>
+    >>> gen = ac.SineGenerator(
+    ...     amplitude=2.0,
+    ...     freq=50.0,
+    ...     phase=0.0,
+    ...     num_samples=1000,
+    ...     sample_freq=1000,
+    ... )
+    >>> signal = gen.signal()
+    >>> signal[:5]  # The first 5 samples
+    array([0.        , 0.61803399, 1.1755705 , 1.61803399, 1.90211303])
+
+    Generate a sine wave with a phase shift (arguably a cosine wave):
+
+    >>> import numpy as np
+    >>>
+    >>> gen = ac.SineGenerator(
+    ...     amplitude=1.0,
+    ...     freq=100.0,
+    ...     phase=np.pi / 2,
+    ...     num_samples=500,
+    ...     sample_freq=2000,
+    ... )
+    >>> signal = gen.signal()
+    >>> signal[:5]  # The first 5 samples
+    array([1.        , 0.95105652, 0.80901699, 0.58778525, 0.30901699])
+    """
+
+    #: A unique checksum identifier based on the object properties. (read-only)
     digest = Property(depends_on=['num_samples', 'sample_freq', 'amplitude', 'freq', 'phase'])
 
     @cached_property
@@ -273,12 +532,25 @@ class SineGenerator(PeriodicSignalGenerator):
         return digest(self)
 
     def signal(self):
-        """Deliver the signal.
+        r"""
+        Generate and return the sine wave signal.
+
+        The method computes the sine wave based on the specified
+        :attr:`~PeriodicSignalGenerator.amplitude`, :attr:`frequency<PeriodicSignalGenerator.freq>`,
+        and :attr:`~PeriodicSignalGenerator.phase`. The time values are determined by the
+        :attr:`sampling frequency<SignalGenerator.sample_freq>` and the
+        :attr:`number of samples<SignalGenerator.num_samples>`.
 
         Returns
         -------
-        array of floats
-            The resulting signal as an array of length :attr:`~SignalGenerator.num_samples`.
+        :class:`numpy.ndarray` of :class:`floats<float>`
+            A 1D array representing the sine wave signal.
+            The length of the array is equal to :attr:`~SignalGenerator.num_samples`.
+
+        Notes
+        -----
+        The generator supports high-frequency and high-resolution signals,
+        limited by the Nyquist criterion.
         """
         t = arange(self.num_samples, dtype=float) / self.sample_freq
         return self.amplitude * sin(2 * pi * self.freq * t + self.phase)
@@ -286,33 +558,51 @@ class SineGenerator(PeriodicSignalGenerator):
 
 @deprecated_alias({'rms': 'amplitude'})
 class GenericSignalGenerator(SignalGenerator):
-    """Generate signal from output of :class:`~acoular.base.SamplesGenerator` object.
+    """
+    Generate signals from a :class:`~acoular.base.SamplesGenerator` or derived object.
+
+    The :class:`GenericSignalGenerator` class enables the integration of arbitrary signals into
+    Acoular processing chains. The signal is fetched from a specified data source and optionally
+    scaled by an amplitude factor. It supports looping the signal to match the desired number of
+    samples and can handle signals with multiple channels (only the first channel is used).
 
-    This class can be used to inject arbitrary signals into Acoular processing
-    chains. For example, it can be used to read signals from a HDF5 file or create any signal
-    by using the :class:`acoular.sources.TimeSamples` class.
+    Common use cases include:
+        - Injecting custom or pre-recorded signals from HDF5 files.
+        - Creating signals using the :class:`~acoular.sources.TimeSamples` class.
+        - Generating a continuous or repeated signal for simulations.
 
-    Example
-    -------
+    Notes
+    -----
+    If the signal source has more than one channel, only channel 0 is used.
+
+    Examples
+    --------
+    Inject a random signal into a processing chain:
+
+    >>> import acoular as ac
     >>> import numpy as np
-    >>> from acoular import TimeSamples, GenericSignalGenerator
+    >>>
     >>> data = np.random.rand(1000, 1)
-    >>> ts = TimeSamples(data=data, sample_freq=51200)
-    >>> sig = GenericSignalGenerator(source=ts)
+    >>> ts = ac.TimeSamples(data=data, sample_freq=51200)
+    >>> sig = ac.GenericSignalGenerator(source=ts)
+    >>> output_signal = sig.signal()
     """
 
-    #: Data source; :class:`~acoular.base.SamplesGenerator` or derived object.
+    #: The data source from which the signal is fetched.
+    #: This can be any object derived from :class:`SamplesGenerator`.
     source = Instance(SamplesGenerator)
 
-    #: Amplitude of the signal. Defaults to 1.0.
+    #: Scaling factor applied to the generated signal. Defaults to ``1.0``.
     amplitude = Float(1.0)
 
-    #: Sampling frequency of output signal, as given by :attr:`source`.
+    #: Sampling frequency of the output signal, as provided by the :attr:`source` object.
     sample_freq = Delegate('source')
 
     _num_samples = CInt(0)
 
-    #: Number of samples to generate. Is set to source.num_samples by default.
+    #: The number of samples to generate. Default is the number of samples available in the
+    #: :attr:`source` (``source.num_samples``). If set explicitly, it can exceed the source length,
+    #: in which case the signal will loop if :attr:`loop_signal` is ``True``.
     num_samples = Property()
 
     def _get_num_samples(self):
@@ -323,11 +613,11 @@ class GenericSignalGenerator(SignalGenerator):
     def _set_num_samples(self, num_samples):
         self._num_samples = num_samples
 
-    #: Boolean flag, if 'True' (default), signal track is repeated if requested
-    #: :attr:`num_samples` is higher than available sample number
+    #: If ``True`` (default), the signal is repeated to meet the requested :attr:`num_samples`.
+    #: If ``False``, the signal stops once the source data is exhausted.
     loop_signal = Bool(True)
 
-    # internal identifier
+    #: A unique checksum identifier based on the object properties. (read-only)
     digest = Property(
         depends_on=['source.digest', 'loop_signal', 'num_samples', 'amplitude'],
     )
@@ -337,13 +627,18 @@ class GenericSignalGenerator(SignalGenerator):
         return digest(self)
 
     def signal(self):
-        """Deliver the signal.
+        """
+        Deliver the signal from the specified source.
 
         Returns
         -------
-        array of floats
-            The resulting signal as an array of length :attr:`~GenericSignalGenerator.num_samples`.
+        :class:`numpy.array` of :class:`floats<float>`
+            The resulting signal, scaled by the :attr:`amplitude` attribute, with a length
+            matching :attr:`~GenericSignalGenerator.num_samples`.
 
+        Warnings
+        --------
+        A warning is raised if the source has more than one channel.
         """
         block = 1024
         if self.source.num_channels > 1: