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.

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 package. Each class defines parameters for a specific algorithm or step in a clustering workflow.

class pyoma2.algorithms.data.run_params.BaseRunParams

Bases: BaseModel

Base class for storing run parameters for modal analysis algorithms.

This class configures Pydantic to: - Allow attributes to be set from class defaults or keyword arguments. - Forbid any extra fields not defined in subclasses.

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

Bases: BaseModel

Main class for clustering analysis orchestration.

name

Name of the clustering instance.

Type:

str

steps

Tuple of Step1, Step2, and Step3 instances defining the clustering workflow. If None, steps are assembled automatically based on quick.

Type:

tuple[Step1, Step2, Step3], optional

quick

Predefined clustering configuration. Supported values: [‘Magalhaes’, ‘Reynders’, ‘Neu’, ‘Kvaale’, ‘Dederichs’,

‘hdbscan’, ‘affinity’, ‘spectral’, ‘optics’, ‘hier_avg’, ‘hier_sing’, ‘hier_sing_nodc’].

If provided and steps is None, assemble_steps will populate steps.

Type:

str, optional

freqlim

Global frequency range limits (min, max) for clustering. Passed to Step3 if using a quick configuration.

Type:

tuple[float, float], optional

assemble_steps(freqlim)

Populate steps automatically when quick is specified and steps is None.

This method runs after model initialization and validation. It reads self.quick and constructs Step1, Step2, and Step3 instances according to predefined strategies. If quick is not recognized, raises AttributeError.

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

Bases: BaseRunParams

Run parameters for the Enhanced Frequency Domain Decomposition (EFDD) method.

nxseg

Number of points per segment used in spectral density estimation. Default: 1024.

Type:

int

method_SD

Method for spectral density estimation: - ‘per’: Periodogram - ‘cor’: Correlation-based Default: ‘per’.

Type:

{‘per’, ‘cor’}

pov

Percentage of overlap between segments when method_SD=’per’. Must be between 0.0 and 1.0. Default: 0.5.

Type:

float

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

Bases: BaseRunParams

Run parameters for the Frequency Domain Decomposition (FDD) method.

nxseg

Number of points per segment used in spectral density estimation. Default: 1024.

Type:

int

method_SD

Method for spectral density estimation: - ‘per’: Periodogram - ‘cor’: Correlation-based Default: ‘per’.

Type:

{‘per’, ‘cor’}

pov

Percentage of overlap between segments when method_SD=’per’. Must be between 0.0 and 1.0. Default: 0.5.

Type:

float

class pyoma2.algorithms.data.run_params.HCDictType

Bases: TypedDict

Hard validation criteria (HC) dictionary.

xi_max

Maximum allowable damping ratio. Defaults to None (no limit).

Type:

float, optional

mpc_lim

Modal Phase Collinearity (MPC) limit. Defaults to None.

Type:

float, optional

mpd_lim

Mean Phase Deviation (MPD) limit. Defaults to None.

Type:

float, optional

CoV_max

Maximum coefficient of variation (CoV) of the frequencies. Only used when `calc_unc=True`(i.e., when uncertainty bounds of modal parameters are calculated). Defaults to None.

Type:

float, optional

class pyoma2.algorithms.data.run_params.SCDictType

Bases: TypedDict

Soft validation criteria (SC) dictionary.

err_fn

Maximum threshold for relative natural frequency difference. Default: 0.05.

Type:

float

err_xi

Maximum threshold for relative damping difference. Default: 0.1.

Type:

float

err_phi

Maximum threshold for Modal Assurance Criterion (MAC) difference. Default: 0.05.

Type:

float

class pyoma2.algorithms.data.run_params.SSIRunParams(*, br: int = 20, method: Literal['cov', 'cov_R', 'dat', 'IOcov'] | None = 'cov', 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.1}, hc: HCDictType = {'CoV_max': 0.2, 'mpc_lim': 0.5, 'mpd_lim': 0.5, 'xi_max': 0.2}, calc_unc: bool = False, nb: int = 50, U: ndarray[tuple[Any, ...], dtype[float64]] | None = None, spetrum: bool = False, fdd_run_params: FDDRunParams | None = None)

Bases: BaseRunParams

