Plotly - Simian GUI Documentation v2.0.2

The Plotly component

Visualize data with the Plotly component. The Plotly implementations for the MATLAB and Python versions of Simian GUI differ significantly, so they are documented in separate subsections below. It is possible to combine multiple types of plots in the same figure, which is demonstrated with an example.

Plotly barchart example

In addition to the properties and methods listed below, this component inherits properties and methods from the superclass Component. For example, any Plotly component has a label and hidden property even though these are not explicitly listed here.

MATLAB

The Plotly component creates a Plotly figure in which data can be visualized.

Properties

Name	Description	Datatype	Default
defaultValue	Default settings for the Plotly figure. This will be an object of type `utils.Plotly` (described below) by default. An example on how to use this property to create an initial plot is given below.	`utils.Plotly`	`utils.Plotly` This hides the Plotly logo in the toolbar at the top.

utils.Plotly

The utils.Plotly class provides methods that resemble MATLAB plotting functions with which data can be presented in several chart types. When the Plotly utils class object is put in the payload and returned to the form, the created plot is shown in the form. Since the data to plot is often calculated based on certain inputs, the Plotly utils class object is often added in the guiEvent function, as illustrated by the example below the properties and methods described next.

utils.Plotly properties

Name	Description	Datatype	Default
config	Additional configuration of the plot such as toggling responsiveness or zooming.	Struct	`struct("displaylogo", false)`
data	Data to be shown in the figure.	Cell	`{}`
layout	Layout to be used in the figure	Struct	`struct()`

utils.Plotly methods

Name	Syntax	Description
area	`obj.area(varargin)`	Add a series to an area plot.
bar	`obj.bar(varargin)`	Add a series to a bar plot.
boxplot	`obj.boxplot(varargin)`	Add a box to a box plot.
bubblechart	`obj.bubblechart(varargin)`	Add bubbles to the bubble chart.
contour	`obj.contour(varargin)`	Add a series to a contour plot.
clf	`obj.clf(keepLayout)`	Clear the plot. Use `obj.clf(true)` to keep the title, legend, etc. and only reset the `data` and `config` properties.
legend	`obj.legend(varargin)`	Add a legend to a plot.
loglog	`obj.loglog(varargin)`	Add a series to a 2-D plot.
pie	`obj.pie(varargin)`	Add a series to a pie chart.
plot	`obj.plot(varargin)`	Add a series to a 2-D plot.
plot3	`obj.plot3(varargin)`	Add a series to a 3-D plot.
polarplot	`obj.polarplot(varargin)`	Add a series to a 2-D polarplot.
semilogx	`obj.semilogx(varargin)`	Add a series to a 2-D plot.
semilogy	`obj.semilogy(varargin)`	Add a series to a 2-D plot.
surf	`obj.surf(varargin)`	Add a series to a surface plot
title	`obj.title(varargin)`	Add a title to a plot.
xlabel	`obj.xlabel(varargin)`	Add a xlabel to a plot.
ylabel	`obj.ylabel(varargin)`	Add a ylabel to a plot.

Usage

Below is an example illustrating the MATLAB plotly functionality. You can call multiple plotting functions on the same Plotly object to plot multiple things in the same figure. The resulting plot is shown below the code.

function payload = guiInit(metaData)
    form            = Form();
    payload.form    = form;
    component.Plotly("my_plot", form);

    % When this button is clicked, the data is plotted.
    btn         = component.Button("plot_data", form);
    btn.label   = "Plot data";
    btn.setEvent("PlotData");
end

function payload = guiEvent(metaData, payload)
    plotObj = utils.getSubmissionData(payload, "my_plot");
    plotObj.clf();

    % Add a line plot and a bar chart in the same figure.
    nPoints = 4;
    plotObj.bar(1:nPoints, rand(nPoints, 2));
    plotObj.plot(1:nPoints, rand(nPoints, 1), "LineWidth", 3);

    % Add peripherals such as labels etc.
    plotObj.title("Recent efficiency compared to average efficiency");
    plotObj.xlabel("N");
    plotObj.ylabel("Efficiency [-]");
    plotObj.legend("This year", "Last year", "Average last ten years");

    payload = utils.setSubmissionData(payload, "my_plot", plotObj);
end

Plotly example with a grouped bar-chart and line-plot

The same plot can also be achieved during initialization by calling the methods above on the object in the defaultValue property of the Plotly component object:

