The gen module

Part of the pyOMA2 package, this module provides general utility functions crucial for implementational aspects of Operational Modal Analysis (OMA). These functions support data preprocessing, mode shape merging, and key calculations such as the Modal Assurance Criterion (MAC), Modal Scale Factor (MSF), and Modal Complexity Factor (MCF).

Functions:

  • applymask(): Apply a mask to a list of arrays, filtering their values based on the mask.

  • HC_conj(): Apply Hard validation Criteria, complex conjugates.

  • HC_damp(): Apply Hard validation Criteria, damping.

  • HC_MPC(): Apply Hard validation Criteria, modal phase collinearity (MPC).

  • HC_MPD(): Apply Hard validation Criteria, modal phase deviation (MPD).

  • HC_CoV(): Apply Hard validation Criteria, Coefficient of Variation.

  • SC_apply(): Apply Soft validation Criteria.

  • dfphi_map_func(): Maps mode shapes to sensor locations and constraints.

  • check_on_geo1(): Validates geometry1 data.

  • check_on_geo2(): Validates geometry2 data.

  • flatten_sns_names(): Ensures that sensors names is in the correct form.

  • example_data(): Generates the example dataset.

  • merge_mode_shapes(): Merges mode shapes from different setups into a unified mode shape array.

  • MPC(): Calculate the Modal Phase Collinearity of a complex mode shape.

  • MPD(): Calculate the Mean Phase Deviation of a complex mode shape.

  • MSF(): Computes the Modal Scale Factor between two mode shape sets.

  • MCF(): Determines the complexity of mode shapes.

  • MAC(): Calculates the correlation between two sets of mode shapes.

  • pre_multisetup(): Preprocesses data from multiple setups, distinguishing between reference and moving sensors.

  • invperm(): Computes the inverse permutation of an array.

  • find_map(): Establishes a mapping between two arrays based on sorting order.

  • filter_data(): Apply a Butterworth filter to the input data.

  • save_to_file(): Save the specified setup instance to a file.

  • load_from_file(): Load a setup instance from a file.

  • read_excel_file(): Read an Excel file and return its contents as a dictionary.

General Utility Functions module. Part of the pyOMA2 package. Author: Dag Pasca

pyoma2.functions.gen.HC_CoV(Fn, Fn_std, CoV_max) → Tuple[ndarray, ndarray][source]

Apply Hard validation Criteria (HC), retaining only those elements which have a Coefficient of Variation (CoV) less than a specified maximum.

Parameters:

  • Fn (np.ndarray) – Array of frequencies.

  • Fn_std (np.ndarray) – Array of frequency covariances (standard deviation).

  • CoV_max (float) – Maximum allowed Coefficient of Variation (standard deviation/mean value).

Returns:

  • filt_cov (np.ndarray) – Array of the same shape as Fn_std with elements that do not satisfy the condition set to NaN.

  • mask (np.ndarray) – Boolean array of the same shape as Fn_std, where True indicates that the element is less than max_cov.

pyoma2.functions.gen.HC_MPC(phi, mpc_lim) → ndarray[source]

Apply Hard validation Criteria (HC), based on modal phase collinearity (MPC) limit.

Parameters:

  • phi (np.ndarray) – Array of mode shapes with shape (number of modes, number of channels, mode shape length).

  • mpc_lim (float) – Minimum allowed value for modal phase collinearity.

Returns:

mask_mpc – Boolean array indicating elements that satisfy the MPC condition.

Return type:

np.ndarray

pyoma2.functions.gen.HC_MPD(phi, mpd_lim) → ndarray[source]

Apply Hard validation Criteria (HC), based on modal phase deviation (MPD) limit.

Parameters:

  • phi (np.ndarray) – Array of mode shapes with shape (number of modes, number of channels, mode shape length).

  • mpd_lim (float) – Maximum allowed value for modal phase deviation.

Returns:

mask_mpd – Boolean array indicating elements that satisfy the MPD condition.

