Marks

Graphical marks visually encode data using geometric primitives such as rectangles, lines, and plotting symbols. Marks are the basic visual building block of a visualization, providing basic shapes whose properties can be set according to backing data. Mark property definitions may be simple constants or data fields, or scales can be used to map data values to visual values.

Supported Mark Types

The supported mark types are:

• arc - Circular arcs, including pie and donut slices.
• area - Filled areas with horizontal or vertical alignment.
• image - Images, including icons or photographs.
• group - Containers for other marks, useful for sub-plots.
• line - Stroked lines, often used for showing change over time.
• path - Arbitrary paths or polygons, defined using SVG path syntax.
• rect - Rectangles, as in bar charts and timelines.
• rule - Rules are line segments, often used for axis ticks and grid lines.
• shape - A special variant of path marks for faster drawing of cartographic maps.
• symbol - Plotting symbols, including circles, squares and other shapes.
• text - Text labels with configurable fonts, alignment and angle.
• trail - Lines that can change size based on underlying data.

Visual Encoding

Each mark supports a set of visual encoding properties that determine the position and appearance of mark instances. Typically one mark instance is generated per input data element; the exceptions are the line and area mark types, which represent multiple data elements as a single line or area shape.

A mark definition typically looks something like this:

{
  "type": "rect",
  "from": {"data": "table"},
  "encode": {
    "enter": {
      "y": {"scale": "yscale", "field": "value"},
      "y2": {"scale": "yscale", "value": 0},
      "fill": {"value": "steelblue"}
    },
    "update": {...},
    "exit": {...},
    "hover": {...}
  }
}

There are three primary property sets: enter, update, exit. The enter properties are evaluated when data is processed for the first time and a mark instance is newly added to a scene. The update properties are evaluated for all existing (non-exiting) mark instances. The exit properties are evaluated when the data backing a mark is removed, and so the mark is leaving the visual scene. To better understand how enter, update, and exit sets work, take a look at Mike Bostock’s Thinking with Joins.

In addition, an optional hover set determines visual properties when the mouse cursor hovers over a mark instance. Upon mouse out, the update set is applied.

There is also a special group mark type (group) that can contain other marks, as well as local data, signal, scale, axis and legend definitions. Groups can be used to create visualizations consisting of grouped or repeated elements; examples include stacked graphs (each stack is a separate group containing a series of data values) and small multiples displays (each plot is contained in its own group). See the Group Marks page for more.

Top-Level Mark Properties

Accessibility Properties ≥ 5.11

Accessibility properties are used to determine ARIA (Accessible Rich Internet Applications) attributes when using Vega to render SVG output. Vega will automatically generate ARIA “role” and “roleDescription” attributes for container SVG <g> elements for a set of mark items. The properties below can be used to disable ARIA attributes or add additional description text. In addition, individual mark items can have per-item ARIA attributes, defined within encoding channels.

Mark Clipping

The clip property limits the area in which a set of marks is visible. The default value (boolean false) disables clipping. A boolean true value clips the marks to the width and height of the enclosing group mark. The clip property also accepts a signal that evaluates to a boolean value.

An object specification can be used to define more sophisticated clipping regions. An object-valued clip must have either a path property (for arbitrary SVG paths) or a sphere property (to clip to the globe, relative to a geographic projection), but not both. Either property can be a signal value to enable dynamic clipping regions.

Mark Data Sources (from)

The from property indicates the data source for a set of marks.

Faceting

The facet directive splits up a data source among multiple group mark items. Each group mark is backed by an aggregate data value representing the entire group, and then instantiated with its own named data source that contains a local partition of the data. Facets can either be data-driven, in which partitions are determined by grouping data values according to specified attributes, or pre-faceted, such that a source data value already contains within it an array of sub-values.

When generating data-driven facets, by default new aggregate data values are generated to serve as the data backing each group mark item. However, if both the data and facet properties are defined in the from object, pre-existing aggregate values will be pulled from the named data source. In such cases it is critical that the aggregate and facet groupby domains match. If they do not match, the behavior of the resulting visualization is undefined.

Reactive Geometry

Typically a "from": {"data": "..."} statement draws data from a backing data source defined within a "data" block. However, Vega can also use a set of marks as the backing data objects for a new set of marks — a feature referred to as reactive geometry. For example, one might add text marks to serve as labels, using computed x, y, width, or height values of the source marks to determine label placement.

To use a set of marks as a backing data source, the mark definition must include a unique name property. The marks can then be referenced as "from": {"data": "name"}.

Here is an example in which point marks serve as the backing data for a set of text marks:

{
  "marks": [
    {
      "name": "baseMarks",
      "type": "point",
      "from": {"data": "source"},
      "encode": {...}
    },
    {
      "type": "text",
      "from": {"data": "baseMarks"},
      "encode": {
        "update": {
          "x": {"field": "x", "offset": 4},
          "y": {"field": "y"},
          "text": {"field": "datum.label"}
        }
      }
    }
  ]
}

Mark Encoding Sets

All visual mark property definitions are specified as name-value pairs in a property set (such as update, enter, or exit). The name is simply the name of the visual property: individual mark types support standardized encoding channel names, but arbitrary names are also allowed, resulting in new named properties on output scenegraph items. The value of a property definition should be a value reference or production rule, as defined below.

The enter set is invoked when a mark item is first instantiated. Unless otherwise indicated, the update set is invoked whenever data or display properties update. The exit set is invoked when the data value backing a mark item is removed. If hover processing is requested on the Vega View instance, the hover set will be invoked upon mouse hover.

Custom encoding sets with arbitrary names are also allowed. To invoke a custom encoding set (e.g., instead of the update set), either pass the encoding set name to the Vega View run method or define a signal event handler with an "encode" directive.

Value References

A value reference specifies the value for a given mark property. The value may be a constant or drawn from a data object. In addition, the value may be run through a scale transform and further modified. Examples include:

• {"value": "left"} - Literal value
• {"field": "amount"} - Data field value
• {"scale": "yscale", "field": "amount"} - Scale-transformed data field value
• {"signal": "hypot(datum.a, datum.b)" - Signal expression value

For more, see the Value type documentation, including the specialized Color Value and Field Value types.

Production Rules

Visual properties can also be set by evaluating an “if-then-else” style chain of production rules. Rules consist of an array of value reference objects, each of which must contain an additional test property. The value of this property should be a predicate expression, that evaluates to true or false. The visual property is set to the value reference corresponding to the first predicate that evaluates to true within the rule.

A single value reference, without a test property, can be specified as the final element within the rule to serve as the “else” condition. If no test properties evaluate to true, the property is set to this final (predicate-less) value reference. If no “else” condition is specified, the property value defaults to null.

For example, the following specification sets a mark’s fill colour using a production rule:

"fill": [
  {
    "test": "indata('selectedPoints', 'key', datum.key)",
    "scale": "c",
    "field": "species"
  },
  {"value": "grey"}
]

Here, if the ID of a particular data point is found in the selectedPoints data source, the fill color is determined by a scale transform. Otherwise, the mark instance is filled grey.