The plot module

This module, part of the pyOMA2 package, offers a suite of plotting functions designed specifically for use within the pyOMA2 module. These functions aid in visualizing modal analysis data, such as time histories, frequency responses, and stabilization charts. They facilitate the intuitive interpretation of Operational Modal Analysis (OMA) results.

Functions:

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

pyoma2.functions.plot.CMIF_plot(S_val: ndarray, freq: ndarray, freqlim: Tuple | None = None, nSv: str = 'all', fig: Figure | None = None, ax: Axes | None = None) → Tuple[Figure, Axes][source]

Plots the Complex Mode Indicator Function (CMIF) based on given singular values and frequencies.

Parameters:

  • S_val (ndarray) – A 3D array representing the singular values, with shape [nChannel, nChannel, nFrequencies].

  • freq (ndarray) – An array representing the frequency values corresponding to the singular values.

  • freqlim (tuple of float, optional) – The frequency range (lower, upper) for the plot. If None, includes all frequencies. Default is None.

  • nSv (int or str, optional) – The number of singular values to plot. If “all”, plots all singular values. Otherwise, should be an integer specifying the number of singular values. Default is “all”.

  • fig (matplotlib.figure.Figure, optional) – An existing matplotlib figure object to plot on. If None, a new figure is created. Default is None.

  • ax (matplotlib.axes.Axes, optional) – An existing axes object to plot on. If None, new axes are created on the provided or new figure. Default is None.

Returns:

  • fig (matplotlib.figure.Figure) – The matplotlib figure object.

  • ax (matplotlib.axes.Axes) – The axes object with the CMIF plot.

Raises:

ValueError – If nSv is not “all” and is not less than the number of singular values in S_val.

pyoma2.functions.plot.EFDD_FIT_plot(Fn: ndarray, Xi: ndarray, PerPlot: List[Tuple], freqlim: Tuple | None = None) → Tuple[Figure, List[Axes]][source]

Plot detailed results for the Enhanced Frequency Domain Decomposition (EFDD) and the Frequency Spatial Domain Decomposition (FSDD) algorithms.

Parameters:

  • Fn (ndarray) – An array containing the natural frequencies identified for each mode.

  • Xi (ndarray) – An array containing the damping ratios identified for each mode.

  • PerPlot (list of tuples) – A list where each tuple contains data for one mode. Each tuple should have the structure (freq, time, SDOFbell, Sval, idSV, normSDOFcorr, minmax_fit_idx, lam, delta).

  • freqlim (tuple of float, optional) – The frequency range (lower, upper) for the plots. If None, includes all frequencies. Default is None.

Returns:

  • figs (list of matplotlib.figure.Figure) – A list of matplotlib figure objects.

  • axs (list of lists of matplotlib.axes.Axes) – A list of lists containing axes objects for each figure.

Note

The function plots several aspects of the EFDD method for each mode, including the SDOF Bell function, auto-correlation function, and the selected portion for fit and the actual fit. Each mode’s plot includes four subplots, showing the details of the EFDD fit process, including identified frequency and damping ratio.

pyoma2.functions.plot.STFT(data: ndarray, fs: float, nxseg: int = 512, pov: float = 0.9, win: str = 'hann', freqlim: Tuple | None = None, ch_idx: int | List[int] | str = 'all') → Tuple[Figure, ndarray][source]

Perform the Short Time Fourier Transform (STFT) to generate spectrograms for given signal data.

This function computes the STFT for each channel in the signal data, visualising the frequency content of the signal over time. It allows for the selection of specific channels and customisation of the STFT computation parameters.

Parameters:

  • data (ndarray) – The input signal data.

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

  • nxseg (int, optional) – The number of points per segment for the STFT. Default is 512.

  • pov (float, optional) – The proportion of overlap between segments, expressed as a value between 0 and 1. Default is 0.9.

  • win (str, optional) – The type of window function to apply. Default is “hann”.

  • freqlim (tuple of float, optional) – The frequency limits (minimum, maximum) for the frequency axis of the spectrogram. If None, the full frequency range is used. Default is None.

  • ch_idx (int, list of int, or "all", optional) – The index (indices) of the channel(s) to compute the STFT for. If “all”, the STFT for all channels is computed. Default is “all”.

