Chapter 7. Plotting with Plotly – The Basics

The Dakota GUI provides simple plotting capabilities that allow you to explore your data output.  A number of 2D and 3D plot types are supported, including scatter plots, surface plots, box-and-whisker, histograms, correlation tables, and bar charts.  The underlying plotting library used is plotly.js.

  • Note:  Currently, the Dakota GUI fully supports plotly.js integration on Windows and Mac systems.  Linux is only supported on Red Hat and similar flavors, such as CentOS.

Before we begin plotting, there are three major plotting concepts to talk about.  Understanding these will give you a lot of flexibility in the types of plots you can create.

  • Plot Trace:  A plot trace is the most basic grouping of information that can be visualized in the Dakota GUI.  A trace represents a single Dakota variable (either parameter or response) visually rendered in some way.  To give a basic example, a trace could be a series of points plotted on a Cartesian plane (i.e. a scatter plot).  A trace can also be represented in other ways that we don’t naturally think of as “tracing” (such as a histogram)
  • Plot Canvas:  A plot canvas can be thought of a single set of axes.  A plot canvas can show one or more plot traces by grouping them onto the same axes.
  • Plot Window:  A plot window is the top-level container for a graphical visualization of Dakota data.  A plot window can contain one or more plot canvases.  Right now, only one plot window can be rendered at a time.  However, you can have as many plot windows as you like in your Dakota GUI project - plot windows are saved as .plot files in the Dakota project navigator view.

Here is an example to demonstrate these plotting concepts:

DakotaGuiManual_68_Chapter7_1.png

In this image, we see two canvases - the one on the left and the one on the right.  Each of these canvases has one trace on it - the left canvas has a red trace and the right canvas has a green trace.  All of this is rendered onto one plot window.  The plot window is named “Cantilever Example Plot.”

Accessing Plotting Tools

There are a multitude of ways to access plotting in the Dakota GUI.

  • Right-click on a Dakota project and select New > Plot.  This will take you to the Plot Manager Dialog (see “Plot Manager Dialog” section below).
  • Right-click on a Dakota input file and select New.  You can also right-click on files that contain plottable data (such as tabular output files) and select New.  From the New menu, you may either choose “Plot trace from this file,” “Plot template from this file,” or “Plot from this file.”
    • Plot template from this file:  See Chapter 8.
    • Plot trace from this file:  See “Plot from a single trace” section directly below.
    • Plot from this file:  See “Plot Manager Dialog” section further below.

Plot from a single trace

You may not want to bother with the idea of multiple canvases or even multiple traces.  If you just want a single trace plotted quickly, use the Plot Trace Creator by left-clicking either a Dakota input file or file with plottable data, right-click, and select New > Plot trace from this file.

For this example, we will be using a tabular output data file from the rosen_multidim.in example file (see chapters 3-5).

(Note:  If you receive a warning about your plotting library not being configured, "plotly.js (SWT Browser)" is the recommended default.)

DakotaGuiManual_68_Chapter7_2.png

The Plot Trace Creator is a powerful dialog that puts a lot of plotting control at your fingertips.

Let’s talk about the Plot Window Settings options group first.  These are options global to your entire plot window:

  • Plot Title:  The title displayed at the top of your plot.
  • Font:  The font used by your graph.
  • Plot Size:  The size of your plot in pixels.  These options are useful for customizing if you’re interested in exporting your plot at a large size (for instance, for a publication), or if the default view of your data is too crowded.  By default, the plotting library will scale your plot to fit within the Dakota GUI's Plot View.

Along the top of this dialog is the Plot Data group.  There is a single button in this dialog (the file-and-folder button) that allows you to select different data sets from the Dakota GUI for the purpose of plotting.  Select that button now.

DakotaGuiManual_68_Chapter7_3.png

The “Select Plot Data” dialog informs the plot where to collect its information from.  In Dakota GUI 6.8, plotting data comes from two combined sources:

  • The original Dakota input file provides variable and response labels.
  • Files such as tabular data output files provide the data calculated for each iteration of Dakota.

If you previously selected a Dakota input file to get here, the “Link to original Dakota input file” field will already be populated.  If not, go ahead and select your original Dakota input file.

In the tree view below, find the file that contains your plottable data, as shown here:

DakotaGuiManual_68_Chapter7_4.png

