Creating a new scale¶

Adding a new scale consists of defining a subclass ofmatplotlib.scale.ScaleBase, that includes the followingelements:

• A transformation from data coordinates into display coordinates.
• An inverse of that transformation. This is used, for example, toconvert mouse positions from screen space back into data space.
• A function to limit the range of the axis to acceptable values(limit_range_for_scale()). A log scale, for instance, wouldprevent the range from including values less than or equal tozero.
• Locators (major and minor) that determine where to place ticks inthe plot, and optionally, how to adjust the limits of the plot tosome “good” values. Unlikelimit_range_for_scale(), which isalways enforced, the range setting here is only used whenautomatically setting the range of the plot.
• Formatters (major and minor) that specify how the tick labelsshould be drawn.

Once the class is defined, it must be registered with matplotlib sothat the user can select it.

A full-fledged and heavily annotated example is inexamples/api/custom_scale_example.py. There are also some classesinmatplotlib.scale that may be used as starting points.

Creating a new projection¶

Adding a new projection consists of defining a projection axes whichsubclassesmatplotlib.axes.Axes and includes the followingelements:

• A transformation from data coordinates into display coordinates.
• An inverse of that transformation. This is used, for example, toconvert mouse positions from screen space back into data space.
• Transformations for the gridlines, ticks and ticklabels. Customprojections will often need to place these elements in speciallocations, and matplotlib has a facility to help with doing so.
• Setting up default values (overridingcla()), since the defaults for arectilinear axes may not be appropriate.
• Defining the shape of the axes, for example, an elliptical axes,that will be used to draw the background of the plot and forclipping any data elements.
• Defining custom locators and formatters for the projection. Forexample, in a geographic projection, it may be more convenient todisplay the grid in degrees, even if the data is in radians.
• Set up interactive panning and zooming. This is left as an“advanced” feature left to the reader, but there is an example ofthis for polar plots inmatplotlib.projections.polar.
• Any additional methods for additional convenience or features.

Once the projection axes is defined, it can be used in one of two ways:

• By defining the class attributename, the projection axes can beregistered withmatplotlib.projections.register_projection()and subsequently simply invoked by name:

  plt.axes(projection='my_proj_name')

• For more complex, parameterisable projections, a generic “projection”object may be defined which includes the method_as_mpl_axes._as_mpl_axes should take no arguments and return the projection’saxes subclass and a dictionary of additional arguments to pass to thesubclass’__init__ method. Subsequently a parameterised projectioncan be initialised with:

  plt.axes(projection=MyProjection(param1=param1_value))

  where MyProjection is an object which implements a_as_mpl_axes method.

A full-fledged and heavily annotated example is inexamples/api/custom_projection_example.py. The polar plotfunctionality inmatplotlib.projections.polar may also be ofinterest.

API documentation¶

• matplotlib.scale
• matplotlib.projections
• matplotlib.projections.polar