utils module

SignalForge.utils.alpha_spec_index(fpsd: ndarray, psd: ndarray, order: int, deriv_order: int)[source]

Compute the spectral index (alpha) of a process.

Parameters:

  • fpsd (np.ndarray) – Frequency vector.

  • psd (np.ndarray) – Power spectral density.

  • order (int) – Order of the moment.

  • deriv_order (int) – Derivative order.

Returns:

Spectral index.

Return type:

float

SignalForge.utils.fast_kurtogram(x: ndarray, fs: float, nlevel=7)[source]

Fast Kurtogram computation

Parameters:

  • x (np.ndarray) – input signal (1D array)

  • nlevel (int) – number of decomposition levels (Maximum number of decomposition levels is log2(length(x)), but it is recommended to stay by a factor 1/8 below this.)

  • fs (float) – sampling frequency of signal x (default is Fs = 1)

Returns:

  • Kwav (np.ndarray) – 2D ndarray of shape (2 * nlevel, 3 * 2**nlevel) Kurtosis map (Fast Kurtogram). Each entry Kwav[i, j] is the envelope kurtosis of the sub-band corresponding to level Level_w[i] and center frequency freq_w[j].

  • Level_w (np.ndarray) – 1D ndarray of length 2 * nlevel Effective decomposition levels associated with each row of Kwav. It contains both binary and ternary levels, ordered as in the original MATLAB implementation (top row = level 0).

  • freq_w (np.ndarray) – 1D ndarray of length 3 * 2**nlevel Center frequencies [Hz] of each sub-band along the horizontal axis (columns) of Kwav.

  • fc (float) – Optimal center frequency [Hz] corresponding to the maximum kurtosis in Kwav (i.e. frequency of the most impulsive band).

  • bandwidth (float) – Bandwidth [Hz] of the optimal sub-band associated with fc.

  • max_kurt (float) – Maximum kurtosis value found in Kwav.

  • level_max (float) – Effective decomposition level (in Level_w) at which the maximum kurtosis max_kurt occurs.

  • c (np.ndarray) – Signal filtered in the optimal sub-band (center frequency fc and bandwidth bandwidth). This is the band-limited signal typically used for further analysis (e.g., envelope analysis and envelope spectrum for fault detection).

Source

  1. Antoni, Fast Computation of the Kurtogram for the Detection of Transient Faults, Mechanical Systems and Signal Processing, Volume 21, Issue 1, 2007, pp.108-124.

SignalForge.utils.gaussian_bell(grid: ndarray, var: float, mean: float = 0)[source]

Evaluate a Gaussian distribution over a grid.

Parameters:

  • grid (np.ndarray) – Input grid.

  • var (float) – Variance.

  • mean (float, optional) – Mean. Default is 0.

Returns:

Evaluated Gaussian PDF values.

Return type:

np.ndarray

Source: Squires, G. L. (2001-08-30). Practical Physics (4 ed.). Cambridge University Press. doi:10.1017/cbo9781139164498. ISBN 978-0-521-77940-1.

SignalForge.utils.get_adf_index(signal: ndarray, maxlag: int = None, regression: str = 'c', autolag: str = 'AIC', *args, **kwargs)[source]

Augmented Dickey-Fuller unit root test from the statsmodels package.

The Augmented Dickey-Fuller test can be used to test for a unit root in a univariate process in the presence of serial correlation.

For the complete documentation please refer to: https://www.statsmodels.org/stable/generated/statsmodels.tsa.stattools.adfuller.html#statsmodels.tsa.stattools.adfuller

Parameters:

  • signal (array_like, 1d) – The data series to test.

  • maxlag ({None, int}) – Maximum lag which is included in test, default value of 12*(nobs/100)^{1/4} is used when None.

  • regression ({"c","ct","ctt","n"}) –

    Constant and trend order to include in regression.

    • ”c” : constant only (default).

    • ”ct” : constant and trend.

    • ”ctt” : constant, and linear and quadratic trend.

    • ”n” : no constant, no trend.

  • autolag ({"AIC", "BIC", "t-stat", None}) –

    Method to use when automatically determining the lag length among the values 0, 1, …, maxlag.

    • If “AIC” (default) or “BIC”, then the number of lags is chosen to minimize the corresponding information criterion.

    • ”t-stat” based choice of maxlag. Starts with maxlag and drops a lag until the t-statistic on the last lag length is significant using a 5%-sized test.

    • If None, then the number of included lags is set to maxlag.

  • *args (optional) – Additional arguments for the method

  • **kwargs (optional) – Additional arguments for the method

Returns:

  • test_results (dict) – Dictionary containing the non-stationarity test results: ‘outcome’, ‘test’, ‘p-value’, ‘lag’, ‘crit_values’

  • Source

  • ——

  • Dickey, D. A., and W. A. Fuller. “Distribution of the Estimators for Autoregressive Time Series with a Unit Root.” Journal of the American Statistical Association. Vol. 74, 1979, pp. 427–431.

