Signals - smclements/vega GitHub Wiki

Wiki ▸ Documentation ▸ Signals

Signals are dynamic variables that drive interactive behaviours. They can be used throughout a Vega specification (e.g., with mark or data transform properties), and their values are determined by expressions or event streams. Event streams capture and sequence hardware events (e.g., mousedown or touchmove). When an event occurs, dependent signals are re-evaluated in their specification order. These new signal values propagate to the rest of the specification, and the visualization is re-rendered automatically.

A signal definition, and it's use in the rest of a specification, looks something like this:

{
  "signals": [{
    "name": "indexDate",
    "streams": [{
      "type": "mousemove", 
      "expr": "eventX()", 
      "scale": {"name": "x", "invert": true}
    }]
  }],

  "data": [{
    "name": "index",
    "source": "stocks",
    "transform": [
      {
        "type": "filter",
        "test": "month(datum.date) == month(indexDate)"
      }
    ]
  }],

  "marks": [{
    "type": "rule",
    "properties": {
      "update": {
        "x": {"scale": "x", "signal": "indexDate"}
      }
    } 
  }]
}

Signal values can be determined in one of two ways: purely by other signals, or by event streams as well. If a signal is only dependent on other signals, two additional properties can be specified:

To have interaction events (e.g., mousedown, or touchmove) trigger changes in signal values, an additional streams property must be defined as an array of objects with the following properties:

For events that occur within the visualization, the following special event functions are also available

eventGroup takes an optional name argument to return a named ancestor group mark item. Only named ancestors of the event target are addressable here.

Similarly, the eventX, eventY, and eventXY take an optional argument that can either be the name or scenegraph item of an enclosing ancestor. If provided, coordinates are translated to the given group's coordinates.

For example, if a rectangle mark item in the following specification was clicked

{
  "marks": [{
    "name": "foo",
    "type": "group",

    "marks": [{
      "name": "bar",
      "type": "group",

      "marks": [{
        "type": "rect"
      }]
    }]
  }]
}

eventItem would return the specific rectangle that was clicked. eventGroup() would return the enclosing group mark item (bar), and eventGroup('foo') would return its parent. eventX and the others would return the position of the click relative to the entire visualization, whereas eventX('foo') would return the position of the click within the foo group mark.

Event selectors specify the sequence of events ("event stream") that must occur in order to trigger an interactive behaviour. The syntax consists of the following:

When defining an interactive behaviour, it can often be useful to mix between the visual/pixel space of the rendered visualization, and its backing data space. For example, with brushing & linking a scatterplot matrix, the pixel extents of the brush are inverted to produce a data range to highlight points across all cells of the matrix. Scoped scale references help with this. They can be either an object, or the name of a top-level scale. In the latter case, the scale transform is applied as normal (transforming the signal value from the data domain to the visual range).

If the scope scale reference is an object, the following properties are available

For example, in the following specification, the group mark named cell is captured by the corresponding signal. This signal is used to lookup the x scale, which subsequently inverts the value of the start_x signal.

{
  "signals": [
    {
      "name": "cell",
      "streams": [
        {"type": "@cell:mousedown", "expr": "eventGroup('cell')"}
      ]
    },
    {
      "name": "start_x",
      "init": 0,
      "streams": [
        {
          "type": "mousedown", 
          "expr": "eventX()",
          "scale": {"name": "x", "scope": {"signal": "cell"}, "invert": true}
        }
      ]
    }
  ],

  "marks": [
    {
      "name": "cell",
      "type": "group",

      "scales": [{"name": "x", ...}],
      ...
    }
  ]
}

Once defined, signals can be used throughout a specification. They are available for use within all expressions (e.g., with the filter or formula transforms), and a signal property is available with mark property value references. For other areas of the specification, a special signal reference ("SignalRef") can be used. A SignalRef is an object with a single signal property. For example,

{
  "signals": [{"name": "xMin", ...}, {"name": "xMax", ...}],

  "scales": [
    {
      "name": "x",
      "range": "width",
      "domainMin": {"signal": "xMin"},
      "domainMax": {"signal": "xMax"}
    }
  ]
}

Dot notation can also be used to access nested signal values. For example,

{
  "signals": [
    {
      "name": "brush_start",
      "init": {"x": 0, "y": 0},
      "streams": [{"type": "mousedown", "expr": "{x: eventX(), y: eventY()}"}]
    }
  ],

  "marks": [
    {
      "type": "rect",
      "properties": {
        "update": {
          "x": {"signal": "brush_start.x"},
          ...
        }
      }
    }
  ]
}