Axis and Grid

PlotAxis

class chaco.api.PlotAxis(component=None, **kwargs)

Bases: chaco.abstract_overlay.AbstractOverlay

The PlotAxis is a visual component that can be rendered on its own as a standalone component or attached as an overlay to another component. (To attach it as an overlay, set its component attribute.)

When it is attached as an overlay, it draws into the padding around the component.

axis_line_color = ColorTrait("black")

The color of the axis line.

axis_line_style = LineStyle('solid')

The dash style of the axis line.

axis_line_visible = Bool(True)

Is the axis line visible?

axis_line_weight = Float(1.0)

The line thickness (in pixels) of the axis line.

bgcolor = ColorTrait("transparent")

Background color (overrides AbstractOverlay). Axes usually let the color of the container show through.

ensure_labels_bounded = Bool(False)

Does the axis ensure that its end labels fall within its bounding area?

ensure_ticks_bounded = Bool(False)

Does the axis prevent the ticks from being rendered outside its bounds? This flag is off by default because the standard axis does render ticks that encroach on the plot area.

invalidate()

Invalidates the pre-computed layout and scaling data.

mapper = Instance(AbstractMapper)

The mapper that drives this axis.

mapper_updated()

Event handler that is bound to this axis’s mapper’s updated event

orientation = Enum("top", "bottom", "left", "right")

The location of the axis relative to the plot. This determines where the axis title is located relative to the axis line.

origin = Enum("bottom left", "top left", "bottom right", "top right")

Keep an origin for plots that aren’t attached to a component

overlay(component, gc, view_bounds=None, mode='normal')

Draws this component overlaid on another component.

Overrides AbstractOverlay.

resizable = "hv"

Dimensions that the axis is resizable in (overrides PlotComponent). Typically, axes are resizable in both dimensions.

small_haxis_style = Bool(False)

A special version of the axis line that is more useful for geophysical plots.

tick_color = ColorTrait("black")

The color of the ticks.

tick_generator = Instance(AbstractTickGenerator)

A callable that implements the AbstractTickGenerator interface.

tick_in = Int(5)

The number of pixels by which the ticks extend into the plot area.

tick_interval = Trait('auto', 'auto', Float)

The dataspace interval between ticks.

tick_label_alignment = Enum('edge', 'corner')

Whether to align to corners or edges (corner is better for 45 degree rotation)

tick_label_color = ColorTrait("black")

The color of the tick labels.

tick_label_font = KivaFont('modern 10')

The font of the tick labels.

tick_label_formatter = Callable(DEFAULT_TICK_FORMATTER)

A callable that is passed the numerical value of each tick label and that returns a string.

tick_label_margin = Int(2)

The margin around the tick labels.

tick_label_offset = Float(8.)

The distance of the tick label from the axis.

tick_label_position = Enum("outside", "inside")

Whether the tick labels appear to the inside or the outside of the plot area

tick_label_rotate_angle = Float(0)

The rotation of the tick labels.

tick_out = Int(5)

The number of pixels by which the ticks extend into the label area.

tick_visible = Bool(True)

Are ticks visible at all?

tick_weight = Float(1.0)

The thickness (in pixels) of each tick.

title = Trait('', Str, Unicode) #May want to add PlotLabel option

The text of the axis title.

title_angle = Float(0.)

The angle of the title, in degrees, from horizontal line

title_color = ColorTrait("black")

The color of the title.

title_font = KivaFont('modern 12')

The font of the title.

title_spacing = Trait('auto', 'auto', Float)

The spacing between the axis line and the title

traits_view()

Returns a View instance for use with Traits UI. This method is called automatically be the Traits framework when .edit_traits() is invoked.

updated = Event

Fired when the axis’s range bounds change.

LabelAxis

class chaco.api.LabelAxis(component=None, **kwargs)

Bases: chaco.axis.PlotAxis

An axis whose ticks are labeled with text instead of numbers.

label_rotation = Float(0)

The angle of rotation of the label.

labels = List(Str)

List of labels to use on tick marks.

positions = ArrayOrNone()

List of indices of ticks

PlotGrid

class chaco.api.PlotGrid(**traits)

Bases: chaco.abstract_overlay.AbstractOverlay

An overlay that represents a grid.

A grid is a set of parallel lines, horizontal or vertical. You can use multiple grids with different settings for the horizontal and vertical lines in a plot.

data_max = Trait(None, None, Float)

The dataspace value at which to end this grid. If None, then uses the mapper.range.high.

data_min = Trait(None, None, Float)

The dataspace value at which to start this grid. If None, then uses the mapper.range.low.

