Marks#

We saw in Encodings that the encode() method is used to map columns to visual attributes of the plot. The mark property is what specifies how exactly those attributes should be represented on the plot.

Altair provides a number of basic mark properties (the mark properties column links to the Vega-Lite documentation that allows you to interactively explore the effects of modifying each property):

Mark

Description

Example

Mark Properties

mark_arc()

A pie chart.

Pie Chart

Vega-Lite Docs

mark_area()

A filled area plot.

Simple Stacked Area Chart

Vega-Lite Docs

mark_bar()

A bar plot.

Simple Bar Chart

Vega-Lite Docs

mark_circle()

A scatter plot with filled circles.

One Dot Per Zipcode

Vega-Lite Docs

mark_geoshape()

A geographic shape

Choropleth Map

Vega-Lite Docs

mark_image()

A scatter plot with image markers.

Image Mark

Vega-Lite Docs

mark_line()

A line plot.

Simple Line Chart

Vega-Lite Docs

mark_point()

A scatter plot with configurable point shapes.

Multi-panel Scatter Plot with Linked Brushing

Vega-Lite Docs

mark_rect()

A filled rectangle, used for heatmaps

Simple Heatmap

Vega-Lite Docs

mark_rule()

A vertical or horizontal line spanning the axis.

Candlestick Chart

Vega-Lite Docs

mark_square()

A scatter plot with filled squares.

N/A

Vega-Lite Docs

mark_text()

A scatter plot with points represented by text.

Bar Chart with Labels

Vega-Lite Docs

mark_tick()

A vertical or horizontal tick mark.

Simple Strip Plot

Vega-Lite Docs

mark_trail()

A line with variable widths.

Line Chart with Varying Size

Vega-Lite Docs

In addition, Altair provides the following compound marks:

Mark

Description

Example

Mark Properties

mark_boxplot()

A box plot.

Boxplot with Min/Max Whiskers

Vega-Lite Docs

mark_errorband()

A continuous band around a line.

Line Chart with Confidence Interval Band

Vega-Lite Docs

mark_errorbar()

An errorbar around a point.

Error Bars showing Confidence Interval

Vega-Lite Docs

In Altair, marks can be most conveniently specified by the mark_* methods of the Chart object, which take optional keyword arguments that are passed to MarkDef to configure the look of the marks.

For example, the following uses mark_circle() with additional arguments to represent points as red semi-transparent filled circles:

import altair as alt
from vega_datasets import data

url = data.cars.url

alt.Chart(url).mark_circle(
    color='red',
    opacity=0.3
).encode(
    x='Horsepower:Q',
    y='Miles_per_Gallon:Q'
)

Image Mark#

The image mark, unlike other simple marks, requires the mark to include a url encoding, which specifies the PNG to use for the image:

import altair as alt
import pandas as pd

source = pd.DataFrame.from_records([
      {"x": 0.5, "y": 0.5, "img": "https://vega.github.io/vega-datasets/data/ffox.png"},
      {"x": 1.5, "y": 1.5, "img": "https://vega.github.io/vega-datasets/data/gimp.png"},
      {"x": 2.5, "y": 2.5, "img": "https://vega.github.io/vega-datasets/data/7zip.png"}
])

alt.Chart(source).mark_image(
    width=50,
    height=50
).encode(
    x='x',
    y='y',
    url='img'
)

Compound Marks#

BoxPlot#

The compound mark mark_boxplot() can be used to create a boxplot without having to specify each part of the plot (box, whiskers, outliers) separately.

import altair as alt
from vega_datasets import data

source = data.population.url

alt.Chart(source).mark_boxplot().encode(
    y='people:Q'
).properties(
    width=200,
    height=300
)

To create a side-by-side boxplot, simply encode the group column on the other axis.

import altair as alt
from vega_datasets import data

source = data.population.url

alt.Chart(source).mark_boxplot().encode(
    x='age:O',
    y='people:Q'
)