Return type:

np.ndarray

pyoma2.functions.gen.HC_conj(lambd) → Tuple[ndarray, ndarray][source]

Apply Hard validation Criteria (HC), retaining only those elements which have their conjugates also present in the array.

Parameters:

lambd (np.ndarray) – Array of complex numbers.

Returns:

  • filt_lambd (np.ndarray) – Array of the same shape as lambd with only elements that have their conjugates also present. Other elements are set to NaN.

  • mask (np.ndarray) – Boolean array of the same shape as lambd, where True indicates that the element and its conjugate are both present.

pyoma2.functions.gen.HC_damp(damp, max_damp) → Tuple[ndarray, ndarray][source]

Apply Hard validation Criteria (HC), retaining only those elements which are positive and less than a specified maximum (damping).

Parameters:

  • damp (np.ndarray) – Array of damping ratios.

  • max_damp (float) – Maximum allowed damping ratio.

Returns:

  • filt_damp (np.ndarray) – Array of the same shape as damp with elements that do not satisfy the condition set to NaN.

  • mask (np.ndarray) – Boolean array of the same shape as damp, where True indicates that the element is positive and less than max_damp.

pyoma2.functions.gen.MAC(phi_X: ndarray, phi_A: ndarray) → ndarray[source]

Calculates the Modal Assurance Criterion (MAC) between two sets of mode shapes.

Parameters:

  • phi_X (ndarray) – Mode shape matrix X, shape: (n_locations, n_modes) or n_locations.

  • phi_A (ndarray) – Mode shape matrix A, shape: (n_locations, n_modes) or n_locations.

Returns:

MAC matrix. Returns a single MAC value if both phi_X and phi_A are one-dimensional arrays.

Return type:

ndarray

Raises:

Exception – If mode shape matrices have more than 2 dimensions or if their first dimensions do not match.

pyoma2.functions.gen.MCF(phi: ndarray) → ndarray[source]

Calculates the Modal Complexity Factor (MCF) for mode shapes.

Parameters:

phi (ndarray) – Complex mode shape matrix, shape: (n_locations, n_modes) or n_locations.

Returns:

MCF values, ranging from 0 (for real modes) to 1 (for complex modes).

Return type:

ndarray

pyoma2.functions.gen.MPC(phi: ndarray) → float[source]

Calculate the Modal Phase Collinearity (MPC) of a complex mode shape.

The MPC is a measure of the collinearity between the real and imaginary parts of a mode shape. A value of 1 indicates perfect collinearity, while lower values indicate a more complex (non-collinear) mode.

Parameters:

phi (ndarray) – Complex mode shape vector, shape: (n_locations, ).

Returns:

MPC value, ranging between 0 and 1, where 1 indicates perfect collinearity.

Return type:

float

pyoma2.functions.gen.MPD(phi: ndarray) → float[source]

Calculate the Mean Phase Deviation (MPD) of a complex mode shape.

The MPD measures the deviation of the mode shape phases from a purely real mode. It quantifies the phase variation along the mode shape.

Parameters:

phi (ndarray) – Complex mode shape vector, shape: (n_locations, ).

Returns:

MPD value, representing the average deviation of the phase from a purely real mode.

Return type:

float

pyoma2.functions.gen.MSF(phi_1: ndarray, phi_2: ndarray) → ndarray[source]

Calculates the Modal Scale Factor (MSF) between two sets of mode shapes.

Parameters:

  • phi_1 (ndarray) – Mode shape matrix X, shape: (n_locations, n_modes) or n_locations.

  • phi_2 (ndarray) – Mode shape matrix A, shape: (n_locations, n_modes) or n_locations.

Returns:

The MSF values, real numbers that scale phi_1 to phi_2.

Return type:

ndarray

Raises:

Exception – If phi_1 and phi_2 do not have the same shape.

pyoma2.functions.gen.SC_apply(Fn, Xi, Phi, ordmin, ordmax, step, err_fn, err_xi, err_phi) → ndarray[source]

