The run_params module

These classes are were the parameters used to run the analyses are stored.

Classes:

BaseRunParams

Base class for storing run parameters for modal analysis algorithms.

FDDRunParams

Class for storing Frequency Domain Decomposition (FDD) run parameters.

EFDDRunParams

Class for storing Enhanced Frequency Domain Decomposition (EFDD) run parameters.

SSIRunParams

Parameters for the Stochastic Subspace Identification (SSI) method.

pLSCFRunParams

Parameters for the poly-reference Least Square Complex Frequency (pLSCF) method.

AutoSSIRunParams

Run parameters for automated SSI.

Step1

Parameters for the first step of clustering analysis.

Step2

Parameters for the second step of clustering analysis.

Step3

Parameters for the third step of clustering analysis.

Clustering

Main class for clustering analysis.

Warning

The module is designed to be used as part of the pyOMA2 package and relies on its internal data structures and algorithms.

This module provides classes for storing run parameters for various modal analysis algorithms included in the pyOMA2 module.

class pyoma2.algorithms.data.run_params.AutoSSIRunParams(*, br: int | None = None, method: Literal['cov', 'cov_R', 'dat'] | None = None, ref_ind: List[int] | None = None, ordmin: int = 0, ordmax: int | None = None, step: int = 1, calc_unc: bool = False, nb: int = 50)

Bases: BaseRunParams

Run parameters for automated SSI.

br

Number of block rows.

Type:

int

method

Method for assembling the Hankel/subspace matrix.

Type:

{‘cov’, ‘cov_R’, ‘dat’}

ref_ind

Indices of reference/projection channels.

Type:

list of int, optional

ordmin

Minimum model order.

Type:

int

ordmax

Maximum model order.

Type:

int

step

Step size for model order increment.

Type:

int

calc_unc

Whether to calculate uncertainty in results.

Type:

bool

nb

Number of data blocks for uncertainty calculations.

Type:

int

class pyoma2.algorithms.data.run_params.BaseRunParams

Bases: BaseModel

Base class for storing run parameters for modal analysis algorithms.

class pyoma2.algorithms.data.run_params.Clustering(*, name: str, steps: Tuple[Step1, Step2, Step3] | None = None, quick: str | None = None)

Bases: BaseModel

Main class for clustering analysis.

name

Name of the clustering instance.

Type:

str

steps

Steps defining the clustering process.

Type:

tuple of (Step1, Step2, Step3), optional

quick

Predefined configurations for specific clustering strategies.

Type:

{‘Magalhaes’, ‘Reynders’, ‘Neu’, ‘Kvaale’, ‘Dederichs’}, optional

assemble_steps()

Automatically assembles steps based on the quick parameter if steps is not provided.

class pyoma2.algorithms.data.run_params.EFDDRunParams(*, nxseg: int = 1024, method_SD: Literal['per', 'cor'] = 'per', pov: float = 0.5)

Bases: BaseRunParams

Class for storing Enhanced Frequency Domain Decomposition (EFDD) run parameters.

nxseg

Number of points per segment, default is 1024.

Type:

int, optional

method_SD

Method used for spectral density estimation, default is “per”.

Type:

str, optional [“per”, “cor”]

pov

Percentage of overlap between segments (only for “per”), default is 0.5.

Type:

float, optional

class pyoma2.algorithms.data.run_params.FDDRunParams(*, nxseg: int = 1024, method_SD: Literal['per', 'cor'] = 'per', pov: float = 0.5)

Bases: BaseRunParams

Class for storing Frequency Domain Decomposition (FDD) run parameters.

nxseg

Number of points per segment, default is 1024.

Type:

int, optional

method_SD

Method used for spectral density estimation, default is “per”.

Type:

str, optional [“per”, “cor”]

pov

Percentage of overlap between segments (only for “per”), default is 0.5.

Type:

float, optional

class pyoma2.algorithms.data.run_params.HCDictType

Bases: TypedDict

A TypedDict representing Hard validation Criteria (HC).

xi_max

The maximum value for damping.

Type:

float, optional

mpc_lim

The limit value for Modal Phase Collinearity (MPC).

Type:

float, optional

mpd_lim

The limit value for Mean Phase Deviation (MPD).

Type:

float, optional

CoV_max

The maximum coefficient of variation (CoV). Only used when calc_unc == True, i.e. when the uncertainty bounds of the modal parameters are calculated.

Type:

float, optional

class pyoma2.algorithms.data.run_params.SCDictType

