Home

API Reference

benchmark_methods

openconmo.benchmark_methods.DRS(signal, N, Delta)

Discrete/Random Separation (DRS) to remove deterministic components.

This method separates a signal into deterministic and random parts by constructing a frequency-domain filter based on delayed cross-power spectra. The approach is based on: “Unsupervised Noise Cancellation for Vibration Signals: Part II— A Novel Frequency-Domain Algorithm.” https://doi.org/10.1016/S0888-3270(03)00013-X

Parameters:

  • signal (ndarray) – The input time-domain signal.

  • N (int) – Window length used for spectral estimation.

  • Delta (int) – Delay applied to the signal in the cross-correlation.

Returns:

  • random_part (ndarray) – The component of the signal with deterministic content removed.

  • deterministic_part (ndarray) – The reconstructed deterministic (periodic/discrete frequency) part of the signal.

openconmo.benchmark_methods.benchmark_method(signal, fs, N=16384, Delta=500, nlevel=2)

Fault detection using DRS, kurtogram-based filtering, and envelope analysis.

The approach is based on: “Rolling elment bearing diagnostics using the Case Western Reserve University data: A benchmark study” https://doi.org/10.1016/j.ymssp.2015.04.021

This method combines three steps for enhancing impulsive features in vibration signals: 1. Discrete/Random Separation (DRS) to remove deterministic frequency components. 2. Spectral kurtosis analysis via a fast kurtogram to select the most impulsive frequency band. 3. Envelope analysis (squared envelope spectrum) of the filtered signal to extract fault signatures.

Parameters:

  • signal (ndarray) – Input time-domain signal.

  • fs (float) – Sampling frequency of the signal in Hz.

  • N (int, optional) – Length of the window used for DRS filtering (default is 16384).

  • Delta (int, optional) – Overlap or shift value used in DRS (default is 500).

  • nlevel (int, optional) – Number of decomposition levels used in the fast kurtogram (default is 2).

Returns:

  • t (ndarray) – Time vector corresponding to the filtered signal after DRS.

  • filtered_signal (ndarray) – Signal after DRS and kurtogram-based bandpass filtering.

  • f (ndarray) – Frequency vector of the squared envelope spectrum.

  • X (ndarray) – Amplitude of the squared envelope spectrum.

openconmo.benchmark_methods.cepstrum_prewhitening(signal, fs)

Apply cepstrum editing (liftering) for signal pre-whitening.

This method performs signal pre-whitening using cepstrum editing, as described in “Signal Pre-whitening Using Cepstrum Editing (Liftering) to Enhance Fault Detection in Rolling Element Bearings.”

Parameters:

  • signal (ndarray) – The input time-domain signal.

  • fs (float) – Sampling frequency of the signal in Hz.

Returns:

  • t (ndarray) – Time vector corresponding to the reconstructed signal.

  • time_signal (ndarray) – Time-domain signal after cepstrum-based pre-whitening.

openconmo.benchmark_methods.envelope(signal, fs)

Perform squared envelope spectrum analysis of a signal.

This method applies envelope analysis using the squared envelope spectrum of the full-bandwidth signal. It is suitable when there are no strong masking sources in the signal, and bearing faults can be diagnosed directly. Often used as a simple baseline in fault detection.

Parameters:

  • signal (ndarray) – The input raw signal.

  • fs (float) – Sampling frequency of the signal in Hz.

Returns:

  • f (ndarray) – Frequency vector corresponding to the squared envelope spectrum.

  • X (ndarray) – Amplitude of the squared envelope spectrum.

kurtogram

openconmo.kurtogram.fast_kurtogram(x, fs, nlevel=7, verbose=False)

Compute the fast kurtogram of a signal using wavelet packet decomposition.

This implementation is adapted from Jerome Antoni’s fast kurtogram algorithm, and is used to estimate spectral kurtosis of signal over different frequency bands. https://se.mathworks.com/matlabcentral/fileexchange/48912-fast-kurtogram

Parameters:

  • x (ndarray) – Input signal (1D array). Should be a real-valued or complex-valued signal.

  • fs (float) – Sampling frequency of the signal in Hz.

  • nlevel (int, optional) – Number of decomposition levels (default is 7). Must be small enough to satisfy the signal length requirement.

  • verbose (bool, optional) – If True, prints additional information about the maximum kurtosis and corresponding frequency.

