matplotlib

Table Of Contents

Previous topic

spines

Next topic

tight_layout

This Page

ticker

matplotlib.ticker

Tick locating and formatting

This module contains classes to support completely configurable tick locating and formatting. Although the locators know nothing about major or minor ticks, they are used by the Axis class to support major and minor tick locating and formatting. Generic tick locators and formatters are provided, as well as domain specific custom ones..

Tick locating

The Locator class is the base class for all tick locators. The locators handle autoscaling of the view limits based on the data limits, and the choosing of tick locations. A useful semi-automatic tick locator is MultipleLocator. You initialize this with a base, eg 10, and it picks axis limits and ticks that are multiples of your base.

The Locator subclasses defined here are

NullLocator
No ticks
FixedLocator
Tick locations are fixed
IndexLocator
locator for index plots (e.g., where x = range(len(y)))
LinearLocator
evenly spaced ticks from min to max
LogLocator
logarithmically ticks from min to max
MultipleLocator
ticks and range are a multiple of base;
either integer or float
OldAutoLocator
choose a MultipleLocator and dyamically reassign it for intelligent ticking during navigation
MaxNLocator
finds up to a max number of ticks at nice locations
AutoLocator
MaxNLocator with simple defaults. This is the default tick locator for most plotting.
AutoMinorLocator
locator for minor ticks when the axis is linear and the major ticks are uniformly spaced. It subdivides the major tick interval into a specified number of minor intervals, defaulting to 4 or 5 depending on the major interval.

There are a number of locators specialized for date locations - see the dates module

You can define your own locator by deriving from Locator. You must override the __call__ method, which returns a sequence of locations, and you will probably want to override the autoscale method to set the view limits from the data limits.

If you want to override the default locator, use one of the above or a custom locator and pass it to the x or y axis instance. The relevant methods are:

ax.xaxis.set_major_locator( xmajorLocator )
ax.xaxis.set_minor_locator( xminorLocator )
ax.yaxis.set_major_locator( ymajorLocator )
ax.yaxis.set_minor_locator( yminorLocator )

The default minor locator is the NullLocator, eg no minor ticks on by default.

Tick formatting

Tick formatting is controlled by classes derived from Formatter. The formatter operates on a single tick value and returns a string to the axis.

NullFormatter
no labels on the ticks
IndexFormatter
set the strings from a list of labels
FixedFormatter
set the strings manually for the labels
FuncFormatter
user defined function sets the labels
FormatStrFormatter
use a sprintf format string
ScalarFormatter
default formatter for scalars; autopick the fmt string
LogFormatter
formatter for log axes

You can derive your own formatter from the Formatter base class by simply overriding the __call__ method. The formatter class has access to the axis view and data limits.

To control the major and minor tick label formats, use one of the following methods:

ax.xaxis.set_major_formatter( xmajorFormatter )
ax.xaxis.set_minor_formatter( xminorFormatter )
ax.yaxis.set_major_formatter( ymajorFormatter )
ax.yaxis.set_minor_formatter( yminorFormatter )

See pylab_examples example code: major_minor_demo1.py for an example of setting major an minor ticks. See the matplotlib.dates module for more information and examples of using date locators and formatters.

class matplotlib.ticker.TickHelper

Bases: object

axis = None
create_dummy_axis(**kwargs)
set_axis(axis)
set_bounds(vmin, vmax)
set_data_interval(vmin, vmax)
set_view_interval(vmin, vmax)
class matplotlib.ticker.Formatter

Bases: matplotlib.ticker.TickHelper

Convert the tick location to a string

fix_minus(s)
some classes may want to replace a hyphen for minus with the proper unicode symbol as described `here <http://sourceforge.net/tracker/index.php?func=detail&aid=1962574&
group_id=80706&atid=560720>`_.

The default is to do nothing

Note, if you use this method, e.g., in format_data() or call, you probably don’t want to use it for format_data_short() since the toolbar uses this for interactive coord reporting and I doubt we can expect GUIs across platforms will handle the unicode correctly. So for now the classes that override fix_minus() should have an explicit format_data_short() method

