visualopts

This module contains options dataclasses for controlling the appearance of visualisations in pyvale.

class pyvale.visualopts.EAnimationType(value)

Bases: Enum

NOTE: This is a feature under developement.

Enumeration for specifying the save file type for animations.

GIF = 2

MP4 = 1

class pyvale.visualopts.EExpVisBounds(value)

Bases: Enum

Enumeration for plotting the uncertainty bounds of a series of virtual sensor experiment traces. The uncertainty bounds are shown by filling between the given upper and lower bounds. See the experient trace opts dataclass which also allows for a scaling factor to be set to allow for plotting a given multiple of the standard deviation.

MAD = 3

Median absolute deviation over all virtual experiments for each sampling point.

MINMAX = 1

Minimum and maximum over all virtual experiments for each sampling point.

QUARTILE = 2

Lower 25% and upper 75% quartiles over all virtual experiments for each sampling point.

STD = 4

Standard deviation over all virtual sensor experiments for each sampling point.

class pyvale.visualopts.EExpVisCentre(value)

Bases: Enum

Enumeration for plotting the center of the distribution of a series of virtual sensor experiment traces.

MEAN = 1

Mean over all virtual experiments for plotting the center of the virtual experiment traces.

MEDIAN = 2

Median over all virtual experiments for plotting the center of the virtual experiment traces.

class pyvale.visualopts.EImageType(value)

Bases: Enum

NOTE: This is a feature under developement.

Enumeration for specifying the format for saving images.

PNG = 1

SVG = 2

class pyvale.visualopts.PlotOptsGeneral(aspect_ratio: float = 1.62, single_fig_scale: float = 0.5, resolution: float = 300.0, font_def_weight: str = 'normal', font_def_size: float = 8.0, font_tick_size: float = 8.0, font_head_size: float = 9.0, font_ax_size: float = 8.0, font_leg_size: float = 8.0, ms: float = 3.2, lw: float = 0.8, cmap_seq: str = 'cividis', cmap_div: str = 'RdBu', a4_width: float = 8.25, a4_height: float = 11.75, a4_margin_width: float = 0.5, a4_margin_height: float = 0.5)

Bases: object

Dataclass for controlling the properties of figures and graphs such as figure size, resolution, font sizes, marker sizes, line widths and colormaps. This dataclass is used to interact with matplotlib and pyvista so units conform to these packages. The defaults set in this dataclass are selected based on producing print quality figures for journal articles.

a4_height: float

Height of an A4 page in inches.

a4_margin_height: float

Margin heigh on an A4 page in inches.

a4_margin_width: float

Margin width on an A4 page in inches.

a4_print_height: float

Does not need to be initialised, calculated from other inputs. Printable height of an A4 page in inches based on subtracting twice the margin width.

a4_print_width: float

Does not need to be initialised, calculated from other inputs. Printable width of an A4 page in inches based on subtracting twice the margin width.

a4_width: float

Width of an A4 page in inches.

aspect_ratio: float

Aspect ratio of the figure canvas.

cmap_div: str

The colormap to use for diverging fields, defaults to Red-Blue.

cmap_seq: str

The colormap to use for monotonic fields

colors = ['#1f77b4', '#ff7f0e', '#2ca02c', '#d62728', '#9467bd', '#8c564b', '#e377c2', '#7f7f7f', '#bcbd22', '#17becf']

Color cycle for lines on plots.

colors_num: int

Does not need to be initialised, calculated from other inputs. The number of colors in the line color cycle.

font_ax_size: float

Default axis label font size.

font_def_size: float

Default font size for plots.

font_def_weight: str

Default weight for fonts on plots.

font_head_size: float

Default font size for headings/titles on plots.

font_leg_size: float

Default font size for legends.

font_name: str

Does not need to be initialised, calculated from other inputs. Name of the font to use. Defaults to Arial on Windows/Mac and Liberation Sans on Linux.

font_tick_size: float

Default font tick label size

lw: float

Line width for traces on plots.

ms: float

Marker size for points on plots

resolution: float

Figure resolution in dpi, defaults to 300dpi for print quality.

single_fig_scale: float

Scaling for a single column figure, defaults to a half (0.5) page width.

single_fig_size_landscape: tuple[float, float]

