The Interactive Visualization (viz) Library

Easily generate a locally-hosted GUI for interactively visualizing your MOOP results.

The public interface can be accessed by importing the viz module, which contains three functions for creating interactive visualizations of the approximate Pareto front and objective data; these visualizations run on the browser in a Dash app. There is a known issue when using parmoo.viz in the Chrome browser, Firefox or Safari is recommended.

import parmoo.viz

Public Plotting Functions Running in Python Plotly and Dash

A plotting library for interactive visualization of MOOP objects.

To generate a plot, generate create a MOOP object and use it to solve a problem. Then call one of the following function, passing the MOOP object as the first argument:

viz.scatter(moop)

viz.parallel_coordinates(moop)

viz.radar(moop)

Please take note of the following:

Via the interactivity features, all of the arguments except for the moop field can be adjusted interactively through the pop-up GUI. The plot type can also be adjusted from the dropdown menu while running the GUI..

The viz tool hosts a Dash app through the local port http://127.0.0.1:8050/. This means that only one visualization can be hosted at a time. Also, killing the Dash app will end the interactivity in the browser, although a static plot may remain in your broswer window.

Finally, note that there is a known issue when using the Chrome browser. The Firefox or Safari browsers are recommended.

To interact with the plots:

To multi-select in scatterplots and radar plots, hold down SHIFT while making additional selections.

To remove all selections from a scatterplot and radar plot, select without holding down the SHIFT key or double click.

To select in parallel coordinates plots, click along an axis and then drag the cursor elsewhere along the same axis. The highlighted part of the axis is the area that is selected. There is no need to hold down SHIFT when making multiple selections in parallel coordinates plots.

To remove a parallel coordinates plot selection, click on the highlighted selection bar you wish to delete.

To reset plot interactions made through the toolbar in the top right of a graph (not interactions made through buttons, dropdowns, toggles, or input boxes), double click on the plot. This will undo selections, zoom, pan, etc.

The three basic plot options are detailed below.

viz.plot.scatter(moop, db='pf', output='dash', points='constraint_satisfying', height='auto', width='auto', font='auto', fontsize='auto', background_color='auto', screenshot='svg', image_export_format='svg', data_export_format='csv', dev_mode=False, pop_up=True, port='http://127.0.0.1:8050/')

Create a scatter plot matrix to visualize the results of a MOOP.

Parameters:

moop (MOOP) – The MOOP results that you would like to visualize.
db (str) – Either ‘pf’ to plot just the Pareto front, or ‘obj’ to plot the complete objective database. Defaults to ‘pf’.
output (str) – Either ‘dash’ to generate an interactive plot running in your browser using the dash app, or anything else to save a static plot to the desktop. Defaults to ‘dash’.
points (str) – Plot only constraint satisfying points (‘constraint_satisfying’), constraint violating points (‘constraint_violating’), all points (‘all’), or no points (‘none’).
height (str) – The height in pixels of the resulting figure. Defaults to ‘auto’, which matches your screen size.
width (str) – The width in pixels of the resulting figure. Defaults to ‘auto’, which matches your screen size.
font (str) – The font that will be used for axis labels and legends. These values are automatically inferred from the name fields of your MOOP object. Any specified font must be available on your computer and available in the appropriate path. Defaults ‘auto’, which is times new roman on most machines.
fontsize (str) – The font size (in points). Defaults to ‘auto’, which infers the size based on the plot dimensions.
background_color (str) – Set the background color for this plot. Defaults to ‘auto’, which is white with grey axis lines on most systems.
screenshot (str) – Set the download mode when saving a screenshot using the “screenshot” button. Defaults to ‘svg’. Other available options include: ‘html’, ‘webp’, ‘jpeg’, ‘png’, ‘svg’, ‘eps’, and ‘pdf’. Note that the ‘eps’ option requires the poppler library, which is not included in any of ParMOO’s dependency lists.
image_export_format (str) – Set the export format when exporting a plot directly image file. Defaults to ‘svg’. Other available options include: ‘html’, ‘webp’, ‘jpeg’, ‘png’, ‘svg’, ‘eps’, and ‘pdf’. Note that the ‘eps’ option requires the poppler library, which is not included in any of ParMOO’s dependency lists.
data_export_format (str) – Set the format for exporting selected data to a file. Defaults to ‘csv’. The other option is ‘json’.
dev_mode (bool) – Run in developer mode, which allows changes to the code to automatically render in the browser. Activating this mode will interfere with some functionalities (such as checkpointing) since it results in multiple calls to the script. This value defaults to False, and should only be adjusted by developers.
pop_up (bool) – Automatically pop-up the dash app when called. Defaults to True. The only reason one might want to adjust, is if the environment prevents pop-ups or a non default browser is desired.
port (str) – The port through which the Dash app is hosted. Defaults to ‘http://127.0.0.1:8050/’.

