plotly Extension

MooseDocs uses plotly for creating interactive graphs. Graphs are invoked with the !plot command, the available sub-commands are detailed in the following sections. Table 1 lists the configuration options for the extension.

Table 1: Available configuration options for the PlotlyExtension object.

KeyDefaultDescription
prefixFigureThe caption prefix (e.g., Fig.).

The syntax for the support chart types is defined in a manner that allows for all plotly settings to be available for defining the data as well as the chart layout. For a complete list of available options refer to the reference manual.

Scatter and Line Plots

Scatter and line plots are create with the scatter sub-command. As shown in the plotly documentation the plot command accepts a single JSON data structure that contains the data and settings for each line. For simplicity and to remain consistent with the library this same data structure is used within MooseDocs, as shown in Example 1.

Example 1: Example scatter plot using plotly data structure.

!plot scatter data=[{'x':[1,2,3,4], 'y':[2,4,6,8], 'name':'2x'},
                    {'x':[1,2,3,4], 'y':[1,4,9,16], 'name':'x*x', 'marker':{'size':14}}]

In most circumstances it is desired to load scatter data from a file, this is done using the "filename" setting. When used the "x" and "y" data should contain the column name rather than the actual data, as shown in Example 2. All other aspects of the data field remain the same.

Example 2: Example scatter plot using file-based data.

!plot scatter filename=test_files/white_elephant_jan_2016.csv
              data=[{'x':'time', 'y':'air_temp_set_1', 'name':'Air Temp.'}]
              layout={'xaxis':{'title':'Time (days)'},
                      'yaxis':{'title':'Temperature (C)'},
                      'title':'January 2016 White Elephant Weather Station'}

A complete list of settings available to the plot scatter command are included in Table 2.

Table 2: Available settings for the plot scatter command.

KeyDefaultDescription
styleThe style settings that are passed to rendered HTML tag.
layoutdict()Plotly layout settings for the chart, refer to https://plot.ly/javascript/reference/#layout for available options.
filenameNoneThe name of a CSV file for extracting data, when used the 'x' and 'y' fields of the 'data' setting should be replaced by column names or numbers.
captionNoneThe caption to use for the chart.
prefixNonePrefix to use when a caption and id are provided.
idThe class settings to be passed to the rendered tag.
dataNoneDirectly supply a list of dict items (i.e., JSON data) to the plotly plot command, see https://plot.ly/javascript/line-and-scatterfor additional details.
classThe class settings to be passed to rendered HTML tag.