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 mark properties:

Mark Name Method Description Example
area mark_area() A filled area plot.  
bar mark_bar() A bar plot.  
circle mark_circle() A scatter plot with filled circles.  
geoshape mark_geoshape() A geographic shape  
line mark_line() A line plot.  
point mark_point() A scatter plot with configurable point shapes.  
rect mark_rect() A filled rectangle, used for heatmaps  
rule mark_rule() A vertical or horizontal line spanning the axis.  
square mark_square() A scatter plot with filled squares.  
text mark_text() A scatter plot with points represented by text  
tick mark_tick() A vertical or horizontal tick mark.  

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'
)

The additional arguments to mark_*() methods are passed along to an associated MarkDef instance, which supports the following attributes:

Property Type Description
align HorizontalAlign The horizontal alignment of the text. One of "left", "right", "center".
angle number The rotation angle of the text, in degrees.
baseline VerticalAlign The vertical alignment of the text. One of "top", "middle", "bottom". Default value: "middle"
clip boolean Whether a mark be clipped to the enclosing group’s width and height.
color string  
cursor [‘auto’, ‘default’, ‘none’, ‘context-menu’, ‘help’, ‘pointer’, ‘progress’, ‘wait’, ‘cell’, ‘crosshair’, ‘text’, ‘vertical-text’, ‘alias’, ‘copy’, ‘move’, ‘no-drop’, ‘not-allowed’, ‘e-resize’, ‘n-resize’, ‘ne-resize’, ‘nw-resize’, ‘s-resize’, ‘se-resize’, ‘sw-resize’, ‘w-resize’, ‘ew-resize’, ‘ns-resize’, ‘nesw-resize’, ‘nwse-resize’, ‘col-resize’, ‘row-resize’, ‘all-scroll’, ‘zoom-in’, ‘zoom-out’, ‘grab’, ‘grabbing’] The mouse cursor used over the mark. Any valid CSS cursor type can be used.
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.
fill string Default Fill Color. This 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: true for all marks except point and false for point. Applicable for: bar, point, circle, square, and area marks. 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.
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).
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.
limit number The maximum length of the text mark in pixels (default 0, indicating no limit). The text value will be automatically truncated if the rendered size exceeds the limit.
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.
orient Orient 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, 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.
radius number Polar coordinate radial offset, in pixels, of the text label from the origin determined by the x and y properties.
shape string The default symbol shape to use. One of: "circle" (default), "square", "cross", "diamond", "triangle-up", or "triangle-down", or a custom SVG path. Default value: "circle"
size number The pixel area each the point/circle/square. For example: in the case of circles, the radius is determined in part by the square root of the size value. Default value: 30
stroke string Default Stroke Color. This has higher precedence than config.color Default value: (None)
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.
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 string 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”.
type Mark The mark type. One of "bar", "circle", "square", "tick", "line", "area", "point", "geoshape", "rule", and "text".

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