Returns:

  • figs (list of matplotlib.figure.Figure) – The list of figure objects created, each corresponding to a channel in the input data.

  • axs (list of matplotlib.axes.Axes) – The list of Axes objects corresponding to each figure, used for plotting the spectrograms.

Notes

The function visualises the magnitude of the STFT, showing how the frequency content of the signal changes over time. This is useful for analysing non-stationary signals. The function returns the figures and axes for further customisation or display.

pyoma2.functions.plot.adjust_alpha(color, alpha)[source]

Adjust the alpha (opacity) of a given color.

Parameters:

  • color (str or tuple) – The input color in any valid Matplotlib format (e.g., string name, hex code, or RGB tuple).

  • alpha (float) – The desired alpha value, between 0 (completely transparent) and 1 (completely opaque).

Returns:

The RGBA representation of the input color with the specified alpha value.

Return type:

tuple

pyoma2.functions.plot.cluster_plot(Fn: ndarray, Xi: ndarray, Lab: ndarray, ordmin: int = 0, freqlim: Tuple | None = None, hide_poles: bool = True, color_scheme: Literal['default', 'classic', 'high_contrast', 'viridis'] = 'default') → Tuple[Figure, Axes][source]

Plots the frequency-damping clusters of the identified poles.

Parameters:

  • Fn (ndarray) – An array containing the frequencies of poles for each model order and identification step.

  • Xi (ndarray) – An array containing the damping ratios associated with the poles in Fn.

  • Lab (ndarray) – Labels indicating whether each pole is stable (1) or unstable (0).

  • ordmin (int, optional) – The minimum model order to be displayed on the plot. Default is 0.

  • freqlim (tuple of float, optional) – The frequency limits for the x-axis as a tuple (min_freq, max_freq), by default None.

  • hide_poles (bool, optional) – Whether to hide the unstable poles, by default True.

  • color_scheme (Literal["default", "classic", "high_contrast", "viridis"], optional) – Color scheme to use for stable/unstable poles. Options: ‘default’, ‘classic’, ‘high_contrast’, ‘viridis’. Default is ‘default’ (colorblind-friendly).

Returns:

figmatplotlib.figure.Figure

The matplotlib figure object.

axmatplotlib.axes.Axes

The axes object with the stabilization chart.

Return type:

tuple

pyoma2.functions.plot.freq_vs_damp_plot(Fn_fl: ndarray, Xi_fl: ndarray, labels: ndarray, freqlim: Tuple | None = None, plot_noise: bool = False, name: str = None, fig: Figure | None = None, ax: Axes | None = None) → Tuple[Figure, Axes][source]

Plot frequency versus damping, with points grouped by clusters.

Parameters:

  • Fn_fl (np.ndarray) – Array of natural frequencies (flattened, 1d).

  • Xi_fl (np.ndarray) – Array of damping ratios (flattened, 1d).

  • labels (np.ndarray) – Cluster labels for each data point. Use -1 for noise.

  • freqlim (tuple of float, optional) – Tuple specifying the (min, max) limits for the frequency axis, by default None.

  • plot_noise (bool, optional) – Whether to include points labeled as noise (-1) in the plot, by default False.

  • fig (plt.Figure, optional) – Existing Matplotlib figure to plot on, by default None.

  • ax (plt.Axes, optional) – Existing Matplotlib axes to plot on, by default None.

Returns:

  • fig (plt.Figure) – The Matplotlib figure object containing the plot.

  • ax (plt.Axes) – The Matplotlib axes object containing the plot.

pyoma2.functions.plot.get_pole_colors(color_scheme: Literal['default', 'classic', 'high_contrast', 'viridis'] = 'default') → dict[source]

Get color scheme for stable and unstable poles.

Parameters:

color_scheme (str, optional) – Color scheme to use. Options: ‘default’, ‘classic’, ‘high_contrast’, ‘viridis’. Default is ‘default’ which uses colorblind-friendly colors.

Returns:

Dictionary with ‘stable’ and ‘unstable’ color keys.

Return type:

dict

pyoma2.functions.plot.plot_dtot_hist(dtot, bins='auto', sugg_co=True)[source]

Plot a histogram of the total distance matrix with optional suggested cut-off distances.

This function plots a histogram of the values in the input distance matrix or vector dtot. It overlays a kernel density estimate (KDE) and optionally indicates suggested cut-off distances for clustering using single-linkage and average-linkage methods.

Parameters:

  • dtot (ndarray) – The input distance data. If a 2D array is provided, the upper triangular elements (excluding the diagonal) are extracted. If a 1D array is provided, it is used as is.

  • bins (int or str, optional) – The number of bins for the histogram. Defaults to “auto”.

  • sugg_co (bool, optional) – Whether to compute and display suggested cut-off distances for clustering. Defaults to True.

Returns:

  • fig (matplotlib.figure.Figure) – The figure object containing the plot.

  • ax (matplotlib.axes.Axes) – The axes object for the histogram plot.

pyoma2.functions.plot.plot_mac_matrix(array1, array2, colormap='plasma', ax=None) → Tuple[Figure, Axes][source]

Compute and plot the MAC matrix between the columns of two 2D arrays.

Parameters:

  • array1 (np.ndarray) – The first 2D array with shape (n_modes, n_dofs).

  • array2 (np.ndarray) – The second 2D array with shape (n_modes, n_dofs).

  • colormap (str, optional) – The colormap to use for the plot. Default is ‘plasma’.

  • ax (matplotlib.axes.Axes, optional) – The axes object to plot on. If None, a new figure and axes will be created. Default is None.

Returns:

  • fig (matplotlib.figure.Figure) – The matplotlib figure object.

  • ax (matplotlib.axes.Axes) – The matplotlib axes object.

pyoma2.functions.plot.plot_mode_complexity(mode_shape)[source]

Plot the complexity of a mode shape.

pyoma2.functions.plot.plt_ch_info(data: ndarray, fs: float, nxseg: int = 1024, freqlim: Tuple | None = None, logscale: bool = False, ch_idx: int | List[int] | str = 'all', unit: str = 'unit') → Tuple[Figure, ndarray][source]

Plot channel information including time history, normalised auto-correlation, power spectral density (PSD), probability density function, and a normal probability plot for each channel in the data.

Parameters:

  • data (ndarray) – The input signal data.

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

  • nxseg (int, optional) – The number of points per segment.

  • freqlim (tuple of float, optional) – The frequency limits (min, max) for the PSD plot. If None, the full frequency range is used. Default is None.

  • logscale (bool, optional) – If True, the PSD plot will be in log scale (decibel). Otherwise, it will be in linear scale. Default is False.

  • ch_idx (int, list of int, or "all", optional) – The index (indices) of the channel(s) to plot. If “all”, information for all channels is plotted. Default is “all”.

  • unit (str, optional) – The unit of the input data for labelling the PSD plot. Default is “unit”.

Returns:

  • fig (matplotlib.figure.Figure) – The figure object containing all the plots.

  • axes (list of matplotlib.axes.Axes) – The list of axes objects corresponding to each subplot.

Note

This function is designed to provide a comprehensive overview of the signal characteristics for one or multiple channels of a dataset. It plots the time history, normalised auto-correlation, PSD, probability density function, and a normal probability plot for each specified channel.

pyoma2.functions.plot.plt_data(data: ndarray, fs: float, nc: int = 1, names: List[str] | None = None, unit: str = 'unit', show_rms: bool = False) → Tuple[Figure, ndarray][source]

Plots time series data for multiple channels, with an option to include the Root Mean Square (RMS) of each signal.

