Signal Processing (labtoolbox.signals)#

Signal processing functions for LabToolbox.

This submodule provides FFT/IFFT, Fourier series, and envelope extraction utilities for time series data.

labtoolbox.signals.envelope(signal, method='peaks', mode='upper', filter_size=31, fs=1.0, remove_mean=False)[source]#

Compute the envelope of a 1D real-valued signal.

Parameters:

  • signal (array-like) – The input real-valued signal (1D array).

  • method ({'hilbert', 'peaks', 'adaptive'}, optional) –

    The method to compute the envelope:

    • ’hilbert’: Uses the analytic signal via the Hilbert transform (best for bandpass signals).

    • ’peaks’: Interpolates a smooth curve through signal peaks (versatile for general signals).

    • ’adaptive’: Applies a variable-width filter to abs(signal) (robust to noise).

    Defaults to ‘peaks’.

  • mode ({'upper', 'lower', 'both'}, optional) –

    Select which envelope to return:

    • ’upper’: The upper envelope (default).

    • ’lower’: The lower envelope.

    • ’both’: Returns a tuple (upper, lower).

  • filter_size (int, optional) – Size of the smoothing filter for ‘adaptive’ method. Must be odd and positive. Defaults to 31.

  • fs (float, optional) – Sampling frequency in Hz, used for frequency estimation in ‘adaptive’ method. Defaults to 1.0.

  • remove_mean (bool, optional) – If True, removes the signal mean before computing the envelope. Defaults to False.

Returns:

The computed envelope(s):

  • If mode=’upper’ or ‘lower’, returns a 1D array.

  • If mode=’both’, returns a tuple (upper, lower).

Return type:

ndarray or tuple of ndarrays

Notes

  • The ‘hilbert’ method is mathematically rigorous for bandpass signals but may fail for broadband or non-oscillatory signals.

  • The ‘peaks’ method is versatile, interpolating through local maxima/minima, and works well for most signals.

  • The ‘adaptive’ method adjusts filter width based on local signal frequency, ideal for noisy or irregular signals.

labtoolbox.signals.fft(data, t=None, dt=None, oversample=2)[source]#

Compute the Fast Fourier Transform (FFT) of a signal.

For 1D signals, supports both uniformly and non-uniformly sampled data using FFT or Non-Uniform FFT (NUFFT). For 2D signals, supports only uniformly sampled data using 2D FFT applied along rows and columns.

Parameters:

  • data (ndarray) – Input signal as a 1D or 2D NumPy array (real or complex). For 1D, shape (N,). For 2D, shape (N, M).

  • t (ndarray or tuple of ndarray, optional) –

    Time samples:

    • For 1D: 1D array of shape (N,), monotonically increasing.

    • For 2D: Tuple (t1, t2) where t1 and t2 are 1D arrays, monotonically increasing.

    If None, only X is returned unless dt is provided. Defaults to None.

  • dt (float or tuple of float, optional) –

    Time interval(s) for uniform sampling:

    • For 1D: Single float dt_interval.

    • For 2D: Tuple (dt1, dt2) for intervals along axes.

    Ignored if t is provided. Used to calculate frequency bins if t is None. Defaults to None.

  • oversample (int, optional) – Oversampling factor for NUFFT interpolation in non-uniform 1D case. Must be >= 1. Defaults to 2. Ignored for 2D data.

Returns:

  • X (ndarray) – The FFT or NUFFT of the input signal. For 1D, shape (N,). For 2D, shape (N, M). Complex-valued.

  • f (ndarray, optional) – For 1D: Frequency bins, shape (N,). Returned only if t or dt is provided.

  • f1, f2 (ndarray, optional) – For 2D: Frequency bins along axes 0 and 1, shapes (N,) and (M,), respectively. Returned only if t or dt is provided.

Notes

  • For 1D uniform sampling with N ≤ 16, a direct DFT is used. For power-of-2 lengths, the Cooley-Tukey FFT algorithm is used.

  • For 1D non-uniform sampling, a NUFFT algorithm with Gaussian interpolation is used, with O(N log N + M) complexity.

  • For 2D signals, applies 1D FFTs along rows and columns for uniform sampling.

