Link¶

The "link" mark displays each data item as a curve that connects two points. The mark can be used to display structural variation and interactions, for example. The mark has several different linkShapes that control how the curve is drawn.

{
  "data": {
    "sequence": { "start": 0, "stop": 30, "as": "z" }
  },
  "transform": [
    { "type": "formula", "expr": "round(random() * 800)", "as": "x" },
    {
      "type": "formula",
      "expr": "round(datum.x + pow(2, random() * 10))",
      "as": "x2"
    }
  ],
  "mark": "link",
  "encoding": {
    "x": { "field": "x", "type": "index" },
    "x2": { "field": "x2" }
  }
}

Channels¶

In addition to the primary and secondary position channels and the color and opacity channels, link mark supports the following channels: size.

Properties¶

arcFadingDistance

Type: [number, number] | boolean | ExprRef

The range of the "arc" shape's fading distance in pixels. This property allows for making the arc's opacity fade out as it extends away from the chord. The fading distance is interpolated from one to zero between the interval defined by this property. Both false and [0, 0] disable fading.

Default value: false

arcHeightFactor

Type: number | ExprRef

Scaling factor for the "arc" shape's height. The default value 1.0 produces roughly circular arcs.

Default value: 1.0

clampApex

Type: boolean | ExprRef

Whether the apex of the "dome" shape is clamped to the viewport edge. When over a half of the dome is located outside the viewport, clamping allows for more accurate reading of the value encoded by the apex' position.

Default value: false

clip

Type: boolean | "never"

If true, the mark is clipped to the UnitView's rectangle. By default, clipping is enabled for marks that have zoomable positional scales.

color

Type: string | ExprRef

Color of the mark. Affects either fill or stroke, depending on the filled property.

linkShape

Type: "arc" | "diagonal" | "line" | "dome" | ExprRef

The shape of the link path.

The "arc" shape draws a circular arc between the two points. The apex of the arc resides on the left side of the line that connects the two points. The "dome" shape draws a vertical or horizontal arc with a specific height. The primary positional channel determines the apex of the arc and the secondary determines the endpoint placement. The "diagonal" shape draws an "S"-shaped curve between the two points. The "line" shape draws a straight line between the two points. See an example of the different shapes below.

Default value: "arc"

maxChordLength

Type: number | ExprRef

The maximum length of "arc" shape's chord in pixels. The chord is the line segment between the two points that define the arc. Limiting the chord length serves two purposes when zooming in close enough: 1) it prevents the arc from becoming a straight line and 2) it mitigates the limited precision of floating point numbers in arc rendering.

Default value: 50000

minArcHeight

Type: number | ExprRef

The minimum height of an "arc" shape. Makes very short links more clearly visible.

Default value: 1.5

minBufferSize

Type: number

Minimum size for WebGL buffers (number of data items). Allows for using bufferSubData() to update graphics.

This property is intended for internal use.

minPickingSize

Type: number | ExprRef

The minimum picking size invisibly increases the stroke width or point diameter of marks when pointing them with the mouse cursor, making it easier to select them. The valus is the minimum size in pixels.

Default value: 3.0 for "link" and 2.0 for "point"

noFadingOnPointSelection

Type: boolean | ExprRef

Disables fading of the link when an mark instance is subject to any point selection. As the fading distance is unavailable as a visual channel, this property allows for enhancing the visibility of the selected links.

Default value: true

opacity

Type: number | ExprRef

Opacity of the mark. Affects fillOpacity or strokeOpacity, depending on the filled property.

orient

Type: "vertical" | "horizontal" | ExprRef

The orientation of the link path. Either "vertical" or "horizontal". Only applies to diagonal links.

Default value: "vertical"

segments

Type: number | ExprRef

The number of segments in the bézier curve. Affects the rendering quality and performance. Use a higher value for a smoother curve.

Default value: 101

size

Type: number | ExprRef

Stroke width of "link" and "rule" marks in pixels, the area of the bounding square of "point" mark, or the font size of "text" mark.

tooltip

Type: HandledTooltip | null

Tooltip handler. If null, no tooltip is shown. If string, specifies the tooltip handler to use.

x

Type: number | ExprRef

Position on the x axis.

x2

Type: number | ExprRef

The secondary position on the x axis.

xOffset

Type: number

Offsets of the x and x2 coordinates in pixels. The offset is applied after the viewport scaling and translation.

Default value: 0

y

Type: number | ExprRef

Position on the y axis.

y2

Type: number | ExprRef

The secondary position on the y axis.

yOffset

Type: number

Offsets of the y and y2 coordinates in pixels. The offset is applied after the viewport scaling and translation.

Default value: 0

Examples¶

Different link shapes and orientations¶

This example shows the different link shapes and orientations. All links have the same coordinates: { x: 2, y: 2, x2: 8, y2: 8 }. The links are arranged in grid with

linkShape as columns: "arc", "dome", "diagonal", "line".
orient as rows: "vertical", "horizontal".

{
  "data": { "values": [{ "x": 2, "x2": 8 }] },
  "resolve": {
    "scale": { "x": "shared", "y": "shared" },
    "axis": { "x": "shared", "y": "shared" }
  },

  "encoding": {
    "x": {
      "field": "x",
      "type": "quantitative",
      "scale": { "domain": [0, 10] },
      "axis": { "grid": true }
    },
    "x2": { "field": "x2" },
    "y": {
      "field": "x",
      "type": "quantitative",
      "scale": { "domain": [0, 10] },
      "axis": { "grid": true }
    },
    "y2": { "field": "x2" },
    "size": { "value": 2 }
  },

  "columns": 4,
  "spacing": 20,

  "concat": [
    { "mark": { "type": "link", "linkShape": "arc", "orient": "vertical" } },
    { "mark": { "type": "link", "linkShape": "dome", "orient": "vertical" } },
    {
      "mark": { "type": "link", "linkShape": "diagonal", "orient": "vertical" }
    },
    { "mark": { "type": "link", "linkShape": "line", "orient": "vertical" } },
    { "mark": { "type": "link", "linkShape": "arc", "orient": "horizontal" } },
    { "mark": { "type": "link", "linkShape": "dome", "orient": "horizontal" } },
    {
      "mark": {
        "type": "link",
        "linkShape": "diagonal",
        "orient": "horizontal"
      }
    },
    { "mark": { "type": "link", "linkShape": "line", "orient": "horizontal" } }
  ]
}

Varying the dome height¶

This example uses the "dome" shape to draw links with varying heights. The height is determined by the y channel. The clampApex property is set to true to ensure that the apex of the dome is always visible. Try to zoom in and pan around to see it in action.

{
  "data": {
    "sequence": { "start": 0, "stop": 20, "as": "z" }
  },

  "transform": [
    { "type": "formula", "expr": "round(random() * 1000)", "as": "x" },
    {
      "type": "formula",
      "expr": "round(datum.x + random() * 500)",
      "as": "x2"
    },
    { "type": "formula", "expr": "random() * 1000 - 500", "as": "y" }
  ],

  "mark": {
    "type": "link",
    "linkShape": "dome",
    "orient": "vertical",
    "clampApex": true,
    "color": "gray"
  },

  "encoding": {
    "x": { "field": "x", "type": "index" },
    "x2": { "field": "x2" },
    "y": {
      "field": "y",
      "type": "quantitative",
      "axis": { "grid": true }
    }
  }
}