Apply Soft validation Criteria (SC) to determine the stability of modal parameters between consecutive orders.

Parameters:

  • Fn (np.ndarray) – Array of natural frequencies.

  • Xi (np.ndarray) – Array of damping ratios.

  • Phi (np.ndarray) – Array of mode shapes.

  • ordmin (int) – Minimum model order.

  • ordmax (int) – Maximum model order.

  • step (int) – Step size for increasing model order.

  • err_fn (float) – Tolerance for the natural frequency error.

  • err_xi (float) – Tolerance for the damping ratio error.

  • err_phi (float) – Tolerance for the mode shape error.

Returns:

Lab – Array of labels indicating stability (1 for stable, 0 for unstable).

Return type:

np.ndarray

pyoma2.functions.gen.applymask(list_arr, mask, len_phi) → List[ndarray][source]

Apply a mask to a list of arrays, filtering their values based on the mask.

Parameters:

  • list_arr (list of np.ndarray) – List of arrays to be filtered. Arrays can be 2D or 3D.

  • mask (np.ndarray) – 2D boolean array indicating which values to keep (True) or set to NaN (False).

  • len_phi (int) – The length of the mode shape dimension for expanding the mask to 3D.

Returns:

List of filtered arrays with the same shapes as the input arrays.

Return type:

list of np.ndarray

Notes

  • If an array in list_arr is 3D, the mask is expanded to 3D and applied.

  • If an array in list_arr is 2D, the original mask is applied directly.

  • Values not matching the mask are set to NaN.

pyoma2.functions.gen.check_on_geo1(file_dict, ref_ind=None) → Tuple[List[str], DataFrame, ndarray, ndarray, ndarray, ndarray, ndarray][source]

Validates and processes sensor and background geometry data from a dictionary of dataframes.

Parameters:

  • file_dict (dict) – Dictionary containing dataframes of sensor and background geometry data.

  • ref_ind (list, optional) – List of reference indices for sensor names, by default None.

Returns:

A tuple containing: - sens_names (list): List of sensor names. - sens_coord (pd.DataFrame): DataFrame of sensor coordinates. - sens_dir (np.ndarray): Array of sensor directions. - sens_lines (np.ndarray or None): Array of sensor lines. - BG_nodes (np.ndarray or None): Array of background nodes. - BG_lines (np.ndarray or None): Array of background lines. - BG_surf (np.ndarray or None): Array of background surfaces.

Return type:

tuple

Raises:

ValueError – If required sheets are missing or invalid. If shapes of ‘sensors coordinates’ and ‘sensors directions’ do not match. If ‘sensors coordinates’ or ‘BG nodes’ does not have 3 columns. If ‘BG lines’ does not have 2 columns. If ‘BG surfaces’ does not have 3 columns. If sensor names are not present in the index of ‘sensors coordinates’.

pyoma2.functions.gen.check_on_geo2(file_dict, ref_ind=None, fill_na='zero') → Tuple[List[str], DataFrame, ndarray, DataFrame, DataFrame, ndarray, ndarray, ndarray, ndarray, ndarray][source]

Validates and processes sensor and background geometry data from a dictionary of dataframes.

Parameters:

  • file_dict (dict) – Dictionary containing dataframes of sensor and background geometry data.

  • ref_ind (list, optional) – List of reference indices for sensor names, by default None.

  • fill_na (str, optional) – Method to fill missing values in the mapping dataframe, by default “zero”.

Returns:

A tuple containing: - sens_names (list): List of sensor names. - pts_coord (pd.DataFrame): DataFrame of points coordinates. - sens_map (pd.DataFrame): DataFrame of sensor mappings. - cstr (pd.DataFrame or None): DataFrame of constraints. - sens_sign (pd.DataFrame): DataFrame of sensor signs. - sens_lines (np.ndarray or None): Array of sensor lines. - sens_surf (np.ndarray or None): Array of sensor surfaces. - BG_nodes (np.ndarray or None): Array of background nodes. - BG_lines (np.ndarray or None): Array of background lines. - BG_surf (np.ndarray or None): Array of background surfaces.

