Creating a Custom Panel in s-Dashboard Using Vega

A wide range of custom graphics can be created using the Plots > Custom panel type in s-Dashboard, which uses the Vega visualization language. You can find the documentation for Vega at https://github.com/trifacta/vega/wiki/Documentation. You can also find a very useful live editor for Vega specifications at http://trifacta.github.io/vega/editor/.

To create a custom panel:

Select the Plots > Custom Panel Type in one of the frames on your s-Dashboard page. Even before any data has been sent to the panel, you should see a bar graph with 3 bars:

The Vega spec that generates this plot is:




{
  "width": 400,
  "height": 200,
  "data": [
    {
      "name": "stream",
      "values": [
        {
          "x": "A",
          "y": 1
        },
        {
          "x": "B",
          "y": 2
        },
        {
          "x": "C",
          "y": 3
        }
      ]
    }
  ],
  "scales": [
    {
      "name": "x",
      "type": "ordinal",
      "range": "width",
      "domain": {
        "data": "stream",
        "field": "data.x"
      }
    },
    {
      "name": "y",
      "range": "height",
      "nice": true,
      "domain": {
        "data": "stream",
        "field": "data.y"
      }
    }
  ],
  "axes": [
    {
      "type": "x",
      "scale": "x"
    },
    {
      "type": "y",
      "scale": "y"
    }
  ],
  "marks": [
    {
      "type": "rect",
      "from": {
        "data": "stream"
      },
      "properties": {
  "enter": {
    "x": {
      "scale": "x",
      "field": "data.x"
    },
    "width": {
      "scale": "x",
      "band": true,
      "offset": -1
    },
    "y": {
      "scale": "y",
      "field": "data.y"
    },
    "y2": {
      "scale": "y",
      "value": 0
    }
  },
  "update": {
    "fill": {
      "value": "steelblue"
    },
    "x": {
      "scale": "x",
      "field": "data.x"
    },
    "width": {
      "scale": "x",
      "band": true,
      "offset": -1
    },
    "y": {
      "scale": "y",
      "field": "data.y"
    },
    "y2": {
      "scale": "y",
      "value": 0
    }
  },
  "hover": {
    "fill": {
      "value": "red"
    }
  }
}
    }
  ]
}

When you run this dashboard, s-Dashboard will replace the ‘width’ and ‘height’ properties with the current size of the dashboard frame, and it overwrites the “padding” property as well. It’s a good idea to have default width and height settings so that the spec will work when you paste it into the Vega live editor.

s-Dashboard will also replace the “data” property. This spec includes sample data so that it will work in the Vega editor. The data will be in one of two forms, depending on the “Single-Row Mode” setting in the panel preferences:

In all cases, the name of the data definition will be ‘stream’. If ‘Single-Row Mode’ is enabled, only the most recent row of the stream is shown, with each value stored as a separate {x: y:} object in the values array, where x is the column name and y is the value. As shown in the bar graph example, the column names can be placed on an ordinal.

If the input stream looks like:

name alpha beta gamma delta
Encinitas 1.2 3.4 5.6 7.8
SanFrancisco 9.2 1.4 2.6 8.8
Chicago 3.2 0.4 6.6 3.8

The data when Single-Row Mode and Numbers Only are both enabled will look like the following:

"data": [
  {
    "name": "stream",
    "values": [
      {"x": "alpha", "y": 2.2},
      {"x": "beta", "y": 6.4},
      {"x": "gamma", "y": 7.6},
      {"x": "delta", "y": 8.8}
    ]
  }, …

With ‘Single-Row Mode’ off, the data values will be an array of objects, one per row, up to the number of rows given in the ‘Maximum Rows’ setting. Each object will have property names corresponding to the column names of the stream, as in:

"data": [
  {
    "name": "stream",
    "values": [
      {"name": "Encinitas", "alpha": 1.2, "beta": 3.4, "gamma": 5.6, "delta": 7.8},
      {"name": "Encinitas", "alpha": 4.2, "beta": 2.4, "gamma": 1.6, "delta": 3.8},
      {"name": "San Francisco", "alpha": 9.2, "beta": 1.4, "gamma": 2.6, "delta": 8.8},
      {"name": "San Francisco", "alpha": 0.2, "beta": 8.4, "gamma": 9.6, "delta": 4.8},
      {"name": "Chicago", "alpha": 3.2, "beta": 0.4, "gamma": 6.6, "delta": 3.8},
      {"name": "Chicago", "alpha": 2.2, "beta": 6.4, "gamma": 7.6, "delta": 8.8}
    ]
  }, …

Animation Parameters

The next three parameters control the animation from one update to the next (each new row written to the stream should cause an update). The Animation Period is the duration of the animation in milliseconds. Some animation types work better will longer periods of a second or more. The animation type and mode define the easing function, as described at https://github.com/mbostock/d3/wiki/Transitions. cubic and in-out are good defaults.

Writing a Vega Spec

The final panel setting is the Vega specification. To customize the specification, copy and paste it to an external editor. The Vega live editor http://trifacta.github.io/vega/editor/ is also very handy for developing a Vega spec. You may also find it useful to check that your JSON is valid using a tool such as JSONLint http://jsonlint.com/.

Begin your spec with default width and height settings so that it will work in the Vega editor. Include a default data specification for “stream”. You can use either one of the two examples above, or something similar that includes column names and sample values from the stream you intend to view.

It is best to get the visualization working in the Vega live editor and then in s-Dashboard before you start viewing a live stream, because debugging will be easier on a still image.

Note on Using Vega Live Examples

All dashboards are designed to animate, because of the nature of streaming data. Many of the examples in the Vega live editor were not written with animation in mind. In most cases, you can modify these for animation by taking the following steps: for each “marks” definition, copy all the “enter” settings to the “update” section.

For example, if the “alpha” value is used to set a mark’s height when it enters, in order to animate it also needs to set it when it updates. To see a complete example of a Vega Live example modified for animation, compare the default Vega spec given above to the “bars” example in the Vega live editor.