Parameters:

  • data (ndarray) – A 2D array with dimensions [number of data points, number of channels], representing signal data for multiple channels.

  • fs (float) – Sampling frequency.

  • nc (int, optional) – Number of columns for subplots, indicating how many subplots per row to display. Default is 1.

  • names (list of str, optional) – Names of the channels, used for titling each subplot if provided. Default is None.

  • unit (str, optional) – The unit to display on the y-axis label. Default is “unit”.

  • show_rms (bool, optional) – If True, includes the RMS of each signal on the corresponding subplot. Default is False.

Returns:

  • fig (matplotlib.figure.Figure) – The matplotlib figure object.

  • axs (array of matplotlib.axes.Axes) – An array of axes objects for the generated subplots.

Note

Plots each channel in its own subplot for comparison. Supports multiple columns and adjusts the number of rows based on channels and columns. If show_rms is True, the RMS value of each signal is plotted as a constant line.

pyoma2.functions.plot.plt_lines(ax: Axes, nodes_coord: ndarray, lines: ndarray, alpha: float = 1.0, color: str = 'k', initial_coord: ndarray = None) → Axes[source]

Plots lines between specified nodes in a 3D plot on the provided axes.

Parameters:

  • ax (matplotlib.axes.Axes) – The axes object where the lines will be plotted. This should be a 3D axes.

  • nodes_coord (ndarray) – A 2D array with dimensions [number of nodes, 3], representing the coordinates (x, y, z) of each node.

  • lines (ndarray) – A 2D array with dimensions [number of lines, 2]. Each row represents a line, with the two elements being indices into nodes_coord indicating the start and end nodes of the line.

  • alpha (float, optional) – The alpha blending value for the lines, between 0 (transparent) and 1 (opaque). Default is 1.

  • color (str or list of str, optional) – Color or list of colors for the lines. Default is “k” (black). If ‘cmap’ is provided, initial_coord must be specified.

  • initial_coord (ndarray, optional) – A 2D array with dimensions [number of nodes, 3], representing the initial coordinates (x, y, z) of each node. Required if color is ‘cmap’.

Returns:

The modified axes object with the lines plotted.

Return type:

matplotlib.axes.Axes

Note

This function is designed to work with 3D plots and adds line representations between nodes in an existing 3D plot.

pyoma2.functions.plot.plt_nodes(ax: Axes, nodes_coord: ndarray, alpha: float = 1.0, color: str = 'k', initial_coord: ndarray = None) → Axes[source]

Plots nodes coordinates in a 3D scatter plot on the provided axes.

Parameters:

  • ax (matplotlib.axes.Axes) – The axes object where the nodes will be plotted. This should be a 3D axes.

  • nodes_coord (ndarray) – A 2D array with dimensions [number of nodes, 3], representing the coordinates (x, y, z) of each node.

  • alpha (float, optional) – The alpha blending value, between 0 (transparent) and 1 (opaque). Default is 1.

  • color (str or list of str, optional) – Color or list of colors for the nodes. Default is “k” (black). If ‘cmap’ is provided, initial_coord must be specified.

  • initial_coord (ndarray, optional) – A 2D array with dimensions [number of nodes, 3], representing the initial coordinates (x, y, z) of each node. Required if color is ‘cmap’.

Returns:

The modified axes object with the nodes plotted.

Return type:

matplotlib.axes.Axes

Note

This function is designed to work with 3D plots and adds node representations to an existing 3D plot.

pyoma2.functions.plot.plt_quiver(ax: Axes, nodes_coord: ndarray, directions: ndarray, scaleF: float = 2, color: str = 'red', names: List[str] | None = None, color_text: str = 'red', method: str = '1') → Axes[source]

Plots vectors (arrows) on a 3D plot to represent directions and magnitudes at given node coordinates.