Note that the default behavior is to display outliers as points, where an outlier is defined as any point more than 1.5 IQRs from the box. Users can adjust this threshold using the extent property of the mark.

import altair as alt
from vega_datasets import data

source = data.population.url

alt.Chart(source).mark_boxplot(extent=3.0).encode(
    x='age:O',
    y='people:Q'
)

The outliers can be ignored completely using extent='min-max'

import altair as alt
from vega_datasets import data

source = data.population.url

alt.Chart(source).mark_boxplot(extent='min-max').encode(
    x='age:O',
    y='people:Q'
)

Mark Properties#

As seen in the last two examples, additional arguments to mark_*() methods are passed along to an associated MarkDef instance, which supports the following attributes:

Property

Type

Description

align

anyOf(Align, ExprRef)

The horizontal alignment of the text or ranged marks (area, bar, image, rect, rule). One of "left", "right", "center".

Note: Expression reference is not supported for range marks.

angle

anyOf(number, ExprRef)

aria

anyOf(boolean, ExprRef)

ariaRole

anyOf(string, ExprRef)

ariaRoleDescription

anyOf(string, ExprRef)

aspect

anyOf(boolean, ExprRef)

bandSize

number

The width of the ticks.

Default value: 3/4 of step (width step for horizontal ticks and height step for vertical ticks).

baseline

anyOf(TextBaseline, ExprRef)

For text marks, the vertical text baseline. One of "alphabetic" (default), "top", "middle", "bottom", "line-top", "line-bottom", or an expression reference that provides one of the valid values. The "line-top" and "line-bottom" values operate similarly to "top" and "bottom", but are calculated relative to the lineHeight rather than fontSize alone.

For range marks, the vertical alignment of the marks. One of "top", "middle", "bottom".

Note: Expression reference is not supported for range marks.

binSpacing

number

Offset between bars for binned field. The ideal value for this is either 0 (preferred by statisticians) or 1 (Vega-Lite default, D3 example style).

Default value: 1

blend

anyOf(Blend, ExprRef)

clip

boolean

Whether a mark be clipped to the enclosing group’s width and height.

color

anyOf(Color, Gradient, ExprRef)

Default color.

Default value: "#4682b4"

Note:

  • This property cannot be used in a style config.

  • The fill and stroke properties have higher precedence than color and will override color.

continuousBandSize

number

The default size of the bars on continuous scales.

Default value: 5

cornerRadius

anyOf(number, ExprRef)

cornerRadiusBottomLeft

anyOf(number, ExprRef)

cornerRadiusBottomRight

anyOf(number, ExprRef)

cornerRadiusEnd

anyOf(number, ExprRef)

  • For vertical bars, top-left and top-right corner radius.

  • For horizontal bars, top-right and bottom-right corner radius.

cornerRadiusTopLeft

anyOf(number, ExprRef)

cornerRadiusTopRight

anyOf(number, ExprRef)

cursor

anyOf(Cursor, ExprRef)

description

anyOf(string, ExprRef)

dir

anyOf(TextDirection, ExprRef)

discreteBandSize

anyOf(number, RelativeBandSize)

The default size of the bars with discrete dimensions. If unspecified, the default size is step-2, which provides 2 pixel offset between bars.

dx

anyOf(number, ExprRef)

dy

anyOf(number, ExprRef)

ellipsis

anyOf(string, ExprRef)

fill

anyOf(Color, Gradient, null, ExprRef)

Default fill color. This property has higher precedence than config.color. Set to null to remove fill.

Default value: (None)

fillOpacity

anyOf(number, ExprRef)

filled

boolean

Whether the mark’s color should be used as fill color instead of stroke color.

Default value: false for all point, line, and rule marks as well as geoshape marks for graticule data sources; otherwise, true.

Note: This property cannot be used in a style config.

font

anyOf(string, ExprRef)

fontSize

anyOf(number, ExprRef)

fontStyle

anyOf(FontStyle, ExprRef)

fontWeight

anyOf(FontWeight, ExprRef)

height

anyOf(number, ExprRef, RelativeBandSize)

