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.
Disclaimer: Currently, the Dakota GUI fully supports plotly.js integration on Windows and Mac systems. However, support for Linux is limited, depending on your distribution of Linux and previously installed libraries.
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 the elements accessible in the Dakota project navigator view.
Here is an example to demonstrate these plotting concepts:
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", and this would be the name by which you would look it up in the Dakota GUI project navigator view.
Plot 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 outputted quickly, you can click on the “Plot a single trace from this data” link provided with a run result data table, such as tabular data (A single plot window and a single plot canvas are automatically provided for you under the hood):
You will be presented with the following dialog:
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. By default, the plotting library will scale your plot to fit within the Dakota GUI Plot View. 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.
Along the top of this dialog is the Plot Data options 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. However, for this simple trace workflow, the data set is already selected for you, so you don't need to adjust anything here.
To get started with an example, select “Scatter Plot” from the “Plot Type” combo box.
From here, you have even more options! These options are all specific to scatter plots.
X/Y: Data for the X and Y dimensions of your scatter plot. You can choose any combination of Dakota parameters and responses. You can also choose [Time] which allows you to plot using the monotonically increasing number of Dakota iterations.
Trace Name: A custom label for your data trace.
Trace Color: The color of your plot points.
Dot Type: The shape of your plot points. Plotly (the default plotting library in the Dakota GUI) 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: Ignore areas of your data where nothing changed (either along the X or Y axis)
Normalize Data: Scale your data to fit between 0 and 1 (either along the X or Y axis)
When you’re done, click OK.
Plot View Controls
A quick interlude to talk about the Plot View. You will notice two icons in the top-right corner:
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. Right-clicking it gives you some options:
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 a minute).
Delete Plot: Remove the plot from your project.
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.
First, to open the Plot Manager, you have two options. You can click “Open Plot Manager” from the top-level Dakota project view:
Alternately, you can right-click an existing plot in the Dakota project navigator view and choose “Edit plot” to pre-populate the Plot Manager dialog with that plot’s configuration:
Upon launching, this is what the Plot Manager looks like by default:
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.
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 - these are "Add Row" and "Add Column." Click "Add Column" twice.
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 and horizontally. 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:
Along the top of the Canvas Viewer...
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. A good example of this can be seen in the "Iteration History" plotting template.
Clear Canvas: The final 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.
Because we are interested in “L/mass” and “w/mass” 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.
- Then, 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.
With this dialog, you have two options:
- You can grab a trace you’ve previously created (from any plot in your Dakota project) by using the All Traces dropdown.
- You can create a new trace, 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:
Note that the canvas previews 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.
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.
Manually populating all of this information into the Plot Manager dialog becomes increasingly time-consuming as you add more canvases and traces. For instance, suppose you want to see all parameters and responses for the centered parameter cantilever study that we ran, and suppose you want one canvas per response, and a trace for each parameter on each canvas. This would be a total of 21 traces, which would take a long time to manually input, not to mention the fact that doing so is error-prone, requiring lots of trial and error to get the plot exactly the way you want it.
To alleviate this somewhat, we have provided the concept of “plotting templates,” which are pre-baked configurations for the Plot Manager dialog. To access all available plotting templates, click on the “Choose a plotting template” button in the top-left corner of the Plot Manager dialog:
To satisfy the scenario described above, select "Centered Parameter Study Response Comparison" from the dropdown.
You will need to provide plot data using the Plot Data button, as well as an orientation for your canvases (horizontal or vertical), but everything else is populated for you.
Hit OK with the above options selected and you’ll be taken back to the Plot Manager dialog with everything populated:
Hit the Plot button and you’ll get the response comparison view of the cantilever centered parameter study that we just ran (you’ll most likely need to expand your Plot View and refresh to see everything):
A couple of things to note:
- For each trace, a random color and shape is automatically selected for you, but as you might expect, you can go back into the Plot Manager dialog, drill down to an individual trace, and change the color and point shape if you wish.
- Plotly provides quick comparison data about surrounding points in a trace by hovering the mouse over points on a trace.