Overlays: axis, legend, grid, etc.¶
Overlays are elements that decorate plots, like for example axes, legends, grids, etc.
Overlays are very similar to regular plot elements, and share most
of their interface with plot renderers
(both are subclasses of chaco.plot_component.PlotComponent
).
In addition, they have a lightweight interface defined in
chaco.abstract_overlay.AbstractOverlay
: the additional
features are that 1) they keep a reference to the plot they are decorating in
component
;
2) the background color
bgcolor
is ‘transparent’ by default;
3) they plot on the ‘overlay’ layer by default.
TODO: explain how to attach an overlay to an existing plot renderer
There are three important classes of overlays defined in Chaco: axes, legends, and grids.
Axes¶
The Chaco overlay representing a plot axis is defined in the class
PlotAxis
.
A new axis is created by passing a
mapper, usually the mapper defined for the corresponding plot data coordinate.
PlotAxis
also defines a range of attributes to customize
the appearance of labels, ticks, and other axis elements. For example,
given an X-Y plot renderer, plot
, we can define a new x-axis as:
AXIS_DEFAULTS = {
'axis_line_weight': 2,
'tick_weight': 2,
'tick_label_font': 'modern 16',
'title_font': 'modern 20',
}
x_axis = PlotAxis(orientation='bottom',
title='My x axis',
mapper=plot.x_mapper,
component=plot,
**AXIS_DEFAULTS)
The newly created axis can then be attached to the plot renderer by appending it to its underlays layer:
plot.underlays.append(x_axis)
Minor Axes Ticks¶
The Chaco overlay representing a minor plot axis is defined in the class
MinorPlotAxis
(a subclass of
PlotAxis
). This overlay adds minor tick marks to an axis.
A MinorPlotAxis
should be added along with a
PlotAxis
. For example, minor axis tick marks can be
added with:
x_major_axis = PlotAxis(orientation='bottom',
title='My x axis',
mapper=plot.x_mapper,
component=plot)
plot.underlays.append(x_major_axis)
x_minor_axis = MinorPlotAxis(orientation='bottom',
mapper=plot.x_mapper,
component=plot)
plot.underlays.append(x_minor_axis)
Attributes¶
These attributes control the appearance of the axis:
title
,
title_font
,
title_color
,
title_spacing
title_angle
Define the axis label.
title
is a string or unicode object that is rendered using the given font and color.title_font
is a string describing a font (e.g. ‘12 pt bold italic’, ‘swiss family Arial’ or ‘default 12’; seeTraitKivaFont
for details). Finally,title_spacing
is the space between the axis line and the title (either the number of pixels or ‘auto’, default) andtitle_angle
can be overridden to change the rotation angle (in deg, wrt horizontal).
tick_weight
,
tick_color
,
tick_in
,
tick_out
,
tick_visible
,
These attributes control the aspect of the ticks on the axis. If
tick_visible
is True, ticks are represented as lines of colortick_color
(default is black) and thicknesstick_weight
(in pixels, default is 1). Each line extends into the plot area bytick_in
pixels and into the label area bytick_out
pixels (default is 5).
tick_label_font
,
tick_label_color
,
tick_label_rotate_angle
,
tick_label_alignment
,
tick_label_margin
,
tick_label_offset
,
tick_label_position
,
These attributes allow to fine-tune the aspect of the tick labels: first of all, the font (e.g. ‘12 pt bold italic’) and color of the labels. The position and orientation of the label can be also be closely controlled:
tick_label_rotate_angle
give the rotation angle (only multiples of 90 degrees are supported);tick_label_alignment
selects whether the corner (‘corner’) or center (‘edge’, default) of the label are aligned to the corresponding tick (‘corner’ is better for 45 degrees rotation);tick_label_margin
andtick_label_offset
control the margin around the tick labels, and their distance from the axis; finally,tick_label_position
can be set to either ‘outside’ (default) or ‘inside’ depending on whether the labels should be displayed inside or outside the plot area.
tick_label_formatter
By default, tick labels are assumed to be floating point numbers, and are displayed as such after removing trailing zeros and the decimal dot if necessary (e.g., ‘10.000’ will be displayed as ‘10’, and ‘21.10’ as ‘21.1’). The default behavior can be changed by setting
tick_label_formatter
to a callable that takes the value of the tick label and returns a formatted string.
tick_interval
,
tick_generator
,
Locations and distances of ticks are controlled by the attribute
tick_generator
Default is chaco.ticks.auto_ticks or chaco.ticks.log_auto_ticks
Events¶
updated
Fired when the axis’s range bounds change.