Returns:

  • Kwav (ndarray) – 2D array representing the kurtosis map over the wavelet packet decomposition levels and subbands.

  • Level_w (ndarray) – 1D array of decomposition levels corresponding to the rows of Kwav.

  • freq_w (ndarray) – 1D array of center frequencies corresponding to the columns of Kwav.

  • fc (float) – Center frequency (in Hz) of the subband with the highest kurtosis.

  • bandwidth (float) – Bandwidth (in Hz) of the optimal subband with maximum kurtosis.

Raises:

ValueError – If the number of decomposition levels exceeds the limit based on input signal length.

openconmo.kurtogram.plot_kurtogram(data, sampling_rate, nlevel=9, verbose=False)

Plots the kurtogram for a given signal data.

Parameters:

  • data (array_like) – Input signal data (should be a 1D array or a 2D array).

  • sampling_rate (float) – Sampling rate of the signal in Hz.

  • nlevel (int, optional) – The number of decomposition levels for the kurtogram. Default is 9.

  • verbose (bool, optional) – If True, prints additional information. Default is False.

Returns:

This function does not return any value, but generates a plot of the kurtogram.

Return type:

None

utils

openconmo.utils.bandpass_filter(signal, fs, fc, BW, order=200)

Designs and applies a bandpass FIR filter to the input signal.

The filter is centered at the given frequency fc and spans the specified bandwidth BW. It uses a linear-phase FIR design with the given filter order.

Parameters:

  • signal (ndarray) – Input time-domain signal (1D array).

  • fs (float) – Sampling frequency of the signal in Hz.

  • fc (float) – Center frequency of the bandpass filter in Hz.

  • BW (float) – Bandwidth of the bandpass filter in Hz.

  • order (int, optional) – Filter order (default is 200). Determines the sharpness of the filter.

Returns:

filtered_signal – The signal after applying the bandpass FIR filter.

Return type:

ndarray

openconmo.utils.downsample(x, fs_now, fs_resampled)

Downsamples or upsamples a signal to a new sampling frequency.

This function resamples the input signal x from its current sampling frequency fs_now to a new target sampling frequency fs_resampled. The signal is resampled by changing the number of samples based on the ratio of the two frequencies.

Parameters:

  • x (np.ndarray) – Input signal to be resampled, of shape (N,).

  • fs_now (float) – Current sampling frequency of the input signal x.

  • fs_resampled (float) – Target sampling frequency to which the signal should be resampled.

Returns:

The resampled signal with a new number of samples based on the ratio fs_resampled / fs_now.

Return type:

np.ndarray

openconmo.utils.nls(x, L, t, fs, f_start, f_end, fast=True, num_points=5000)

Non-linear least squares (NLS) estimation to fit a signal to a specified model.

Parameters:

  • x (np.ndarray) – Input signal to be fitted, of shape (N, 1).

  • L (int) – Model order, which determines the number of harmonics

  • t (np.ndarray) – Time vector of shape (N,), representing the time points of the signal.

  • fs (float) – Sampling frequency of the signal x.

  • fast (bool, optional) – If True, uses a faster but approximate computation of the cost function J. Default is True.

  • f_start (float) – Starting frequency for the output

  • f_end (float) – End frequency for the output

  • num_points (int, optional) – Number of frequency points in the grid for f0_grid. Default is 5000.

Returns:

  • f0_grid (np.ndarray) – The frequency grid used for fitting, of shape (num_points,).

  • J (np.ndarray) – The computed cost function values for each frequency in f0_grid, of shape (K,).

openconmo.utils.oneside_fft(x, fs)

Compute the one-sided FFT (magnitude spectrum) of a real-valued signal.

This function returns the positive frequency components of the discrete Fourier transform (DFT) of the input signal, scaled appropriately for power analysis.

Parameters:

  • x (ndarray) – Input time-domain signal (real-valued).

  • fs (float) – Sampling frequency of the signal in Hz.

Returns:

  • freqs (ndarray) – Array of positive frequency values in Hz.

  • spectrum (ndarray) – One-sided magnitude spectrum of the input signal.

openconmo.utils.vandermonde(t, w0, L)

Constructs a Vandermonde-like matrix for sinusoidal modeling.

Parameters:

  • t (np.ndarray) – Time vector of shape (N,), representing the time points at which the model is evaluated.

  • w0 (float) – Base angular frequency (in radians per second) for generating the sine and cosine terms.

  • L (int) – Model order, which determines the number of harmonics (terms) in the Vandermonde matrix. The matrix will include terms for the first L harmonics.

Returns:

Z – The Vandermonde-like matrix of shape (N, 2*L), containing both sine and cosine terms for each harmonic frequency up to L. The first L columns are sine terms, and the last L columns are cosine terms.

Return type:

np.ndarray