Click OK.  We now have a plottable data source selected for the Plot Trace Dialog.

DakotaGuiManual_68_Chapter7_5.png

Next, select “Scatter Plot” from the “Plot Type” combo box.

DakotaGuiManual_68_Chapter7_6.png

From here, you have even more options!  These options are all specific to scatter plots.

  • X/Y/Z:  Data for the X and Y dimensions of your scatter plot (a Z axis dropdown will also be provided for 3D plot types).  You can choose any combination of Dakota parameters and responses.
    • Note:  "Time [Time]" is a special option in the X/Y/Z dropdowns which allows you to plot using the monotonically increasing number of Dakota iterations.
  • Trace Name:   A custom label for your data trace.  The trace label does not get displayed in the Plot View, but it's a good idea to give your traces memorable names in case you need to find them again later.  When populating the X/Y/Z axis choices, the Plot Trace Creator dialog will try to give you a reasonable default trace name if it sees that the Trace Name field is left blank.
  • Trace Color:  The color of your plot points.
  • Dot Type:  The shape of your plot points.  The default plotting library (plotly.js) provides dozens of shapes you can use.
  • Connect Dots:  Select this checkbox to connect the points of your trace with a line.
  • Linear Regression:  Select this checkbox to draw a linear regression line through your data set.
  • Trim No Change:  Omits areas of your data where nothing changed (either along the X or Y axis).  This is a useful feature if you want your trace to only show areas of change.
  • Normalize Data:  Scale your data to fit between 0 and 1 (either along the X or Y axis)

Here is an example of what your Plot Trace Creator dialog could look like when you're done configuring your plot.

DakotaGuiManual_68_Chapter7_7.png

When you’re done, click OK.

Two things will happen:

  • A new .plot file will be added to your project at plots/plotly/<The title of your new plot>.plot
  • The plot will be displayed in the Plot View window:

DakotaGuiManual_68_Chapter7_8.png

This scatter plot shows us a 2D flattening of the Rosenbrock curve.

 

Plot View Controls

A quick interlude to talk about the Plot View.  You will notice two icons in the top-right corner:

DakotaGuiManual_68_Chapter7_9.png

  • Refresh:  This button will re-render the plot to fit the view.  This is especially useful if you rescale the Plot View (i.e. to take advantage of more screen real estate) and would like to view the plot in more detail.  However, if you have already specified a custom size for this plot window (see the Plot Trace Creator instructions), the plot won’t resize to respect the size of the view.  You will need to go back in and edit your plot window to make it use the default option of whatever screen size is available.
  • Save Screenshot:  Saves what you see on the screen as an image file on your computer.

Options for Already Created Plots

After plotting a single trace, the promised “single canvas, single trace” plot window has been added to your project as a .plot file.  Right-clicking it gives you some options:

DakotaGuiManual_68_Chapter7_10.png

Show Plot:  Re-render this plot in the Plot View.

Edit Plot:  Go back and make modifications to this plot.  Clicking this will open the more sophisticated Plot Manager (more on that in the next section...).

The Plot Manager

The Plot Manager dialog is the big brother to the Plot Trace Creator that we just went through.  The Plot Manager allows you to specify multiple canvases with multiple traces.  You can get extremely sophisticated with this dialog, so there are a lot of options to cover.

For the following example, we will use tabular data from the example cantilever beam problem, which can be generated by following the tutorial in Chapter 6.

To open the Plot Manager dialog:

  • Right-click on a Dakota project and select New > Plot.
  • Right-click on a Dakota input file and select New > Plot from this file.

Upon launching, this is what the Plot Manager looks like by default:

DakotaGuiManual_68_Chapter7_11.png

  • Choose a plotting template:  This option allows you to populate the entire Plot Manager dialog with configuration for certain types of exploratory plots.  Don’t click this button for now… we will come back to this later in Chapter 8.
  • Title:  The title for your plot.
  • Plot Size:  The plot size in pixels.  Leave this blank to let the plot fill the available space in the Plot View.
  • Font:  The font for your plot.
  • Show Legend:  Display a legend for every trace plotted.

For our cantilever example problem, let’s try plotting L/mass and w/mass on two separate canvases oriented horizontally.  Note the two highlighted buttons in the Canvas Viewer section - these are "Add Row" and "Add Column."