Run parameters for the Stochastic Subspace Identification (SSI) method.

br

Number of block rows in the Hankel matrix. Default: 20.

Type:

int

method

Variant of SSI algorithm to use: - ‘cov’: Covariance-driven - ‘cov_R’: Covariance-driven with autocorrelation - ‘dat’: Data-driven - ‘IOcov’: Input-Output covariance-driven Default: ‘cov’.

Type:

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

ref_ind

List of reference sensor indices for subspace identification. Default: None.

Type:

list[int], optional

ordmin

Minimum model order to evaluate. Default: 0.

Type:

int

ordmax

Maximum model order to evaluate. Default: None (no upper limit).

Type:

int, optional

step

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

Type:

int

sc

Soft validation criteria dictionary. Default: {‘err_fn’: 0.05, ‘err_xi’: 0.1, ‘err_phi’: 0.05}.

Type:

SCDictType

hc

Hard validation criteria dictionary. Default: {‘xi_max’: 0.2, ‘mpc_lim’: 0.5, ‘mpd_lim’: 0.5, ‘CoV_max’: 0.2}.

Type:

HCDictType

calc_unc

Whether to calculate uncertainty bounds for modal parameters. Default: False.

Type:

bool

nb

Number of bootstrap samples for uncertainty calculation. Default: 50.

Type:

int

U

Array of input time series (if using input-output SSI). Default: None.

Type:

npt.NDArray[np.float64], optional

spetrum

Whether to compute the frequency spectrum. Default: False.

Type:

bool

fdd_run_params

Instance of FDDRunParams to pass FDD parameters to SSI. Default: None.

Type:

FDDRunParams, optional