SignalForge.utils.get_banded_spectral_kurtosis(signal: ndarray, dt: float, n_bins: int = 10, fl: int = 0, fu: int = 0)[source]

Compute spectral kurtosis in frequency bands.

Parameters:

  • signal (np.ndarray) – Input time history.

  • dt (float) – Sampling interval.

  • n_bins (int) – Number of frequency bands.

  • fl (float) – Lower frequency limit.

  • fu (float) – Upper frequency limit (default is Nyquist).

Returns:

(center frequencies, spectral kurtosis values)

Return type:

tuple

SignalForge.utils.get_hilbert(x: ndarray, *args, **kwargs)[source]

Compute the analytic signal using the Hilbert transform.

Parameters:

  • x (np.ndarray) – Input signal.

  • *args (optional) – Additional arguments passed to scipy.signal.hilbert.

  • **kwargs (optional) – Additional arguments passed to scipy.signal.hilbert.

Returns:

  • analytic_signal (np.ndarray) – Complex-valued analytic signal.

  • amplitude_envelope (np.ndarray) – Instantaneous amplitude (envelope) of the signal.

  • instantaneous_phase (np.ndarray) – Unwrapped instantaneous phase of the signal.

SignalForge.utils.get_kpss_index(signal: ndarray, regression: str = 'c', nlags: str | int = 'auto', *args, **kwargs)[source]

Kwiatkowski-Phillips-Schmidt-Shin test for stationarity.

Computes the Kwiatkowski-Phillips-Schmidt-Shin (KPSS) test for the null hypothesis that x is level or trend stationary.

For the complete documentation please refer to: https://www.statsmodels.org/stable/generated/statsmodels.tsa.stattools.kpss.html#statsmodels.tsa.stattools.kpss

Parameters:

  • signal (array_like, 1d) – The data series to test.

  • regression (str{"c", "ct"}) –

    The null hypothesis for the KPSS test.

    • ”c” : The data is stationary around a constant (default).

    • ”ct” : The data is stationary around a trend.

  • nlags ({str, int}, optional) – Indicates the number of lags to be used. If “auto” (default), lags is calculated using the data-dependent method of Hobijn et al. (1998). See also Andrews (1991), Newey & West (1994), and Schwert (1989). If set to “legacy”, uses int(12 * (n / 100)**(1 / 4)) , as outlined in Schwert (1989).

  • *args (optional) – Additional arguments for the method

  • **kwargs (optional) – Additional arguments for the method

Returns:

  • test_results (dict) – Dictionary containing the non-stationarity test results: ‘outcome’, ‘test’, ‘p-value’, ‘lag’, ‘crit_values’

  • Source

  • ——

  • Kwiatkowski, D., Phillips, P. C. B., Schmidt, P., Shin, Y. (1992). “Testing the null hypothesis of stationarity against the alternative of a unit root”. Journal of Econometrics. 54 (1–3) (159–178. doi:10.1016/0304-4076(92)90104-Y.)

SignalForge.utils.get_nnst_index(signal: ndarray, nperseg=100, noverlap=0, *args, **kwargs)[source]

Non-stationarity index identification using modified run-test. Standard deviation of entire signal is compared to standard deviation of segmented signal, and the number of variations (i.e., runs) is compared to expected value of variations to obtain the non-stationarity index.

For the complete documentation please refer to: https://github.com/LolloCappo/pyNNST

Parameters:

  • signal (array-like) – One dimensional time history

  • nperseg (int) – Length of each segment

  • noverlap (int, optional) – Number of points to overlap between segments. If None, “noverlap = 0”. Defaults to None.

  • confidence (int, optional) – Confidence interval [90-95-98-99] %. If None, “confidence = 95”. Defaults to None.

  • *args (optional) – Additional arguments for the method

  • **kwargs (optional) – Additional arguments for the method

Returns:

  • test_results (dict) – Results of the non-stationary test

  • Source

  • ——

  • L. Capponi, M. Česnik, J. Slavič, F. Cianetti, e M. Boltežar, «Non-stationarity index in vibration fatigue (Theoretical and experimental research», Int. J. Fatigue, vol. 104, pp. 221–230, nov. 2017, doi: 10.1016/j.ijfatigue.2017.07.020.)

SignalForge.utils.get_psd_impulse_response(fpsd: ndarray, psd: ndarray, N: int, fs: int = None)[source]

Compute an impulse response from a target PSD.

Parameters:

  • fpsd – asarrsay Frequency vector.

  • psd (np.ndarray) – PSD values.

  • N (int) – Number of samples in the impulse response.

Returns:

Time-domain impulse response.

Return type:

np.ndarray