Parameters:

  • ax (matplotlib.axes.Axes) – The axes object where the vectors will be plotted. This should be a 3D axes.

  • nodes_coord (ndarray) – A 2D array with dimensions [number of nodes, 3], representing the coordinates (x, y, z) of each node.

  • directions (ndarray) – A 2D array with the same shape as nodes_coord, representing the direction and magnitude vectors originating from the node coordinates.

  • scaleF (float, optional) – Scaling factor for the magnitude of the vectors. Default is 2.

  • color (str, optional) – Color of the vectors. Default is “red”.

  • names (list of str, optional) – Names or labels for each vector. If provided, labels are placed at the end of each vector. Default is None.

  • color_text (str, optional) – Color of the text labels. Default is “red”.

  • method (str, optional) – Method for arrow plotting: ‘1’ for quiver, ‘2’ for line plots. Default is ‘1’.

Returns:

The modified axes object with the vectors plotted.

Return type:

matplotlib.axes.Axes

Note

Designed to work with 3D plots, allowing for the visualization of vector fields or directional data. directions array determines the direction and magnitude of the arrows, while nodes_coord specifies their starting points.

pyoma2.functions.plot.plt_surf(ax: Axes, nodes_coord: ndarray, surf: ndarray, alpha: float = 0.5, color: str = 'cyan', initial_coord: ndarray = None) → Axes[source]

Plots a 3D surface defined by nodes and surface triangulation on the provided axes.

Parameters:

  • ax (matplotlib.axes.Axes) – The axes object where the surface will be plotted. This should be a 3D axes.

  • nodes_coord (ndarray) – A 2D array with dimensions [number of nodes, 3], representing the coordinates (x, y, z) of each node.

  • surf (ndarray) – A 2D array specifying the triangles that make up the surface. Each row represents a triangle, with the three elements being indices into nodes_coord indicating the vertices of the triangle.

  • alpha (float, optional) – The alpha blending value for the surface, between 0 (transparent) and 1 (opaque). Default is 0.5.

  • color (str, optional) – Color for the surface. Default is “cyan”.

Returns:

The modified axes object with the 3D surface plotted.

Return type:

matplotlib.axes.Axes

Note

This function is designed for plotting 3D surfaces in a 3D plot. It uses matplotlib.tri.Triangulation for creating a triangulated surface. Ideal for visualizing complex surfaces or meshes in a 3D space.

pyoma2.functions.plot.rearrange_legend_elements(legend_elements, ncols)[source]

Rearrange legend elements into a column-wise ordering.

Parameters:

  • legend_elements (list of matplotlib.lines.Line2D) – A list of legend elements to be rearranged.

  • ncols (int) – The number of columns to arrange the legend elements into.

Returns:

A reordered list of legend elements arranged column-wise.

Return type:

list

pyoma2.functions.plot.set_ax_options(ax: Axes, bg_color: str = 'w', remove_fill: bool = True, remove_grid: bool = True, remove_axis: bool = True, add_orig: bool = True, scaleF: float = 1) → Axes[source]

Configures various display options for a given matplotlib 3D axes object.

Parameters:

  • ax (matplotlib.axes._subplots.Axes3DSubplot) – The 3D axes object to be configured.

  • bg_color (str, optional) – Background color for the axes. Default is “w” (white).

  • remove_fill (bool, optional) – If True, removes the fill from the axes panes. Default is True.

  • remove_grid (bool, optional) – If True, removes the grid from the axes. Default is True.

  • remove_axis (bool, optional) – If True, turns off the axis lines, labels, and ticks. Default is True.

  • add_orig (bool, optional) – If True, adds origin lines for the x, y, and z axes in red, green, and blue, respectively. Default is True.

Returns:

The modified 3D axes object with the applied configurations.

Return type:

matplotlib.axes._subplots.Axes3DSubplot

Note

Customizes the appearance of 3D plots. Controls background color, fill, grid, and axis visibility.

pyoma2.functions.plot.set_view(ax: Axes, view: str) → Axes[source]

Sets the viewing angle of a 3D matplotlib axes object based on a predefined view option.

Parameters:

  • ax (matplotlib.axes.Axes) – The 3D axes object whose view angle is to be set.

  • view (str) – A string specifying the desired view. Options include “3D”, “xy”, “xz”, and “yz”.