Does not need to be initialised, calculated from other inputs. Uses the printable A4 width and the single figure scaling to create a landscape canvas that fits in a single column of a two column journal article.

single_fig_size_portrait: tuple[float, float]

Does not need to be initialised, calculated from other inputs. Uses the printable A4 width and the single figure scaling to create a potrait canvas that fits in a single column of a two column journal article.

single_fig_size_square: tuple[float, float]

Does not need to be initialised, calculated from other inputs. Uses the printable A4 width and the single figure scaling to create a square canvas that fits in a single column of a two column journal article.

class pyvale.visualopts.TraceOptsExperiment(legend_loc: str | None = 'best', x_label: str = 'x [$mm$]', y_label: str = 'y [$mm$]', z_label: str = 'z [$mm$]', time_label: str = 'Time, $t$ [$s$]', truth_line: str | None = '-', sim_line: str | None = None, exp_centre_line: str = '-', exp_marker_line: str = '+', sensors_to_plot: ndarray | None = None, time_min_max: tuple[float, float] | None = None, centre: EExpVisCentre = EExpVisCentre.MEAN, fill_between: EExpVisBounds | None = EExpVisBounds.MINMAX, fill_scale: float = 1.0, plot_all_exp_points: bool = False)

Bases: object

Dataclass for controlling the properties of sensor trace plots from batches of simulated experiments.

centre: EExpVisCentre

Specifies the summary statistic to use for the center line of the sensor trace distribution. Defaults to EExpVisCentre.MEAN.

exp_centre_line: str

Matplotlib line style string for the experiment centre line.

exp_marker_line: str

Maplotlib line style string use for plotting all experiments.

fill_between: EExpVisBounds | None

Specifies the summary statistic to use for plotting the uncertainty bounds for the virtual sensor traces. Defaults to EExpVisBounds.MINMAX. Note that this statistic will be multipled by the fill_scale parameter.

fill_scale: float

Scaling factor multiplied by the uncertainty bound summary statistic for showing filled uncertainty bounds on sensor traces plots. Defaults to 1.0. A common setting would be 2.0 or 3.0 while setting fill_between = EExpVisBounds.STD (standard deviation).

legend_loc: str | None

Set the legend location based on matplotlib legend location string. If None then no legend is added. The legend lists the sensors by tag

plot_all_exp_points: bool

Allows all experiment points to be plotted. Note that for more than 100 experiments for a given sensor array this will be slow. Defaults to False.

sensors_to_plot: ndarray | None

Array (1D) of indices for the sensors to plot. If None then all sensors are plotted. Defaults to None.

sim_line: str | None

Matplotlib line style for the simulation output at the virtual sensor locations. If None then the line is not plotted for all virtual sensors.

time_label: str

Label for the time axis for traces pots which is assumed to be the horizontal axis.

time_min_max: tuple[float, float] | None

Time range over which to plot the sensor traces. If None then the full time range is plotted. Defaults to None.

truth_line: str | None

Matplotlib line style string for the ground truth virtual sensor values. If None then the truth line is not plotted for all virtual sensors.

x_label: str

r"x [$mm$]".

Type:

Label for the x axis defaults to

y_label: str

r"y [$mm$]".

Type:

Label for the y axis defaults to

z_label: str

r"z [$mm$]".

Type:

Label for the z axis defaults to

class pyvale.visualopts.TraceOptsSensor(legend_loc: str | None = 'best', x_label: str = 'x [$mm$]', y_label: str = 'y [$mm$]', z_label: str = 'z [$mm$]', time_label: str = 'Time, $t$ [$s$]', truth_line: str | None = '-', sim_line: str | None = None, meas_line: str = '--+', sensors_to_plot: ndarray | None = None, time_min_max: tuple[float, float] | None = None)

Bases: object

Dataclass for controlling the appearance of sensor trace plots including axis labels, line styles and time over which to plot the sensor traces. Note that latex symbols can be used in label strings by using a python raw string . For example: r"strain, $epsilon$ [-]".

legend_loc: str | None

Set the legend location based on matplotlib legend location string. If None then no legend is added. The legend lists the sensors by tag

meas_line: str

Matplotlib line style for the virtual sensor measurement traces.