SignalForge.utils.get_stat_history(signal: ndarray, winsize: int, olap: int = 0, idx_type='rms')[source]

Compute a statistical index over a moving window.

Parameters:

  • signal – np.ndarray Time history signal.

  • winsize – int: Window size.

  • olap – int, optional The number of points to overlap on the moving window. If not specified, no overlap is considered

  • idx_type – str Index type: ‘mean’, ‘rms’, ‘var’, or ‘kurtosis’.

Returns:

np.ndarray

Evolution of the statistical index over time.

Return type:

stat_history

SignalForge.utils.get_stat_mom(var: ndarray, probability: ndarray, order: int)[source]

Compute statistical moment of a given order from a PDF.

Parameters:

  • var (np.ndarray) – Grid of variable values.

  • probability (np.ndarray) – PDF values corresponding to var.

  • order (int) – Moment order.

Returns:

Statistical moment of the given order.

Return type:

float

SignalForge.utils.get_stationary_gaussian(fpsd: ndarray, psd: ndarray, T: float, fs: float = None, seed=None, interp: str = 'lin')[source]

Generate a stationary Gaussian signal with a target PSD.

Parameters:

  • fpsd (np.ndarray) – Frequency vector.

  • psd (np.ndarray) – Power spectral density values.

  • T (float) – Duration [s].

  • seed (int, optional) – Random seed for reproducibility.

Returns:

(time vector, generated signal)

Return type:

tuple

Source: D. E. Newland, An introduction to random vibrations, spectral & wavelet analysis, 3. ed., Unabridged republ. Mineola, NY: Dover Publ, 2005

SignalForge.utils.get_welch_spectral_kurtosis(x: ndarray, Nfft: int, noverlap: int = None)[source]

Compute Welch-based spectral kurtosis.

Parameters:

  • x (np.ndarray) – Input signal.

  • Nfft (int) – FFT size.

  • noverlap (int) – Number of overlapping samples.

Returns:

(normalized frequency vector, spectral kurtosis)

Return type:

tuple

Source: J. Antoni, «The spectral kurtosis: a useful tool for characterising non-stationary signals», Mech. Syst. Signal Process., vol. 20, fasc. 2, pp. 282–307, feb. 2006, doi: 10.1016/j.ymssp.2004.09.001.

SignalForge.utils.lin_interp_psd(fpsd: ndarray, psd: ndarray, n_points: int, fs: float = None)[source]

Linear interpolation of a PSD to a uniformly spaced frequency grid.

Parameters:

  • fpsd (array-like) – Original frequency vector.

  • psd (array-like) – Original PSD values.

  • n_points (int) – Number of points in the interpolated frequency vector.

Returns:

(interpolated frequency vector, interpolated PSD)

Return type:

tuple

SignalForge.utils.log_interp_psd(fpsd: ndarray, psd: ndarray, n_points: int, fs: float = None)[source]

Log-log interpolation of a PSD to a uniformly spaced frequency grid.

Parameters:

  • fpsd (array-like) – Original frequency vector.

  • psd (array-like) – Original PSD values.

  • n_points (int) – Number of points in the interpolated frequency vector.

Returns:

(interpolated frequency vector, interpolated PSD)

Return type:

tuple

SignalForge.utils.method_existance_check(method: str, methods: dict)[source]

Check if a method is in a dictionary of available options.

Parameters:

  • method (str) – The method name to check.

  • methods (dict) – A dictionary of available methods.

Raises:

KeyError – If method is not in the dictionary keys.

SignalForge.utils.perfect_passband_filter(signal: ndarray, fl_n: float, fu_n: float)[source]

Applies a perfect passband filter to the signal in the frequency domain.

This function filters the input signal by setting all frequency components outside the specified normalized frequency band (fl_n to fu_n) to zero.

Parameters:

  • signal (np.ndarray) – The input time-history signal.

  • fl_n (float) – Lower normalized frequency limit (0 to 0.5, where 0.5 is Nyquist).

  • fu_n (float) – Upper normalized frequency limit (0 to 0.5, where 0.5 is Nyquist).

Returns:

The filtered signal in the time domain.

Return type:

np.ndarray

SignalForge.utils.print_nonstat_results(ns_test: dict, indent: int = 0)[source]

Recursively prints the results of a non-stationarity test.

Parameters:

  • ns_test (dict) – A dictionary containing the non-stationarity test results. Can contain nested dictionaries.

  • indent (int, optional) – The current indentation level for pretty printing. Default is 0.

SignalForge.utils.step_interp(x: ndarray, xp: ndarray, yp: ndarray)[source]

Step interpolation of yp over xp, evaluated at x.

Parameters:

  • x (array-like) – Points at which to evaluate the interpolated values.

  • xp (array-like) – Known x-coordinates of data points.

  • yp (array-like) – Known y-values at each xp.

Returns:

Interpolated values at x.

Return type:

np.ndarray