Parameters

Work in progress

This page is a work in progress and is incomplete.

Parameters enable various dynamic behaviors in GenomeSpy visualizations, such as interactive selections, conditional encoding, and data filtering with expressions. They also enable parameterization when importing specification fragments from external files or named templates. Parameters in GenomeSpy are heavily inspired by the parameters concept of Vega-Lite.

Examples

Using Input Bindings

Parameters can be bound to input elements, such as sliders, dropdowns, and checkboxes. The GenomeSpy Core library shows the input elements below the visualization. In the GenomeSpy App, the input elements are shown in the View visibility menu, allowing the visualization author to provide sophisticated configuration options to the end user.

The following example shows how to bind parameters to input elements and use them to control the size, angle, and text of a text mark.

{
  "padding": 0,
  "view": { "fill": "#cbeef3" },
  "params": [
    {
      "name": "size",
      "value": 80,
      "bind": { "input": "range", "min": 1, "max": 300 }
    },
    {
      "name": "angle",
      "value": 0,
      "bind": { "input": "range", "min": 0, "max": 360 }
    },
    {
      "name": "text",
      "value": "Params are cool!",
      "bind": {
        "input": "select",
        "options": ["Params are cool!", "GenomeSpy", "Hello", "World"]
      }
    }
  ],

  "data": { "values": [{}] },

  "mark": {
    "type": "text",
    "font": "Lobster",
    "text": { "expr": "text" },
    "size": { "expr": "size" },
    "angle": { "expr": "angle" }
  }
}

Expressions

Parameters can be based on expressions, which can depend on other parameters. They are automatically re-evaluated when the dependent parameters change.

{
  "view": { "stroke": "lightgray" },
  "params": [
    {
      "name": "A",
      "value": 2,
      "bind": { "input": "range", "min": 0, "max": 10, "step": 1 }
    },
    {
      "name": "B",
      "value": 3,
      "bind": { "input": "range", "min": 0, "max": 10, "step": 1 }
    },
    {
      "name": "C",
      "expr": "A * B"
    }
  ],

  "data": { "values": [{}] },

  "mark": {
    "type": "text",
    "size": 30,
    "text": { "expr": "'' + A + ' * ' + B + ' = ' + C" }
  }
}

Selection parameters

Parameters allow for defining interactive selections, which can be used in conditional encodings. GenomeSpy compiles the conditional encoding rules into efficient GPU shader code, enabling fast interactions in very large data sets. However, currently only single-point selections are supported.

The following example has been adapted from Vega-Lite's example gallery with slight modifications (GenomeSpy provides no "bar" mark). The specification below is fully compatible with Vega-Lite.

{
  "description": "A bar chart with highlighting on hover and selecting on click. (Inspired by Tableau's interaction style.)",

  "data": {
    "values": [
      { "a": "A", "b": 28 },
      { "a": "B", "b": 55 },
      { "a": "C", "b": 43 },
      { "a": "D", "b": 91 },
      { "a": "E", "b": 81 },
      { "a": "F", "b": 53 },
      { "a": "G", "b": 19 },
      { "a": "H", "b": 87 },
      { "a": "I", "b": 52 }
    ]
  },
  "params": [
    {
      "name": "highlight",
      "select": { "type": "point", "on": "pointerover" }
    },
    { "name": "select", "select": "point" }
  ],
  "mark": {
    "type": "rect",
    "fill": "#4C78A8",
    "stroke": "black"
  },
  "encoding": {
    "x": {
      "field": "a",
      "type": "ordinal",
      "scale": { "type": "band", "padding": 0.2 }
    },
    "y": { "field": "b", "type": "quantitative" },
    "fillOpacity": {
      "value": 0.3,
      "condition": { "param": "select", "value": 1 }
    },
    "strokeWidth": {
      "value": 0,
      "condition": [
        { "param": "select", "value": 2, "empty": false },
        { "param": "highlight", "value": 1, "empty": false }
      ]
    }
  }
}