do_layout(*args, **kw)

Tells this component to do layout at a given size.

Overrides PlotComponent.

flip_axis = Bool(False)

Draw the ticks starting at the end of the mapper range? If False, the ticks are drawn starting at 0. This setting can be useful to keep the grid from from “flashing” as the user resizes the plot area.

grid_interval = Trait('auto', 'auto', Float)

The dataspace interval between grid lines.

invalidate()

Invalidate cached information about the grid.

line_color = black_color_trait

The color of the grid lines.

line_style = LineStyle('solid')

The style (i.e., dash pattern) of the grid lines.

line_width = CInt(1)

The thickness, in pixels, of the grid lines.

mapper = Instance(AbstractMapper)

The mapper (and associated range) that drive this PlotGrid.

mapper_updated()

Event handler that is bound to this mapper’s updated event.

orientation = Enum('horizontal', 'vertical')

The orientation of the grid lines. “horizontal” means that the grid lines are parallel to the X axis and the ticker and grid interval refer to the Y axis.

overlay(other_component, gc, view_bounds=None, mode='normal')

Draws this component overlaid on another component.

Overrides AbstractOverlay.

resizable = "hv"

Dimensions that the grid is resizable in (overrides PlotComponent).

tick_generator = Instance(AbstractTickGenerator)

A callable that implements the AbstractTickGenerator Interface.

traits_view

Default Traits UI View for modifying grid attributes.

transverse_bounds = Trait(None, Tuple, Callable)

Optional specification of the grid bounds in the dimension transverse to the ticking/gridding dimension, i.e. along the direction specified by self.orientation. If this is specified but transverse_mapper is not specified, then there is no effect.

None : use self.bounds or self.component.bounds (if overlay) Tuple : (low, high) extents, used for every grid line Callable : Function that takes an array of dataspace grid ticks

and returns either an array of shape (N,2) of (starts,ends) for each grid point or a single tuple (low, high)

transverse_mapper = Instance(AbstractMapper)

Mapper in the direction corresponding to self.orientation, i.e. transverse to the direction of self.mapper. This is used to compute the screen position of transverse_bounds. If this is not specified, then transverse_bounds has no effect, and vice versa.

visual_attr_changed()

Called when an attribute that affects the appearance of the grid is changed.

AbstractTickGenerator

class chaco.api.AbstractTickGenerator

Bases: traits.has_traits.HasTraits

Abstract class for tick generators.

get_ticks(data_low, data_high, bounds_low, bounds_high, interval, use_endpoints=False, scale='linear')

Returns a list of ticks points in data space.

Parameters
  • data_low (float) – The actual minimum and maximum of index values of the entire dataset.

  • data_high (float) – The actual minimum and maximum of index values of the entire dataset.

  • bounds_low ("auto", "fit", float) – The range for which ticks should be generated.

  • bounds_high ("auto", "fit", float) – The range for which ticks should be generated.

  • interval ("auto", float) – If the value is a positive number, it specifies the length of the tick interval; a negative integer specifies the number of tick intervals; ‘auto’ specifies that the number and length of the tick intervals are automatically calculated, based on the range of the axis.

  • use_endpoints (Boolean) – If True, the lower and upper bounds of the data are used as the lower and upper end points of the axis. If False, the end points might not fall exactly on the bounds.

  • scale ('linear' or 'log') – The type of scale the ticks are for.

Returns

tick_list – Where ticks are to be placed.

Return type

array of floats

Example

If the range of x-values in a line plot span from -15.0 to +15.0, but the plot is currently displaying only the region from 3.1 to 6.83, and the user wants the interval to be automatically computed to be some nice value, then call get_ticks() thusly:

get_ticks(-15.0, 15.0, 3.1, 6.83, "auto")

A reasonable return value in this case would be:

[3.5, 4.0, 4.5, 5.0, 5.5, 6.0, 6.5]

DefaultTickGenerator

class chaco.api.DefaultTickGenerator

Bases: chaco.ticks.AbstractTickGenerator

An implementation of AbstractTickGenerator that simply uses the auto_ticks() and log_auto_ticks() functions.

get_ticks(data_low, data_high, bounds_low, bounds_high, interval, use_endpoints=False, scale='linear')

Returns a list of ticks points in data space.

