direct_data_driven_mpc.utilities.visualization.plot_utilities

Utility functions and classes for static and animated control input-output plots.

This module provides helper functions used in control input-output data plot generation, and a custom Matplotlib legend handler class for highlighting initial measurement periods in animated plots.

Functions

check_list_length(name, data_list, expected)	Verify whether a list contains the expected number of elements.
create_input_output_figure(m, p, figsize, ...)	Create a Matplotlib figure with two rows of subplots: one for control inputs and one for system outputs, and return the created figure and axes.
filter_and_reorder_legend(axis, legend_params)	Remove duplicate entries from the legend of a Matplotlib axis.
get_label_from_list(label_list, index, fallback)	Get a label from a list by index, or return a fallback value if the list is empty.
get_padded_limits(X[, X_s, pad_percentage])	Get the minimum and maximum limits from two data sequences extended by a specified percentage of the combined data range.
get_text_width_in_data(text_object, axis, fig)	Calculate the bounding box width of a text object in data coordinates.
init_dict_if_none(input_dict)	Return an empty dictionary if the input is None, otherwise return the input.
validate_data_dimensions(u_k, y_k, y_s[, ...])	Validate that input-output data arrays, and bound and ylimit lists have the expected shapes and lengths.

Classes

HandlerInitMeasurementRect

A custom legend handler for the rectangle representing the initial input-output measurement period in control input-output plot animations.

class HandlerInitMeasurementRect

A custom legend handler for the rectangle representing the initial input-output measurement period in control input-output plot animations.

create_artists(legend: Legend, orig_handle: Artist, xdescent: float, ydescent: float, width: float, height: float, fontsize: float, trans: Transform) → list[Rectangle | Line2D]

Return the legend artists generated.

Parameters:

• legend (~matplotlib.legend.Legend) – The legend for which these legend artists are being created.

• orig_handle (~matplotlib.artist.Artist or similar) – The object for which these legend artists are being created.

• xdescent (int) – The rectangle (xdescent, ydescent, width, height) that the legend artists being created should fit within.

• ydescent (int) – The rectangle (xdescent, ydescent, width, height) that the legend artists being created should fit within.

• width (int) – The rectangle (xdescent, ydescent, width, height) that the legend artists being created should fit within.

• height (int) – The rectangle (xdescent, ydescent, width, height) that the legend artists being created should fit within.

• fontsize (int) – The fontsize in pixels. The legend artists being created should be scaled according to the given fontsize.

• trans (~matplotlib.transforms.Transform) – The transform that is applied to the legend artists being created. Typically from unit coordinates in the handler box to screen coordinates.

validate_data_dimensions(u_k: ndarray, y_k: ndarray, y_s: ndarray, u_s: ndarray | None = None, u_bounds_list: list[tuple[float, float]] | None = None, y_bounds_list: list[tuple[float, float]] | None = None, u_ylimits_list: list[tuple[float, float]] | None = None, y_ylimits_list: list[tuple[float, float]] | None = None, u_setpoint_labels: list[str] | None = None, y_setpoint_labels: list[str] | None = None, x_axis_labels: list[str] | None = None, input_y_axis_labels: list[str] | None = None, output_y_axis_labels: list[str] | None = None) → None

Validate that input-output data arrays, and bound and ylimit lists have the expected shapes and lengths.

Parameters:

• u_k (numpy.ndarray) – An array containing control input data of shape (T, m), where m is the number of inputs and T is the number of time steps.

• y_k (numpy.ndarray) – An array containing system output data of shape (T, p), where p is the number of outputs and T is the number of time steps.

• y_s (numpy.ndarray) – An array containing output setpoint values of shape (T, p), where p is the number of outputs and T is the number of time steps.

• u_s (np.ndarray | None) – An array containing input setpoint values of shape (T, m), where m is the number of inputs and T is the number of time steps.

• u_bounds_list (list[tuple[float, float]] | None) – A list of tuples (lower_bound, upper_bound) specifying bounds for each input data sequence.

• y_bounds_list (list[tuple[float, float]] | None) – A list of tuples (lower_bound, upper_bound) specifying bounds for each output data sequence.

• u_ylimits_list (list[tuple[float, float]] | None) – A list of tuples (lower_limit, upper_limit) specifying the Y-axis limits for each input subplot.

• y_ylimits_list (list[tuple[float, float]] | None) – A list of tuples (lower_limit, upper_limit) specifying the Y-axis limits for each output subplot.