Return type:

tuple

Raises:

ValueError – If required sheets are missing or invalid. If shapes of ‘points coordinates’ and ‘mapping’ do not match. If ‘points coordinates’ or ‘BG nodes’ does not have 3 columns. If ‘BG lines’ does not have 2 columns. If ‘BG surfaces’ does not have 3 columns. If sensor names are not present in the mapping dataframe. If constraints columns do not correspond to sensor names. If constraints names are not the same as those used in the mapping.

pyoma2.functions.gen.dfphi_map_func(phi, sens_names, sens_map, cstrn=None) → DataFrame[source]

Maps mode shapes to sensor locations and constraints, creating a dataframe.

Parameters:

  • phi (np.ndarray) – Array of mode shapes.

  • sens_names (list) – List of sensor names corresponding to the mode shapes.

  • sens_map (pd.DataFrame) – DataFrame containing the sensor mappings.

  • cstrn (pd.DataFrame, optional) – DataFrame containing constraints, by default None.

Returns:

DataFrame with mode shapes mapped to sensor points.

Return type:

pd.DataFrame

pyoma2.functions.gen.example_data() → dict[source]

This function generates a time history of acceleration for a 5 DOF system.

The function returns a (360001,5) array and a tuple containing: the natural frequencies of the system (fn = (5,) array); the unity displacement normalised mode shapes matrix (FI_1 = (5,5) array); and the damping ratios (xi = float)

Returns:

  • acc (2D array) – Time histories of the 5 DOF of the system.

  • (fn, FI_1, xi) (tuple) – Tuple containing the natural frequencies (fn), the mode shape matrix (FI_1), and the damping ratio (xi) of the system.

pyoma2.functions.gen.filter_data(data: ndarray, fs: float, Wn: float, order: int = 4, btype: str = 'lowpass') → ndarray[source]

Apply a Butterworth filter to the input data.

This function designs and applies a digital Butterworth filter to the input data array. The filter is applied in a forward-backward manner using the second-order sections representation to minimize phase distortion.

Parameters:

  • data (array_like) – The input signal to filter. If data is a multi-dimensional array, the filter is applied along the first axis.

  • fs (float) – The sampling frequency of the input data.

  • Wn (array_like) – The critical frequency or frequencies. For lowpass and highpass filters, Wn is a scalar; for bandpass and bandstop filters, Wn is a length-2 sequence.

  • order (int, optional) – The order of the filter. Higher order means a sharper frequency cutoff, but the filter will also be less stable. The default is 4.

  • btype (str, optional) – The type of filter to apply. Can be ‘lowpass’, ‘highpass’, ‘bandpass’, or ‘bandstop’. The default is ‘lowpass’.

Returns:

filt_data – The filtered signal.

Return type:

ndarray

Note

