pyOMA.core.PreProcessingTools.PreProcessSignals#

class pyOMA.core.PreProcessingTools.PreProcessSignals(signals, sampling_rate, ref_channels=None, accel_channels=None, velo_channels=None, disp_channels=None, **kwargs)[source]#

Bases: object

Pre-processor for multi-channel ambient-vibration signals.

Provides signal conditioning (filtering, decimation, offset removal, scaling), spectral estimation (Welch, Blackman-Tukey), and book-keeping of channel metadata (reference channels, measurement quantities, channel-DOF assignments). All downstream pyOMA modules (system identification, stabilisation diagram, mode-shape visualisation) consume an instance of this class.

Todo

time-step integration of signals
Multi-block Blackman-Tukey PSD

__init__(signals, sampling_rate, ref_channels=None, accel_channels=None, velo_channels=None, disp_channels=None, **kwargs)[source]#

Parameters:

signals (np.ndarray, shape (n_samples, n_channels), or str/os.PathLike) – Raw measurement time series; must have more rows than columns. A path to a .npy file is also accepted and loaded via np.load. A .npz path is rejected with a pointer to load_state(), since that format holds a full saved session (multiple fields), not a bare array.
sampling_rate (float) – Sampling frequency in Hz.
ref_channels (list of int, optional) – Column indices of reference (fixed) sensors. Defaults to all channels.
accel_channels (list of int, optional) – Column indices of acceleration channels. Defaults to all channels not in velo_channels or disp_channels.
velo_channels (list of int, optional) – Column indices of velocity channels.
disp_channels (list of int, optional) – Column indices of displacement channels.
setup_name (str, optional) – Label for this measurement setup.
channel_headers (list of str, optional) – Human-readable channel names; defaults to [0, 1, 2, ...].
start_time (datetime.datetime, optional) – Measurement start timestamp; defaults to datetime.datetime.now().
F (np.ndarray, optional) – Optional forcing signal array (used only for FRF-based ERA).

Methods

