feat: uncertainty calculation; fix: various fix

dagghe · Jan 23, 2025 · 7634f44 · 7634f44
1 parent 2952bed
commit 7634f44
Show file tree

Hide file tree

Showing 33 changed files with 1,843 additions and 1,329 deletions.
diff --git a/.DS_Store b/.DS_Store
diff --git a/.virtual_documents/Examples/Example1.ipynb b/.virtual_documents/Examples/Example1.ipynb
@@ -0,0 +1,93 @@
+
+
+
+
+
+
+import os
+import sys
+import numpy as np
+# Add the directory we executed the script from to path:
+sys.path.insert(0, os.path.realpath('__file__'))
+
+# import the function to generate the example dataset
+from pyoma2.functions.gen import example_data
+
+# generate example data and results
+data, ground_truth = example_data()
+
+# Print the exact results
+np.set_printoptions(precision=3)
+print(f"the natural frequencies are: {ground_truth[0]} \n")
+print(f"the damping is: {ground_truth[2]} \n")
+print("the (column-wise) mode shape matrix: \n"
+f"{ground_truth[1]} \n")
+
+
+
+
+
+from pyoma2.setup.single import SingleSetup
+
+simp_5dof = SingleSetup(data, fs=600)
+
+
+
+
+
+# Decimate the data by factor 10
+simp_5dof.decimate_data(q=20)
+
+
+
+
+
+from pyoma2.algorithms.fdd import FDD
+from pyoma2.algorithms.ssi import SSIdat
+
+# Initialise the algorithms
+fdd = FDD(name="FDD", nxseg=1024, method_SD="cor")
+ssidat = SSIdat(name="SSIdat", br=30, ordmax=30)
+
+# Add algorithms to the class
+simp_5dof.add_algorithms(fdd, ssidat)
+
+# run
+simp_5dof.run_all()
+
+
+
+
+
+# plot singular values of the spectral density matrix
+_, _ = fdd.plot_CMIF(freqlim=(0,8))
+
+# plot the stabilisation diagram
+_, _ = ssidat.plot_stab(freqlim=(0,10),hide_poles=False)
+
+
+
+
+
+# get the modal parameters with the interactive plot
+# simp_ex.mpe_from_plot("SSIdat", freqlim=(0,10))
+
+# or manually
+simp_5dof.mpe("SSIdat", sel_freq=[0.89, 2.598, 4.095, 5.261, 6.], order="find_min")
+
+
+
+
+
+# dict of results
+ssidat_res = dict(ssidat.result)
+
+from pyoma2.functions.plot import plot_mac_matrix
+
+# print the results
+print(f"order out: {ssidat_res['order_out']} \n")
+print(f"the natural frequencies are: {ssidat_res['Fn']} \n")
+print(f"the dampings are: {ssidat_res['Xi']} \n")
+print("the (column-wise) mode shape matrix:")
+print(f"{ssidat_res['Phi'].real} \n")
+_, _ = plot_mac_matrix(ssidat_res['Phi'].real, ground_truth[1])
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -7,15 +7,30 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Fixed
+
+- uncertainty calculations for SSI algorithm
+- animation problem in pyvista
+- small fix (moved ax.grid()) in plt_data
+- updated docs
+
 ### Changed
 
 - Renamed `anim_mode_g2` to `anim_mode_geo2` in `GeometryMixin` class
 - Updated hierarchy for results and run_params classes
-- enhanced `fdd.plot_EFDDfit` error log
+- Renamed `plot_cluster()` method to `plot_freqvsdamp()`
+- SSI functions and classes re-organization:
+  - `cov_mm`method renamed to `cov`
+  - removed `ac2mp` function
+  - Hard criteria on MPC and MPD splitted
+  - HC on damping and on complex conjugate included into `SSI_poles`function
+  - order for run_param renamed to `order_in`
+  - Renamed uncertanties component from `xxx_cov`to `xxx_std`
 
 ### Added
 
 - pre commit in github workflow
+- clustering plotting functions to plot.py
 
 
 ## [1.0.0] - 2024-09-12

diff --git a/Examples/Example1.ipynb b/Examples/Example1.ipynb
diff --git a/Examples/Example2.ipynb b/Examples/Example2.ipynb
diff --git a/Examples/Example3.ipynb b/Examples/Example3.ipynb
diff --git a/Examples/Example4.ipynb b/Examples/Example4.ipynb
diff --git a/README.md b/README.md
@@ -12,14 +12,7 @@ This is the new and updated version of pyOMA module, a Python module designed fo
 With this update, we've transformed pyOMA from a basic collection of functions into a more sophisticated module that fully leverages the capabilities of Python classes.
 
 The module now supports analysis of both single and multi-setup data measurements, which includes handling multiple acquisitions with a mix of reference and roving sensors. We've also introduced interactive plots, allowing users to select desired modes for extraction directly from the plots generated by the algorithms. Additionally, a new feature enables users to define the geometry of the structures being tested, facilitating the visualization of mode shapes after modal results are obtained. The underlying functions of these classes have been rigorously revised, resulting in significant enhancements and optimizations.