• u_setpoint_labels (list[str] | None) – A list of strings specifying custom legend labels for input setpoint series.

• y_setpoint_labels (list[str] | None) – A list of strings specifying custom legend labels for output setpoint series.

• x_axis_labels (list[str] | None) – A list of strings specifying custom X-axis labels for each subplot.

• input_y_axis_labels (list[str] | None) – A list of strings specifying custom Y-axis labels for each input subplot.

• output_y_axis_labels (list[str] | None) – A list of strings specifying custom Y-axis labels for each output subplot.

Raises:

ValueError – If any array dimensions mismatch expected shapes, or if the lengths of the list arguments do not match the number of subplots.

get_padded_limits(X: ndarray, X_s: ndarray | None = None, pad_percentage: float = 0.05) → tuple[float, float]

Get the minimum and maximum limits from two data sequences extended by a specified percentage of the combined data range.

Parameters:

• X (numpy.ndarray) – First data array.

• X_s (np.ndarray | None) – Second data array. If None, only X is considered. Defaults to None.

• pad_percentage (float) – The percentage of the data range to be used as padding. Defaults to 0.05.

Returns:

tuple[float, float] – A tuple containing padded minimum and maximum limits for the combined data from X and X_s.

get_text_width_in_data(text_object: Text, axis: Axes, fig: Figure | SubFigure) → float

Calculate the bounding box width of a text object in data coordinates.

Parameters:

• text_object (Text) – A Matplotlib text object.

• axis (Axes) – The axis on which the text object is displayed.

• fig (Figure | SubFigure) – The Matplotlib figure or subfigure that contains the axis.

Returns:

float – The width of the text object’s bounding box in data coordinates.

filter_and_reorder_legend(axis: Axes, legend_params: dict[str, Any], end_labels_list: list[str] | None = None) → None

Remove duplicate entries from the legend of a Matplotlib axis. Optionally, move specified labels to the end of the legend.

Note

The appearance of the plot legend can be customized by passing a dictionary of Matplotlib legend properties.

Parameters:

• axis (Axes) – The Matplotlib axis containing the legend to modify.

• legend_params (dict[str, Any]) – A dictionary of Matplotlib properties for customizing the plot legend (e.g., fontsize, loc, handlelength).

• end_labels_list (list[str] | None) – A list of labels to move to the end of the legend. Labels are moved in the order provided, with the last label in the list becoming the final legend entry. If not provided, the legend labels will not be reordered. Defaults to None.

create_input_output_figure(m: int, p: int, figsize: tuple[float, float], dpi: int, fontsize: int, title: str | None = None) → tuple[Figure, list[Axes], list[Axes]]

Create a Matplotlib figure with two rows of subplots: one for control inputs and one for system outputs, and return the created figure and axes.

If a title is provided, it will be set as the overall figure title. Each row of subplots will have its own title for ‘Control Inputs’ and ‘System Outputs’.

Parameters:

• m (int) – The number of control inputs (subplots in the first row).

• p (int) – The number of system outputs (subplots in the second row).

• figsize (tuple[float, float]) – The (width, height) dimensions of the created Matplotlib figure.

• dpi (int) – The DPI resolution of the figure.

• fontsize (int) – The fontsize for suptitles.

• title (str | None) – The title for the overall figure. If None, no title will be added. Defaults to None.

Returns:

tuple – A tuple containing:

• Figure: The created Matplotlib figure.

• list[Axes]: A list of axes for control inputs subplots.

• list[Axes]: A list of axes for system outputs subplots.

init_dict_if_none(input_dict: dict | None) → dict

Return an empty dictionary if the input is None, otherwise return the input.

Parameters:

input_dict (dict | None) – A dictionary or None.

Returns:

dict – The original dictionary or an empty one.

get_label_from_list(label_list: list[str], index: int, fallback: str) → str

Get a label from a list by index, or return a fallback value if the list is empty.

Parameters:

• label_list (list[str]) – A list of label strings.

• index (int) – The index of the desired label.

• fallback (str) – A fallback string to return if the list is empty.

Returns:

str – The label at the specified index or the fallback string.

check_list_length(name: str, data_list: list | None, expected: int) → None

Verify whether a list contains the expected number of elements.

Parameters:

• name (str) – The name of the list (for error message context).

• data_list (list | None) – The list to check.

• expected (int) – The expected number of elements in the list.

Raises:

ValueError – If the list length does not match the expected value.