Text¶

Text mark displays each data item as text.

{
  "data": {
    "values": [
      { "x": 1, "text": "Hello" },
      { "x": 2, "text": "world!" }
    ]
  },
  "mark": "text",
  "encoding": {
    "x": { "field": "x", "type": "ordinal" },
    "color": { "field": "x", "type": "nominal" },
    "text": { "field": "text" },
    "size": { "value": 100 }
  }
}

Channels¶

In addition to primary and secondary position channels and color and opacity channels, point mark has the following channels: text, size, and angle.

Properties¶

align

Type: "left" | "center" | "right"

The horizontal alignment of the text. One of "left", "center", or "right".

Default value: "left"

angle

Type: number | ExprRef

The rotation angle in degrees.

Default value: 0

baseline

Type: "top" | "middle" | "bottom" | "alphabetic"

The vertical alignment of the text. One of "top", "middle", "bottom".

Default value: "bottom"

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.

dx

Type: number

The horizontal offset between the text and its anchor point, in pixels. Applied after the rotation by angle.

dy

Type: number

The vertical offset between the text and its anchor point, in pixels. Applied after the rotation by angle.

fitToBand

Type: boolean | ExprRef

If true, sets the secondary positional channel that allows the text to be squeezed (see the squeeze property). Can be used when: 1) "band", "index", or "locus" scale is being used and 2) only the primary positional channel is specified.

Default value: false

flushX

Type: boolean | ExprRef

If true, the text is kept inside the viewport when the range of x and x2 intersect the viewport.

flushY

Type: boolean | ExprRef

If true, the text is kept inside the viewport when the range of y and y2 intersect the viewport.

font

Type: string

The font typeface. GenomeSpy uses SDF versions of Google Fonts. Check their availability at the A-Frame Fonts repository. System fonts are not supported.

Default value: "Lato"

fontStyle

Type: "normal" | "italic"

The font style. Valid values: "normal" and "italic".

Default value: "normal"

fontWeight

The font weight. The following strings and numbers are valid values: "thin" (100), "light" (300), "regular" (400), "normal" (400), "medium" (500), "bold" (700), "black" (900)

Default value: "regular"

logoLetters

Type: boolean | ExprRef

Stretch letters so that they can be used with sequence logos, etc...

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.

opacity

Type: number | ExprRef

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

paddingX

Type: number | ExprRef

The horizontal padding, in pixels, when the x2 channel is used for ranged text.

Default value: 0

paddingY

Type: number | ExprRef

The vertical padding, in pixels, when the y2 channel is used for ranged text.

Default value: 0

size

Type: number | ExprRef

The font size in pixels.

Default value: 11

squeeze

Type: boolean | ExprRef

If the squeeze property is true and secondary positional channels (x2 and/or y2) are used, the text is scaled to fit mark's width and/or height.

Default value: true

text

Type: Scalar | ExprRef

The text to display. The format of numeric data can be customized by setting a format specifier to channel definition's format property.

Default value: ""

tooltip

Type: HandledTooltip | null

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

viewportEdgeFadeDistanceBottom

Type: number

TODO

viewportEdgeFadeDistanceLeft

Type: number

TODO

viewportEdgeFadeDistanceRight

Type: number

TODO

viewportEdgeFadeDistanceTop

Type: number

TODO

viewportEdgeFadeWidthBottom

Type: number

TODO

viewportEdgeFadeWidthLeft

Type: number

TODO

viewportEdgeFadeWidthRight

Type: number

TODO

viewportEdgeFadeWidthTop

Type: number

TODO

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¶

GenomeSpy's text mark provides several tricks useful with segmented data and zoomable visualizations.

Ranged text¶

The x2 and y2 channels allow for positioning the text inside a segment. The text is either squeezed (default) or hidden when it does not fit in the segment. The squeeze property controls the behavior.

The example below has two layers: gray rectangles at the bottom and ranged text on the top. Try to zoom and pan to see how they behave!

{
  "data": {
    "values": ["A", "B", "C", "D", "E", "F", "G"]
  },
  "transform": [
    { "type": "formula", "expr": "round(random() * 100)", "as": "a" },
    { "type": "formula", "expr": "datum.a + round(random() * 60)", "as": "b" }
  ],
  "encoding": {
    "x": { "field": "a", "type": "quantitative", "scale": { "zoom": true } },
    "x2": { "field": "b" },
    "y": {
      "field": "data",
      "type": "nominal",
      "scale": {
        "padding": 0.3
      }
    }
  },
  "layer": [
    {
      "mark": "rect",
      "encoding": { "color": { "value": "#eaeaea" } }
    },
    {
      "mark": {
        "type": "text",
        "align": "center",
        "baseline": "middle",
        "paddingX": 5
      },
      "encoding": {
        "text": {
          "expr": "'Hello ' + floor(datum.a)"
        },
        "size": { "value": 12 }
      }
    }
  ]
}

Sequence logo¶

The example below demonstrates the use of the logoLetters, squeeze, and fitToBand properties to ensure that the letters fully cover the rectangles defined by the primary and secondary positional channels. Not all fonts look good in sequence logos, but Source Sans Pro seems decent.

{
  "data": {
    "values": [
      { "pos": 1, "base": "A", "count": 2 },
      { "pos": 1, "base": "C", "count": 3 },
      { "pos": 1, "base": "T", "count": 5 },
      { "pos": 2, "base": "A", "count": 7 },
      { "pos": 2, "base": "C", "count": 3 },
      { "pos": 3, "base": "A", "count": 10 },
      { "pos": 4, "base": "T", "count": 9 },
      { "pos": 4, "base": "G", "count": 1 },
      { "pos": 5, "base": "G", "count": 8 },
      { "pos": 6, "base": "G", "count": 7 }
    ]
  },
  "transform": [
    {
      "type": "stack",
      "field": "count",
      "groupby": ["pos"],
      "offset": "information",
      "as": ["_y0", "_y1"],
      "baseField": "base",
      "sort": { "field": "count", "order": "ascending" }
    }
  ],
  "encoding": {
    "x": { "field": "pos", "type": "index" },
    "y": {
      "field": "_y0",
      "type": "quantitative",
      "scale": { "domain": [0, 2] },
      "title": "Information"
    },
    "y2": { "field": "_y1" },
    "text": { "field": "base", "type": "nominal" },
    "color": {
      "field": "base",
      "type": "nominal",
      "scale": {
        "type": "ordinal",
        "domain": ["A", "C", "T", "G"],
        "range": ["#7BD56C", "#FF9B9B", "#86BBF1", "#FFC56C"]
      }
    }
  },
  "mark": {
    "type": "text",
    "font": "Source Sans Pro",
    "fontWeight": 700,
    "size": 100,
    "squeeze": true,
    "fitToBand": true,

    "paddingX": 0,
    "paddingY": 0,

    "logoLetters": true
  }
}