altair.Legend

class altair.Legend(clipHeight=Undefined, columnPadding=Undefined, columns=Undefined, cornerRadius=Undefined, direction=Undefined, fillColor=Undefined, format=Undefined, formatType=Undefined, gradientLength=Undefined, gradientOpacity=Undefined, gradientStrokeColor=Undefined, gradientStrokeWidth=Undefined, gradientThickness=Undefined, gridAlign=Undefined, labelAlign=Undefined, labelBaseline=Undefined, labelColor=Undefined, labelExpr=Undefined, labelFont=Undefined, labelFontSize=Undefined, labelFontStyle=Undefined, labelFontWeight=Undefined, labelLimit=Undefined, labelOffset=Undefined, labelOpacity=Undefined, labelOverlap=Undefined, labelPadding=Undefined, labelSeparation=Undefined, legendX=Undefined, legendY=Undefined, offset=Undefined, orient=Undefined, padding=Undefined, rowPadding=Undefined, strokeColor=Undefined, symbolDash=Undefined, symbolDashOffset=Undefined, symbolFillColor=Undefined, symbolLimit=Undefined, symbolOffset=Undefined, symbolOpacity=Undefined, symbolSize=Undefined, symbolStrokeColor=Undefined, symbolStrokeWidth=Undefined, symbolType=Undefined, tickCount=Undefined, tickMinStep=Undefined, title=Undefined, titleAlign=Undefined, titleAnchor=Undefined, titleBaseline=Undefined, titleColor=Undefined, titleFont=Undefined, titleFontSize=Undefined, titleFontStyle=Undefined, titleFontWeight=Undefined, titleLimit=Undefined, titleLineHeight=Undefined, titleOpacity=Undefined, titleOrient=Undefined, titlePadding=Undefined, type=Undefined, values=Undefined, zindex=Undefined, **kwds)

Legend schema wrapper

Mapping(required=[]) Properties of a legend or boolean flag for determining whether to show it.

Attributes:
clipHeight : float

The height in pixels to clip symbol legend entries and limit their size.

columnPadding : float

The horizontal padding in pixels between symbol legend entries.

Default value: 10.

columns : float

The number of columns in which to arrange symbol legend entries. A value of 0 or lower indicates a single row with one column per entry.

cornerRadius : float

Corner radius for the full legend.

direction : Orientation

The direction of the legend, one of "vertical" or "horizontal".

Default value:

  • For top-/bottom- orient ed legends, "horizontal"
  • For left-/right- orient ed legends, "vertical"
  • For top/bottom-left/right- orient ed legends, "horizontal" for gradient legends and "vertical" for symbol legends.
fillColor : anyOf(None, Color)

Background fill color for the full legend.

format : anyOf(string, Mapping(required=[]))

When used with the default "number" and "time" format type, the text formatting pattern for labels of guides (axes, legends, headers) and text marks.

See the format documentation for more examples.

When used with a custom “formatType” that takes datum.value and format parameter as input), this property represents the format parameter.

Default value: Derived from numberFormat config for number format and from timeFormat config for time format.

formatType : string

The format type for labels ( "number" or "time" or a registered custom format type ).

Default value:

  • "time" for temporal fields and ordinal and nomimal fields with timeUnit.
  • "number" for quantitative fields as well as ordinal and nomimal fields without timeUnit.
gradientLength : float

The length in pixels of the primary axis of a color gradient. This value corresponds to the height of a vertical gradient or the width of a horizontal gradient.

Default value: 200.

gradientOpacity : float

Opacity of the color gradient.

gradientStrokeColor : anyOf(None, Color)

The color of the gradient stroke, can be in hex color code or regular color name.

Default value: "lightGray".

gradientStrokeWidth : float

The width of the gradient stroke, in pixels.

Default value: 0.

gradientThickness : float

The thickness in pixels of the color gradient. This value corresponds to the width of a vertical gradient or the height of a horizontal gradient.

Default value: 16.

gridAlign : LayoutAlign

The alignment to apply to symbol legends rows and columns. The supported string values are "all", "each" (the default), and none. For more information, see the grid layout documentation.

Default value: "each".

labelAlign : Align

The alignment of the legend label, can be left, center, or right.

labelBaseline : TextBaseline

The position of the baseline of legend label, can be "top", "middle", "bottom", or "alphabetic".

Default value: "middle".

labelColor : anyOf(None, Color)

The color of the legend label, can be in hex color code or regular color name.

labelExpr : string

Vega expression for customizing labels.

Note: The label text and value can be assessed via the label and value properties of the legend’s backing datum object.

labelFont : string

The font of the legend label.

labelFontSize : float

The font size of legend label.

Default value: 10.

labelFontStyle : FontStyle

The font style of legend label.

labelFontWeight : FontWeight

The font weight of legend label.

labelLimit : float

Maximum allowed pixel width of legend tick labels.

Default value: 160.

labelOffset : float

The offset of the legend label.

labelOpacity : float

Opacity of labels.

labelOverlap : LabelOverlap