viz.plot.parallel_coordinates(moop, db='pf', output='dash', points='constraint_satisfying', height='auto', width='auto', font='auto', fontsize='auto', background_color='auto', screenshot='svg', image_export_format='svg', data_export_format='csv', dev_mode=False, pop_up=True, port='http://127.0.0.1:8050/')

Create a parallel coordinates plot to visualize the results of a MOOP.

Parameters:

moop (MOOP) – The MOOP results that you would like to visualize.
db (str) – Either ‘pf’ to plot just the Pareto front, or ‘obj’ to plot the complete objective database. Defaults to ‘pf’.
output (str) – Either ‘dash’ to generate an interactive plot running in your browser using the dash app, or anything else to save a static plot to the desktop. Defaults to ‘dash’.
points (str) – Plot only constraint satisfying points (‘constraint_satisfying’), constraint violating points (‘constraint_violating’), all points (‘all’), or no points (‘none’).
height (str) – The height in pixels of the resulting figure. Defaults to ‘auto’, which matches your screen size.
width (str) – The width in pixels of the resulting figure. Defaults to ‘auto’, which matches your screen size.
font (str) – The font that will be used for axis labels and legends. These values are automatically inferred from the name fields of your MOOP object. Any specified font must be available on your computer and available in the appropriate path. Defaults ‘auto’, which is times new roman on most machines.
fontsize (str) – The font size (in points). Defaults to ‘auto’, which infers the size based on the plot dimensions.
background_color (str) – Set the background color for this plot. Defaults to ‘auto’, which is white with grey axis lines on most systems.
screenshot (str) – Set the download mode when saving a screenshot using the “screenshot” button. Defaults to ‘svg’. Other available options include: ‘html’, ‘webp’, ‘jpeg’, ‘png’, ‘svg’, ‘eps’, and ‘pdf’. Note that the ‘eps’ option requires the poppler library, which is not included in any of ParMOO’s dependency lists.
image_export_format (str) – Set the export format when exporting a plot directly image file. Defaults to ‘svg’. Other available options include: ‘html’, ‘webp’, ‘jpeg’, ‘png’, ‘svg’, ‘eps’, and ‘pdf’. Note that the ‘eps’ option requires the poppler library, which is not included in any of ParMOO’s dependency lists.
data_export_format (str) – Set the format for exporting selected data to a file. Defaults to ‘csv’. The other option is ‘json’.
dev_mode (bool) – Run in developer mode, which allows changes to the code to automatically render in the browser. Activating this mode will interfere with some functionalities (such as checkpointing) since it results in multiple calls to the script. This value defaults to False, and should only be adjusted by developers.
pop_up (bool) – Automatically pop-up the dash app when called. Defaults to True. The only reason one might want to adjust, is if the environment prevents pop-ups or a non default browser is desired.
port (str) – The port through which the Dash app is hosted. Defaults to ‘http://127.0.0.1:8050/’.

viz.plot.radar(moop, db='pf', output='dash', points='constraint_satisfying', height='auto', width='auto', font='auto', fontsize='auto', background_color='auto', screenshot='svg', image_export_format='svg', data_export_format='csv', dev_mode=False, pop_up=True, port='http://127.0.0.1:8050/')

Create a radar plot to visualize the results of a MOOP.

Parameters:

moop (MOOP) – The MOOP results that you would like to visualize.
db (str) – Either ‘pf’ to plot just the Pareto front, or ‘obj’ to plot the complete objective database. Defaults to ‘pf’.
output (str) – Either ‘dash’ to generate an interactive plot running in your browser using the dash app, or anything else to save a static plot to the desktop. Defaults to ‘dash’.
points (str) – Plot only constraint satisfying points (‘constraint_satisfying’), constraint violating points (‘constraint_violating’), all points (‘all’), or no points (‘none’).
height (str) – The height in pixels of the resulting figure. Defaults to ‘auto’, which matches your screen size.
width (str) – The width in pixels of the resulting figure. Defaults to ‘auto’, which matches your screen size.
font (str) – The font that will be used for axis labels and legends. These values are automatically inferred from the name fields of your MOOP object. Any specified font must be available on your computer and available in the appropriate path. Defaults ‘auto’, which is times new roman on most machines.
fontsize (str) – The font size (in points). Defaults to ‘auto’, which infers the size based on the plot dimensions.
background_color (str) – Set the background color for this plot. Defaults to ‘auto’, which is white with grey axis lines on most systems.
screenshot (str) – Set the download mode when saving a screenshot using the “screenshot” button. Defaults to ‘svg’. Other available options include: ‘html’, ‘webp’, ‘jpeg’, ‘png’, ‘svg’, ‘eps’, and ‘pdf’. Note that the ‘eps’ option requires the poppler library, which is not included in any of ParMOO’s dependency lists.
image_export_format (str) – Set the export format when exporting a plot directly image file. Defaults to ‘svg’. Other available options include: ‘html’, ‘webp’, ‘jpeg’, ‘png’, ‘svg’, ‘eps’, and ‘pdf’. Note that the ‘eps’ option requires the poppler library, which is not included in any of ParMOO’s dependency lists.
data_export_format (str) – Set the format for exporting selected data to a file. Defaults to ‘csv’. The other option is ‘json’.
dev_mode (bool) – Run in developer mode, which allows changes to the code to automatically render in the browser. Activating this mode will interfere with some functionalities (such as checkpointing) since it results in multiple calls to the script. This value defaults to False, and should only be adjusted by developers.
pop_up (bool) – Automatically pop-up the dash app when called. Defaults to True. The only reason one might want to adjust, is if the environment prevents pop-ups or a non default browser is desired.
port (str) – The port through which the Dash app is hosted. Defaults to ‘http://127.0.0.1:8050/’.

Other Private Classes and Functions

There are several other private submodules, classes, and functions contained in the viz module that are used for creating and hosting the dashboard. These do not need to be referenced by the user, but are detailed below for developers.

Please note that documentation for some of these functions may be incomplete.

This module contains private methods for hosting and receiving callbacks from an interactiv dashboard. This module is intended only for developer use.

Note that some docstrings may be incomplete.

class viz.dashboard.Dash_App(moop, plot_type, db, points, height, width, font, fontsize, background_color, screenshot, image_export_format, data_export_format, dev_mode, pop_up, port)

A class for hosting the dashboard app.

__init__(moop, plot_type, db, points, height, width, font, fontsize, background_color, screenshot, image_export_format, data_export_format, dev_mode, pop_up, port): Constructor for dashboard app.

generate_graph(): Documentation incomplete.

configure(): Documentation incomplete.

update_height(): Documentation incomplete.

update_width(): Documentation incomplete.

update_font(): Documentation incomplete.

update_font_size(): Documentation incomplete.

update_plot_name(): Documentation incomplete.

update_background_color(): Documentation incomplete.

update_plot_type(): Documentation incomplete.

update_database(): Documentation incomplete.

evaluate_height(height_value): Documentation incomplete.

evaluate_width(width_value): Documentation incomplete.

evaluate_font(font_value): Documentation incomplete.

evaluate_font_size(font_size_value): Documentation incomplete.

evaluate_background_color(background_color_value): Documentation incomplete.

evaluate_plot_name(plot_name_value): Documentation incomplete.

evaluate_plot_type(plot_type_value): Documentation incomplete.

evaluate_database(database_value): Documentation incomplete.

evaluate_dataset_download(n_clicks): Documentation incomplete.

evaluate_selected_data(data, type): Documentation incomplete.

set_constraint_range(restyleData): Documentation incomplete.

update_constraint_range(restyleData): Documentation incomplete.

evaluate_selection_download(n_clicks): Documentation incomplete.

evaluate_image_export_format(image_export_format_value): Documentation incomplete.

evaluate_data_export_format(data_export_format_value): Documentation incomplete.

evaluate_image_download(n_clicks): Documentation incomplete.

evaluate_customization_options(action, n_clicks): Documentation incomplete.

evaluate_export_options(action, n_clicks): Documentation incomplete.

evaluate_constraint_showr(value): Documentation incomplete.