`__init__`(signals, sampling_rate[, ...])
`add_chan_dofs`(chan_dofs)	chan_dofs = [ (chan_num, node_name, az, elev, chan_name) , .
`add_noise`([amplitude, snr])	Add Gaussian white noise to the signals (useful for simulation studies).
`corr_blackman_tukey`(m_lags[, n_segments, ...])	Estimate the (cross- and auto-) correlation functions (C/ACF), by direct computation of the standard un-biased estimator:
`corr_welch`([m_lags, n_segments, refs_only])	Estimate the (cross- and auto-) correlation functions (C/ACF), by the inverse Fourier Transform of Power Spectral Densities, estimated according to Welch's method.
`correct_offset`()	corrects a constant offset from measured signals
`correlation`([m_lags, method])	A convenience method for obtaining the correlation sequence by the default or any specified estimation method.
`decimate_signals`(decimate_factor[, nyq_rat, ...])	Decimate the signals by an integer factor.
`delete_channels`(channels)	Remove one or more channels from the signals and all associated channel-index bookkeeping.
`filter_signals`([lowpass, highpass, ...])	Apply a zero-phase IIR or FIR filter to the measurement signals.
`get_chan_dof`(channel)	Return the `(node, az, elev)` assignment for channel, or None.
`init_from_config`(conf_file, meas_file[, ...])	initializes the PreProcessor object with a configuration file
`load_chan_dofs`(fname)	chan_dofs[i] = (chan_num, node_name, az, elev, chan_name)
`load_measurement_file`(fname, **kwargs)	A method for loading a signals file
`load_state`(fname)
`precondition_signals`([method])	Remove the DC offset and scale each channel by its spread.
`psd`([n_lines, method])	A convenience method for obtaining the PSD by the default or any specified estimation method.
`psd_blackman_tukey`([n_lines, refs_only, window])	Estimate the (cross- and auto-) power spectral densities (PSD), by Fourier Transform of correlation functions estimated according to Blackman-Tukey's method.
`psd_welch`([n_lines, n_segments, refs_only, ...])	Estimate the (cross- and auto-) power spectral densities (PSD), according to Welch's method.
`remove_chan_dof`(channel)	Remove any existing DOF assignment for channel, if present.
`rename_channel`(channel, new_name)	Rename a channel, keeping any `chan_dofs` annotation in sync.
`save_chan_dofs`(fname)	Write `self.chan_dofs` to fname in the format read by `load_chan_dofs()`.
`save_config`(fname[, delete_channels])	Write a config file readable by `init_from_config()`.
`save_state`(fname)
`save_undo_snapshot`()	Capture the current state for a single-step undo.
`set_chan_dof`(channel, node, az, elev)	Assign channel to a node and direction (azimuth/elevation).
`signal_clarity_score`()
`sv_psd`([n_lines])	Compute the singular values of the power spectral density matrices, for which the complete (all cross spectral densities) matrices are used.
`undo`()	Restore the state captured by the last `save_undo_snapshot()` call.
`validate_channels`(channels[, quant_check])
`welch`(n_lines, **kwargs)

Attributes

`accel_channels`
`corr_matrices`
`corr_matrix`
`disp_channels`
`dt`
`duration`
`freqs`	returns: freqs -- Array with the frequency lines corresponding to the spectral values :rtype: np.ndarray (n_lines, )
`freqs_bt`	returns: freqs -- Array with the frequency lines corresponding to the spectral values :rtype: np.ndarray (n_lines, )
`freqs_wl`	returns: freqs -- Array with the frequency lines corresponding to the spectral values :rtype: np.ndarray (n_lines, )
`lags`
`lags_bt`
`lags_wl`
`m_lags`
`n_lines`
`n_segments`
`num_analised_channels`
`num_ref_channels`
`psd_matrix`
`ref_channels`
`signal_power`
`signal_rms`
`t`
`total_time_steps`
`undo_available`	Whether a single-step undo snapshot is available.
`velo_channels`

add_chan_dofs(chan_dofs)[source]#: chan_dofs = [ (chan_num, node_name, az, elev, chan_name) , … ] This function is not checking if channels or nodes actually exist the former should be added the latter might only be possible, if the geometry object is known to the class

add_noise(amplitude=0, snr=0)[source]#

Add Gaussian white noise to the signals (useful for simulation studies).

Parameters:

amplitude (float, optional) – Absolute noise amplitude (standard deviation). Ignored when snr is non-zero.
snr (float, optional) – Noise amplitude as a fraction of the per-channel RMS. At least one of amplitude or snr must be non-zero.

corr_blackman_tukey(m_lags, n_segments=None, refs_only=True, **kwargs)[source]#

Estimate the (cross- and auto-) correlation functions (C/ACF), by direct computation of the standard un-biased estimator:

\[\hat{R}_{fg}[m] = \frac{1}{N - m}\sum_{n=0}^{N - m - 1} f[n] g[n + m]\]

Computes correlation functions of all channels with selected reference channels up to, but excluding, a time lag of m_lags. Normalization is done according to the unbiased estimator, i.e. 0-lag correlation value must be multiplied by n_lines to get the signals cross-power.

Variance estimation for each time lag is performed by dividing the signals into n_segments non-overlapping blocks for individual estimation of correlation functions. With increasing numbers of non-overlapping blocks the confidence intervals of the correlation functions increase (“worsen”), especially at higher lags and short block lengths, due to a larger number of time steps being discarded.

Note that:

m_lags = n_lines // 2 + 1

n_lines = (m_lags - 1) * 2

Parameters:

m_lags (integer, optional) – Number of lags (positive). Note: this includes the 0-lag, therefore excludes the “m_lags”-lag.
n_segments (integer, optional) – Number of blocks to perform averaging over. If blocks are shorter than m_lags it raises a ValueError.
refs_only (bool, optional) – Compute cross-ACFss only with reference channels
kwargs – Additional kwargs are currently not used

Returns:

corr_matrix – Array of shape (num_channels, num_ref_channels, m_lags) containing the correlation values of the respective channels and lags

Return type:

np.ndarray