Point¶
Point mark displays each data item as a symbol. Points are often used to create a scatter plot. In the genomic context, they could represent, for example, point mutations at genomic loci.
{
"data": { "url": "sincos.csv" },
"mark": "point",
"encoding": {
"x": { "field": "x", "type": "quantitative" },
"y": { "field": "sin", "type": "quantitative" },
"size": { "field": "x", "type": "quantitative" }
}
}
Channels¶
In addition to standard position channels and
color
, opacity
, and strokeWidth
channels, point mark has the following
channels: size
, shape
, dx
, and dy
.
Properties¶
angle
-
Type: number | ExprRef
The rotation angle in degrees.
Default value:
0
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. fill
-
Type: string | ExprRef
The fill color.
fillGradientStrength
-
Type: number | ExprRef
Gradient strength controls the amount of the gradient eye-candy effect in the fill color. Valid values are between
0
and1
.Default value:
0
fillOpacity
-
Type: number | ExprRef
The fill opacity. Value between
0
and1
. filled
-
Type: boolean
Whether the
color
represents thefill
color (true
) or thestroke
color (false
). geometricZoomBound
-
Type: number
Enables geometric zooming. The value is the base two logarithmic zoom level where the maximum point size is reached.
Default value:
0
inwardStroke
-
Type: boolean | ExprRef
Should the stroke only grow inwards, e.g, the diameter/outline is not affected by the stroke width. Thus, a point that has a zero size has no visible stroke. This allows strokes to be used with geometric zoom, etc.
Default value:
false
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"
opacity
-
Type: number | ExprRef
Opacity of the mark. Affects
fillOpacity
orstrokeOpacity
, depending on thefilled
property. semanticZoomFraction
-
Type: number | ExprRef
TODO
Default value:
0.02
shape
-
Type: string | ExprRef
One of
"circle"
,"square"
,"cross"
,"diamond"
,"triangle-up"
,"triangle-down"
,"triangle-right"
,"triangle-left"
,"tick-up"
,"tick-down"
,"tick-right"
, or"tick-left"
Default value:
"circle"
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. stroke
-
Type: string | ExprRef
The stroke color
strokeOpacity
-
Type: number | ExprRef
The stroke opacity. Value between
0
and1
. strokeWidth
-
Type: number | ExprRef
The stroke width in pixels.
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.
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.
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¶
Plenty of points¶
The example below demonstrates how points can be varied by using
shape
, fill
, size
, strokeWidth
, and angle
channels.
{
"data": {
"sequence": { "start": 0, "stop": 160, "as": "z" }
},
"transform": [
{ "type": "formula", "expr": "datum.z % 20", "as": "x" },
{ "type": "formula", "expr": "floor(datum.z / 20)", "as": "y" }
],
"mark": {
"type": "point",
"stroke": "black"
},
"encoding": {
"x": { "field": "x", "type": "ordinal", "axis": null },
"y": { "field": "y", "type": "ordinal", "axis": null },
"shape": { "field": "x", "type": "nominal" },
"fill": { "field": "x", "type": "nominal" },
"size": {
"field": "x",
"type": "quantitative",
"scale": { "type": "pow", "exponent": 2, "range": [0, 900] }
},
"strokeWidth": {
"field": "y",
"type": "quantitative",
"scale": { "range": [0, 4] }
},
"angle": {
"field": "y",
"type": "quantitative",
"scale": { "range": [0, 45] }
}
}
}
Zoom behavior¶
Although points are infinitely small on the real number line, they have a specific diameter on the screen. Thus, closely located points tend to overlap each other. Decreasing the point size reduces the probability of overlap, but in a zoomed-in view, the plot may become overly sparse.
To control overplotting, the point mark provides two zooming behaviors that adjust the point size and visibility based on the zoom level.
Geometric zoom¶
Geometric zoom scales the point size down if the current zoom level is lower
than the specified level (bound). geometricZoomBound
mark property enables
geometric zooming. The value is the negative base two logarithm of the
relative width of the visible domain. Example: 0
: (the default) full-size
points are always shown, 1
: when a half of the domain is visible, 2
: when
a quarter is visible, and so on.
The example below displays 200 000 semi-randomly generated points. The points reach their full size when 1 / 2^10.5 of the domain is visible, which equals about 1500X zoom.
{
"data": {
"sequence": { "start": 0, "stop": 200000, "as": "x" }
},
"transform": [
{ "type": "formula", "expr": "random() * 0.682", "as": "u" },
{
"type": "formula",
"expr": "((datum.u % 1e-8 > 5e-9 ? 1 : -1) * (sqrt(-log(max(1e-9, datum.u))) - 0.618)) * 1.618 + sin(datum.x / 10000)",
"as": "y"
}
],
"mark": {
"type": "point",
"geometricZoomBound": 10.5
},
"encoding": {
"x": { "field": "x", "type": "quantitative", "scale": { "zoom": true } },
"y": { "field": "y", "type": "quantitative" },
"size": { "value": 200 },
"opacity": { "value": 0.6 }
}
}
Tip
You can use geometric zoom to improve rendering performance. Smaller points are faster to render than large points.
Semantic zoom¶
The score-based semantic zoom adjusts the point visibility by coupling a score
threshold to current zoom level. The semanticScore
channel enables the
semantic zoom and specifies the score field. The semanticZoomFraction
property
controls the fraction of data items to show in the fully zoomed-out view, i.e.,
it specifies the threshold score. The fraction is scaled as the viewport is
zoomed. Thus, if the data is distributed roughly uniformly along the zoomed
axis, roughly constant number of points are visible at all zoom levels. The
score can be arbitrarily distributed, as the threshold is computed using
p-quantiles.
The example below has 200 000 semi-randomly generated points with an exponentially distributed score. As the view is zoomed in, new points appear. Their number in the viewport stays approximately constant until the lowest possible score has been reached.
{
"data": {
"sequence": { "start": 0, "stop": 200000, "as": "x" }
},
"transform": [
{ "type": "formula", "expr": "random() * 0.682", "as": "u" },
{
"type": "formula",
"expr": "((datum.u % 1e-8 > 5e-9 ? 1 : -1) * (sqrt(-log(max(1e-9, datum.u))) - 0.618)) * 1.618",
"as": "y"
},
{
"type": "formula",
"expr": "-log(random())",
"as": "score"
}
],
"mark": {
"type": "point",
"semanticZoomFraction": 0.002
},
"encoding": {
"x": { "field": "x", "type": "quantitative", "scale": { "zoom": true } },
"y": { "field": "y", "type": "quantitative" },
"opacity": {
"field": "score",
"type": "quantitative",
"scale": { "range": [0.1, 1] }
},
"semanticScore": { "field": "score", "type": "quantitative" },
"size": { "value": 100 }
}
}
Tip
The score-based semantic zoom is great for filtering point mutations and indels that are scored using CADD, for example.