Bases: TypedDict

A TypedDict representing Soft validation Criteria (SC).

err_fn

The maximum thresholds for relative frequency difference.

Type:

float

err_xi

The maximum thresholds for relative damping difference.

Type:

float

err_phi

The maximum thresholds for MAC difference.

Type:

float

class pyoma2.algorithms.data.run_params.SSIRunParams(*, br: int = 20, method: str = None, ref_ind: List[int] | None = None, ordmin: int = 0, ordmax: int | None = None, step: int = 1, sc: SCDictType = {'err_fn': 0.05, 'err_phi': 0.05, 'err_xi': 0.05}, hc: HCDictType = {'CoV_max': 0.05, 'mpc_lim': 0.5, 'mpd_lim': 0.5, 'xi_max': 0.1}, calc_unc: bool = False, nb: int = 50)

Bases: BaseRunParams

Parameters for the Stochastic Subspace Identification (SSI) method.

br

Number of block rows in the Hankel matrix.

Type:

int

method_hank

Method used in the SSI algorithm. Options are [‘data’, ‘cov’, ‘cov_R’]. Method used in the SSI algorithm. Options are [‘data’, ‘cov’, ‘cov_R’]. Default is None.

Type:

str or None, optional

ref_ind

List of reference indices used for subspace identification. Default is None.

Type:

list of int or None, optional

ordmin

Minimum model order for the analysis. Default is 0.

Type:

int, optional

ordmax

Maximum model order for the analysis. Default is None.

Type:

int or None, optional

step

Step size for iterating through model orders. Default is 1.

Type:

int, optional

sc

Soft validation criteria for the analysis.

Type:

dict, optional

hc

Hard validation criteria for the analysis.

Type:

dict, optional

calc_unc

Whether to calculate uncertainty. Default is False.

Type:

bool, optional

nb

Number of bootstrap samples to use for uncertainty calculations (default is 50).

Type:

int, optional

class pyoma2.algorithms.data.run_params.Step1(*, hc: bool | Literal['after'] = True, hc_dict: HCDictType = {'CoV_max': 0.05, 'mpc_lim': 0.5, 'mpd_lim': 0.5, 'xi_max': 0.1}, sc: bool | Literal['after'] = True, sc_dict: SCDictType = {'err_fn': 0.03, 'err_phi': 0.05, 'err_xi': 0.1}, pre_cluster: bool = False, pre_clus_typ: Literal['GMM', 'kmeans'] = 'GMM', pre_clus_dist: List[Literal['dfn', 'dxi', 'dlambda', 'dMAC', 'dMPC', 'dMPD', 'MPC', 'MPD']] = ['dlambda', 'dMAC'], transform: Literal['box-cox'] | None = None)

Bases: BaseRunParams

Parameters for the first step of clustering analysis.

hc

Whether to apply hard validation criteria (HC) to the poles, (‘after’ delays it until after the pre clustering has been executed).

Type:

{bool, ‘after’}

hc_dict

Dictionary of hard criteria (HC).

Type:

HCDictType

sc

Whether to apply soft validation criteria (SC) to the poles, (‘after’ delays it until after the pre clustering has been executed).

Type:

{bool, ‘after’}

sc_dict

Dictionary of soft criteria (HC).

Type:

SCDictType

pre_cluster

Whether to pre-cluster data before analysis.

Type:

bool

pre_clus_typ

Type of pre-clustering algorithm.

Type:

{‘GMM’, ‘kmeans’}

pre_clus_dist

Distance metrics used for pre-clustering.

Type:

list of {‘dfn’, ‘dxi’, ‘dlambda’, ‘dMAC’, ‘dMPC’, ‘dMPD’, ‘MPC’, ‘MPD’}

transform

Data transformation method.

Type:

{‘box-cox’}, optional

Notes

The hc_dict and sc_dict attributes are used only when hc and sc are set to True. The pre_clus_typ, pre_clus_dist and transform attributes are used only when pre_cluster is set to True.

class pyoma2.algorithms.data.run_params.Step2(*, distance: List[Literal['dfn', 'dxi', 'dlambda', 'dMAC', 'dMPC', 'dMPD']] = ['dlambda', 'dMAC'], weights: Literal['tot_one'] | None | list = None, sqrtsqr: bool = False, algo: Literal['hdbscan', 'hierarc', 'optics', 'spectral', 'affinity'] = 'hierarc', dc: float | Literal['auto', 'mu+2sig', '95weib'] | None = 'auto', linkage: Literal['average', 'complete', 'single'] = 'average', min_size: int | None | Literal['auto'] = 'auto', n_clusters: int | None | Literal['auto'] = None)