Click "Add Column" twice.

DakotaGuiManual_68_Chapter7_12.png

In the middle of this dialog, we now have a rough preview of how our canvases will look once rendered – i.e. we have two boxes that are displayed side-by-side.  We can edit what will go onto each canvas by pushing the respective “Edit this canvas” button.  

Click on the "Edit this canvas" button inside of the left canvas.  This puts the leftmost canvas into "focus" and activates several canvas-specific controls, as you can see here:

DakotaGuiManual_68_Chapter7_13.png

Along the top of the Canvas Viewer, some of the buttons have been activated...

  • Delete Row:  This deletes the row that the current canvas is in.  At the moment, this would have the effect of deleting both canvases.
  • Delete Column:  This deletes the column that the current canvas is in.  At the moment, this would have the effect of only deleting the leftmost canvas.
  • Move Right:  The blue arrow button will cause the selected canvas to shift to the right.  Since there are only two canvases, this has the effect of causing our two canvases to swap places.
  • Overlay Canvas:  Overlaying canvases is a feature that is generally not required except in very specific cases.  In some situations, a user may want to have several canvases with differing axis scales placed on top of each other, rather than placing a number of traces on the same canvas, which forces all those traces to adhere to one canvas scale.  A good example of this can be seen in the "Iteration History" plotting template (see Chapter 8).
  • Clear Canvas:  This button will clear any data off the selected canvas, including traces and canvas properties.

In the Canvas group on the right, we have...

  • X Axis:  Label for the canvas's X axis.  Note that we can also configure the color of the axis, and specify whether or not this axis uses a log scale.
  • Y Axis:  Label for the canvas's Y axis.  Note that we can also configure the color of the axis, and specify whether or not this axis uses a log scale.
  • Z Axis:  Label for the canvas's Z axis.  Note that we can also configure the color of the axis, and specify whether or not this axis uses a log scale. (Z axis configuration is disabled for 2D plots)
  • Autoscale:  Autoscale applies to overlaid canvases.  When checked, an overlaid canvas will disregard the data on other canvases and adhere to its own "best" scale.  When unchecked, an overlaid canvas will observe data on other canvases and attempt to scale itself relative to other canvases in the canvas stack.
  • Axis Lines:  When checked, one-pixel lines will be drawn for the axes of the plot.
  • Grid Lines:  When checked, gray grid lines will be drawn behind the plot.
  • List of Traces:  This area will display a list of all trace data on the canvas.
  • Add/Edit/Remove:  These buttons pertain to traces on the canvas.

We are interested in “L/mass” and “w/mass” for this example, so we can label the axes accordingly:

  • For the currently-selected canvas, put "L" in the X Axis field and "mass" in the Y Axis field.
  • Next, click on the "Edit this canvas" button of the rightmost canvas to put the right canvas into focus.
  • Put "w" in the X Axis field and "mass" in the Y Axis field.

We still need to add our traces to the canvas.  Re-select the leftmost canvas by clicking "Edit this canvas", then click Add" in the bottom-right corner to add a trace to your canvas.

DakotaGuiManual_68_Chapter7_14.png

With the "Select Plot Trace" dialog, you have two options:

  • You can grab a trace you’ve previously created (from any plot in any project in your workspace!) by using the search controls.  This part of the dialog functions similarly to the Search dialog covered in Chapter 3.
  • Alternately, you can create a new trace by clicking the "Create New Trace" button, which takes you back to the Plot Trace Creator that we already covered.

You should have enough information now to proceed on your own with populating traces onto the canvas.  Put an “L/mass” scatter plot trace onto the left canvas, then and a “w/mass” scatter plot trace onto the right canvas.  Take some creative liberties with specifiying color and point shape.

When you’re done, your Plot Manager dialog should look something like this:

DakotaGuiManual_68_Chapter7_15.png

Note that the canvas previews in the center of the dialog give us summary information about how many traces are on each canvas.

When you’re satisfied that you’re done, hit the Plot button to see your plot in the Plot View.

DakotaGuiManual_68_Chapter7_16.png

If you did something wrong, or if you’re not satisfied with the way your plot looks, you can immediately get back to where you left things in the Plot Manager dialog by right-clicking your newly-created plot in the Dakota project navigator view and choosing “Edit plot” from the context menu.