Height of the marks. One of:

  • A number representing a fixed pixel height.

  • A relative band size definition. For example, {band: 0.5} represents half of the band

href

anyOf(URI, ExprRef)

innerRadius

anyOf(number, ExprRef)

The inner radius in pixels of arc marks. innerRadius is an alias for radius2.

Default value: 0

interpolate

anyOf(Interpolate, ExprRef)

invalid

[‘filter’, None]

Defines how Vega-Lite should handle marks for invalid values (null and NaN).

  • If set to "filter" (default), all data items with null values will be skipped (for line, trail, and area marks) or filtered (for other marks).

  • If null, all data items are included. In this case, invalid values will be interpreted as zeroes.

limit

anyOf(number, ExprRef)

line

anyOf(boolean, OverlayMarkDef)

A flag for overlaying line on top of area marks, or an object defining the properties of the overlayed lines.

  • If this value is an empty object ({}) or true, lines with default properties will be used.

  • If this value is false, no lines would be automatically added to area marks.

Default value: false.

lineBreak

anyOf(string, ExprRef)

lineHeight

anyOf(number, ExprRef)

opacity

anyOf(number, ExprRef)

The overall opacity (value between [0,1]).

Default value: 0.7 for non-aggregate plots with point, tick, circle, or square marks or layered bar charts and 1 otherwise.

order

[null, boolean]

For line and trail marks, this order property can be set to null or false to make the lines use the original order in the data sources.

orient

Orientation

The orientation of a non-stacked bar, tick, area, and line charts. The value is either horizontal (default) or vertical.

  • For bar, rule and tick, this determines whether the size of the bar and tick should be applied to x or y dimension.

  • For area, this property determines the orient property of the Vega output.

  • For line and trail marks, this property determines the sort order of the points in the line if config.sortLineBy is not specified. For stacked charts, this is always determined by the orientation of the stack; therefore explicitly specified value will be ignored.

outerRadius

anyOf(number, ExprRef)

The outer radius in pixels of arc marks. outerRadius is an alias for radius.

Default value: 0

padAngle

anyOf(number, ExprRef)

point

anyOf(boolean, OverlayMarkDef, string)

A flag for overlaying points on top of line or area marks, or an object defining the properties of the overlayed points.

  • If this property is "transparent", transparent points will be used (for enhancing tooltips and selections).

  • If this property is an empty object ({}) or true, filled points with default properties will be used.

  • If this property is false, no points would be automatically added to line or area marks.

Default value: false.

radius

anyOf(number, ExprRef)

For arc mark, the primary (outer) radius in pixels.

For text marks, polar coordinate radial offset, in pixels, of the text from the origin determined by the x and y properties.

Default value: min(plot_width, plot_height)/2

radius2

anyOf(number, ExprRef)

The secondary (inner) radius in pixels of arc marks.

Default value: 0

radius2Offset

anyOf(number, ExprRef)

Offset for radius2.

radiusOffset

anyOf(number, ExprRef)

Offset for radius.

shape

anyOf(anyOf(SymbolShape, string), ExprRef)

size

anyOf(number, ExprRef)

Default size for marks.

  • For point/circle/square, this represents the pixel area of the marks. Note that this value sets the area of the symbol; the side lengths will increase with the square root of this value.

  • For bar, this represents the band size of the bar, in pixels.

  • For text, this represents the font size, in pixels.

Default value:

  • 30 for point, circle, square marks; width/height’s step

  • 2 for bar marks with discrete dimensions;

  • 5 for bar marks with continuous dimensions;

  • 11 for text marks.

smooth

anyOf(boolean, ExprRef)

stroke

anyOf(Color, Gradient, null, ExprRef)

Default stroke color. This property has higher precedence than config.color. Set to null to remove stroke.

Default value: (None)

strokeCap

anyOf(StrokeCap, ExprRef)

strokeDash

anyOf(array(number), ExprRef)

strokeDashOffset

anyOf(number, ExprRef)

strokeJoin

