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 linkShape
s 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. Bothfalse
and[0, 0]
disable fading.Default value:
false
arcHeightFactor
-
Type: number | ExprRef
Scaling factor for the
"arc
" shape's height. The default value1.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
orstroke
, depending on thefilled
property. linkShape
-
Type:
"arc"
|"diagonal"
|"line"
|"dome"
| ExprRefThe 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"
and2.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
orstrokeOpacity
, depending on thefilled
property. orient
-
Type:
"vertical"
|"horizontal"
| ExprRefThe 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
andx2
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
andy2
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 }
}
}
}