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[float, float] | None = None, nSv: int | str = 'all', fig: Figure | None = None, ax: Axes | None = None) → Tuple[Figure, Axes][source]

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

Parameters:

  • S_val (ndarray, shape (n_channel, n_channel, n_frequencies)) – A 3D array representing the singular values of the spectral matrix at each frequency.

  • freq (ndarray, shape (n_frequencies,)) – Frequency vector corresponding to the third axis of S_val.

  • freqlim (tuple(float, float), optional) – Frequency limits for the x-axis as (min_freq, max_freq). If None, the full frequency range is used.

  • nSv (int or "all", optional) – The number of singular values to plot per mode. If “all”, all singular values are plotted. Otherwise, must be an integer less than or equal to the number of modes. Defaults to “all”.

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

  • ax (matplotlib.axes.Axes, optional) – Existing axes to plot on. If None, new axes are created.

Returns:

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

  • ax (matplotlib.axes.Axes) – The Matplotlib axes object containing the CMIF curves.

Raises:

ValueError – If nSv is not “all” and is greater than the number of modes in S_val.

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

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

For each mode in PerPlot, this function creates a 2x2 subplot figure showing: 1. The Spectral Density Function (SDOF bell) compared to the spectrum peak. 2. The normalized autocorrelation function over time. 3. The selected portion of the autocorrelation used for the damping fit. 4. The linear fit to ln(r0/|rk|) vs. index of extrema, from which frequency and damping are derived.

Parameters:

  • Fn (ndarray, shape (n_modes,)) – Array of natural frequencies identified for each mode.

  • Xi (ndarray, shape (n_modes,)) – Array of damping ratios identified for each mode.

  • PerPlot (list of tuples, length = n_modes) – Each tuple corresponds to one mode and contains: (freq, time, SDOFbell, Sval, idSV, normSDOFcorr, minmax_fit_idx, lam, delta) - freq : ndarray of frequency values - time : ndarray of time lags for autocorrelation - SDOFbell : ndarray of SDOF bell function values - Sval : ndarray of spectral values used to compute SDOFbell - idSV : indices of frequency bins at which SDOFbell is evaluated - normSDOFcorr : normalized autocorrelation values - minmax_fit_idx : indices of minima/maxima in autocorrelation used for fit - lam : slope parameter used in damping fit - delta : values of 2 * ln(r0 / |rk|) used for linear regression

  • freqlim (tuple(float, float), optional) – Frequency axis limits for the first subplot (SDOF bell) as (min_freq, max_freq). If None, the full frequency range is shown.

Returns:

  • figs (list of matplotlib.figure.Figure) – List of figure objects, one per mode.

  • axs (list of list of matplotlib.axes.Axes) – Nested list of axes for each figure: [[ax1, ax2, ax3, ax4], …] for each mode.

Notes

  • Subplot arrangement:

    (ax1) SDOF Bell vs. normalized spectral peak (ax2) Normalized autocorrelation function (ax3) Portion of autocorrelation selected for fit (highlighted extrema) (ax4) Linear fit for 2 ln(r0/|rk|) vs. extrema index, annotated with Fn and Xi

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

Compute and plot the Short-Time Fourier Transform (STFT) spectrogram for each channel.

Parameters:

  • data (ndarray, shape (n_samples, n_channels)) – Time-domain input signal data.

  • fs (float) – Sampling frequency in Hz.

  • nxseg (int, optional) – Window (segment) length for STFT in samples. Default is 512.

  • pov (float, optional) – Proportion of overlap between segments (0 < pov < 1). Default is 0.9.

  • win (str, optional) – Window function name for STFT (e.g., “hann”). Default is “hann”.

  • freqlim (tuple(float, float), optional) – Frequency limits for plotting as (min_freq, max_freq). If None, full range is used.

  • ch_idx (int, list of int, or "all", optional) – Index or indices of channels to process. If “all”, all channels are used. Default is “all”.

Returns:

  • figs (list of matplotlib.figure.Figure) – List of figures created, one per channel.

  • axs (list of matplotlib.axes.Axes) – List of axes objects corresponding to each figure’s spectrogram plot.

Notes

  • Uses SciPy’s signal.stft function to compute the complex STFT.

  • Plot uses pcolormesh of the magnitude of the STFT.

  • If freqlim is provided, the frequency axis is cropped accordingly.

pyoma2.functions.plot.adjust_alpha(color: str | tuple, alpha: float) → tuple[source]

