single_chan_signal module

class SignalForge.single_chan_signal.SingleChanSignal(x: ndarray, fs: float, dfpsd=0.5, name: str = '', var: str = 'x', unit: str = '$m/s^2$', signal_type: str = 'User provided signal')[source]

Bases: object

SingleChanSignal is the parent class of StationaryGaussian, StationaryNonGaussian and NonStationaryNonGaussian. Advanced signal analisys class.

Parameters:

x (np.ndarray) – frequency vector of the power spectral density
fs (float) – power density vector of the power spectral density
dfpsd (float) – frequency discretization of the psd to be stored
name (str) – name of the process (used for plots)
var (str) – name of the variable (used for plots)
unit (str) – unit of measure of the signal (used for plots)
seed (int) – seed for the random generator used in non-gaussian models
interp ('lin' or 'log') – interpolation rule for increasing resolution on given PSD

property f_fft_os: one-sided frequency vector

property f_fft_ts: two-sided frequency vector

property fft_os: one-sided Fourier coefficients

property fft_ts: two-sided Fourier coefficients

get_banded_spectral_kurtosis(n_bins=10, fl: int = 0, fu: int = 0)[source]

Compute banded spectral kurtosis over specified frequency bands.

Parameters:

n_bins (int, optional) – Number of frequency bands to divide the spectrum into.
fl (int, optional) – Lower frequency limit (Hz).
fu (int, optional) – Upper frequency limit (Hz).

Returns:

fvec (ndarray) – Center frequencies of each band.
SK (ndarray) – Spectral kurtosis values for each frequency band.

get_bestfit_gaussian_pdf(bins='auto', grid=None)[source]

Compute the best-fit Gaussian PDF based on the signal’s mean and variance.

Parameters:

bins (int, sequence, or str, optional) – Used to compute a default grid if one is not provided.
grid (ndarray, optional) – The grid (support) over which to evaluate the Gaussian PDF. If None, computed from histogram.

Returns:

grid (ndarray) – Grid points where the Gaussian PDF is evaluated.
pgauss (ndarray) – Gaussian PDF values on the grid.

get_hilbert(*args, **kwargs)[source]

Compute the analytic signal using the Hilbert transform.

Parameters:

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

Returns:

analytic_signal (ndarray) – Complex-valued analytic signal.
amplitude_envelope (ndarray) – Instantaneous amplitude (envelope) of the signal.
instantaneous_phase (ndarray) – Unwrapped instantaneous phase of the signal.

get_kurtogram(n_bins: tuple | int = None, method='fast', _plot_call=False)[source]

Calculate the kurtogram of the signal.

Parameters:

ax (matplotlib.axes.Axes, optional) – The axes to plot on. If None, a new figure and axes are created.
n_bins (tuple, optional) – The range of bins to use for the kurtogram. (start, finish, step)

Returns:

ax – The axes with the plotted kurtogram.

Return type:

matplotlib.axes.Axes

get_nonstat_index(idx_type='nnst', *args, **kwargs)[source]

Computes the requested non stationary test from the given one dimensional time history

Parameters:

signal (array-like) – One dimensional time history
index_type (str, optional) – Type of non stationary index to be assessed. Supported methods are: Non-Stationarity index [1]: ‘nnst’, Augmented Dickey-Fuller [2]: ‘adf’, Kwiatkowski-Phillips-Schmidt-Shin [3]: ‘kpss’
kwargs (optional) – Argument to be passed to the specific method implementation

Returns:

test_results (dict) – Results of the non-stationary test
Source
——
[1] 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.)
[2] 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.
[3] 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.)

get_pdf(bins='auto')[source]

Estimate the empirical probability density function (PDF) of the signal.

Parameters:

bins (int, sequence, or str, optional) – Binning strategy for histogram computation. Passed directly to np.histogram.

Returns:

grid (ndarray) – Center values of the histogram bins.
prob (ndarray) – Normalized histogram values representing the PDF.

get_psd(df=0.5, noverlap=None)[source]

Estimate power spectral density (PSD) using the Welch method.

This method is typically called by __init__.

Parameters:

df (float, optional) – Frequency resolution for the Welch method. Default is 0.5.
noverlap (int, optional) – Number of points to overlap between segments. If None, it uses the default for scipy.signal.welch.

Returns:

fpsd (np.ndarray) – Frequencies corresponding to the PSD.
psd (np.ndarray) – Estimated power spectral density values.

get_sftf(nperseg: int = 1024, hop=32, nargout=1)[source]

Compute the Short-Time Fourier Transform (STFT) of the signal.

Parameters:

nperseg (int, optional) – Length of each segment (window size) for the STFT.
hop (int, optional) – Hop size (step between windows).
nargout (int, optional) – If >1, also returns the SFTF object.

Returns:

Sx (ndarray) – STFT magnitude spectrum.
SFT (ShortTimeFFT, optional) – SFTF object containing additional metadata and transform options.

get_spectrogram(nperseg: int = 1024, hop=32, nargout=1)[source]

Compute the Spectrogram of the signal via Short-Time Fourier Transform (STFT).

Parameters:

nperseg (int, optional) – Length of each segment (window size) for the STFT.
hop (int, optional) – Hop size (step between windows).
nargout (int, optional) – If >1, also returns the SFTF object.

Returns:

Sxx (ndarray) – STFT power densitt spectrum.
SFT (ShortTimeFFT, optional) – SFTF object containing additional metadata and transform options.

get_stat_history(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

get_wavelet_transform(wavetype='morl', **kwargs)[source]

Compute the Continuous Wavelet Transform (CWT) of the signal.

Parameters:

wavetype (str, optional) – Type of mother wavelet to use (e.g., ‘morl’, ‘cmor’).
**kwargs (dict, optional) – Additional keyword arguments passed to pywt.cwt.

Returns:

data (ndarray) – Wavelet coefficient matrix.
f (ndarray) – Frequencies corresponding to wavelet scales.

get_welch_spectral_kurtosis(Nfft: int = None, noverlap: int = 0)[source]

Compute Welch-based spectral kurtosis of the signal.

Parameters:

Nfft (int, optional) – FFT length used in the Welch method. Defaults to length of self.psd.
noverlap (int, optional) – Number of overlapping points between segments.

Returns:

f_norm (ndarray) – Frequency vector (in Hz).
SK (ndarray) – Spectral kurtosis values across the frequency range.

plot(ax=None, xlims: list = None, ylims: list = None)[source]

Plot the time history of the signal.

Parameters:

ax (matplotlib.axes.Axes, optional) – The axes to plot on. If None, a new figure and axes are created.
xlims (list, optional) – The limits for the x-axis.
ylims (list, optional) – The limits for the y-axis.

Returns:

ax – The axes with the plotted time history.

Return type:

matplotlib.axes.Axes

plot_fft(ax=None, two_sided: bool = False, xlims: list = None, ylims: list = None)[source]

Plot the Fourier Transform (FT) of the signal.

Parameters:

ax (matplotlib.axes.Axes, optional) – The axes to plot on. If None, a new figure and axes are created.
xlims (list, optional) – The limits for the x-axis.
ylims (list, optional) – The limits for the y-axis.

Returns:

ax – The axes with the plotted FT.

Return type:

matplotlib.axes.Axes

plot_hilbert(ax=None)[source]

Plot the Hilbert transform of the signal, showing the amplitude envelope and instantaneous frequency.

Parameters:: ax (matplotlib.axes.Axes, optional) – The axes to plot on. If None, a new figure and axes are created.
Returns:: ax – The axes with the plotted Hilbert transform.
Return type:: matplotlib.axes.Axes

plot_kurtogram(ax=None, n_bins: tuple | int = None, method: str = 'fast', ylims: list = None, xlims: list = None)[source]

Plot the kurtogram of the signal.

Parameters:

ax (matplotlib.axes.Axes, optional) – The axes to plot on. If None, a new figure and axes are created.
n_bins (tuple, optional) – The range of bins to use for the kurtogram. (start, finish, step)
ylims (list, optional) – The limits for the y-axis.

Returns:

ax – The axes with the plotted kurtogram.

Return type:

matplotlib.axes.Axes

plot_pdf(ax=None, xlims: list = None, log: bool = False, plot_gaussian_bestfit=True)[source]

Plot the Probability Density Function (PDF) of the signal.

Parameters:

ax (matplotlib.axes.Axes, optional) – The axes to plot on. If None, a new figure and axes are created.
xlims (list, optional) – The limits for the x-axis.
log (bool, optional) – Whether to plot on a logarithmic scale.
plot_gaussian_bestfit (bool, optional) – Whether to plot the best-fit Gaussian distribution.

Returns:

ax – The axes with the plotted PDF.

Return type:

matplotlib.axes.Axes

plot_psd(ax=None, xlims: list = None, ylims: list = None, log: bool = False)[source]

Plot the Power Spectral Density (PSD) of the signal.

Parameters:

ax (matplotlib.axes.Axes, optional) – The axes to plot on. If None, a new figure and axes are created.
xlims (list, optional) – The limits for the x-axis.
ylims (list, optional) – The limits for the y-axis.
log (str, optional) – Specifies the logarithmic scale for x, y, or both axes.

Returns:

ax – The axes with the plotted PSD.

Return type:

matplotlib.axes.Axes

plot_scalogram(ax=None, wavetype='morl', **kwargs)[source]

Plot the scalogram of the signal using wavelet transformation.

Parameters:

ax (matplotlib.axes.Axes, optional) – The axes to plot on. If None, a new figure and axes are created.
wavetype (str, optional) – The type of wavelet to use for the transform.
**kwargs
transformation. (Additional keyword arguments for wavelet)

Returns:

ax – The axes with the plotted scalogram.

Return type:

matplotlib.axes.Axes

plot_spectral_kurtosis(ax=None, Nfft: int = None, n_bins: int = None, fl: int = None, fu: int = None, xlims: list = None, ylims: list = None)[source]

Plot the spectral kurtosis of the signal.

Parameters:

ax (matplotlib.axes.Axes, optional) – The axes to plot on. If None, a new figure and axes are created.
Nfft (int, optional) – Number of opints used to calculate the spectral kurtosis with the fast approach
n_bins (int, optional) – The number of bins for the spectral kurtosis calculation.
fl (int, optional) – The lower frequency bound.
fu (int, optional) – The upper frequency bound.
ylims (list, optional) – The limits for the y-axis.

Returns:

ax – The axes with the plotted spectral kurtosis.

Return type:

matplotlib.axes.Axes

plot_spectrogram(ax=None, window: tuple = ('tukey', 1), nperseg: int = 1024, ylims: list = None, clims: list = None)[source]

Plot the spectrogram of the signal.

Parameters:

ax (matplotlib.axes.Axes, optional) – The axes to plot on. If None, a new figure and axes are created.
window (tuple, optional) – The window type and parameter for the spectrogram.
nperseg (int, optional) – The number of data points per segment for the spectrogram.
ylims (list, optional) – The limits for the y-axis.
clims (list, optional) – The color limits for the spectrogram.

Returns:

ax – The axes with the plotted spectrogram.

Return type:

matplotlib.axes.Axes

plot_stat_history(winsize: int, olap: int = 0, idx_type: str = 'rms', ax=None, xlims: list = None, ylims: list = None)[source]

Plot the statistical indicator time history of the signal on a moving window.

Parameters:

winsize (int) – The window size for the non-stationarity index calculation.
olap (int, optional) – The number of points to overlap on the moving window. If not specified, no overlap is considered
idx_type (str, optional) – The type of index to calculate (‘rms’ or ‘kurt’).
ax (matplotlib.axes.Axes, optional) – The axes to plot on. If None, a new figure and axes are created.
xlims (list, optional) – The limits for the x-axis.
ylims (list, optional) – The limits for the y-axis.

Returns:

The axes with the plotted non-stationarity index.

Return type:

ax :: matplotlib.axes.Axes

plot_stft(nperseg: int = 1024, hop=256, flims: list = None, fig=None, ax=None)[source]

Plot the Short-Time Fourier Transform (STFT) of the signal.

Parameters:

nperseg (int, optional) – The number of data points per segment for the STFT.
hop (int, optional) – The number of data points between segments.
flims (list, optional) – The limits of the frequencies shown of the plot
fig (optional) – Matplotlib figure handle
ax (optional) – Matplotlib axis handle

Returns:

ax – The axes with the plotted STFT.

Return type:

matplotlib.axes.Axes

save_to_csv(filename: str)[source]

Save the signal time history to a CSV file using numpy.savetxt.

Parameters:: filename (str) – Full path (or filename) where the CSV will be saved.

property t: time vector