visualopts.py

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

class PlotOptsGeneral(aspect_ratio=1.62, single_fig_scale=0.5, resolution=300.0, font_def_weight='normal', font_def_size=8.0, font_tick_size=8.0, font_head_size=9.0, font_ax_size=8.0, font_leg_size=8.0, ms=3.2, lw=0.8, cmap_seq='cividis', cmap_div='RdBu', a4_width=8.25, a4_height=11.75, a4_margin_width=0.5, a4_margin_height=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.

aspect_ratio

Aspect ratio of the figure canvas.

single_fig_scale

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

resolution

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

font_def_weight

Default weight for fonts on plots.

font_def_size

Default font size for plots.

font_tick_size

Default font tick label size

font_head_size

Default font size for headings/titles on plots.

font_ax_size

Default axis label font size.

font_leg_size

Default font size for legends.

ms

Marker size for points on plots

lw

Line width for traces on plots.

cmap_seq

The colormap to use for monotonic fields

cmap_div

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

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

Color cycle for lines on plots.

a4_width

Width of an A4 page in inches.

a4_height

Height of an A4 page in inches.

a4_margin_width

Margin width on an A4 page in inches.

a4_margin_height

Margin heigh on an A4 page in inches.

font_name

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.

a4_print_width

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_print_height

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.

single_fig_size_square

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.

single_fig_size_portrait

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_landscape

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.

colors_num

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

__init__(aspect_ratio=1.62, single_fig_scale=0.5, resolution=300.0, font_def_weight='normal', font_def_size=8.0, font_tick_size=8.0, font_head_size=9.0, font_ax_size=8.0, font_leg_size=8.0, ms=3.2, lw=0.8, cmap_seq='cividis', cmap_div='RdBu', a4_width=8.25, a4_height=11.75, a4_margin_width=0.5, a4_margin_height=0.5)

class TraceOptsSensor(legend_loc='best', x_label='x [$mm$]', y_label='y [$mm$]', z_label='z [$mm$]', time_label='Time, $t$ [$s$]', truth_line='-', sim_line=None, meas_line='--+', sensors_to_plot=None, time_min_max=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

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

x_label

r”x [$mm$]”.

Type:

Label for the x axis defaults to

y_label

r”y [$mm$]”.

Type:

Label for the y axis defaults to

z_label

r”z [$mm$]”.

Type:

Label for the z axis defaults to

time_label

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

truth_line

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

sim_line

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

meas_line

Matplotlib line style for the virtual sensor measurement traces.

sensors_to_plot

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

time_min_max

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

__init__(legend_loc='best', x_label='x [$mm$]', y_label='y [$mm$]', z_label='z [$mm$]', time_label='Time, $t$ [$s$]', truth_line='-', sim_line=None, meas_line='--+', sensors_to_plot=None, time_min_max=None)

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

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.

MAD = 3

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

STD = 4

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

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

Bases: object

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

legend_loc

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

x_label

r”x [$mm$]”.

Type:

Label for the x axis defaults to

y_label

r”y [$mm$]”.

Type:

Label for the y axis defaults to

z_label

r”z [$mm$]”.

Type:

Label for the z axis defaults to

__init__(legend_loc='best', x_label='x [$mm$]', y_label='y [$mm$]', z_label='z [$mm$]', time_label='Time, $t$ [$s$]', truth_line='-', sim_line=None, exp_centre_line='-', exp_marker_line='+', sensors_to_plot=None, time_min_max=None, centre=EExpVisCentre.MEAN, fill_between=EExpVisBounds.MINMAX, fill_scale=1.0, plot_all_exp_points=False)

time_label

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

truth_line

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

sim_line

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

exp_centre_line

Matplotlib line style string for the experiment centre line.

exp_marker_line

Maplotlib line style string use for plotting all experiments.

sensors_to_plot

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

time_min_max

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

centre

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

fill_between

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

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

plot_all_exp_points

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.

class VisOptsSimSensors(window_size_px=(1280, 800), camera_position='xy', show_edges=True, interactive=True, font_colour='black', background_colour='white', time_label_pos='upper_left', time_label_font_size=12, colour_bar_show=True, colour_bar_font_size=18, colour_bar_lims=None, colour_bar_vertical=True, show_perturbed_pos=True, sens_colour_nom='red', sens_colour_pert='blue', sens_point_size=20.0, sens_label_font_size=30, sens_label_colour='grey')

Bases: object

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

__init__(window_size_px=(1280, 800), camera_position='xy', show_edges=True, interactive=True, font_colour='black', background_colour='white', time_label_pos='upper_left', time_label_font_size=12, colour_bar_show=True, colour_bar_font_size=18, colour_bar_lims=None, colour_bar_vertical=True, show_perturbed_pos=True, sens_colour_nom='red', sens_colour_pert='blue', sens_point_size=20.0, sens_label_font_size=30, sens_label_colour='grey')

window_size_px

(horizontal_px,vertical_px).

Type:

Window size for pyvista canvas in pixels

camera_position

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

show_edges

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

interactive

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

font_colour

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

background_colour

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

time_label_pos

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

time_label_font_size

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

colour_bar_show

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

colour_bar_font_size

Font size for the colourbar. Defaults to 18.

colour_bar_lims

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

colour_bar_vertical

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

show_perturbed_pos

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

sens_colour_nom

Colour for the markers showing the nominal sensor locations.

sens_colour_pert

Colour for the markers showing the perturbed sensor locations.

sens_point_size

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

sens_label_font_size

Font size for the sensor marker labels.

sens_label_colour

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

class EImageType(value)

Bases: Enum

NOTE: This is a feature under developement.

Enumeration for specifying the format for saving images.

PNG = 1

SVG = 2

class VisOptsImageSave(path=None, image_type=EImageType.PNG, transparent_background=False)

Bases: object

NOTE: This is a feature under developement.

Dataclass for image saving options.

__init__(path=None, image_type=EImageType.PNG, transparent_background=False)

path

image_type

transparent_background

class EAnimationType(value)

Bases: Enum

NOTE: This is a feature under developement.

Enumeration for specifying the save file type for animations.

MP4 = 1

GIF = 2

class VisOptsAnimation(frames_per_second=10.0, off_screen=False, save_animation=None, save_path=None)

Bases: object

NOTE: This is a feature under developement.

Dataclass for animation save options.

__init__(frames_per_second=10.0, off_screen=False, save_animation=None, save_path=None)

frames_per_second

off_screen

save_animation

save_path