Adjust the alpha (opacity) of a given color.

Parameters:

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

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

Returns:

rgba – The RGBA representation of the input color with the specified alpha applied.

Return type:

tuple

pyoma2.functions.plot.cluster_plot(Fn: ndarray, Xi: ndarray, Lab: ndarray, freqlim: Tuple[float, float] | None = None, hide_poles: bool = True) → Tuple[Figure, Axes][source]

Plot a frequency-damping clustering chart, marking stable vs unstable poles.

Parameters:

  • Fn (ndarray, shape (n_modes, n_orders)) – 2D array of frequencies for each pole, arranged by mode and order.

  • Xi (ndarray, shape (n_modes, n_orders)) – 2D array of damping ratios corresponding to each pole. Same shape as Fn.

  • Lab (ndarray, shape (n_modes, n_orders)) – 2D array of labels indicating whether each pole is stable (1) or unstable (0).

  • freqlim (tuple(float, float), optional) – Frequency axis limits as (min_freq, max_freq). If None, full range is used.

  • hide_poles (bool, optional) – If True, only stable poles are plotted. If False, both stable and unstable are plotted.

Returns:

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

  • ax (matplotlib.axes.Axes) – The axes object containing the plotted clusters.

Notes

  • Uses green circles for stable poles, red circles for unstable poles (if shown).

  • Sets equal aspect by default.

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.plot_dtot_hist(dtot: ndarray, bins: int | str = 'auto', sugg_co: bool = True) → Tuple[Figure, Axes][source]

Plot a histogram of the total distance data 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 (including the diagonal) are extracted and flattened. If a 1D array is provided, it is used directly.

  • bins (int or str, optional) – The number of bins or binning strategy 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 histogram and KDE plot.

  • ax (matplotlib.axes.Axes) – The axes object for the histogram (primary y-axis). The KDE is plotted on a secondary y-axis.

Notes

  • If dtot is 2D, all entries from the upper triangular part (k=0) are used.

  • Uses SciPy’s gaussian_kde to overlay a continuous density estimate.

  • For suggested cut-offs:

    • Single-linkage: the first local maximum of the KDE.

    • Average-linkage: the first local minimum of the KDE.

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

Compute and plot the Modal Assurance Criterion (MAC) matrix between two sets of mode shapes.

Parameters:

  • array1 (ndarray, shape (n_dofs, n_modes1)) – First set of mode shape vectors as columns.

  • array2 (ndarray, shape (n_dofs, n_modes2)) – Second set of mode shape vectors as columns.

  • colormap (str, optional) – Colormap name for the heatmap. Default is “plasma”.

  • ax (matplotlib.axes.Axes, optional) – Existing axes to plot on. If None, creates a new figure and axes.

Returns:

  • fig (matplotlib.figure.Figure) – The figure object containing the MAC matrix heatmap.

  • ax (matplotlib.axes.Axes) – The axes object containing the heatmap.

Raises:

ValueError – If either array1 or array2 has fewer than 2 modes (columns).

Notes

  • The MAC value between mode i of array1 and mode j of array2 is defined as: |(phi1_i^H phi2_j)|^2 / [(phi1_i^H phi1_i)(phi2_j^H phi2_j)].

  • Calls the MAC function from .gen to compute the matrix.

pyoma2.functions.plot.plot_mode_complexity(mode_shape: ndarray | List[complex]) → Tuple[Figure, Axes][source]

Plot the complexity of a mode shape on a polar coordinate plot.

Each element of mode_shape is a complex number; its magnitude and phase are represented as arrows radiating from the origin. Principal directions at 0° and 180° are highlighted.

Parameters:

mode_shape (array_like, shape (n_dofs,)) – Complex-valued mode shape vector. Each element’s magnitude and angle (phase) are plotted.

Returns:

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

  • ax (matplotlib.axes.Axes) – The polar axes object containing the mode shape complexity visualization.

Notes

  • 0 degrees is set to East (positive x-axis) and direction is CCW.

  • Radial axis is scaled to accommodate maximum magnitude plus a small margin (1.1).

  • Arrows represent each complex component with an arrow from origin to (magnitude, angle).

pyoma2.functions.plot.plot_silhouette(distance_matrix: ndarray, labels: ndarray, name: str) → Tuple[Figure, Axes][source]

Plot a silhouette plot for clustering results given a precomputed distance matrix.