The strategy to use for resolving overlap of labels in gradient legends. If false, no overlap reduction is attempted. If set to true (default) or "parity", a strategy of removing every other label is used. If set to "greedy", a linear scan of the labels is performed, removing any label that overlaps with the last visible label (this often works better for log-scaled axes).

Default value: true.

labelPadding : float

Padding in pixels between the legend and legend labels.

labelSeparation : float

The minimum separation that must be between label bounding boxes for them to be considered non-overlapping (default 0 ). This property is ignored if labelOverlap resolution is not enabled.

legendX : float

Custom x-position for legend with orient “none”.

legendY : float

Custom y-position for legend with orient “none”.

offset : float

The offset in pixels by which to displace the legend from the data rectangle and axes.

Default value: 18.

orient : LegendOrient

The orientation of the legend, which determines how the legend is positioned within the scene. One of "left", "right", "top", "bottom", "top-left", "top-right", "bottom-left", "bottom-right", "none".

Default value: "right"

padding : float

The padding between the border and content of the legend group.

Default value: 0.

rowPadding : float

The vertical padding in pixels between symbol legend entries.

Default value: 2.

strokeColor : anyOf(None, Color)

Border stroke color for the full legend.

symbolDash : List(float)

An array of alternating [stroke, space] lengths for dashed symbol strokes.

symbolDashOffset : float

The pixel offset at which to start drawing with the symbol stroke dash array.

symbolFillColor : anyOf(None, Color)

The color of the legend symbol,

symbolLimit : float

The maximum number of allowed entries for a symbol legend. Additional entries will be dropped.

symbolOffset : float

Horizontal pixel offset for legend symbols.

Default value: 0.

symbolOpacity : float

Opacity of the legend symbols.

symbolSize : float

The size of the legend symbol, in pixels.

Default value: 100.

symbolStrokeColor : anyOf(None, Color)

Stroke color for legend symbols.

symbolStrokeWidth : float

The width of the symbol’s stroke.

Default value: 1.5.

symbolType : SymbolShape

The symbol shape. One of the plotting shapes circle (default), square, cross, diamond, triangle-up, triangle-down, triangle-right, or triangle-left, the line symbol stroke, or one of the centered directional shapes arrow, wedge, or triangle. Alternatively, a custom SVG path string can be provided. 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".

tickCount : TickCount

The desired number of tick values for quantitative legends.

tickMinStep : float

The minimum desired step between legend ticks, in terms of scale domain values. For example, a value of 1 indicates that ticks should not be less than 1 unit apart. If tickMinStep is specified, the tickCount value will be adjusted, if necessary, to enforce the minimum step value.

Default value : undefined

title : anyOf(Text, None)

A title for the field. If null, the title will be removed.

Default value: derived from the field’s name and transformation function ( aggregate, bin and timeUnit ). If the field has an aggregate function, the function is displayed as part of the title (e.g., "Sum of Profit" ). If the field is binned or has a time unit applied, the applied function is shown in parentheses (e.g., "Profit (binned)", "Transaction Date (year-month)" ). Otherwise, the title is simply the field name.

Notes :

1) You can customize the default field title format by providing the fieldTitle property in the config or fieldTitle function via the compile function’s options.

2) If both field definition’s title and axis, header, or legend title are defined, axis/header/legend title will be used.

titleAlign : Align

Horizontal text alignment for legend titles.

Default value: "left".

titleAnchor : TitleAnchor

Text anchor position for placing legend titles.

titleBaseline : TextBaseline

Vertical text baseline for legend titles.

Default value: "top".

titleColor : anyOf(None, Color)

The color of the legend title, can be in hex color code or regular color name.

titleFont : string

The font of the legend title.

titleFontSize : float

The font size of the legend title.

titleFontStyle : FontStyle

The font style of the legend title.

titleFontWeight : FontWeight

The font weight of the legend title. This can be either a string (e.g "bold", "normal" ) or a number ( 100, 200, 300, …, 900 where "normal" = 400 and "bold" = 700 ).

titleLimit : float

Maximum allowed pixel width of legend titles.

Default value: 180.

titleLineHeight : float

Line height in pixels for multi-line title text.

titleOpacity : float

Opacity of the legend title.

titleOrient : Orient

Orientation of the legend title.

titlePadding : float

The padding, in pixels, between title and legend.

Default value: 5.

type : enum(‘symbol’, ‘gradient’)

The type of the legend. Use "symbol" to create a discrete legend and "gradient" for a continuous color gradient.

Default value: "gradient" for non-binned quantitative fields and temporal fields; "symbol" otherwise.

values : anyOf(List(float), List(string), List(boolean), List(DateTime))

Explicitly set the visible legend values.

zindex : float

A non-negative integer indicating the z-index of the legend. If zindex is 0, legend should be drawn behind all chart elements. To put them in front, use zindex = 1.