Parameters
  • data_low (float) – The actual minimum and maximum of index values of the entire dataset.

  • data_high (float) – The actual minimum and maximum of index values of the entire dataset.

  • bounds_low ("auto", "fit", float) – The range for which ticks should be generated.

  • bounds_high ("auto", "fit", float) – The range for which ticks should be generated.

  • interval ("auto", float) – If the value is a positive number, it specifies the length of the tick interval; a negative integer specifies the number of tick intervals; ‘auto’ specifies that the number and length of the tick intervals are automatically calculated, based on the range of the axis.

  • use_endpoints (Boolean) – If True, the lower and upper bounds of the data are used as the lower and upper end points of the axis. If False, the end points might not fall exactly on the bounds.

  • scale ('linear' or 'log') – The type of scale the ticks are for.

Returns

tick_list – Where ticks are to be placed.

Return type

array of floats

Example

If the range of x-values in a line plot span from -15.0 to +15.0, but the plot is currently displaying only the region from 3.1 to 6.83, and the user wants the interval to be automatically computed to be some nice value, then call get_ticks() thusly:

get_ticks(-15.0, 15.0, 3.1, 6.83, "auto")

A reasonable return value in this case would be:

[3.5, 4.0, 4.5, 5.0, 5.5, 6.0, 6.5]

auto_ticks

chaco.api.auto_ticks(data_low, data_high, bound_low, bound_high, tick_interval, use_endpoints=True)

Finds locations for axis tick marks.

Calculates the locations for tick marks on an axis. The bound_low, bound_high, and tick_interval parameters specify how the axis end points and tick interval are calculated.

Parameters
  • data_low (number) – The minimum and maximum values of the data along this axis. If any of the bound settings are ‘auto’ or ‘fit’, the axis traits are calculated automatically from these values.

  • data_high (number) – The minimum and maximum values of the data along this axis. If any of the bound settings are ‘auto’ or ‘fit’, the axis traits are calculated automatically from these values.

  • bound_low ('auto', 'fit', or a number.) – The lower and upper bounds of the axis. If the value is a number, that value is used for the corresponding end point. If the value is ‘auto’, then the end point is calculated automatically. If the value is ‘fit’, then the axis bound is set to the corresponding data_low or data_high value.

  • bound_high ('auto', 'fit', or a number.) – The lower and upper bounds of the axis. If the value is a number, that value is used for the corresponding end point. If the value is ‘auto’, then the end point is calculated automatically. If the value is ‘fit’, then the axis bound is set to the corresponding data_low or data_high value.

  • tick_interval (can be 'auto' or a number) – If the value is a positive number, it specifies the length of the tick interval; a negative integer specifies the number of tick intervals; ‘auto’ specifies that the number and length of the tick intervals are automatically calculated, based on the range of the axis.

  • use_endpoints (Boolean) – If True, the lower and upper bounds of the data are used as the lower and upper end points of the axis. If False, the end points might not fall exactly on the bounds.

Returns

  • An array of tick mark locations. The first and last tick entries are the

  • axis end points.

auto_interval

chaco.api.auto_interval(data_low, data_high, max_ticks=9)

Calculates the tick interval for a range.

The boundaries for the data to be plotted on the axis are:

data_bounds = (data_low,data_high)

The function chooses the number of tick marks, which can be between 3 and max_ticks marks (including end points), and chooses tick intervals at 1, 2, 2.5, 5, 10, 20, …

Returns

interval – tick mark interval for axis

Return type

float

tick_intervals

chaco.api.tick_intervals(data_low, data_high, intervals)

Computes the best tick interval length to achieve a specified number of tick intervals.

Parameters
  • data_low (number) – The minimum and maximum values of the data along this axis. If any of the bound settings are ‘auto’ or ‘fit’, the axis traits are calculated automatically from these values.

  • data_high (number) – The minimum and maximum values of the data along this axis. If any of the bound settings are ‘auto’ or ‘fit’, the axis traits are calculated automatically from these values.

  • intervals (number) – The desired number of intervals

Returns

Return type

Returns a float indicating the tick interval length.

log_auto_ticks

chaco.api.log_auto_ticks(data_low, data_high, bound_low, bound_high, tick_interval, use_endpoints=True)

Like auto_ticks(), but for log scales.

auto_bounds

chaco.api.auto_bounds(data_low, data_high, tick_interval)

Calculates appropriate upper and lower bounds for the axis from the data bounds and the given axis interval.

The boundaries hit either exactly on the lower and upper values or on the tick mark just beyond the lower and upper values.

calc_bound

chaco.api.calc_bound(end_point, tick_interval, is_upper)

Finds an axis end point that includes the value end_point.

If the tick mark interval results in a tick mark hitting directly on the end point, end_point is returned. Otherwise, the location of the tick mark just past end_point is returned. The is_upper parameter specifies whether end_point is at the upper (True) or lower (False) end of the axis.