function payload = guiInit(metaData)
    form            = Form();
    payload.form    = form;

    % Add a Plotly component and add a line plot and a bar chart in the same figure.
    comp    = component.Plotly("plot", form);
    nPoints = 4;
    comp.defaultValue.bar(1:nPoints, rand(nPoints, 2));
    comp.defaultValue.plot(1:nPoints, rand(nPoints, 1), "LineWidth", 3);

    % Add peripherals such as labels etc.
    comp.defaultValue.title("Recent efficiency compared to average efficiency");
    comp.defaultValue.xlabel("N");
    comp.defaultValue.ylabel("Efficiency [-]");
    comp.defaultValue.legend("This year", "Last year", "Average last ten years");

    % When this button is clicked, the data is plotted.
    btn         = component.Button("plot_data", form);
    btn.label   = "Plot data";
    btn.setEvent("PlotData");
end

In addition to the chart types available through the methods of the Plotly class, you can use all functionality from the Python Plotly library if you set the submission data such that it can be interpreted as a Plotly component correctly. For example, you can change the font-size of the ticks on the x-axis using plotObj.layout.xaxis.tickfont.size = 10;.

Python

The Plotly functionality in the Python version of Simian GUI differs significantly from the MATLAB implementation as the Plotly library is directly available from Python, which can be used to visualize data in the form. Most functionality from the Python Plotly API can be used (animations and controls are not supported) when a Plotly Figure object is put in the Plotly object's figure property.

The Plotly component creates a Plotly figure in which data can be visualized.

Properties

Name	Description	Datatype	Default
config	Additional configuration of the plot such as toggling responsiveness or zooming.	Dict	`{"displaylogo": False}`
data	Data to be shown in the figure.	List	`list()`
figure	Plotly Figure object containing the figure to be shown.	Figure	`None`
layout	Layout to be used in the figure	Dict	`dict()`

utils.Plotly

This utility class should be used in guiEvent, not in guiInit. The utils.getSubmissionData function returns a utils.Plotly object containing the payload data for the Plotly component. When the Plotly utils class object is put in the payload and returned to the form, the created plot is shown in the form.

utils.Plotly properties

Name	Description	Datatype	Default
config	Additional configuration of the plot such as toggling responsiveness or zooming.	Dict	`{"displaylogo": False}`
data	Data to be shown in the figure.	List	`list()`
figure	Plotly Figure object containing the figure to be shown.	Figure	`None`
layout	Layout to be used in the figure	Dict	`dict()`

utils.Plotly methods

Name	Syntax	Description
preparePayloadValue	`plot_dict = preparePayloadValue(self)`	Prepares a `dict` representation of the figure in the `Plotly` component, which can be put in the payload without using `setSubmissionData`.

Usage

Below is an example illustrating the Python plotly functionality with an initial bar plot that is extended with an extra line when the guiEvent function is executed. Note that in Python the Plotly Express functions are available to allow for easier creation and modification of plotly figures.

import plotly.express as px
import plotly.graph_objects as go


def gui_init(meta_data):
    app_form = Form()
    plot_obj = component.Plotly("plot", app_form)
    plot_obj.figure = go.Figure(
        go.Bar(
            x=[1, 2, 3, 4, 5],
            y=[0.81, 0.58, 0.25, 0.45, 0.41],
            name="This year",
        )
    )
    plot_obj.figure.update_layout(
        title="This year's efficiency compared to the average efficiency",
        xaxis_title="N",
        yaxis_title="Efficiency [-]",
        autosize=False,
        width=600,
        height=400,
    )

    # When this button is clicked, the data is plotted.
    btn = component.Button("plot_data", app_form)
    btn.label = "Plot data"
    btn.setEvent("PlotData")

    return {"form": app_form}


def gui_event(meta_data, payload):
    plot_obj, _ = utils.getSubmissionData(payload, "plot")
    plot_obj.figure.add_scatter(
        x=[1, 2, 3, 4, 5],
        y=[0.35, 0.95, 0.32, 0.54, 0.23],
        name="Average last<br>ten years",
    )

    # Update the payload with the new values in the Plotly object.
    payload, _ = utils.setSubmissionData(payload, "plot", plot_obj)

    return payload

The form generated with the above code will look like this:

Plotly example with bar-chart and line-plot

Resizing

Please note that the Plotly component spans the entire width of its parent component, even if the plot itself is smaller. This means that if you set layout.width and layout.height, the plot itself becomes smaller but the containing component does not, resulting in subsequent components ending up way below the plot. In order to mitigate this, you can reduce the width of the component by placing it in a Columns component, like so:

function payload = guiInit(metaData)
    form            = Form();
    payload.form    = form;
    
    % Add the Plotly component to the first column of a Columns component.
    plotObj = component.Plotly("my_plot");
    cols    = component.Columns("plot_cols", form);
    cols.setContent({plotObj, {}}, [4, 8])    

    % When this button is clicked, the data is plotted.
    btn         = component.Button("plot_data", form);
    btn.label   = "Plot data";
    btn.setEvent("PlotData");
end