generate_graph(): Documentation incomplete.

configure(): Documentation incomplete.

update_height(): Documentation incomplete.

update_width(): Documentation incomplete.

update_font(): Documentation incomplete.

update_font_size(): Documentation incomplete.

update_plot_name(): Documentation incomplete.

update_background_color(): Documentation incomplete.

update_plot_type(): Documentation incomplete.

update_database(): Documentation incomplete.

evaluate_height(height_value): Documentation incomplete.

evaluate_width(width_value): Documentation incomplete.

evaluate_font(font_value): Documentation incomplete.

evaluate_font_size(font_size_value): Documentation incomplete.

evaluate_background_color(background_color_value): Documentation incomplete.

evaluate_plot_name(plot_name_value): Documentation incomplete.

evaluate_plot_type(plot_type_value): Documentation incomplete.

evaluate_database(database_value): Documentation incomplete.

evaluate_dataset_download(n_clicks): Documentation incomplete.

evaluate_selected_data(data, type): Documentation incomplete.

set_constraint_range(restyleData): Documentation incomplete.

update_constraint_range(restyleData): Documentation incomplete.

evaluate_selection_download(n_clicks): Documentation incomplete.

evaluate_image_export_format(image_export_format_value): Documentation incomplete.

evaluate_data_export_format(data_export_format_value): Documentation incomplete.

evaluate_image_download(n_clicks): Documentation incomplete.

evaluate_customization_options(action, n_clicks): Documentation incomplete.

evaluate_export_options(action, n_clicks): Documentation incomplete.

evaluate_constraint_showr(value): Documentation incomplete.

This module contains tools to generate interactive Plotly-based graphs.

The functions are:

Display data in interactive browser plot

generate_scatter(moop) – Generate interactive scatterplot matrix

generate_parallel(moop) – Generate interactive parallel plot

generate_radar(moop) – Generate interactive radar plot

viz.graph.generate_scatter(moop, db, points)

Generate a scatterplot or scatterplot matrix.

Parameters:

moop (MOOP) – An object containing the data to be visualized.
db (string) – Filter traces by dataset. * ‘pf’ - Plot the Pareto Front. * ‘obj’ - Plot objective data.
points (string) –
Filter traces by constraint score. * ‘constraint_satisfying’ - Show only points that

satisfy every constraint.
- ’constraint_violating’ - Show only points that violate any constraint.
- ’all’ - Plot all points.
- ’none’ - Plot no points.

Returns:

A scatterplot or scatterplot matrix displaying traces that fit the filtering criteria.

Return type:

plotly.graph_objects.Figure

viz.graph.generate_parallel(moop, db, points)

Generate a parallel coordinates plot.

Parameters:

moop (MOOP) – An object containing the data to be visualized.
db (string) – Filter traces by dataset. * ‘pf’ - Plot the Pareto Front. * ‘obj’ - Plot objective data.
points (string) –
Filter traces by constraint score. * ‘constraint_satisfying’ - Show only points that

satisfy every constraint.
- ’constraint_violating’ - Show only points that violate any constraint.
- ’all’ - Plot all points.
- ’none’ - Plot no points.

Returns:

A parallel coordinates plot displaying traces that fit the filtering criteria.

Return type:

plotly.graph_objects.Figure

viz.graph.generate_radar(moop, db, points)

Generate a radar plot.

Parameters:

moop (MOOP) – An object containing the data to be visualized.
db (string) – Filter traces by dataset. * ‘pf’ - Plot the Pareto Front. * ‘obj’ - Plot objective data.
points (string) –
Filter traces by constraint score. * ‘constraint_satisfying’ - Show only points that

satisfy every constraint.
- ’constraint_violating’ - Show only points that violate any constraint.
- ’all’ - Plot all points.
- ’none’ - Plot no points.

Returns:

A radar plot displaying traces that fit the filtering criteria.

Return type:

plotly.graph_objects.Figure

This module contains utilities (helper functions) that are used throughout the viz tool.

viz.utilities.export_file(fig, plot_name, file_type)

Export image of figure to working directory.

Parameters:

fig (plotly.graph_objects.Figure) – The figure to export.
plot_name (string) – Set the filename of the image file.
file_type (string) –
Set the image file type. - ‘html’ - Export as .html file. - ‘pdf’ - Export as .pdf file. - ‘svg’ - Export as .svg file. - ‘eps’ - Export as .eps file

