Mappers

Mappers perform the job of mapping a data space region to screen space, and vice versa. They are used by plots to transform their data sources to pixel coordinates on the screen. While most of the time this is a relatively simple rescaling operation, mapper can also be used for non-linear transformations, most notably to map a data source to logarithmic coordinates on screen.

Interface

The general interface for mappers is defined in AbstractMapper and defines only a few methods:

map_screen(data_value), map_data(screen_value)

Maps a vector of data coordinates to screen coordinates, and vice versa.

map_data_array(screen_value_array)

Maps an array of points in data coordinates to screen coordinates. By default, this method just loops over the points, calling map_data() on each one. For vectorizable mapping functions, this implementation is overridden with a faster one.

Mappers for 1D data have a slightly larger interface, defined in Base1DMapper. These mappers rely on a DataRange1D object to find the bounds on the data domain.

range

A DataRange1D instance to define the data-space bounds of the mapper. The mapper listens to the updated event of the range and re-fires it as its own updated event (see below).

low_pos, high_pos, screen_bounds

The screen space position of the lower/upper bound of the data space. screen_bounds is a convenience property to set/get the screen bounds with a single attribute.

stretch_data

When the screen bounds change (in response, for instance, to the window resizing) one could either fit more data space on the screen, or stretch the data space to the new bounds. If stretch_data is True (default), the data is stretched; if it is False, the mapper preserves the screen-to-data ratio.

Events

The AbstractMapper interface defines a single generic event, updated, which is fired when the bound values change.

For subclasses of Base1DMapper, the updated event is also fired in response to an updated event fired by the underlying data range. The value of the new event is the tuple (low_bound, high_bound) contained in the triggering event.

List of Chaco data mappers

LinearMapper (subclass of Base1DMapper)

This mapper transforms a 1D data space range linearly to a fixed 1D range in screen space.

LogMapper (subclass of Base1DMapper)

Maps a 1D data space range to a 1D range in screen space through a logarithmic transform. Data values smaller than or equal to 0.0 are substituted by fill_value (default is 1.0) before the logarithmic transformation.

GridMapper

Same as LinearMapper for 2D ranges. This class replaces the Base1DMapper attributes with analogous ones:

range

A DataRange2D instance to define the data-space bounds of the mapper.

x_low_pos, y_low_pos, x_high_pos, y_high_pos

Screen space positions for the lower and upper bounds of the x and y axes.

screen_bounds

Convenience property to set/get the screen bounds with a single attribute. The value of this attribute is a 4-element tuple (x_low_pos, x_high_pos, y_low_pos, y_high_pos).

GridMapper uses two Base1DMapper instances to define mappers for the two axes (accessible from the two private attributes _xmapper and _ymapper). It thus possible to set them to be linear or logarithmic mappers. This is best made using the class constructor, which has this signature:

GridMapper(x_type="linear", y_type="linear", range=None, **kwargs)

x_type and y_type can be either ‘linear’ or ‘log’, which will create a corresponding LinearMapper or LogMapper classes.