format_data(value)
format_data_short(value)

return a short string version

get_offset()
locs = []
set_locs(locs)
class matplotlib.ticker.FixedFormatter(seq)

Bases: matplotlib.ticker.Formatter

Return fixed strings for tick labels

seq is a sequence of strings. For positions i < len(seq) return seq[i] regardless of x. Otherwise return ‘’

get_offset()
set_offset_string(ofs)
class matplotlib.ticker.NullFormatter

Bases: matplotlib.ticker.Formatter

Always return the empty string

class matplotlib.ticker.FuncFormatter(func)

Bases: matplotlib.ticker.Formatter

User defined function for formatting

class matplotlib.ticker.FormatStrFormatter(fmt)

Bases: matplotlib.ticker.Formatter

Use a format string to format the tick

class matplotlib.ticker.ScalarFormatter(useOffset=True, useMathText=None, useLocale=None)

Bases: matplotlib.ticker.Formatter

Tick location is a plain old number. If useOffset==True and the data range is much smaller than the data average, then an offset will be determined such that the tick labels are meaningful. Scientific notation is used for data < 10^-n or data >= 10^m, where n and m are the power limits set using set_powerlimits((n,m)). The defaults for these are controlled by the axes.formatter.limits rc parameter.

fix_minus(s)

use a unicode minus rather than hyphen

format_data(value)

return a formatted string representation of a number

format_data_short(value)

return a short formatted string representation of a number

get_offset()

Return scientific notation, plus offset

get_useLocale()
get_useOffset()
pprint_val(x)
set_locs(locs)

set the locations of the ticks

set_powerlimits(lims)

Sets size thresholds for scientific notation.

e.g., formatter.set_powerlimits((-3, 4)) sets the pre-2007 default in which scientific notation is used for numbers less than 1e-3 or greater than 1e4. See also set_scientific().

set_scientific(b)

True or False to turn scientific notation on or off see also set_powerlimits()

set_useLocale(val)
set_useOffset(val)
useLocale None
useOffset None
class matplotlib.ticker.LogFormatter(base=10.0, labelOnlyBase=True)

Bases: matplotlib.ticker.Formatter

Format values for log axis;

base is used to locate the decade tick, which will be the only one to be labeled if labelOnlyBase is False

base(base)

change the base for labeling - warning: should always match the base used for LogLocator

format_data(value)
format_data_short(value)

return a short formatted string representation of a number

label_minor(labelOnlyBase)

switch on/off minor ticks labeling

pprint_val(x, d)
class matplotlib.ticker.LogFormatterExponent(base=10.0, labelOnlyBase=True)

Bases: matplotlib.ticker.LogFormatter

Format values for log axis; using exponent = log_base(value)

base is used to locate the decade tick, which will be the only one to be labeled if labelOnlyBase is False

class matplotlib.ticker.LogFormatterMathtext(base=10.0, labelOnlyBase=True)

Bases: matplotlib.ticker.LogFormatter

Format values for log axis; using exponent = log_base(value)

base is used to locate the decade tick, which will be the only one to be labeled if labelOnlyBase is False

class matplotlib.ticker.Locator

Bases: matplotlib.ticker.TickHelper

Determine the tick locations;

Note, you should not use the same locator between different Axis because the locator stores references to the Axis data and view limits

MAXTICKS = 1000
autoscale()

autoscale the view limits

pan(numsteps)

Pan numticks (can be positive or negative)

raise_if_exceeds(locs)

raise a RuntimeError if Locator attempts to create more than MAXTICKS locs

refresh()

refresh internal information based on current lim

tick_values(vmin, vmax)

Return the values of the located ticks given vmin and vmax.

Note

To get tick locations with the vmin and vmax values defined automatically for the associated axis simply call the Locator instance:

>>> print(type(loc))
<type 'Locator'>
>>> print(loc())
[1, 2, 3, 4]
view_limits(vmin, vmax)

select a scale for the range from vmin to vmax

Normally this method is overridden by subclasses to change locator behaviour.

zoom(direction)

Zoom in/out on axis; if direction is >0 zoom in, else zoom out

