Skip to content

Rule

Rule mark displays each row as a line segment. Rules can span the whole width or height of the view. Alternatively, they may have specific endpoints.

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

  "data": {
    "sequence": { "start": 0, "stop": 15, "as": "y" }
  },

  "mark": { "type": "rule", "strokeDash": [6, 3] },

  "encoding": {
    "x": { "field": "y", "type": "quantitative" },
    "color": { "field": "y", "type": "nominal", "legend": null }
  }
}

Channels

Rule mark supports the primary and secondary position channels and the color, fill, fillOpacity, stroke, strokeWidth, strokeOpacity, opacity, and size channels.

fill sets the body color and takes precedence over color. Both support constant values, fields, expressions, and conditional encodings. size controls the body thickness in logical pixels. stroke adds a border whose full thickness is strokeWidth (default 1). strokeAlign places that band inside, centered on, or outside the nominal body boundary; the default is "outside". Alignment also applies at caps and dash boundaries and supports parameter expressions. With the default outside alignment, a four-pixel body with a one-pixel border has a total thickness of six pixels. Borders are absent by default. fillOpacity and strokeOpacity control the paints separately; opacity affects both. Setting filled: false routes color to the border and leaves the body unfilled, unless an explicit fill is provided.

Properties

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.

clamp

Type: boolean | "x" | "y"

Clamps projected anchors or range endpoints to the view before constructing mark geometry. true clamps both axes; "x" or "y" selects one axis. Position offsets are included. For rectangles, clamping keeps outlines around the visible part of a group during zooming. With clip: false, full strokes remain visible at the boundary; symbols, arrowheads, and text glyphs can extend beyond it.

Rectangles and explicit text ranges collapsed on a clamped axis are hidden. Rules and ticks intersect the selected bounds without changing direction; excluded or collapsed segments are hidden. Zero-length rules are hidden even when clamp is false. Links and arrows with coincident endpoints are hidden. Shared scales and their inversion are unchanged.

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

fill

Type: string | ExprRef

The fill color.

fillOpacity

Type: number | ExprRef

The fill opacity. Value between 0 and 1.

filled

Type: boolean

Whether the color represents the fill color (true) or the stroke color (false).

minLength

Type: number | ExprRef

The minimum stroke length in pixels. Use this property to ensure that very short strokes remain visible even when the user zooms out.

Default value: 0

opacity

Type: number | ExprRef

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

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

strokeAlign

Type: "inside" | "center" | "outside" | ExprRef

Position of the full-width stroke band relative to the nominal body. Inside strokes extend inward by strokeWidth, centered strokes extend half inward and half outward, and outside strokes extend entirely outward. The nominal body is unchanged. Canvas uses an outside-style approximation for all alignments.

Default value: "outside"

strokeCap

Type: "butt" | "square" | "round" | ExprRef

The style of stroke ends. Available choices: "butt", "round", and "square".

Default value: "butt"

strokeDash

Type: array

An array of of alternating stroke and gap lengths or null for solid strokes.

Default value: null

strokeDashOffset

Type: number

An offset for the stroke dash pattern.

Default value: 0

strokeOpacity

Type: number | ExprRef

The stroke opacity. Value between 0 and 1.

strokeWidth

Type: number | ExprRef

The stroke width in pixels.

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

strokeCap applies to each dash as well as the rule endpoints. Dash lengths and gaps are measured along the centerline in logical pixels, before cap extension. Round and square caps can close small gaps; a zero-length dash such as strokeDash: [0, 28] produces dots with round caps, squares with square caps, and no body with butt caps. Outside borders follow the combined dash silhouette.

Examples

Ranged rules

{
  "description": "Ranged rule mark example.",

  "data": {
    "values": [
      { "y": "A", "x": 2, "x2": 7 },
      { "y": "B", "x": 0, "x2": 3 },
      { "y": "B", "x": 5, "x2": 6 },
      { "y": "C", "x": 4, "x2": 8 },
      { "y": "D", "x": 1, "x2": 5 }
    ]
  },

  "mark": { "type": "rule", "size": 10, "strokeCap": "round" },

  "encoding": {
    "y": { "field": "y", "type": "nominal" },
    "x": { "field": "x", "type": "quantitative" },
    "x2": { "field": "x2" }
  }
}

Outlined rules

Solid, dashed, and dotted rules can share the same fill and outside border:

