Skip to content

Link

The "link" mark displays each row 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.

{
  "description": "Link mark example.",

  "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 fading distance range for "arc" and "dome" shapes, in logical screen pixels. Opacity fades smoothly from one to zero between these perpendicular distances from the line joining the rendered endpoints. For domes, this is the baseline rather than the apex position, regardless of orientation, direction, or the scale used for height. 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

buildIndex
Type: boolean

Whether the x channel should build an index for efficient subset rendering. If omitted, GenomeSpy enables indexing automatically for positional x encodings.

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 | "x" | "y" | "never"

Controls whether the mark is clipped to the UnitView's rectangle. The values "x" and "y" clip only in the corresponding screen-space direction. Inherited clipping from parent containers still applies unless "never" is used.

Default value: true when either positional scale is zoomable; otherwise false

color
Type: string | ExprRef

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

cullByVisibleRange
Type: boolean | "x" | "y"

Hide point-like mark instances whose anchor falls outside the inherited visible range in the given screen-space direction.

cursor
Type: string | ExprRef

Mouse cursor shown while the pointer is over the mark. Mark cursor takes precedence over enclosing view cursors.

Default value: browser default

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

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 for selected links. Tests selections referenced by conditional encodings, excluding empty selections. Despite the property name, interval selections also bypass fading when either link endpoint is inside each selected interval. Only marks that participate in picking use this bypass.

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.

style
Type: string | string[]

Named style reference(s) resolved from config.style. If an array is provided, later styles override earlier ones.

tooltip
Type: HandledTooltip | null | boolean

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.

x2Offset
Type: number | ExprRef

Offset of the x2 coordinate in logical pixels. When x2 is implicit, it inherits xOffset unless this property is specified.

Default value: inherited from xOffset for an implicit x2, otherwise 0

xOffset
Type: number | ExprRef

Offset of the x coordinate in logical pixels.

Default value: 0

y
Type: number | ExprRef

Position on the y axis.

y2
Type: number | ExprRef

The secondary position on the y axis.

y2Offset
Type: number | ExprRef

Offset of the y2 coordinate in logical pixels. When y2 is implicit, it inherits yOffset unless this property is specified.

Default value: inherited from yOffset for an implicit y2, otherwise 0

yOffset
Type: number | ExprRef

Offset of the y coordinate in logical pixels.

Default value: 0

Examples

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".

{
  "description": "Link mark example showing shapes and orientations.",

  "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] }
    },
    "x2": { "field": "x2" },
    "y": {
      "field": "x",
      "type": "quantitative",
      "scale": { "domain": [0, 10] }
    },
    "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" }
    }
  ],

  "config": {
    "axisQuantitative": { "grid": true }
  }
}

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.

{
  "description": "Link mark example with variable dome heights.",

  "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 }
    }
  }
}