Parameters:

  • distance_matrix (array-like, shape (n_samples, n_samples)) – Pairwise distance matrix between samples.

  • labels (array-like, shape (n_samples,)) – Cluster labels for each sample.

  • name (str) – A label or title identifier used in the plot title.

Returns:

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

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

Notes

  • Computes the average silhouette score for the provided labels.

  • Colors each cluster’s silhouette values, and draws a vertical line at the average score.

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

Plot channel diagnostic information: time history, autocorrelation, PSD, PDF, and normal probability plot.

For each specified channel, creates a 3x2 grid of subplots showing: - Time history - Normalized autocorrelation - Power spectral density (PSD) - Probability density function (PDF) estimate - Normal probability plot

Parameters:

  • data (ndarray, shape (n_samples, n_channels)) – Input signal data.

  • fs (float) – Sampling frequency in Hz.

  • nxseg (int, optional) – Number of points per segment for PSD and autocorrelation. Default is 1024.

  • freqlim (tuple(float, float), optional) – Frequency axis limits for PSD as (min_freq, max_freq). If None, full range is used.

  • logscale (bool, optional) – If True, PSD is plotted in dB. Otherwise, amplitude spectral density is plotted. Default is False.

  • ch_idx (int, list of int, or "all", optional) – Index or list of indices of channels to plot. If “all”, all channels are plotted. Default is “all”.

  • unit (str, optional) – Unit label for PSD y-axis (linear scale) or dB reference. Default is “unit”.

Returns:

  • figs (list of matplotlib.figure.Figure) – List of figure objects, one per channel plotted.

  • axs (list of list of matplotlib.axes.Axes) – Nested list of axes for each figure: [[ax0, ax1, ax2, ax3, ax4], …]

Notes

  • Autocorrelation is normalized by its maximum (lag 0).

  • PSD computed via SciPy’s signal.welch with 50% overlap.

  • PDF estimated via numerical differentiation of the sorted CDF.

  • Normal probability plot compares normalized data to a standard normal distribution.

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]

Plot time-series data for multiple channels, optionally showing RMS value lines.

Parameters:

  • data (ndarray, shape (n_samples, n_channels)) – Time-domain signal data for multiple channels.

  • fs (float) – Sampling frequency in Hz.

  • nc (int, optional) – Number of columns in the subplot grid. Determines how many subplots per row. Default is 1.

  • names (list of str, optional) – Channel names for titling each subplot. If None, no titles are set. Default is None.

  • unit (str, optional) – Unit label for the y-axis. Default is “unit”.

  • show_rms (bool, optional) – If True, plot the root mean square (RMS) value of each channel as a horizontal red line. Default is False.

Returns:

  • fig (matplotlib.figure.Figure) – The figure object containing the subplots for each channel.

  • axs (ndarray of matplotlib.axes.Axes) – 2D array of axes objects for each subplot with shape (n_rows, nc).

Notes

  • Arranges subplots in a grid with nc columns and as many rows as needed.

  • Shares x- and y-axes across subplots for consistent scaling.

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”.

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: List[Line2D], ncols: int) → List[Line2D][source]

Rearrange legend elements into a column-wise ordering.

For example, if there are 6 elements and 2 columns, ordering by columns yields: [e1, e3, e5, e2, e4, e6]

Parameters:

  • legend_elements (list of matplotlib.lines.Line2D) – A list of legend handles (e.g., Line2D instances) to be rearranged.

  • ncols (int) – The desired number of columns in the legend.

Returns:

rearranged_elements – A reordered list of legend handles arranged column-wise.

Return type:

list of matplotlib.lines.Line2D

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.spectra_comparison(S_val: ndarray, S_val1: ndarray, freq: ndarray, freqlim: Tuple[float, float] | None = None, nSv: int | 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, shape (n_channel, n_channel, n_frequencies)) – A 3D array of singular values for the measured spectrum.

  • S_val1 (ndarray, shape (n_channel, n_channel, n_frequencies)) – A 3D array of singular values for the synthesized (reference) spectrum.

  • freq (ndarray, shape (n_frequencies,)) – Frequency vector corresponding to the third axis of S_val and S_val1.

  • freqlim (tuple(float, float), optional) – Frequency limits for the x-axis as (min_freq, max_freq). If None, full range is used.

  • nSv (int or "all", optional) – Number of singular values (modes) to plot. If “all”, all are plotted. Defaults to “all”.

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

  • ax (matplotlib.axes.Axes, optional) – Existing axes to plot on. If None, new axes are created.