class pyoma2.algorithms.data.run_params.Step1(*, hc: bool | Literal['after'] = True, hc_dict: HCDictType = {'CoV_max': 0.15, 'mpc_lim': 0.8, 'mpd_lim': 0.3, 'xi_max': 0.15}, sc: bool | Literal['after'] = False, sc_dict: SCDictType = {'err_fn': 0.03, 'err_phi': 0.05, 'err_xi': 0.05}, pre_cluster: bool = False, pre_clus_typ: Literal['GMM', 'kmeans', 'FCMeans'] = '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. If ‘after’, HC is applied after pre-clustering. Default: True.

Type:

bool or {‘after’}

hc_dict

Hard validation criteria dictionary. Used only if hc=True. Default: {‘xi_max’: 0.15, ‘mpc_lim’: 0.8, ‘mpd_lim’: 0.3, ‘CoV_max’: 0.15}.

Type:

HCDictType

sc

Whether to apply soft validation criteria (SC) to the poles. If ‘after’, SC is applied after pre-clustering. Default: False.

Type:

bool or {‘after’}

sc_dict

Soft validation criteria dictionary. Used only if sc=True. Default: {‘err_fn’: 0.03, ‘err_xi’: 0.05, ‘err_phi’: 0.05}.

Type:

SCDictType

pre_cluster

Whether to perform a pre-clustering step before validation. Default: False.

Type:

bool

pre_clus_typ

Type of pre-clustering algorithm to use. Default: ‘GMM’.

Type:

{‘GMM’, ‘kmeans’, ‘FCMeans’}

pre_clus_dist

‘dfn’, ‘dxi’, ‘dlambda’, ‘dMAC’, ‘dMPC’, ‘dMPD’, ‘MPC’, ‘MPD’

Type:

list of {

}

Distance metrics to use for pre-clustering. Default: [‘dlambda’, ‘dMAC’].

transform

Data transformation method to apply before clustering. Default: None.

Type:

{‘box-cox’}, optional

class pyoma2.algorithms.data.run_params.Step2(*, distance: list[Literal['dfn', 'dxi', 'dlambda', 'dMAC', 'dMPC', 'dMPD']] = ['dlambda', 'dMAC'], weights: Literal['tot_one'] | list[float] | None = 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 | Literal['auto'] | None = 'auto', n_clusters: int | Literal['auto'] | None = None)

Bases: BaseRunParams

Parameters for the second step of clustering analysis.

distance

‘dfn’, ‘dxi’, ‘dlambda’, ‘dMAC’, ‘dMPC’, ‘dMPD’

Type:

list of {

}

Distance metrics for clustering. Default: [‘dlambda’, ‘dMAC’].

weights

Weighting scheme for distance metrics. If ‘tot_one’, all distances sum to one. If a list, its length must equal len(distance). Default: None.

Type:

{‘tot_one’} or list[float], optional

sqrtsqr

Whether to apply square-root to the sum of squares of distances. Default: False.

Type:

bool

algo

Clustering algorithm to use. Default: ‘hierarc’.

Type:

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

dc

Distance threshold for hierarchical clustering (only if algo=’hierarc’). - ‘auto’: Automatic threshold - ‘mu+2sig’: Mean plus two standard deviations - ‘95weib’: 95th percentile of Weibull fit If None, n_clusters must be specified. Default: ‘auto’.

Type:

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

linkage

Linkage criterion for hierarchical clustering (only if algo=’hierarc’). Default: ‘average’.

Type:

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

min_size

Minimum cluster size for ‘hdbscan’ or ‘optics’. Default: ‘auto’.

Type:

int or {‘auto’}, optional

n_clusters

Number of clusters for ‘spectral’ or ‘hierarc’ (if dc=None). Default: None.

Type:

int or {‘auto’}, optional

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', 'ABP']] = ['merge_similar', 'damp_IQR', 'fn_IQR', '1xorder', 'min_size_pctg', 'MTT'], merge_dist: Literal['auto', 'deder'] | float = 'auto', min_pctg: float = 0.3, select: Literal['avg', 'fn_mean_close', 'xi_med_close', 'medoid'] = 'medoid', freqlim: tuple[float, float] | None = None)

Bases: BaseRunParams

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

post_proc

• ‘merge_similar’: Merge similar clusters.

• ‘damp_IQR’: Damp clusters based on Interquartile Range (IQR) of damping.

• ‘fn_IQR’: Filter clusters based on IQR of natural frequencies.

• ‘fn_med’: Filter clusters based on median natural frequencies.

• ‘1xorder’: Filter clusters allowing 1 pole per order.

• ‘min_size’: Filter clusters based on minimum size (from Step2).

• ‘min_size_pctg’: Filter clusters based on minimum size as a percentage of the largest cluster.

• ‘min_size_kmeans’: Filter clusters based on minimum size using k-means.

• ‘min_size_gmm’: Filter clusters based on minimum size using Gaussian Mixture Models.

• ‘MTT’: Filter clusters based on Modified Thompson Tau technique.

• ‘ABP’: Filter clusters based on Adjusted boxplot technique.

Type:

list of post-processing steps to apply to clustering results:

merge_dist

Threshold for merging similar clusters. Default: ‘auto’.

Type:

float or {‘auto’, ‘deder’}

min_pctg

Minimum cluster size expressed as a fraction of the largest cluster. Default: 0.3.

Type:

float

select

Method for selecting the final representative cluster: - ‘avg’: Average of each cluster. - ‘fn_mean_close’: Cluster with mean natural frequency closest to overall mean. - ‘xi_med_close’: Cluster with median damping ratio closest to overall median. - ‘medoid’: Actual medoid of the cluster. Default: ‘medoid’.

Type:

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

freqlim

Frequency range limits (min, max) to filter clusters. Default: None.

Type:

tuple[float, 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

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

ordmax

Maximum model order for the analysis. (Required)

Type:

int

ordmin

Minimum model order for the analysis. Default: 0.

Type:

int

nxseg

Number of points per segment for Power Spectral Density (PSD) estimation. Default: 1024.

Type:

int

method_SD

Method for PSD estimation: - ‘per’: Periodogram - ‘cor’: Correlation-based Default: ‘per’.

Type:

{‘per’, ‘cor’}

pov

Percentage of overlap between segments when method_SD=’per’. Must be between 0.0 and 1.0. Default: 0.5.

Type:

float

sc

Soft validation criteria dictionary. Default: {‘err_fn’: 0.05, ‘err_xi’: 0.05, ‘err_phi’: 0.05}.

Type:

SCDictType

hc

Hard validation criteria dictionary. Default: {‘xi_max’: 0.1, ‘mpc_lim’: 0.7, ‘mpd_lim’: 0.3}.

Type:

HCDictType