-
-*03/09/2024:
-We have introduced uncertainty calculations for the SSIcov algorithm. Currently, this feature is
-supported only by the "cov_mm" method and provides covariances for natural frequencies and damping
-ratios only. We are actively working to extend this functionality to include uncertainties in mode
-shapes, and to make it available for the "cov_R" method and the SSIdat class (contributions from
-the community are welcome). Please note that these calculations can* **significantly** *increase
-computation time due to the extensive operations required on large matrices.*
+Since version 1.0.1, the uncertainty bounds of the modal properties can also be estimated for the SSI family of algorithms.
 
 ## Documentation
 
@@ -66,31 +59,3 @@ ____
 ![](docs/img/info.svg "")
 
 ____
-
-# Main Developers
-
-- **Dag Pasquale Pasca** *(Ph.D., Norwegian Institute of Wood Technology, Norsk Treteknisk Institutt, Norway)*
-
-  [ResearchGate](https://www.researchgate.net/profile/Dag-Pasquale-Pasca) • [GitHub](https://github.com/dagghe) • [Linkedin](https://www.linkedin.com/in/dag-pasca-33a947a7/)
-
-- **Diego Federico Margoni** *(Eng. M.Sc., Politecnico di Torino University, Italy)*
-
-  [GitHub](https://github.com/dfm88) • [Linkedin](https://www.linkedin.com/in/diego-federico-margoni-7568061a2)
-
-# Other Contributors
-
-- **Marco Martino Rosso** *(Ph.D., Politecnico di Torino University, Italy)*
-
-  [PoliTO](https://www.polito.it/personale?p=marco.rosso) • [ResearchGate](https://www.researchgate.net/profile/Marco-Martino-Rosso) • [GitHub](https://github.com/marco-rosso-m) • [Linkedin](https://www.linkedin.com/in/marco-martino-rosso-01952a201/)
-
-- **Angelo Aloisio** *(Ph.D., University of L’Aquila, Italy)*
-
-  [UnivAQ](https://www.ing.univaq.it/personale/scheda_personale.php?codice=693) • [ResearchGate](https://www.researchgate.net/profile/Angelo-Aloisio) • [Linkedin](https://www.linkedin.com/in/angelo-aloisio-3b344b148/)
-
-# Supervision and promotion
-
-- **Prof. Giuseppe Carlo Marano** *(Politecnico di Torino University, Italy)*
-
-  [PoliTO](https://www.polito.it/personale?p=giuseppe.marano) • [ArtIStE](http://www.civilml.polito.it/)
-
-![loghi per pyoma](https://github.com/user-attachments/assets/8ca0356a-ecb5-4e4e-9302-8df89ed37951)
diff --git a/docs/Example1 - Getting started.rst b/docs/Example1 - Getting started.rst
@@ -36,16 +36,16 @@ Now we can instantiate the SingleSetup class, passing the dataset and the sampli
 
     from pyoma2.setup.single import SingleSetup
 
-    simp_5dof = SingleSetup(data, fs=200)
+    simp_5dof = SingleSetup(data, fs=600)
 
 
 Since the maximum frequency is at approximately 6Hz, we can decimate the signal quite a bit.
 To do this we can call the ``decimate_data()`` method
 
 .. code:: python
 
-    # Decimate the data by factor 10
-    simp_5dof.decimate_data(q=10)
+    # Decimate the data
+    simp_5dof.decimate_data(q=30)
 
 
 To analise the data we need to instanciate the desired algorithm to use with a name and the required arguments.
@@ -89,7 +89,7 @@ or we can get the results "manually" with the ``mpe()`` method.
     # simp_ex.mpe_from_plot("SSIdat", freqlim=(0,10))
 
     # or manually
-    simp_5dof.mpe("SSIdat", sel_freq=[0.89, 2.598, 4.095, 5.261, 6.], order="find_min")
+    simp_5dof.mpe("SSIdat", sel_freq=[0.89, 2.598, 4.095, 5.261, 6.], order_in="find_min")
 
 
 Now we can now access all the results and compare them to the exact solution

diff --git a/docs/Example2 - Real dataset.rst b/docs/Example2 - Real dataset.rst
@@ -185,7 +185,7 @@ using the ``mpe()`` method.
     # Pali_ss.mpe_from_plot("SSIcov", freqlim=(0,5))
 
     # or directly
-    Pali_ss.mpe("SSIcov", sel_freq=[1.88, 2.42, 2.68], order=40)
+    Pali_ss.mpe("SSIcov", sel_freq=[1.88, 2.42, 2.68], order_in=40)
 
     # update dict of results
     ssi_res = dict(ssicov.result)

diff --git a/docs/Example3 - Multisetup PoSER.rst b/docs/Example3 - Multisetup PoSER.rst
@@ -78,15 +78,15 @@ remains the same as described in the example for the single setup.
    ss1.mpe(
          "SSIcov1",
          sel_freq=[2.63, 2.69, 3.43, 8.29, 8.42, 10.62, 14.00, 14.09, 17.57],
-         order=50)
+         order_in=50)
    ss2.mpe(
          "SSIcov2",
          sel_freq=[2.63, 2.69, 3.43, 8.29, 8.42, 10.62, 14.00, 14.09, 17.57],
-         order=40)
+         order_in=40)
    ss3.mpe(
          "SSIcov3",
          sel_freq=[2.63, 2.69, 3.43, 8.29, 8.42, 10.62, 14.00, 14.09, 17.57],
-         order=40)
+         order_in=40)
 
 .. figure:: /img/Ex3-Fig1.png
 .. figure:: /img/Ex3-Fig2.png

diff --git a/docs/Example4 - Multisetup PreGER.rst b/docs/Example4 - Multisetup PreGER.rst
@@ -96,7 +96,7 @@ poles and plot the mode shapes.
    msp.mpe(
          "SSIdat",
          sel_freq=[2.63, 2.69, 3.43, 8.29, 8.42, 10.62, 14.00, 14.09, 17.57],
-         order=80)
+         order_in=80)
 
    # plot mode shapes
    msp.plot_mode_geo1(alg_res=SSIdat.result, mode_nr=1, view="3D", scaleF=2)

diff --git a/docs/docu/2_2 Algo_ssi.rst b/docs/docu/2_2 Algo_ssi.rst
@@ -3,9 +3,7 @@ The ``ssi`` algorithm module
 
 This module implements the Stochastic Subspace Identification (SSI) [BPDG99]_, [MiDo11]_ algorithm in various forms,
 tailored for both single and multiple experimental setup scenarios [MiDo11]_, [DOME13]_. It includes classes and methods
-for conducting data-driven and covariance-driven SSI analyses. The primary focus of this module is
-on structural analysis and system identification, providing tools to process measurement data, extract
-modal parameters, and perform comprehensive system dynamics analysis.
+for conducting data-driven and covariance-driven SSI analyses, with optional uncertainty bounds estimation.
 
 Classes:
    :class:`.SSIdat`

diff --git a/docs/docu/3_4 result module.rst b/docs/docu/3_4 result module.rst
@@ -1,6 +1,8 @@
 The ``result`` module
 ---------------------
 
+These classes are were the results of the analyses are stored.
+
 .. Warning::
     The module is designed to be used as part of the pyOMA2 package and relies on its
     internal data structures and algorithms.

diff --git a/docs/docu/3_5 run_param module.rst b/docs/docu/3_5 run_param module.rst
@@ -1,6 +1,8 @@
 The ``run_params`` module
 -------------------------
 
+These classes are were the parameters used to run the analyses are stored.
+
 .. Warning::
     The module is designed to be used as part of the pyOMA2 package and relies on its
     internal data structures and algorithms.

diff --git a/docs/docu/4_2 gen.rst b/docs/docu/4_2 gen.rst
@@ -10,8 +10,9 @@ Functions:
     - :func:`.applymask`: Apply a mask to a list of arrays, filtering their values based on the mask.
     - :func:`.HC_conj`: Apply Hard validation Criteria, complex conjugates.
     - :func:`.HC_damp`: Apply Hard validation Criteria, damping.
-    - :func:`.HC_phi_comp`: Apply Hard validation Criteria, mode shapes complexity.
-    - :func:`.HC_cov`: Apply Hard validation Criteria, covariance.
+    - :func:`.HC_MPC`: Apply Hard validation Criteria, modal phase collinearity (MPC).
+    - :func:`.HC_MPD`: Apply Hard validation Criteria, modal phase deviation (MPD).
+    - :func:`.HC_CoV`: Apply Hard validation Criteria, Coefficient of Variation.
     - :func:`.SC_apply`: Apply Soft validation Criteria.
     - :func:`.dfphi_map_func`: Maps mode shapes to sensor locations and constraints.
     - :func:`.check_on_geo1`: Validates geometry1 data.
@@ -30,6 +31,8 @@ Functions:
     - :func:`.filter_data`: Apply a Butterworth filter to the input data.
     - :func:`.save_to_file`: Save the specified setup instance to a file.
     - :func:`.load_from_file`: Load a setup instance from a file.
+    - :func:`.read_excel_file`: Read an Excel file and return its contents as a dictionary.
+
 
 
 .. automodule:: pyoma2.functions.gen

diff --git a/docs/docu/4_3 ssi.rst b/docs/docu/4_3 ssi.rst
@@ -9,7 +9,6 @@ SSI, and extracting modal parameters from identified systems.
 
 Functions:
     - :func:`.build_hank`: Constructs a Hankel matrix from time series data.
-    - :func:`.ac2mp`: Converts state-space matrices (A, C) to modal parameters.
     - :func:`.SSI`: Performs system identification using the SSI method.
     - :func:`.SSI_fast`: Efficient implementation of the SSI system identification.
     - :func:`.SSI_poles`: Computes modal parameters from identified state-space models.

diff --git a/docs/docu/4_4 plot.rst b/docs/docu/4_4 plot.rst
@@ -8,10 +8,16 @@ and stabilization charts. They facilitate the intuitive interpretation of Operat
 Modal Analysis (OMA) results.
 
 Functions:
+    - :func:`.plot_dtot_hist`: Plot a histogram of the total distance matrix.
+    - :func:`.adjust_alpha`: Adjust the alpha (opacity) of a given color.
+    - :func:`.rearrange_legend_elements`: Rearrange legend elements into a column-wise ordering.
+    - :func:`.freq_vs_damp_plot`: Plot frequency versus damping, with points grouped by clusters.
+    - :func:`.stab_clus_plot`: Plots a stabilization chart of the poles of a system with clusters.
     - :func:`.CMIF_plot`: Visualizes the Complex Mode Indicator Function (CMIF).
     - :func:`.EFDD_FIT_plot`: Presents detailed plots for EFDD and FSDD algorithms.
     - :func:`.stab_plot`: Generates stabilization charts.
     - :func:`.cluster_plot`: Visualizes frequency-damping clusters.
+    - :func:`.svalH_plot`: Plot the singular values of the Hankel matrix.
     - :func:`.plt_nodes`: Function for plotting 3D geometrical representations.
     - :func:`.plt_lines`: Function for plotting 3D geometrical representations.
     - :func:`.plt_surf`: Function for plotting 3D geometrical representations.
@@ -22,6 +28,7 @@ Functions:
     - :func:`.plt_ch_info`: Generates comprehensive channel information plots.
     - :func:`.STFT`: Perform the Short Time Fourier Transform (STFT) to generate spectrograms.
     - :func:`.plot_mac_matrix`: Compute and plot the MAC matrix between the columns of two 2D arrays.
+    - :func:`.plot_mode_complexity`: Plot the complexity of a mode shape.
 
 .. automodule:: pyoma2.functions.plot
    :members:
diff --git a/docs/index.rst b/docs/index.rst
@@ -18,17 +18,10 @@ The module now supports analysis of both single and multi-setup data measurement
 handling multiple acquisitions with a mix of reference and roving sensors. We've also introduced
 interactive plots, allowing users to select desired modes for extraction directly from the plots
 generated by the algorithms. Additionally, a new feature enables users to define the geometry of
-the structures being tested, facilitating the visualization of mode shapes after modal results
-are obtained. The underlying functions of these classes have been rigorously revised, resulting
-in significant enhancements and optimizations.
-
-*03/09/2024:
-We have introduced uncertainty calculations for the SSIcov algorithm* [DLM13]_ *. Currently, this feature is
-supported only by the "cov_mm" method and provides covariances for natural frequencies and damping
-ratios only. We are actively working to extend this functionality to include uncertainties in mode
-shapes, and to make it available for the "cov_R" method and the SSIdat class (contributions from
-the community are welcome). Please note that these calculations can* **significantly** *increase
-computation time due to the extensive operations required on large matrices.*
+the structures being tested, facilitating the visualization of mode shapes after modal results are
+obtained. The underlying functions of these classes have been rigorously revised, resulting in
+significant enhancements and optimizations. Since version 1.0.1, the uncertainty bounds of the
+modal properties can also be estimated for the SSI family of algorithms.
 
 We provide four :doc:`examples` to show the modules capabilities:
 

diff --git a/src/.DS_Store b/src/.DS_Store
diff --git a/src/pyoma2/.DS_Store b/src/pyoma2/.DS_Store
diff --git a/src/pyoma2/algorithms/.DS_Store b/src/pyoma2/algorithms/.DS_Store