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:

Mark Name	Method	Description	Example
area	mark_area()	A filled area plot.	Simple Stacked Area Chart
bar	mark_bar()	A bar plot.	Simple Bar Chart
circle	mark_circle()	A scatter plot with filled circles.	One Dot Per Zipcode
geoshape	mark_geoshape()	A geographic shape	Choropleth Map
image	mark_image()	A scatter plot with image markers.	Image Mark
line	mark_line()	A line plot.	Simple Line Chart
point	mark_point()	A scatter plot with configurable point shapes.	Multi-panel Scatter Plot with Linked Brushing
rect	mark_rect()	A filled rectangle, used for heatmaps	Simple Heatmap
rule	mark_rule()	A vertical or horizontal line spanning the axis.	Candlestick Chart
square	mark_square()	A scatter plot with filled squares.	N/A
text	mark_text()	A scatter plot with points represented by text.	Bar Chart with Labels
tick	mark_tick()	A vertical or horizontal tick mark.	Simple Strip Plot

In addition, Altair provides the following compound marks:

Mark Name	Method	Description	Example
box plot	mark_boxplot()	A box plot.	Box Plot with Min/Max Whiskers
error band	mark_errorband()	A continuous band around a line.	Line Chart with Confidence Interval Band
error bar	mark_errorbar()	An errorbar around a point.	Error Bars showing Confidence Interval

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='max-min'

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	Align	The horizontal alignment of the text or ranged marks (area, bar, image, rect, rule). One of "left", "right", "center".
angle	number	The rotation angle of the text, in degrees.
aspect	boolean	Whether to keep aspect ratio of image marks.
baseline	TextBaseline	The vertical text baseline. One of "alphabetic" (default), "top", "middle", "bottom", "line-top", or "line-bottom". The "line-top" and "line-bottom" values operate similarly to "top" and "bottom", but are calculated relative to the lineHeight rather than fontSize alone.
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	Blend	The color blend mode for drawing an item on its current background. Any valid CSS mix-blend-mode value can be used. __Default value: "source-over"
clip	boolean	Whether a mark be clipped to the enclosing group’s width and height.
color	anyOf(Color, Gradient)	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.
cornerRadius	number	The radius in pixels of rounded rectangle corners. Default value: 0
cornerRadiusBottomLeft	number	The radius in pixels of rounded rectangle bottom left corner. Default value: 0
cornerRadiusBottomRight	number	The radius in pixels of rounded rectangle bottom right corner. Default value: 0
cornerRadiusEnd	number	For vertical bars, top-left and top-right corner radius. For horizontal bars, top-right and bottom-right corner radius.
cornerRadiusTopLeft	number	The radius in pixels of rounded rectangle top right corner. Default value: 0
cornerRadiusTopRight	number	The radius in pixels of rounded rectangle top left corner. Default value: 0
cursor	Cursor	The mouse cursor used over the mark. Any valid CSS cursor type can be used.
dir	TextDirection	The direction of the text. One of "ltr" (left-to-right) or "rtl" (right-to-left). This property determines on which side is truncated in response to the limit parameter. Default value: "ltr"
dx	number	The horizontal offset, in pixels, between the text label and its anchor point. The offset is applied after rotation by the angle property.
dy	number	The vertical offset, in pixels, between the text label and its anchor point. The offset is applied after rotation by the angle property.
ellipsis	string	The ellipsis string for text truncated in response to the limit parameter. Default value: "…"
fill	anyOf(Color, Gradient, null)	Default Fill Color. This property has higher precedence than config.color. Default value: (None)
fillOpacity	number	The fill opacity (value between [0,1]). Default value: 1
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	string	The typeface to set the text in (e.g., "Helvetica Neue").
fontSize	number	The font size, in pixels. Default value: 11
fontStyle	FontStyle	The font style (e.g., "italic").
fontWeight	FontWeight	The font weight. This can be either a string (e.g "bold", "normal") or a number (100, 200, 300, …, 900 where "normal" = 400 and "bold" = 700).
height	number	Height of the marks.
href	string	A URL to load upon mouse click. If defined, the mark acts as a hyperlink.
interpolate	Interpolate	The line interpolation method to use for line and area marks. One of the following: "linear": piecewise linear segments, as in a polyline. "linear-closed": close the linear segments to form a polygon. "step": alternate between horizontal and vertical segments, as in a step function. "step-before": alternate between vertical and horizontal segments, as in a step function. "step-after": alternate between horizontal and vertical segments, as in a step function. "basis": a B-spline, with control point duplication on the ends. "basis-open": an open B-spline; may not intersect the start or end. "basis-closed": a closed B-spline, as in a loop. "cardinal": a Cardinal spline, with control point duplication on the ends. "cardinal-open": an open Cardinal spline; may not intersect the start or end, but will intersect other control points. "cardinal-closed": a closed Cardinal spline, as in a loop. "bundle": equivalent to basis, except the tension parameter is used to straighten the spline. "monotone": cubic interpolation that preserves monotonicity in y.
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	number	The maximum length of the text mark in pixels. The text value will be automatically truncated if the rendered size exceeds the limit. Default value: 0 – indicating no limit
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	string	A delimiter, such as a newline character, upon which to break text strings into multiple lines. This property is ignored if the text is array-valued.
lineHeight	number	The line height in pixels (the spacing between subsequent lines of text) for multi-line text marks.
opacity	number	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.
point	anyOf(boolean, OverlayMarkDef, [‘transparent’])	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	number	Polar coordinate radial offset, in pixels, of the text label from the origin determined by the x and y properties.
shape	anyOf(SymbolShape, string)	Shape of the point marks. Supported values include: plotting shapes: "circle", "square", "cross", "diamond", "triangle-up", "triangle-down", "triangle-right", or "triangle-left". the line symbol "stroke" centered directional shapes "arrow", "wedge", or "triangle" a custom SVG path string (For correct sizing, custom shape paths should be defined within a square bounding box with coordinates ranging from -1 to 1 along both the x and y dimensions.) Default value: "circle"
size	number	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.
stroke	anyOf(Color, Gradient, null)	Default Stroke Color. This property has higher precedence than config.color. Default value: (None)
strokeCap	string	The stroke cap for line ending style. One of "butt", "round", or "square". Default value: "butt"
strokeDash	array(number)	An array of alternating stroke, space lengths for creating dashed or dotted lines.
strokeDashOffset	number	The offset (in pixels) into which to begin drawing with the stroke dash array.
strokeJoin	string	The stroke line join method. One of "miter", "round" or "bevel". Default value: "miter"
strokeMiterLimit	number	The miter limit at which to bevel a line join.
strokeOffset	number	The offset in pixels at which to draw the group stroke and fill. If unspecified, the default behavior is to dynamically offset stroked groups such that 1 pixel stroke widths align with the pixel grid.
strokeOpacity	number	The stroke opacity (value between [0,1]). Default value: 1
strokeWidth	number	The stroke width, in pixels.
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	number	Depending on the interpolation type, sets the tension parameter (for line and area marks).
text	Text	Placeholder text if the text channel is not specified
theta	number	Polar coordinate angle, in radians, of the text label from the origin determined by the x and y properties. Values for theta follow the same convention of arc mark startAngle and endAngle properties: angles are measured in radians, with 0 indicating “north”.
thickness	number	Thickness of the tick mark. Default value: 1
timeUnitBand	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.
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.
tooltip	anyOf(number, string, boolean, TooltipContent, 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").
width	number	Width of the marks.
x	anyOf(number, [‘width’])	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, [‘width’])	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	number	Offset for x2-position.
xOffset	number	Offset for x-position.
y	anyOf(number, [‘height’])	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, [‘height’])	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	number	Offset for y2-position.
yOffset	number	Offset for y-position.

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