{
  "description": [
    "Outlined rules",
    "Solid, dashed, and dotted rules with a shared fill and outside border."
  ],

  "data": { "values": [{ "start": 10, "end": 90 }] },

  "config": {
    "rule": {
      "size": 8,
      "fill": "skyblue",
      "stroke": "midnightblue",
      "strokeWidth": 2,
      "strokeCap": "round"
    }
  },

  "encoding": {
    "x": {
      "field": "start",
      "type": "quantitative",
      "scale": { "domain": [0, 100] },
      "axis": null
    },
    "x2": { "field": "end" }
  },

  "vconcat": [
    {
      "title": "Solid",
      "height": 32,
      "mark": "rule"
    },

    {
      "title": "Dashed",
      "height": 32,
      "mark": { "type": "rule", "strokeDash": [24, 16] }
    },

    {
      "title": "Dotted",
      "height": 32,
      "mark": { "type": "rule", "strokeDash": [0, 24] }
    }
  ]
}

Rendering caveats

The Canvas renderer and Canvas-backed exports approximate outlines with native strokes to maintain interactive performance. They use an outside-style border for every strokeAlign value. Borders can show through translucent fills, opacity can blend differently, and butt endpoints or dash cuts may lack a complete border.

SVG export expands each dash into path geometry and uses a mask for each outlined rule. Large numbers of outlined dashes can produce large SVG files that are slow to render. SVG viewers may also show a thin antialiasing seam between the fill and border.

Weighted network

White outside borders separate crossing links while preserving the colored body thickness set by size, so link weights remain readable. Centered and inside borders cover part of the body and can obscure thin links. The node positions are precomputed with a force-directed layout, and points draw the nodes above the links.

{
  "description": [
    "Weighted network with outlined rules",
    "White outside borders separate crossing links while preserving the body thickness that encodes their weights."
  ],

  "params": [
    {
      "name": "alignment",
      "value": "outside",
      "bind": {
        "input": "radio",
        "options": ["outside", "center", "inside"],
        "name": "Stroke alignment"
      }
    },
    {
      "name": "showStroke",
      "value": true,
      "bind": { "input": "checkbox", "name": "Show border" }
    }
  ],

  "data": {
    "url": "data/weighted-network.json",
    "format": { "property": "nodes" }
  },

  "encoding": {
    "x": {
      "field": "x",
      "type": "quantitative",
      "scale": { "domain": [0, 1] },
      "axis": null
    },
    "y": {
      "field": "y",
      "type": "quantitative",
      "scale": { "domain": [0, 1] },
      "axis": null
    }
  },

  "layer": [
    {
      "data": {
        "url": "data/weighted-network.json",
        "format": { "property": "links" }
      },

      "transform": [
        {
          "type": "lookup",
          "from": {
            "url": "data/weighted-network.json",
            "format": { "property": "nodes" }
          },
          "key": "id",
          "fields": "source",
          "values": ["x", "y"]
        },
        {
          "type": "lookup",
          "from": {
            "url": "data/weighted-network.json",
            "format": { "property": "nodes" }
          },
          "key": "id",
          "fields": "target",
          "values": ["x", "y"],
          "as": ["x2", "y2"]
        },
        {
          "type": "collect",
          "sort": { "field": "weight", "order": "ascending" }
        }
      ],

      "mark": {
        "type": "rule",
        "color": "#4c78a8",
        "stroke": "white",
        "strokeWidth": { "expr": "showStroke ? 1 : 0" },
        "strokeAlign": { "expr": "alignment" }
      },

      "encoding": {
        "x2": { "field": "x2" },
        "y2": { "field": "y2" },
        "size": {
          "field": "weight",
          "type": "quantitative",
          "scale": { "range": [0.5, 5] }
        }
      }
    },

    {
      "mark": {
        "type": "point",
        "filled": true,
        "color": "#f28e2b",
        "size": 225,
        "stroke": "white",
        "strokeWidth": 1
      }
    }
  ]
}

Human-mouse synteny

{
  "description": [
    "Human-mouse synteny example",
    "Data source: http://bioinfo.konkuk.ac.kr/synteny_portal/"
  ],

  "title": "Human-mouse synteny",

  "view": { "stroke": "lightgray" },

  "data": { "url": "data/synteny-hg38-mm10.tsv" },

  "mark": {
    "type": "rule",
    "strokeCap": "round",
    "size": 2
  },

  "encoding": {
    "x": {
      "chrom": "hg38_chrom",
      "pos": "hg38_start",
      "type": "locus",
      "scale": { "type": "locus", "assembly": "hg38" },
      "axis": { "chromGrid": true, "chromGridColor": "#bbb" },
      "title": "hg38"
    },
    "x2": { "chrom": "hg38_chrom", "pos": "hg38_end" },
    "y": {
      "chrom": "mm10_chrom",
      "pos": "mm10_start",
      "type": "locus",
      "scale": { "type": "locus", "assembly": "mm10" },
      "axis": { "chromGrid": true, "chromGridColor": "#bbb" },
      "title": "mm10"
    },
    "y2": { "chrom": "mm10_chrom", "pos": "mm10_end" },
    "color": { "field": "mm10_chrom", "type": "nominal", "legend": null }
  }
}