scipy 1.15.3__cp312-cp312-macosx_14_0_arm64.whl → 1.16.0rc2__cp312-cp312-macosx_14_0_arm64.whl

scipy/signal/_spectral_py.py

@@ -4,10 +4,11 @@ import numpy as np
 import numpy.typing as npt
 from scipy import fft as sp_fft
 from . import _signaltools
+from ._short_time_fft import ShortTimeFFT, FFT_MODE_TYPE
 from .windows import get_window
 from ._arraytools import const_ext, even_ext, odd_ext, zero_ext
 import warnings
-from typing import Literal
+from typing import cast, Literal
 
 
 __all__ = ['periodogram', 'welch', 'lombscargle', 'csd', 'coherence',
@@ -377,8 +378,8 @@ def periodogram(x, fs=1.0, window='boxcar', nfft=None, detrend='constant',
         complex data, a two-sided spectrum is always returned.
     scaling : { 'density', 'spectrum' }, optional
         Selects between computing the power spectral density ('density')
-        where `Pxx` has units of V**2/Hz and computing the squared magnitude
-        spectrum ('spectrum') where `Pxx` has units of V**2, if `x`
+        where `Pxx` has units of V²/Hz and computing the squared magnitude
+        spectrum ('spectrum') where `Pxx` has units of V², if `x`
         is measured in V and `fs` is measured in Hz. Defaults to
         'density'
     axis : int, optional
@@ -399,6 +400,12 @@ def periodogram(x, fs=1.0, window='boxcar', nfft=None, detrend='constant',
 
     Notes
     -----
+    The ratio of the squared magnitude (``scaling='spectrum'``) divided by the spectral
+    power density (``scaling='density'``) is the constant factor of
+    ``sum(abs(window)**2)*fs / abs(sum(window))**2``.
+    If `return_onesided` is ``True``, the values of the negative frequencies are added
+    to values of the corresponding positive ones.
+
     Consult the :ref:`tutorial_SpectralAnalysis` section of the :ref:`user_guide`
     for a discussion of the scalings of the power spectral density and
     the magnitude (squared) spectrum.
@@ -554,6 +561,7 @@ def welch(x, fs=1.0, window='hann', nperseg=None, noverlap=None, nfft=None,
 
     See Also
     --------
+    csd: Cross power spectral density using Welch's method
     periodogram: Simple, optionally modified periodogram
     lombscargle: Lomb-Scargle periodogram for unevenly sampled data
 
@@ -561,12 +569,16 @@ def welch(x, fs=1.0, window='hann', nperseg=None, noverlap=None, nfft=None,
     -----
     An appropriate amount of overlap will depend on the choice of window
     and on your requirements. For the default Hann window an overlap of
-    50% is a reasonable trade off between accurately estimating the
+    50% is a reasonable trade-off between accurately estimating the
     signal power, while not over counting any of the data. Narrower
-    windows may require a larger overlap.
+    windows may require a larger overlap. If `noverlap` is 0, this
+    method is equivalent to Bartlett's method [2]_.
 
-    If `noverlap` is 0, this method is equivalent to Bartlett's method
-    [2]_.
+    The ratio of the squared magnitude (``scaling='spectrum'``) divided by the spectral
+    power density (``scaling='density'``) is the constant factor of
+    ``sum(abs(window)**2)*fs / abs(sum(window))**2``.
+    If `return_onesided` is ``True``, the values of the negative frequencies are added
+    to values of the corresponding positive ones.
 
     Consult the :ref:`tutorial_SpectralAnalysis` section of the :ref:`user_guide`
     for a discussion of the scalings of the power spectral density and
@@ -685,7 +697,8 @@ def csd(x, y, fs=1.0, window='hann', nperseg=None, noverlap=None, nfft=None,
         length of the window.
     noverlap: int, optional
         Number of points to overlap between segments. If `None`,
-        ``noverlap = nperseg // 2``. Defaults to `None`.
+        ``noverlap = nperseg // 2``. Defaults to `None` and may
+        not be greater than `nperseg`.
     nfft : int, optional
         Length of the FFT used, if a zero padded FFT is desired. If
         `None`, the FFT length is `nperseg`. Defaults to `None`.
@@ -739,13 +752,39 @@ def csd(x, y, fs=1.0, window='hann', nperseg=None, noverlap=None, nfft=None,
 
     An appropriate amount of overlap will depend on the choice of window
     and on your requirements. For the default Hann window an overlap of
-    50% is a reasonable trade off between accurately estimating the
+    50% is a reasonable trade-off between accurately estimating the
     signal power, while not over counting any of the data. Narrower
     windows may require a larger overlap.
 
+    The ratio of the cross spectrum (``scaling='spectrum'``) divided by the cross
+    spectral density (``scaling='density'``) is the constant factor of
+    ``sum(abs(window)**2)*fs / abs(sum(window))**2``.
+    If `return_onesided` is ``True``, the values of the negative frequencies are added
+    to values of the corresponding positive ones.
+
     Consult the :ref:`tutorial_SpectralAnalysis` section of the :ref:`user_guide`
     for a discussion of the scalings of a spectral density and an (amplitude) spectrum.
 
+    Welch's method may be interpreted as taking the average over the time slices of a
+    (cross-) spectrogram. Internally, this function utilizes the  `ShortTimeFFT`  to
+    determine the required (cross-) spectrogram. An example below illustrates that it
+    is straightforward to calculate `Pxy` directly with the `ShortTimeFFT`. However,
+    there are some notable differences in the behavior of the `ShortTimeFFT`:
+
+    * There is no direct `ShortTimeFFT` equivalent for the `csd` parameter
+      combination ``return_onesided=True, scaling='density'``, since
+      ``fft_mode='onesided2X'`` requires ``'psd'`` scaling. The is due to `csd`
+      returning the doubled squared magnitude in this case, which does not have a
+      sensible interpretation.
+    * `ShortTimeFFT` uses `float64` / `complex128` internally, which is due to the
+      behavior of the utilized `~scipy.fft` module. Thus, those are the dtypes being
+      returned. The `csd` function casts the return values to `float32` / `complex64`
+      if the input is `float32` / `complex64` as well.
+    * The `csd` function calculates ``np.conj(Sx[q,p]) * Sy[q,p]``, whereas
+      `~ShortTimeFFT.spectrogram` calculates ``Sx[q,p] * np.conj(Sy[q,p])`` where
+      ``Sx[q,p]``, ``Sy[q,p]`` are the STFTs of `x` and `y`. Also, the window
+      positioning is different.
+
     .. versionadded:: 0.16.0
 
     References
@@ -759,17 +798,17 @@ def csd(x, y, fs=1.0, window='hann', nperseg=None, noverlap=None, nfft=None,
 
     Examples
     --------
+    The following example plots the cross power spectral density of two signals with
+    some common features:
+
     >>> import numpy as np
     >>> from scipy import signal
     >>> import matplotlib.pyplot as plt
     >>> rng = np.random.default_rng()
-
-    Generate two test signals with some common features.
-
-    >>> fs = 10e3
-    >>> N = 1e5
-    >>> amp = 20
-    >>> freq = 1234.0
+    ...
+    ... # Generate two test signals with some common features:
+    >>> N, fs = 100_000, 10e3  # number of samples and sampling frequency
+    >>> amp, freq = 20, 1234.0  # amplitude and frequency of utilized sine signal
     >>> noise_power = 0.001 * fs / 2
     >>> time = np.arange(N) / fs
     >>> b, a = signal.butter(2, 0.25, 'low')
@@ -777,40 +816,142 @@ def csd(x, y, fs=1.0, window='hann', nperseg=None, noverlap=None, nfft=None,
     >>> y = signal.lfilter(b, a, x)
     >>> x += amp*np.sin(2*np.pi*freq*time)
     >>> y += rng.normal(scale=0.1*np.sqrt(noise_power), size=time.shape)
+    ...
+    ... # Compute and plot the magnitude of the cross spectral density:
+    >>> nperseg, noverlap, win = 1024, 512, 'hann'
+    >>> f, Pxy = signal.csd(x, y, fs, win, nperseg, noverlap)
+    >>> fig0, ax0 = plt.subplots(tight_layout=True)
+    >>> ax0.set_title(f"CSD ({win.title()}-window, {nperseg=}, {noverlap=})")
+    >>> ax0.set(xlabel="Frequency $f$ in kHz", ylabel="CSD Magnitude in V²/Hz")
+    >>> ax0.semilogy(f/1e3, np.abs(Pxy))
+    >>> ax0.grid()
+    >>> plt.show()
 
-    Compute and plot the magnitude of the cross spectral density.
+    The cross spectral density is calculated by taking the average over the time slices
+    of a spectrogram:
 
-    >>> f, Pxy = signal.csd(x, y, fs, nperseg=1024)
-    >>> plt.semilogy(f, np.abs(Pxy))
-    >>> plt.xlabel('frequency [Hz]')
-    >>> plt.ylabel('CSD [V**2/Hz]')
-    >>> plt.show()
+    >>> SFT = signal.ShortTimeFFT.from_window('hann', fs, nperseg, noverlap,
+    ...                                       scale_to='psd', fft_mode='onesided2X',
+    ...                                       phase_shift=None)
+    >>> Sxy1 = SFT.spectrogram(y, x, detr='constant', k_offset=nperseg//2,
+    ...                        p0=0, p1=(N-noverlap) // SFT.hop)
+    >>> Pxy1 = Sxy1.mean(axis=-1)
+    >>> np.allclose(Pxy, Pxy1)  # same result as with csd()
+    True
 
+    As discussed in the Notes section, the results of using an approach analogous to
+    the code snippet above and the `csd` function may deviate due to implementation
+    details.
+
+    Note that the code snippet above can be easily adapted to determine other
+    statistical properties than the mean value.
     """
-    freqs, _, Pxy = _spectral_helper(x, y, fs, window, nperseg, noverlap,
-                                     nfft, detrend, return_onesided, scaling,
-                                     axis, mode='psd')
+    # The following lines are resembling the behavior of the originally utilized
+    # `_spectral_helper()` function:
+    same_data, axis = y is x, int(axis)
+    x = np.asarray(x)
+
+    if not same_data:
+        y = np.asarray(y)
+        # Check if we can broadcast the outer axes together
+        x_outer, y_outer  = list(x.shape), list(y.shape)
+        x_outer.pop(axis)
+        y_outer.pop(axis)
+        try:
+            outer_shape = np.broadcast_shapes(x_outer, y_outer)
+        except ValueError as e:
+            raise ValueError('x and y cannot be broadcast together.') from e
+        if x.size == 0 or y.size == 0:
+            out_shape = outer_shape + (min([x.shape[axis], y.shape[axis]]),)
+            empty_out = np.moveaxis(np.empty(out_shape), -1, axis)
+            return empty_out, empty_out
+        out_dtype = np.result_type(x, y, np.complex64)
+    else:  # x is y:
+        if x.size == 0:
+            return np.empty(x.shape), np.empty(x.shape)
+        out_dtype = np.result_type(x, np.complex64)
+
+    n = x.shape[axis] if same_data else max(x.shape[axis], y.shape[axis])
+    if isinstance(window, str) or isinstance(window, tuple):
+        nperseg = int(nperseg) if nperseg is not None else 256
+        if nperseg < 1:
+            raise ValueError(f"Parameter {nperseg=} is not a positive integer!")
+        elif n < nperseg:
+            warnings.warn(f"{nperseg=} is greater than signal length max(len(x), " +
+                          f"len(y)) = {n}, using nperseg = {n}", stacklevel=3)
+            nperseg = n
+        win = get_window(window, nperseg)
+    else:
+        win = np.asarray(window)
+        if nperseg is None:
+            nperseg = len(win)
+    if nperseg != len(win):
+        raise ValueError(f"{nperseg=} does not equal {len(win)=}")
+
+    nfft = int(nfft) if nfft is not None else nperseg
+    if nfft < nperseg:
+        raise ValueError(f"{nfft=} must be greater than or equal to {nperseg=}!")
+    noverlap = int(noverlap) if noverlap is not None else nperseg // 2
+    if noverlap >= nperseg:
+        raise ValueError(f"{noverlap=} must be less than {nperseg=}!")
+    if np.iscomplexobj(x) and return_onesided:
+        return_onesided = False
+
+    if x.shape[axis] < y.shape[axis]:  # zero-pad x to shape of y:
+        z_shape = list(y.shape)
+        z_shape[axis] = y.shape[axis] - x.shape[axis]
+        x = np.concatenate((x, np.zeros(z_shape)), axis=axis)
+    elif y.shape[axis] < x.shape[axis]:  # zero-pad y to shape of x:
+        z_shape = list(x.shape)
+        z_shape[axis] = x.shape[axis] - y.shape[axis]
+        y = np.concatenate((y, np.zeros(z_shape)), axis=axis)
+
+    # using cast() to make mypy happy:
+    fft_mode = cast(FFT_MODE_TYPE, 'onesided' if return_onesided else 'twosided')
+    if scaling not in (scales := {'spectrum': 'magnitude', 'density': 'psd'}):
+        raise ValueError(f"Parameter {scaling=} not in {scales}!")
+
+    SFT = ShortTimeFFT(win, nperseg - noverlap, fs, fft_mode=fft_mode, mfft=nfft,
+                       scale_to=scales[scaling], phase_shift=None)
+    # csd() calculates X.conj()*Y instead of X*Y.conj():
+    Pxy = SFT.spectrogram(y, x, detr=None if detrend is False else detrend,
+                          p0=0, p1=(n - noverlap) // SFT.hop, k_offset=nperseg // 2,
+                          axis=axis)
+
+    # Note:
+    # 'onesided2X' scaling of ShortTimeFFT conflicts with the
+    # scaling='spectrum' parameter, since it doubles the squared magnitude,
+    # which in the view of the ShortTimeFFT implementation does not make sense.
+    # Hence, the doubling of the square is implemented here:
+    if return_onesided:
+        f_axis = Pxy.ndim - 1 + axis if axis < 0 else axis
+        Pxy = np.moveaxis(Pxy, f_axis, -1)
+        Pxy[..., 1:-1 if SFT.mfft % 2 == 0 else None] *= 2
+        Pxy = np.moveaxis(Pxy, -1, f_axis)
 
     # Average over windows.
-    if len(Pxy.shape) >= 2 and Pxy.size > 0:
-        if Pxy.shape[-1] > 1:
-            if average == 'median':
-                # np.median must be passed real arrays for the desired result
-                bias = _median_bias(Pxy.shape[-1])
-                if np.iscomplexobj(Pxy):
-                    Pxy = (np.median(np.real(Pxy), axis=-1)
-                           + 1j * np.median(np.imag(Pxy), axis=-1))
-                else:
-                    Pxy = np.median(Pxy, axis=-1)
-                Pxy /= bias
-            elif average == 'mean':
-                Pxy = Pxy.mean(axis=-1)
+    if Pxy.shape[-1] > 1:
+        if average == 'median':
+            # np.median must be passed real arrays for the desired result
+            bias = _median_bias(Pxy.shape[-1])
+            if np.iscomplexobj(Pxy):
+                Pxy = (np.median(np.real(Pxy), axis=-1) +
+                       np.median(np.imag(Pxy), axis=-1) * 1j)
             else:
-                raise ValueError(f'average must be "median" or "mean", got {average}')
+                Pxy = np.median(Pxy, axis=-1)
+            Pxy /= bias
+        elif average == 'mean':
+            Pxy = Pxy.mean(axis=-1)
         else:
-            Pxy = np.reshape(Pxy, Pxy.shape[:-1])
+            raise ValueError(f"Parameter {average=} must be 'median' or 'mean'!")
+    else:
+        Pxy = np.reshape(Pxy, Pxy.shape[:-1])
 
-    return freqs, Pxy
+    # cast output type;
+    Pxy = Pxy.astype(out_dtype)
+    if same_data:
+        Pxy = Pxy.real
+    return SFT.f, Pxy
 
 
 def spectrogram(x, fs=1.0, window=('tukey', .25), nperseg=None, noverlap=None,
@@ -997,7 +1138,26 @@ def spectrogram(x, fs=1.0, window=('tukey', .25), nperseg=None, noverlap=None,
 
 
 def check_COLA(window, nperseg, noverlap, tol=1e-10):
-    r"""Check whether the Constant OverLap Add (COLA) constraint is met.
+    r"""Check whether the Constant OverLap Add (COLA) constraint is met
+    (legacy function).
+
+    .. legacy:: function
+
+        The COLA constraint is equivalent of having a constant dual window, i.e.,
+        ``all(ShortTimeFFT.dual_win == ShortTimeFFT.dual_win[0])``. Hence,
+        `closest_STFT_dual_window` generalizes this function, as the following
+        example shows:
+
+        >>> import numpy as np
+        >>> from scipy.signal import check_COLA, closest_STFT_dual_window, windows
+        ...
+        >>> w, w_rect, hop = windows.hann(12, sym=False), np.ones(12), 6
+        >>> dual_win, alpha = closest_STFT_dual_window(w, hop, w_rect, scaled=True)
+        >>> np.allclose(dual_win/alpha, w_rect, atol=1e-10, rtol=0)
+        True
+        >>> check_COLA(w, len(w), len(w) - hop)  # equivalent legacy function call
+        True
+
 
     Parameters
     ----------
@@ -1023,17 +1183,22 @@ def check_COLA(window, nperseg, noverlap, tol=1e-10):
 
     See Also
     --------
+    closest_STFT_dual_window: Allows determining the closest window meeting the
+                              COLA constraint for a given window
     check_NOLA: Check whether the Nonzero Overlap Add (NOLA) constraint is met
-    stft: Short Time Fourier Transform
-    istft: Inverse Short Time Fourier Transform
+    ShortTimeFFT: Provide short-time Fourier transform and its inverse
+    stft: Short-time Fourier transform (legacy)
+    istft: Inverse Short-time Fourier transform (legacy)
 
     Notes
     -----
-    In order to enable inversion of an STFT via the inverse STFT in
-    `istft`, it is sufficient that the signal windowing obeys the constraint of
+    In order to invert a short-time Fourier transfrom (STFT) with the so-called
+    "overlap-add method", the signal windowing must obey the constraint of
     "Constant OverLap Add" (COLA). This ensures that every point in the input
     data is equally weighted, thereby avoiding aliasing and allowing full
-    reconstruction.
+    reconstruction. Note that the algorithms implemented in `ShortTimeFFT.istft`
+    and in `istft` (legacy) only require that the weaker "nonzero overlap-add"
+    condition (as in `check_NOLA`) is met.
 
     Some examples of windows that satisfy COLA:
         - Rectangular window at overlap of 0, 1/2, 2/3, 3/4, ...
@@ -1802,7 +1967,7 @@ def coherence(x, y, fs=1.0, window='hann', nperseg=None, noverlap=None,
     -----
     An appropriate amount of overlap will depend on the choice of window
     and on your requirements. For the default Hann window an overlap of
-    50% is a reasonable trade off between accurately estimating the
+    50% is a reasonable trade-off between accurately estimating the
     signal power, while not over counting any of the data. Narrower
     windows may require a larger overlap.
 
@@ -1866,6 +2031,11 @@ def _spectral_helper(x, y, fs=1.0, window='hann', nperseg=None, noverlap=None,
                      padded=False):
     """Calculate various forms of windowed FFTs for PSD, CSD, etc.
 
+    .. legacy:: function
+
+        This function is soley used by the legacy functions `spectrogram` and `stft`
+        (which are also in this same source file `scipy/signal/_spectral_py.py`).
+
     This is a helper function that implements the commonality between
     the stft, psd, csd, and spectrogram functions. It is not designed to
     be called externally. The windows are not averaged over; the result
@@ -1910,8 +2080,8 @@ def _spectral_helper(x, y, fs=1.0, window='hann', nperseg=None, noverlap=None,
         complex data, a two-sided spectrum is always returned.
     scaling : { 'density', 'spectrum' }, optional
         Selects between computing the cross spectral density ('density')
-        where `Pxy` has units of V**2/Hz and computing the cross
-        spectrum ('spectrum') where `Pxy` has units of V**2, if `x`
+        where `Pxy` has units of V²/Hz and computing the cross
+        spectrum ('spectrum') where `Pxy` has units of V², if `x`
         and `y` are measured in V and `fs` is measured in Hz.
         Defaults to 'density'
     axis : int, optional
@@ -2160,6 +2330,11 @@ def _fft_helper(x, win, detrend_func, nperseg, noverlap, nfft, sides):
     Calculate windowed FFT, for internal use by
     `scipy.signal._spectral_helper`.
 
+    .. legacy:: function
+
+        This function is solely used by the legacy `_spectral_helper` function,
+        which is located also in this file.
+
     This is a helper function that does the main FFT calculation for
     `_spectral helper`. All input validation is performed there, and the
     data axis is assumed to be the last axis of x. It is not designed to
@@ -2209,6 +2384,11 @@ def _triage_segments(window, nperseg, input_length):
     Parses window and nperseg arguments for spectrogram and _spectral_helper.
     This is a helper function, not meant to be called externally.
 
+    .. legacy:: function
+
+        This function is soley used by the legacy functions `spectrogram` and
+        `_spectral_helper` (which are also in this file).
+
     Parameters
     ----------
     window : string, tuple, or ndarray