if the poppler dependency is installed.
- ’jpeg’ - Export as .jpeg file.
- ’png’ - Export as .png file.
- ’webp’ - Export as .webp file.

viz.utilities.set_plot_name(db)

Provide a default graph title.

Parameters:: db (string) – Graph contents inform title. - ‘pf’ - Set plot name to “Pareto Front” - ‘obj’ - Set plot name to “Objective Data”
Returns:: The default plot name.
Return type:: plot_name (string)

viz.utilities.set_database(moop, db, points)

Choose which points from MOOP object to plot.

Parameters:

db (string) – Set dataset. - ‘pf’ - Set Pareto Front as dataset. - ‘obj’ - Set objective data as dataset.
points (string) –
Filter traces from dataset by constraint score. - ‘constraint_satisfying’ - Include only points that

satisfy every constraint.
- ’constraint_violating’ - Include only points that violate any constraint.
- ’all’ - Include all points in dataset.
- ’none’ - Include no points in dataset.

Returns:

A 2D dataframe containing post-filter data from the MOOP.

Return type:

df (Pandas dataframe)

viz.utilities.set_hover_info(database, i)

Customize information in hover label for trace i.

Parameters:

database (Pandas dataframe) – A 2D dataframe containing the traces to be graphed.
i (int) – An index indicating the row where the trace we’re labeling is located.

Returns:

An HTML-format string to display when users hover over trace i.

Return type:

hover_info (string)

viz.utilities.check_inputs(db, output, points, height, width, font, fontsize, background_color, screenshot, image_export_format, data_export_format, dev_mode, pop_up, port)

Check keyword inputs to user-facing functions for validity

Parameters:

db – The item passed to the ‘db’ keyword in a user-facing function. If db cannot be cast to a string valued ‘pf’ or ‘obj’, a ValueError is raised.
output – The item passed to the ‘output’ keyword in a user-facing function. If output cannot be cast to a string corresponding to one of the supported output filetypes, a ValueError is raised.
points – The item passed to the ‘points’ keyword in a user-facing function. If points cannot be cast to a string corresponding to one of the supported contraint filters, a ValueError is raised.
height – The item passed to the ‘height’ keyword in a user-facing function. If height is not the default string ‘auto’ or cannot be cast to an int of value greater than one, a ValueError is raised.
width – The item passed to the ‘width’ keyword in a user-facing function. If width is not the default string ‘auto’ or cannot be cast to an int of value greater than one, a ValueError is raised.
font – The item passed to the ‘font’ keyword in a user-facing function. If font cannot be cast to a string, a ValueError is raised.
fontsize – The item passed to the ‘fontsize’ keyword in a user-facing function. If fontsize is not the default value ‘auto’ or cannot be cast to an int of value between 1 and 100 inclusive, a ValueError is raised.
background_color – The item passed to the ‘background_color’ keyword in a user-facing function. If background_color cannot be cast to a string, a ValueError is raised.
screenshot – The item passed to the ‘screenshot’ keyword in a user-facing function. If screenshot cannot be cast to a string corresponding to one of the supported screenshot filetypes, a ValueError is raised.
image_export_format – The item passed to the ‘image_export_format’ keyword in a user-facing function. If image_export_format cannot be cast to a string corresponding to one of the supported image_export_format filetypes, a ValueError is raised.
data_export_format – The item passed to the ‘data_export_format’ keyword in a user-facing function. If data_export_format cannot be cast to a string corresponding to one of the supported data_export_format filetypes, a ValueError is raised.
data_export_format – The item passed to the ‘data_export_format’ keyword in a user-facing function. If data_export_format cannot be cast to a string corresponding to one of the supported data_export_format filetypes, a ValueError is raised.
dev_mode – The item passed to the ‘dev_mode’ keyword in a user-facing function. If dev_mode cannot be cast to one of the boolean values True and False, a ValueError is raised.
pop_up – The item passed to the ‘pop_up’ keyword in a user-facing function. If pop_up cannot be cast to one of the boolean values True and False, a ValueError is raised.
port – The item passed to the ‘port’ keyword in a user-facing function. If port cannot be cast to a string beginning with ‘http’, a ValueError is raised.

Raises:

A ValueError if any of the values passed by a user to a keyword in –
a user-facing function are judged invalid. –