Returns:

The modified axes object with the new view angle set.

Return type:

matplotlib.axes.Axes

Raises:

ValueError – If the ‘view’ parameter is not one of the specified options.

Note

Useful for quickly setting the axes to a standard viewing angle, especially in 3D visualizations. View options: “3D” (azimuth -60, elevation 30), “xy” (top-down), “xz” (side, along y-axis), “yz” (side, along x-axis).

pyoma2.functions.plot.stab_clus_plot(Fn_fl: ndarray, order_fl: ndarray, labels: ndarray, step: int, ordmax: int, ordmin: int = 0, freqlim: Tuple[float, float] | None = None, Fn_std: ndarray = None, plot_noise: bool = False, name: str = None, fig: Figure | None = None, ax: Axes | None = None) → Tuple[Figure, Axes][source]

Plots a stabilization chart of the poles of a system with clusters indicated by colors. The legend labels clusters as “Cluster 1”, “Cluster 2”, …, “Cluster N”, and “-1” as “Noise”. Additionally, adds a vertical line at the median frequency of each cluster. Optionally, the noise cluster can be excluded from the plot.

Parameters:

  • Fn_fl (np.ndarray) – Frequency values.

  • order_fl (np.ndarray) – Model order values.

  • labels (np.ndarray) – Cluster labels for each point.

  • step (int) – Step parameter (usage not shown in the plot).

  • ordmax (int) – Maximum order for y-axis limit.

  • ordmin (int, optional) – Minimum order for y-axis limit, by default 0.

  • freqlim (tuple of float, optional) – Frequency limits for x-axis, by default None.

  • Fn_std (np.ndarray, optional) – Standard deviation for frequency, by default None.

  • fig (plt.Figure, optional) – Existing figure to plot on, by default None.

  • ax (plt.Axes, optional) – Existing axes to plot on, by default None.

  • plot_noise (bool, optional) – Whether to include the noise cluster in the plot, by default False.

Returns:

  • fig (plt.Figure) – The matplotlib Figure object containing the plot.

  • ax (plt.Axes) – The matplotlib Axes object containing the plot.

pyoma2.functions.plot.stab_plot(Fn: ndarray, Lab: ndarray, step: int, ordmax: int, ordmin: int = 0, freqlim: Tuple | None = None, hide_poles: bool = True, Fn_std: array = None, fig: Figure | None = None, ax: Axes | None = None, color_scheme: Literal['default', 'classic', 'high_contrast', 'viridis'] = 'default') → Tuple[Figure, Axes][source]

Plots a stabilization chart of the poles of a system.

Parameters:

  • Fn (np.ndarray) – The frequencies of the poles.

  • Lab (np.ndarray) – Labels indicating whether each pole is stable (1) or unstable (0).

  • step (int) – The step size between model orders.

  • ordmax (int) – The maximum model order.

  • ordmin (int, optional) – The minimum model order, by default 0.

  • freqlim (tuple, optional) – The frequency limits for the x-axis as a tuple (min_freq, max_freq), by default None.

  • hide_poles (bool, optional) – Whether to hide the unstable poles, by default True.

  • fig (plt.Figure, optional) – A matplotlib Figure object, by default None.

  • ax (plt.Axes, optional) – A matplotlib Axes object, by default None.

  • Fn_std (np.ndarray, optional) – The covariance of the frequencies, used for error bars, by default None.

  • color_scheme (str, optional) – Color scheme to use for stable/unstable poles. Options: ‘default’, ‘classic’, ‘high_contrast’, ‘viridis’. Default is ‘default’ (colorblind-friendly).

Returns:

  • fig (plt.Figure) – The matplotlib Figure object containing the plot.

  • ax (plt.Axes) – The matplotlib Axes object containing the plot.

pyoma2.functions.plot.svalH_plot(H: ndarray, br: int, iter_n: int = None, fig: Figure | None = None, ax: Axes | None = None) → Tuple[Figure, Axes][source]

Plot the singular values of the Hankel matrix.