anyOf(StrokeJoin, ExprRef)

strokeMiterLimit

anyOf(number, ExprRef)

strokeOffset

anyOf(number, ExprRef)

strokeOpacity

anyOf(number, ExprRef)

strokeWidth

anyOf(number, ExprRef)

style

anyOf(string, array(string))

A string or array of strings indicating the name of custom styles to apply to the mark. A style is a named collection of mark property defaults defined within the style configuration. If style is an array, later styles will override earlier styles. Any mark properties explicitly defined within the encoding will override a style default.

Default value: The mark’s name. For example, a bar mark will have style "bar" by default. Note: Any specified style will augment the default style. For example, a bar mark with "style": "foo" will receive from config.style.bar and config.style.foo (the specified style "foo" has higher precedence).

tension

anyOf(number, ExprRef)

text

anyOf(Text, ExprRef)

theta

anyOf(number, ExprRef)

  • For arc marks, the arc length in radians if theta2 is not specified, otherwise the start arc angle. (A value of 0 indicates up or “north”, increasing values proceed clockwise.)

  • For text marks, polar coordinate angle in radians.

theta2

anyOf(number, ExprRef)

The end angle of arc marks in radians. A value of 0 indicates up or “north”, increasing values proceed clockwise.

theta2Offset

anyOf(number, ExprRef)

Offset for theta2.

thetaOffset

anyOf(number, ExprRef)

Offset for theta.

thickness

number

Thickness of the tick mark.

Default value: 1

timeUnitBandPosition

number

Default relative band position for a time unit. If set to 0, the marks will be positioned at the beginning of the time unit band step. If set to 0.5, the marks will be positioned in the middle of the time unit band step.

timeUnitBandSize

number

Default relative band size for a time unit. If set to 1, the bandwidth of the marks will be equal to the time unit band step. If set to 0.5, bandwidth of the marks will be half of the time unit band step.

tooltip

anyOf(number, string, boolean, TooltipContent, ExprRef, null)

The tooltip text string to show upon mouse hover or an object defining which fields should the tooltip be derived from.

  • If tooltip is true or {"content": "encoding"}, then all fields from encoding will be used.

  • If tooltip is {"content": "data"}, then all fields that appear in the highlighted data point will be used.

  • If set to null or false, then no tooltip will be used.

See the tooltip documentation for a detailed discussion about tooltip in Vega-Lite.

Default value: null

type

Mark

The mark type. This could a primitive mark type (one of "bar", "circle", "square", "tick", "line", "area", "point", "geoshape", "rule", and "text") or a composite mark type ("boxplot", "errorband", "errorbar").

url

anyOf(URI, ExprRef)

width

anyOf(number, ExprRef, RelativeBandSize)

Width of the marks. One of:

  • A number representing a fixed pixel width.

  • A relative band size definition. For example, {band: 0.5} represents half of the band.

x

anyOf(number, string, ExprRef)

X coordinates of the marks, or width of horizontal "bar" and "area" without specified x2 or width.

The value of this channel can be a number or a string "width" for the width of the plot.

x2

anyOf(number, string, ExprRef)

X2 coordinates for ranged "area", "bar", "rect", and "rule".

The value of this channel can be a number or a string "width" for the width of the plot.

x2Offset

anyOf(number, ExprRef)

Offset for x2-position.

xOffset

anyOf(number, ExprRef)

Offset for x-position.

y

anyOf(number, string, ExprRef)

Y coordinates of the marks, or height of vertical "bar" and "area" without specified y2 or height.

The value of this channel can be a number or a string "height" for the height of the plot.

y2

anyOf(number, string, ExprRef)

Y2 coordinates for ranged "area", "bar", "rect", and "rule".

The value of this channel can be a number or a string "height" for the height of the plot.

y2Offset

anyOf(number, ExprRef)

Offset for y2-position.

yOffset

anyOf(number, ExprRef)

Offset for y-position.

Marks can also be configured globally using chart-level configurations; see Mark and Mark Style Configuration for details.