Line

{
  "data": ... ,
  "mark": "line",
  "encoding": ... ,
  ...
}

The line mark represents the data points stored in a field with a line connecting all of these points. Line marks are commonly used to depict trajectories or change over time. Unlike most other marks that represent one data element per mark, one line mark represents multiple data element as a single line, akin to area and trail.

Note: For line segments that connect (x,y) positions to (x2,y2) positions, please use rule marks. For continuous lines with varying size, please use trail marks.

Documentation Overview

• Line Mark Properties
• Examples
  • Line Chart
  • Multi-series Colored Line Chart
  • Multi-series Line Chart with the Detail Channel
  • Line Chart with Point Markers
  • Line Chart with Invalid Values
  • Connected Scatter Plot (Line Chart with Custom Path)
  • Line interpolation
  • Geo Line
• Line Config

Line Mark Properties

// Single View Specification
{
  ...
  "mark": {
    "type": "line",
    ...
  },
  "encoding": ... ,
  ...
}

An line mark definition can contain any standard mark properties and the following line interpolation and point overlay properties:

Examples

Line Chart

Using line with one temporal or ordinal field (typically on x) and another quantitative field (typically on y) produces a simple line chart with a single line.

We can add create multiple lines by grouping along different attributes, such as color or detail.

Multi-series Colored Line Chart

Adding a field to a mark property channel such as color groups data points into different series, producing a multi-series colored line chart.

Multi-series Line Chart with the Detail Channel

To group lines by a field without mapping the field to any visual properties, we can map the field to the detail channel to create a multi-series line chart with the same color.

The same method can be used to group lines for a ranged dot plot.

Line Chart with Point Markers

By setting the point property of the mark definition to true or an object defining a property of the overlaying point marks, we can overlay point markers on top of line. Here we set the point color to "red" and set the line color to "green".

This is equilvalent to adding another layer of filled point marks.

Note that the overlay point marks have opacity = 1 by default (instead of semi-transparent like normal point marks).

Line Chart with Invalid Values

By default, data points with invalid x- or y-values (null or NaN) will cause break in the lines.

Note that individual points without connecting points will still be invisible by default.

To show individual points without connecting points, you may set strokeCap to "square":

or overlay it with marker points:

Connected Scatter Plot (Line Chart with Custom Path)

As shown in previous example, the line’s path (order of points in the line) is determined by data values on the temporal/ordinal field by default. However, a field can be mapped to the order channel for determining a custom path.

For example, to show a pattern of data change over time between gasoline price and average miles driven per capita we use order channel to sort the points in the line by time field (year). In this example, we also use the point property to overlay point marks over the line marks to highlight each data point.

Line interpolation

The interpolate property of a mark definition can be used to change line interpolation method. For example, we can set interpolate to "monotone".

We can also set interpolate to "step-after" to create a step-chart.

For the list of all supported interpolate properties, please see the mark definition documentation.

Geo Line

By mapping geographic coordinate data to longitude and latitude channels of a corresponding projection, we can draw lines through geographic points.

Line Config

// Top-level View Specification
{
  ...
  "config": {
    "line": ...,
    ...
  }
}

The line property of the top-level config object sets the default properties for all line marks. If mark property encoding channels are specified for marks, these config values will be overridden.

The line config can contain any line mark properties (except type, style, and clip).