Adding new scales and projections to matplotlib

Matplotlib supports the addition of new transformations that transform

the data before it is displayed. Separable transformations, that work

on a single dimension are called "scales", and non-separable

transformations, that take data in two or more dimensions as input are

called "projections".

This document is intended for developers and advanced users who need

to add more scales and projections to matplotlib.

From the user's perspective, the scale of a plot can be set with

``set_xscale`` and ``set_yscale``. Choosing the projection

currently has no *standardized* method. [MGDTODO]

Creating a new scale

Adding a new scale consists of defining a subclass of ``ScaleBase``,

that brings together the following elements:

- A transformation from data space into plot space.

- An inverse of that transformation. For example, this is used to

convert mouse positions back into data space.

- A function to limit the range of the axis to acceptable values. A

log scale, for instance, would prevent the range from including

values less than or equal to zero.

- Locators (major and minor) that determine where to place ticks in

the plot, and optionally, how to adjust the limits of the plot to

some "good" values.

- Formatters (major and minor) that specify how the tick labels

should be drawn.

There are a number of ``Scale`` classes in ``scale.py`` that may be

used as starting points for new scales. As an example, this document

presents adding a new scale ``MercatorLatitudeScale`` which can be

used to plot latitudes in a Mercator_ projection. For simplicity,

this scale assumes that it has a fixed center at the equator. The

code presented here is a simplification of actual code in

``matplotlib``, with complications added only for the sake of

optimization removed.

First define a new subclass of ``ScaleBase``::

This class must have a member ``name`` that defines the string used to

select the scale. For example,

``gca().set_yscale("mercator_latitude")`` would be used to select the

Mercator latitude scale.

Next define two nested classes: one for the data transformation and

one for its inverse. Both of these classes must be subclasses of

``Transform`` (defined in ``transforms.py``).::

There are two class-members that must be defined. ``input_dims`` and

``output_dims`` specify number of input dimensions and output

dimensions to the transformation. These are used by the

transformation framework to do some error checking and prevent

incompatible transformations from being connected together. When

defining transforms for a scale, which are by definition separable and

only have one dimension, these members should always be 1.

``MercatorLatitudeTransform`` has a simple constructor that takes and

stores the *threshold* for the Mercator projection (to limit its range

to prevent plotting to infinity).::

The ``transform`` method is where the real work happens: It takes an N

x 1 ``numpy`` array and returns a transformed copy. Since the range

of the Mercator scale is limited by the user-specified threshold, the

input array must be masked to contain only valid values.

``matplotlib`` will handle masked arrays and remove the out-of-range

data from the plot. Importantly, the transformation should return an

array that is the same shape as the input array, since these values

need to remain synchronized with values in the other dimension.::

Lastly for the transformation class, define a method to get the

inverse transformation::

The inverse transformation class follows the same pattern, but

obviously the mathematical operation performed is different::

Now we're back to methods for the ``MercatorLatitudeScale`` class.

Any keyword arguments passed to ``set_xscale`` and ``set_yscale`` will

be passed along to the scale's constructor. In the case of

``MercatorLatitudeScale``, the ``thresh`` keyword argument specifies

the degree at which to crop the plot data. The constructor also

creates a local instance of the ``Transform`` class defined above,

which is made available through its ``get_transform`` method::

The ``limit_range_for_scale`` method must be provided to limit the

bounds of the axis to the domain of the function. In the case of

Mercator, the bounds should be limited to the threshold that was

passed in. Unlike the autoscaling provided by the tick locators, this

range limiting will always be adhered to, whether the axis range is set

manually, determined automatically or changed through panning and

zooming::

Lastly, the ``set_default_locators_and_formatters`` method sets up the

locators and formatters to use with the scale. It may be that the new

scale requires new locators and formatters. Doing so is outside the

scope of this document, but there are many examples in ``ticker.py``.

The Mercator example uses a fixed locator from -90 to 90 degrees and a

custom formatter class to put convert the radians to degrees and put a

degree symbol after the value::

Now that the Scale class has been defined, it must be registered so

that ``matplotlib`` can find it::

.. _Mercator: http://en.wikipedia.org/wiki/Mercator_projection