sensors_to_plot: ndarray | None

Array (1D) of indices for the sensors to plot. If None then all sensors are plotted. Defaults to None.

sim_line: str | None

Matplotlib line style for the simulation output at the virtual sensor locations. If None then the line is not plotted for all virtual sensors.

time_label: str

Label for the time axis for traces pots which is assumed to be the horizontal axis.

time_min_max: tuple[float, float] | None

Time range over which to plot the sensor traces. If None then the full time range is plotted. Defaults to None.

truth_line: str | None

Matplotlib line style string for the ground truth virtual sensor values. If None then the truth line is not plotted for all virtual sensors.

x_label: str

r"x [$mm$]".

Type:

Label for the x axis defaults to

y_label: str

r"y [$mm$]".

Type:

Label for the y axis defaults to

z_label: str

r"z [$mm$]".

Type:

Label for the z axis defaults to

class pyvale.visualopts.VisOptsAnimation(frames_per_second: float = 10.0, off_screen: bool = False, save_animation: EAnimationType | None = None, save_path: Path | None = None)

Bases: object

NOTE: This is a feature under developement.

Dataclass for animation save options.

frames_per_second: float

off_screen: bool

save_animation: EAnimationType | None

save_path: Path | None

class pyvale.visualopts.VisOptsImageSave(path: Path | None = None, image_type: EImageType = EImageType.PNG, transparent_background: bool = False)

Bases: object

NOTE: This is a feature under developement.

Dataclass for image saving options.

image_type: EImageType

path: Path | None

transparent_background: bool

class pyvale.visualopts.VisOptsSimSensors(window_size_px: tuple[int, int] = (1280, 800), camera_position: ndarray | str = 'xy', show_edges: bool = True, interactive: bool = True, font_colour: str = 'black', background_colour: str = 'white', time_label_pos: str | None = 'upper_left', time_label_font_size: int = 12, colour_bar_show: bool = True, colour_bar_font_size: int = 18, colour_bar_lims: tuple[float, float] | None = None, colour_bar_vertical: bool = True, show_perturbed_pos: bool = True, sens_colour_nom: str = 'red', sens_colour_pert: str = 'blue', sens_point_size: float = 20.0, sens_label_font_size: int = 30, sens_label_colour: str = 'grey')

Bases: object

Dataclass for controlling displays of the simulation mesh and sensor locations using pyvista.

background_colour: str

Background colour string. Useful for creating "dark mode" style plots with "white" font and a "black background". Defaults to "light mode" with "black" font.

camera_position: ndarray | str

Camera position for the pyvista view either as a string of axis labels or as a 3x3 rotation matrix. Defaults to viewing the x-y plane with "xy".

colour_bar_font_size: int

Font size for the colourbar. Defaults to 18.

colour_bar_lims: tuple[float, float] | None

Max and min limits for the colour bar. If None the default limits are used.

colour_bar_show: bool

Flag to show the colourbar for the simulation field. Defaults to True.

colour_bar_vertical: bool

Flag to set the colourbar to vertical instead of horizontal. Defaults to True.

font_colour: str

Font colour string. Useful for creating "dark mode" style plots with "white" font and a "black background". Defaults to "light mode" with "black" font.

interactive: bool

Flag to allow interactive viewing of the plot. Defaults to True.

sens_colour_nom: str

Colour for the markers showing the nominal sensor locations.

sens_colour_pert: str

Colour for the markers showing the perturbed sensor locations.

sens_label_colour: str

Colour for the sensor labels. Note that this needs to provide reasonable contrast with the selected font colour so "grey" is the default.

sens_label_font_size: int

Font size for the sensor marker labels.

sens_point_size: float

Size for the markers used to show the sensor locations on the mesh.

show_edges: bool

Flag to show the element edges in visualisations. Defaults to True.

show_perturbed_pos: bool

Flag to show the perturbed sensor positions if field errors are used. Defaults to True.

time_label_font_size: int

Font size for the simulation time step label on the canvas. Defaults to 12.

time_label_pos: str | None

Position of the simulation time step label. If None then the simulation time step label is not shown. Defaults to "upper_left".

window_size_px: tuple[int, int]

(horizontal_px,vertical_px).

Type:

Window size for pyvista canvas in pixels