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": 10, "as": "z" }
  },

  "transform": [
    { "type": "formula", "expr": "pow(2, datum.z)", "as": "start" },
    { "type": "formula", "expr": "datum.start * 2", "as": "end" }
  ],

  "mark": "link",

  "encoding": {
    "x": { "field": "start", "type": "index" },
    "x2": { "field": "end" }
  }
}

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

Alias for noFadingOnSecondPass, used only when that property is unspecified. Requires active conditional ordering; selections in color or size encodings alone no longer suppress fading.

noFadingOnSecondPass
Type: boolean | ExprRef

Shows foreground arcs in full by disabling distance fading during the second visual pass of an active conditional order encoding. Configure selected links with the higher order value to draw them unfaded above other links. Reversing the order values instead exempts the unselected links.

Has no effect without active conditional ordering, including when all selections are empty. Picking always uses normal fading.

Default value: false

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 false, no tooltip is shown but the mark remains available for renderer picking and mark interactions. If null, no tooltip is shown and the mark is excluded from picking unless its view declares a point selection; a point selection overrides this picking opt-out. 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

Showing selected arcs in full

Distance fading gives arcs a softer ending than abrupt clipping and reduces clutter when showing structural variants across multiple samples. Disabling fading for selected arcs makes their connections easier to follow, especially in dense multi-sample views. Combine conditional draw order with noFadingOnSecondPass: true:

{
  "mark": {
    "type": "link",
    "arcFadingDistance": [100, 200],
    "noFadingOnSecondPass": true
  },
  "encoding": {
    "order": {
      "condition": { "param": "picked", "empty": false, "value": 1 },
      "value": 0
    }
  }
}

This fragment assumes a selection parameter named picked and positional encodings for the link endpoints. The lower order level draws first with normal fading. The higher level draws second without fading, so selected links appear in full above the others. The option follows the second partition, not selection membership: reversing the order values makes unselected links unfaded.

The option defaults to false. Without active conditional ordering, including when every referenced selection is empty, all links retain normal fading.

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