Bases: BaseRunParams

Parameters for the second step of clustering analysis.

distance

Distance metrics for clustering.

Type:

list of {‘dfn’, ‘dxi’, ‘dlambda’, ‘dMAC’, ‘dMPC’, ‘dMPD’}

weights

Weighting scheme for distance metrics.

Type:

{‘tot_one’, None} or list, optional

sqrtsqr

Whether to apply square-root to the sum of squares.

Type:

bool

algo

Clustering algorithm to use.

Type:

{‘hdbscan’, ‘hierarc’, ‘optics’, ‘spectral’, ‘affinity’}

dc

Distance threshold for hierarchical clustering.

Type:

{float, ‘auto’, ‘mu+2sig’, ‘95weib’}, optional

linkage

Linkage criterion for hierarchical clustering.

Type:

{‘average’, ‘complete’, ‘single’}

min_size

Minimum cluster size.

Type:

{int, ‘auto’}, optional

n_clusters

Number of clusters.

Type:

{int, ‘auto’}, optional

Notes

The dc and linkage parameters are used exclusively for the ‘hierarc’ clustering algorithm. The min_size parameter is relevant only for ‘hdbscan’ and ‘optics’ (but could be used in step3), while n_clusters applies to ‘spectral’, and hierarc’ when ‘dc’ is None.

class pyoma2.algorithms.data.run_params.Step3(*, post_proc: List[Literal['merge_similar', 'damp_IQR', 'fn_IQR', 'fn_med', '1xorder', 'min_size', 'min_size_pctg', 'min_size_kmeans', 'min_size_gmm', 'MTT']] = ['merge_similar', 'damp_IQR', 'fn_IQR', '1xorder', 'min_size', 'MTT'], merge_dist: Literal['auto', 'deder'] | float = 'auto', min_pctg: float = 0.3, select: Literal['avg', 'fn_mean_close', 'xi_med_close', 'medoid'] = 'medoid', freq_lim: tuple | None = None)

Bases: BaseRunParams

Parameters for the third step of clustering analysis (post-processing).

post_proc

‘min_size’, ‘min_size_pctg’, ‘min_size_kmeans’, ‘min_size_gmm’, ‘MTT’}

Post-processing steps to apply to clustering results.

Type:

list of {‘merge_similar’, ‘damp_IQR’, ‘fn_IQR’, ‘fn_med’, ‘1xorder’,

merge_dist

Threshold for merging similar clusters.

Type:

{float, ‘auto’, ‘deder’}

min_pctg

Minimum cluster size as a percentage of the largest cluster.

Type:

float

select

Method for selecting final clustering results.

Type:

{‘avg’, ‘fn_med_close’, ‘xi_med_close’, ‘medoid’}

freq_lim

Frequency range limits for filtering clusters.

Type:

tuple of float, optional

Warning

The post_proc list is applied sequentially, and the order of operations affects the results. Steps listed earlier in the sequence are applied before later ones. Additionally, the same step can appear multiple times in the list, and it will be applied each time it is encountered. Ensure the order and repetition are appropriate for your intended analysis.

class pyoma2.algorithms.data.run_params.pLSCFRunParams(*, ordmax: int, ordmin: int = 0, nxseg: int = 1024, method_SD: Literal['per', 'cor'] = 'per', pov: float = 0.5, sc: SCDictType = {'err_fn': 0.05, 'err_phi': 0.05, 'err_xi': 0.05}, hc: HCDictType = {'mpc_lim': 0.7, 'mpd_lim': 0.3, 'xi_max': 0.1})

Bases: BaseRunParams

Parameters for the poly-reference Least Square Complex Frequency (pLSCF) method.

ordmax

Maximum order for the analysis.

Type:

int

ordmin

Minimum order for the analysis. Default is 0.

Type:

int, optional

nxseg

Number of segments for the Power Spectral Density (PSD) estimation. Default is 1024.

Type:

int, optional

method_SD

Method used for spectral density estimation. Options are [‘per’, ‘cor’]. Default is ‘per’.

Type:

str, optional

pov

Percentage of overlap between segments for PSD estimation (only applicable for ‘per’ method). Default is 0.5.

Type:

float, optional

sc

Soft criteria for the analysis.

Type:

dict, optional

hc

Hard criteria for the analysis.

Type:

dict, optional