class matplotlib.ticker.IndexLocator(base, offset)

Bases: matplotlib.ticker.Locator

Place a tick on every multiple of some base number of points plotted, eg on every 5th point. It is assumed that you are doing index plotting; ie the axis is 0, len(data). This is mainly useful for x ticks.

place ticks on the i-th data points where (i-offset)%base==0

tick_values(vmin, vmax)
class matplotlib.ticker.FixedLocator(locs, nbins=None)

Bases: matplotlib.ticker.Locator

Tick locations are fixed. If nbins is not None, the array of possible positions will be subsampled to keep the number of ticks <= nbins +1. The subsampling will be done so as to include the smallest absolute value; for example, if zero is included in the array of possibilities, then it is guaranteed to be one of the chosen ticks.

tick_values(vmin, vmax)

” Return the locations of the ticks.

Note

Because the values are fixed, vmin and vmax are not used in this method.

class matplotlib.ticker.NullLocator

Bases: matplotlib.ticker.Locator

No ticks

tick_values(vmin, vmax)

” Return the locations of the ticks.

Note

Because the values are Null, vmin and vmax are not used in this method.

class matplotlib.ticker.LinearLocator(numticks=None, presets=None)

Bases: matplotlib.ticker.Locator

Determine the tick locations

The first time this function is called it will try to set the number of ticks to make a nice tick partitioning. Thereafter the number of ticks will be fixed so that interactive navigation will be nice

Use presets to set locs based on lom. A dict mapping vmin, vmax->locs

tick_values(vmin, vmax)
view_limits(vmin, vmax)

Try to choose the view limits intelligently

class matplotlib.ticker.LogLocator(base=10.0, subs=[1.0], numdecs=4, numticks=15)

Bases: matplotlib.ticker.Locator

Determine the tick locations for log axes

place ticks on the location= base**i*subs[j]

base(base)

set the base of the log scaling (major tick every base**i, i integer)

subs(subs)

set the minor ticks the log scaling every base**i*subs[j]

tick_values(vmin, vmax)
view_limits(vmin, vmax)

Try to choose the view limits intelligently

class matplotlib.ticker.AutoLocator

Bases: matplotlib.ticker.MaxNLocator

class matplotlib.ticker.MultipleLocator(base=1.0)

Bases: matplotlib.ticker.Locator

Set a tick on every integer that is multiple of base in the view interval

tick_values(vmin, vmax)
view_limits(dmin, dmax)

Set the view limits to the nearest multiples of base that contain the data

class matplotlib.ticker.MaxNLocator(*args, **kwargs)

Bases: matplotlib.ticker.Locator

Select no more than N intervals at nice locations.

Keyword args:

nbins
Maximum number of intervals; one less than max number of ticks.
steps
Sequence of nice numbers starting with 1 and ending with 10; e.g., [1, 2, 4, 5, 10]
integer
If True, ticks will take only integer values.
symmetric
If True, autoscaling will result in a range symmetric about zero.
prune
[‘lower’ | ‘upper’ | ‘both’ | None] Remove edge ticks – useful for stacked or ganged plots where the upper tick of one axes overlaps with the lower tick of the axes above it. If prune==’lower’, the smallest tick will be removed. If prune==’upper’, the largest tick will be removed. If prune==’both’, the largest and smallest ticks will be removed. If prune==None, no ticks will be removed.
bin_boundaries(vmin, vmax)
default_params = {'trim': True, 'nbins': 10, 'steps': None, 'prune': None, 'integer': False, 'symmetric': False}
set_params(**kwargs)
tick_values(vmin, vmax)
view_limits(dmin, dmax)
class matplotlib.ticker.AutoMinorLocator(n=None)

Bases: matplotlib.ticker.Locator

Dynamically find minor tick positions based on the positions of major ticks. Assumes the scale is linear and major ticks are evenly spaced.

n is the number of subdivisions of the interval between major ticks; e.g., n=2 will place a single minor tick midway between major ticks.

If n is omitted or None, it will be set to 5 or 4.

tick_values(vmin, vmax)