Returns:

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

  • ax (matplotlib.axes.Axes) – The Matplotlib axes object containing the plotted curves.

Raises:

ValueError – If nSv is not “all” and is greater than the number of modes in S_val or S_val1.

pyoma2.functions.plot.stab_clus_plot(Fn_fl: ndarray, order_fl: ndarray, labels: ndarray, ordmax: int, ordmin: int = 0, freqlim: Tuple[float, float] | None = None, Fn_std: ndarray | None = None, plot_noise: bool = False, name: str | None = 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 (ndarray, shape (n_points,)) – Array of frequency values for each identified pole, flattened.

  • order_fl (ndarray, shape (n_points,)) – Array of model order values corresponding to each identified pole.

  • labels (ndarray, shape (n_points,)) – Cluster labels for each data point. Use -1 for noise points.

  • ordmax (int) – Maximum model order; used to set y-axis limit.

  • ordmin (int, optional) – Minimum model order; used to set y-axis limit. Default is 0.

  • freqlim (tuple(float, float), optional) – Frequency axis limits as (min_freq, max_freq). If None, auto-scale is used.

  • Fn_std (ndarray, optional) – Standard deviation of frequency values, used for horizontal error bars. Should match Fn_fl shape. Default is None.

  • plot_noise (bool, optional) – Whether to include and plot noise-labeled points (-1) in grey. Defaults to False.

  • name (str, optional) – An identifier used in the plot title. Defaults to None.

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

  • ax (matplotlib.axes.Axes, optional) – Existing axes to plot on. If None, new axes are created on the provided or new figure.

Returns:

  • fig (matplotlib.figure.Figure) – The Matplotlib figure object containing the stabilization chart.

  • ax (matplotlib.axes.Axes) – The Matplotlib axes object with the plotted data.

Notes

  • Error bars for frequency (horizontal) are drawn if Fn_std is provided.

  • Vertical dashed lines at median frequency for each cluster (excluding noise).

pyoma2.functions.plot.stab_plot(Fn: ndarray, Lab: ndarray, step: int, ordmax: int, ordmin: int = 0, freqlim: Tuple[float, float] | None = None, hide_poles: bool = True, Fn_std: ndarray | None = None, fig: Figure | None = None, ax: Axes | None = None) → Tuple[Figure, Axes][source]

Plot a stabilization chart of poles (frequency vs. model order) for stable vs unstable labeling.

Parameters:

  • Fn (ndarray, shape (n_modes, n_orders)) – 2D array of frequencies for each pole, arranged by mode and order.

  • Lab (ndarray, shape (n_modes, n_orders)) – 2D array of labels indicating whether each pole is stable (1) or unstable (0).

  • step (int) – Incremental step for model order plotting (vertical axis spacing).

  • ordmax (int) – Maximum model order to display (upper y-limit).

  • ordmin (int, optional) – Minimum model order to display (lower y-limit). Default is 0.

  • freqlim (tuple(float, float), optional) – Frequency axis limits as (min_freq, max_freq). If None, auto-scale is used.

  • hide_poles (bool, optional) – If True, only stable poles (Lab == 1) are shown. If False, both stable and unstable are shown.

  • Fn_std (ndarray, optional) – Covariance (standard deviation) of frequencies, same shape as Fn. Used for horizontal error bars. Defaults to None.

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

  • ax (matplotlib.axes.Axes, optional) – Existing axes to plot on. If None, new axes are created on the provided or new figure.

Returns:

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

  • ax (matplotlib.axes.Axes) – The axes object containing the plotted poles.

Notes

  • Green circles denote stable poles; red circles (if shown) denote unstable poles.

  • Error bars represent frequency uncertainty if Fn_std is provided.

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

Plot the singular values of a Hankel matrix as a stem plot.

Parameters:

  • H (ndarray, shape (m, n)) – Hankel matrix for which singular values will be computed.

  • br (int) – Number of block-rows used to construct the Hankel matrix; shown in the plot title.

  • iter_n (int, optional) – Maximum iteration or model order, used to set x-axis limit. If provided, x-axis spans [-1, iter_n].

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

  • ax (matplotlib.axes.Axes, optional) – Existing axes to plot on. If None, new axes are created on the provided or new figure.

Returns:

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

  • ax (matplotlib.axes.Axes) – The axes object containing the stem plot of singular values.