labtoolbox.signals.fourier_series(f, interval, order, num_points=1000, xlabel='x [ux]', ylabel='y [uy]', xscale=0, yscale=0, figsize=(7.68, 5.76))[source]#

Computes the Fourier series approximation of a function f(x)

Parameters:

  • f (callable) – Function to approximate.

  • interval (tuple of float) – The interval (a, b) over which to compute the Fourier series.

  • order (int) – Number of Fourier modes to use in the approximation.

  • num_points (int, optional) – Number of points for plotting. Default is 1000).

  • xlabel (str, optional) – Label for the x-axis.

  • ylabel (str, optional) – Label for the y-axis.

  • xscale (int, optional) – Scaling factor for the x-axis used only for visualization.

  • yscale (int, optional) – Scaling factor for the y-axis used only for visualization.

  • figsize (tuple of float, optional) – Figure size passed to matplotlib. Default is (6.4 * 1.2, 4.8 * 1.2).

Returns:

  • x (array-like) – 1D array representing the uniformly spaced sample points over one period. These are the evaluation points at which both the original function and the Fourier approximation are computed.

  • f_original (array-like) – 1D array representing the values of the original input function evaluated at the sample points x. This is the reference signal used for comparison with the Fourier approximation.

  • f_approx (array-like) – 1D Array containing the values of the truncated Fourier series evaluated at the same sample points x. This is the approximation of f_original using a finite number of harmonics (up to the specified order).

  • a0 (float) – Zeroth Fourier coefficient (mean value component of the function over the period). It corresponds to the constant term of the Fourier series.

  • a_n (array-like) – Array of cosine coefficients (Fourier coefficients of the even part of the function), corresponding to each harmonic up to the specified order (excluding a0).

  • b_n (array-like) – Array of sine coefficients (Fourier coefficients of the odd part of the function), corresponding to each harmonic up to the specified order.

Notes

The values of xscale and yscale affect only the axis scaling in the plot. All parameters are estimated using the original input data as provided.

labtoolbox.signals.ifft(data, freq=None, df=None, oversample=2)[source]#

Compute the Inverse Fast Fourier Transform (IFFT) of a signal.

For 1D signals, supports both uniformly and non-uniformly sampled frequency data using IFFT or Non-Uniform IFFT (NUIFFT). For 2D signals, supports only uniformly sampled data using 2D IFFT applied along rows and columns.

Parameters:

  • data (ndarray) – Input frequency domain signal as a 1D or 2D NumPy array (complex). For 1D, shape (N,). For 2D, shape (N, M).

  • freq (ndarray or tuple of ndarray, optional) –

    Frequency samples:

    • For 1D: 1D array of shape (N,), monotonically increasing.

    • For 2D: Tuple (f1, f2) where f1 (shape (N,)) and f2 (shape (M,)) are 1D arrays, monotonically increasing.

    If None, time bins are returned only if df is provided. Defaults to None.

  • df (float or tuple of float, optional) –

    Frequency spacing(s) for uniform sampling:

    • For 1D: Single float df_interval.

    • For 2D: Tuple (df1, df2) for spacings along axes.

    Ignored if freq is provided. Defaults to None.

  • oversample (int, optional) – Oversampling factor for NUIFFT interpolation in non-uniform 1D case. Must be >= 1. Defaults to 2. Ignored for 2D data.

Returns:

  • x (ndarray) – The IFFT or NUIFFT of the input signal. For 1D, shape (N,). For 2D, shape (N, M). Complex-valued.

  • t (ndarray, optional) – For 1D: Time bins, shape (N,). Returned only if freq or df is provided.

  • t1, t2 (ndarray, optional) – For 2D: Time bins along axes 0 and 1, shapes (N,) and (M,), respectively. Returned only if freq or df is provided.

Notes

  • For 1D uniform sampling with N <= 16, a direct IDFT is used. For power-of-2 lengths, the Cooley-Tukey IFFT algorithm is used.

  • For 1D non-uniform sampling, a NUIFFT algorithm with Gaussian interpolation is used, with O(N log N + M) complexity.

  • For 2D signals, applies 1D IFFTs along rows and columns for uniform sampling.