__init__(clipHeight=Undefined, columnPadding=Undefined, columns=Undefined, cornerRadius=Undefined, direction=Undefined, fillColor=Undefined, format=Undefined, formatType=Undefined, gradientLength=Undefined, gradientOpacity=Undefined, gradientStrokeColor=Undefined, gradientStrokeWidth=Undefined, gradientThickness=Undefined, gridAlign=Undefined, labelAlign=Undefined, labelBaseline=Undefined, labelColor=Undefined, labelExpr=Undefined, labelFont=Undefined, labelFontSize=Undefined, labelFontStyle=Undefined, labelFontWeight=Undefined, labelLimit=Undefined, labelOffset=Undefined, labelOpacity=Undefined, labelOverlap=Undefined, labelPadding=Undefined, labelSeparation=Undefined, legendX=Undefined, legendY=Undefined, offset=Undefined, orient=Undefined, padding=Undefined, rowPadding=Undefined, strokeColor=Undefined, symbolDash=Undefined, symbolDashOffset=Undefined, symbolFillColor=Undefined, symbolLimit=Undefined, symbolOffset=Undefined, symbolOpacity=Undefined, symbolSize=Undefined, symbolStrokeColor=Undefined, symbolStrokeWidth=Undefined, symbolType=Undefined, tickCount=Undefined, tickMinStep=Undefined, title=Undefined, titleAlign=Undefined, titleAnchor=Undefined, titleBaseline=Undefined, titleColor=Undefined, titleFont=Undefined, titleFontSize=Undefined, titleFontStyle=Undefined, titleFontWeight=Undefined, titleLimit=Undefined, titleLineHeight=Undefined, titleOpacity=Undefined, titleOrient=Undefined, titlePadding=Undefined, type=Undefined, values=Undefined, zindex=Undefined, **kwds)

Methods

__init__([clipHeight, columnPadding, …])
copy([deep, ignore]) Return a copy of the object
from_dict(dct[, validate, _wrapper_classes]) Construct class from a dictionary representation
from_json(json_string[, validate]) Instantiate the object from a valid JSON string
resolve_references([schema]) Resolve references in the context of this object’s schema or root schema.
to_dict([validate, ignore, context]) Return a dictionary representation of the object
to_json([validate, ignore, context, indent, …]) Emit the JSON representation for this object as a string.
validate(instance[, schema]) Validate the instance against the class schema in the context of the rootschema.
validate_property(name, value[, schema]) Validate a property against property schema in the context of the
copy(deep=True, ignore=())

Return a copy of the object

Parameters:
deep : boolean or list, optional

If True (default) then return a deep copy of all dict, list, and SchemaBase objects within the object structure. If False, then only copy the top object. If a list or iterable, then only copy the listed attributes.

ignore : list, optional

A list of keys for which the contents should not be copied, but only stored by reference.

from_dict(dct, validate=True, _wrapper_classes=None)

Construct class from a dictionary representation

Parameters:
dct : dictionary

The dict from which to construct the class

validate : boolean

If True (default), then validate the input against the schema.

_wrapper_classes : list (optional)

The set of SchemaBase classes to use when constructing wrappers of the dict inputs. If not specified, the result of cls._default_wrapper_classes will be used.

Returns:
obj : Schema object

The wrapped schema

Raises:
jsonschema.ValidationError :

if validate=True and dct does not conform to the schema

from_json(json_string, validate=True, **kwargs)

Instantiate the object from a valid JSON string

Parameters:
json_string : string

The string containing a valid JSON chart specification.

validate : boolean

If True (default), then validate the input against the schema.

**kwargs :

Additional keyword arguments are passed to json.loads

Returns:
chart : Chart object

The altair Chart object built from the specification.

resolve_references(schema=None)

Resolve references in the context of this object’s schema or root schema.

to_dict(validate=True, ignore=None, context=None)

Return a dictionary representation of the object

Parameters:
validate : boolean or string

If True (default), then validate the output dictionary against the schema. If “deep” then recursively validate all objects in the spec. This takes much more time, but it results in friendlier tracebacks for large objects.

ignore : list

A list of keys to ignore. This will not passed to child to_dict function calls.

context : dict (optional)

A context dictionary that will be passed to all child to_dict function calls

Returns:
dct : dictionary

The dictionary representation of this object

Raises:
jsonschema.ValidationError :

if validate=True and the dict does not conform to the schema

to_json(validate=True, ignore=[], context={}, indent=2, sort_keys=True, **kwargs)

Emit the JSON representation for this object as a string.

Parameters:
validate : boolean or string

If True (default), then validate the output dictionary against the schema. If “deep” then recursively validate all objects in the spec. This takes much more time, but it results in friendlier tracebacks for large objects.

ignore : list

A list of keys to ignore. This will not passed to child to_dict function calls.

context : dict (optional)

A context dictionary that will be passed to all child to_dict function calls

indent : integer, default 2

the number of spaces of indentation to use

sort_keys : boolean, default True

if True, sort keys in the output

**kwargs

Additional keyword arguments are passed to json.dumps()

Returns:
spec : string

The JSON specification of the chart object.

validate(instance, schema=None)

Validate the instance against the class schema in the context of the rootschema.

validate_property(name, value, schema=None)

Validate a property against property schema in the context of the rootschema