indicator trace type

[nicolaskruchten]

@antoinerg please fill in some stuff here.

Five examples including:

• indicator_gauge
• indicator_bullet
• indicator_grid
• indicator_datacard
• indicator_scatter

[Mahdis-z]

plotly/plotly.js#3978
plotly/plotly.js#4007
plotly/plotly.js#4014
plotly/plotly.js#4029
plotly/plotly.js#4037

[antoinerg]

Here's a little summary of what we discussed this morning.

Codepen using plotly.js v1.49.0 that animates the mocks currently on master: https://codepen.io/antoinerg/pen/bPQEPr?editors=0010

The purpose of indicator is to visualize a single value specified by the value attribute. Three distinct visual elements are available to represent that value: number, delta and gauge. Any combination of them can be specified via the mode attribute.

Top-level attributes:

• value: the value to visualize
• mode: what visual elements to draw
• align: how to align number and delta (left, center, right)
• domain: the extent of the figure

Then we can configure the 3 different visual elements via their respective container:
number is simply a representation of the number in text. It has attributes:

• valueformat: to format the number
• prefix: a string before the number
• suffix: a string after the number
• font.(family|size): to control the font

delta simply displays the difference between the value with respect to a reference. It has attributes:

• reference: the number to compare the value with
• relative: whether that difference is absolute or relative
• valueformat: to format the delta
• (increasing|decreasing).color: color to be used for positive or decreasing delta
• (increasing|decreasing).symbol: symbol displayed on the left of the delta
• font.(family|size): to control the font
• position: position relative to number (either top, left, bottom, right)

Note that the attributes related to number and delta are well showcased by the mocks with names starting by indicator_datacard as well as by indicator_bignumber

Finally, we can have a simple title for the indicator via title:

• text: its string
• align: its alignment (left, center, right)
• font

[antoinerg]

Ok so now let me describe gauge. Let's look at one with gauge.shape === 'angular':

or equivalently with gauge.shape === 'bullet':

It has a few elements:

• a bar to display the current value (in green)
• it has a threshold to indicate a target value (in red)
• as well as steps to identify ranges of interest (one in yellow and one in blue).
• Finally, there is an axis with all the usual attributes to style the ticks, labels, etc. Those are found under gauge.axis

The bars (either for the value or the steps) can be configured with the same set of attributes:

• color: its color
• thickness: a number from 0 to 1 to that determines how much it fills the gauge laterally. For example, in the angular gauve above, the bar representing the value (in green) has a thickness of 0.5 (it only fills half the available space perpendicular to the axis direction)
  Also, although it is not showcased in the figures above, one can control the border of the bar or the steps with:
• line.color: the color of the line enclosing the bar (ie. its border)
• line.width: the width of the border (again, currently zero in the figures above)

Plotly.newPlot(gd,[{
    "value": 450,
    "title": {"text": "Speed"},
    "type": "indicator",
    "mode": "gauge+number",
    "delta": {"reference": 400},
    "gauge": {
      "axis": {
        "range": [0, 500],
        "tickwidth": 1,
        "tickcolor": "white"
      },
      "bgcolor": "rgba(255, 255, 255, 0.25)",
      "borderwidth": 2,
      "bordercolor": "rgba(255, 255, 255, 0.5)",
      "steps": [{
        "range": [0, 250],
        "color": "rgba(255, 255, 0, 0.5)"
      }, {
        "range": [250, 400],
        "color": "rgba(0, 0, 255, 0.75)"
      }],
      "threshold": {
        "line": {
          "color": "rgba(255, 0, 0, 1)",
          "width": 4
        },
        "thickness": 0.75,
        "value": 490
      }
    }
  }], {'width': 800, 'paper_bgcolor': 'black', font: {color: 'white'}})

[antoinerg]

Another interesting feature is that indicator trace sits above the other traces (even the 3d ones). This way, it can easily be used as an overlay as demonstrated in the following two mocks:

indicator_scatter

gl3d_indicator_scatter3d

[nicolaskruchten]

• New JS page: https://plot.ly/javascript/indicator/
  • some explanatory text: the various modes (gauge, number, delta) and the two gauge types (angular and bullet)
    • complex example: subplots with each thing based on indicator_grid_template
  • examples of each:
    • link to the gauge page and the bullet page
    • big number example
    • indicator_datacard
    • indicator_scatter (not 3d!!)
• Existing JS Gauge page: https://plot.ly/javascript/gauge-charts/ needs upgrading
  • simple example: gauge+number, no steps, no threshold, no delta
  • complex example: gauge+number+delta, steps, threshold
• New JS page: https://plot.ly/javascript/bullet-charts/
  • simple example: single bullet, no number, no delta
  • complex example: multiple bullets, plus number, plus delta