This function uses scipy.signal.butter to design the filter and scipy.signal.sosfiltfilt for filtering to apply the filter in a zero-phase manner, which does not introduce phase delay to the filtered signal. For more information, see the scipy documentation for signal.butter (https://docs.scipy.org/doc/scipy/reference/generated/scipy.signal.butter.html) and signal.sosfiltfilt (https://docs.scipy.org/doc/scipy/reference/generated/scipy.signal.sosfiltfilt.html).

pyoma2.functions.gen.find_map(arr1: ndarray, arr2: ndarray) → ndarray[source]

Maps the elements of one array to another based on sorting order.

Parameters:

  • arr1 (array-like) – The first input array.

  • arr2 (array-like) – The second input array, which should have the same length as arr1.

Returns:

An array of indices that maps the sorted version of arr1 to the sorted version of arr2.

Return type:

ndarray

pyoma2.functions.gen.flatten_sns_names(sens_names, ref_ind=None) → List[str][source]

Ensures that sensors names is in the correct form (1D list of strings) for both single-setup or multi-setup geometries.

Parameters:

  • sens_names (list, pd.DataFrame, or np.ndarray) – Sensor names which can be a list of strings, list of lists of strings, DataFrame, or 1D numpy array of strings.

  • ref_ind (list, optional) – List of reference indices for multi-setup geometries, by default None.

Returns:

Flattened list of sensor names.

Return type:

list

Raises:

  • AttributeError – If ref_ind is not provided for multi-setup geometries.

  • ValueError – If sens_names is not of the expected types.

pyoma2.functions.gen.invperm(p: ndarray) → ndarray[source]

Compute the inverse permutation of a given array.

Parameters:

p (array-like) – A permutation of integers from 0 to n-1, where n is the length of the array.

Returns:

An array representing the inverse permutation of p.

Return type:

ndarray

pyoma2.functions.gen.load_from_file(file_name: str) → object[source]

Load a setup instance from a file.

This method deserializes a saved setup instance from the specified file.

Parameters:

file_name (str) – The name (path) of the file from which the setup instance will be loaded.

Returns:

An instance of the setup loaded from the file.

Return type:

Setup

pyoma2.functions.gen.merge_mode_shapes(MSarr_list: List[ndarray], reflist: List[List[int]]) → ndarray[source]

Merges multiple mode shape arrays from different setups into a single mode shape array.

Parameters:

  • MSarr_list (List[np.ndarray]) – A list of mode shape arrays. Each array in the list corresponds to a different experimental setup. Each array should have dimensions [N x M], where N is the number of sensors (including both reference and roving sensors) and M is the number of modes.

  • reflist (List[List[int]]) – A list of lists containing the indices of reference sensors. Each sublist corresponds to the indices of the reference sensors used in the corresponding setup in MSarr_list. Each sublist should contain the same number of elements.

Returns:

A merged mode shape array. The number of rows in the array equals the sum of the number of unique sensors across all setups minus the number of reference sensors in each setup (except the first one). The number of columns equals the number of modes.

Return type:

np.ndarray

Raises:

ValueError – If the mode shape arrays in MSarr_list do not have the same number of modes.

pyoma2.functions.gen.pre_multisetup(dataList: List[ndarray], reflist: List[List[int]]) → List[Dict[str, ndarray]][source]

Preprocesses data from multiple setups by separating reference and moving sensor data.

Parameters:

  • DataList (list of numpy arrays) – List of input data arrays for each setup, where each array represents sensor data.

  • reflist (list of lists) – List of lists containing indices of sensors used as references for each setup.

Returns:

A list of dictionaries, each containing the data for a setup. Each dictionary has keys ‘ref’ and ‘mov’ corresponding to reference and moving sensor data.

Return type:

list of dicts

pyoma2.functions.gen.read_excel_file(path: str, sheet_name: str | None = None, engine: str = 'openpyxl', index_col: int = 0, **kwargs: Any) → dict[source]

Read an Excel file and return its contents as a dictionary.

Parameters:

  • path (str) – The path to the Excel file.

  • sheet_name (str, optional) – The name of the sheet to read. If None, all sheets are read. Default is None.

  • engine (str, optional) – The engine to use for reading the Excel file. Default is ‘openpyxl’.

  • index_col (int, optional) – The column to use as the index. Default is 0

  • **kwargs (dict, optional) – Additional keyword arguments to pass to pd.read_excel.

Returns:

A dictionary containing the contents of the Excel file, with sheet names as keys.

Return type:

dict

Raises:

  • ImportError – If the specified engine is not available.

  • RuntimeError – If an error occurs while reading the Excel file.

pyoma2.functions.gen.save_to_file(setup: object, file_name: str) → None[source]

Save the specified setup instance to a file.

This method serializes the current instance and saves it to a file using the pickle module.

Parameters:

  • setup (obj) – The Setup class that is to be saved.

  • file_name (str) – The name (path) of the file where the setup instance will be saved.