Plotly · SimWrapper

plotly example

With the Plotly plug-in it is possible to create any Plotly chart including all of the advanced stacked, 3D, and non-cartesian plot types.

If you just need a simple bar/line/area chart, you might want to use the basic chart plugin instead.

Usage

See the Plotly documentation which catalogs all of the many chart types available, far too numerous to list here. From there, you can find the configuration details that are required for your chart, and you will write that config into a SimWrapper YAML file -- instead of writing the given Plotly javascript code.

The SimWrapper plotly plug-in can be used to add panels in Dashboards. See the Dashboard documentation for general tips on creating dashboard configurations.

Each plotly panel is defined inside a row in a dashboard-*.yaml file.
Use panel type: plotly in the dashboard configuration.
Standard title, description, and width fields define the frame.

Plotly configuration

Data traces. The Plotly examples generally describe data traces, each of which can be defined in the traces section of the SimWrapper YAML configuration; see below for an example.

Datasets. You can specify arrays of data for your x and y data directly in the YAML file, e.g. x: [1,3,5,10.0]. More commonly, you will refer to external datasets such as CSV files. For this, create a datasets: section in your YAML config.

For example, you could read trip data from a CSV file using trips: "tripData.csv". Then, refer to the columns timePeriod and totalTrips in that dataset in the traces section by prefixing the key with a $:

datasets:
  trips: "tripData.csv"
traces:
  - x: $trips.timePeriod
    y: $trips.totalTrips
    ...

SimWrapper will read the file and insert the appropriate data columns into the configuration automatically. Note the $ before the keyword that you used for identifying the dataset.

You can read multiple datasets and refer to columns from each using $key.column for each.

Layout. Layout is handled by SimWrapper automatically; however if you want to override some layout defaults, you can include a layout section. The contents will be merged with the default layout values.

Additional properties

SimWrapper can preprocess datasets with the following special properties for use with the Plotly plug-in. Note, these are not part of the official Plotly library, but are SimWrapper-specific additions.

These are all specified at the plugin level; so at the same indentation level as traces, dataset etc.

Field	Description	Default
colorRamp	String. Set the color ramp that is applied if multiple traces are present. Available color ramp values are on the Plotly docs: see Discrete and Sequential color ramps. Note colorRamp can also be specified for a specific trace.
fixedRatio	Boolean. Define a fixed ratio for x and y axes domain.	false
interactive	String [none, dropdown, slider]. Create an interactive dropdown menu or slider for selecting individual traces.	none
mergeDatasets	Boolean. Merge all given `datasets` into one.	false
multiIndex	Map<String, String>. Merge two columns as index. Column name as key will be merged with the column name value. This allows building multi-level indices for certain plot types.

Detailed dashboard example

To generate the plot from the title image, the following code was used. The .csv file does not contain all the data, but is only meant to explain the structure.

header:
  title: Plotly example
layout:
  arrivals:
    - type: plotly
      height: 10
      title: Departures
      description: by hour and purpose
      datasets:
        dataset: "analysis/population/trip_purposes_by_hour.csv"
      traces:
        - type: bar
          x: $dataset.h
          y: $dataset.arrival
          name: $dataset.purpose
          orientation: v
          colorRamp: Spectral
      layout:
        xaxis:
          title: Hour
          color: '#444'
          type: '-'
        barmode: stack
        yaxis:
          title: Share
          color: '#444'
          type: '-'

Example data snippet: trip_purposes_by_hour.csv

purpose	h	arrival	departure
accomp_children	9	0.0	2.587991718426501E-4
accomp_children	10	2.587991718426501E-4	0.0
...	...	...	...
business	3	2.587991718426501E-4	5.175983436853002E-4
business	4	0.0010351966873706005	7.763975155279503E-4
...	...	...	...
educ_higher	6	2.587991718426501E-4	2.587991718426501E-4
educ_higher	7	2.587991718426501E-4	5.175983436853002E-4
...	...	...	...