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.

Default Formatter

The default formatter identifies when the x-data being plotted is a small range on top of a large off set. To reduce the chances that the ticklabels overlap the ticks are labeled as deltas from a fixed offset. For example:

ax.plot(np.arange(2000, 2010), range(10))

will have tick of 0-9 with an offset of +2e3. If this is not desired turn off the use of the offset on the default formatter:

ax.get_xaxis().get_major_formatter().set_useOffset(False)

set the rcParam axes.formatter.useoffset=False to turn it off globally, or set a different formatter.

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, e.g., 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

SymmetricalLogLocator

locator for use with with the symlog norm, works like the LogLocator for the part outside of the threshold and add 0 if inside the limits

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.

LogitLocator

Locator for logit scaling.

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, e.g., 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

StrMethodFormatter

Use string format method

FormatStrFormatter

Use an old-style sprintf format string

ScalarFormatter

Default formatter for scalars: autopick the format string

LogFormatter

Formatter for log axes

LogFormatterExponent

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

LogFormatterMathtext

Format values for log axis using exponent = log_base(value) using Math text.

LogFormatterSciNotation

Format values for log axis using scientific notation.

LogitFormatter

Probability formatter.

EngFormatter

Format labels in engineering notation

PercentFormatter

Format labels as a percentage

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 and 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

Create a string based on a tick value and location.

fix_minus(s)

Some classes may want to replace a hyphen for minus with the proper unicode symbol (U+2212) for typographical correctness. The default is to not replace it.

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)

Returns the full string representation of the value with the position unspecified.

format_data_short(value)

Return a short string version of the tick value.

Defaults to the position-independent long value.

get_offset()

locs = []

set_locs(locs)

class matplotlib.ticker.FixedFormatter(seq)

Bases: matplotlib.ticker.Formatter

Return fixed strings for tick labels based only on position, not value.

Set the sequence of strings that will be used for labels.

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

Use a user-defined function for formatting.

The function should take in two inputs (a tick value x and a position pos), and return a string containing the corresponding tick label.

class matplotlib.ticker.FormatStrFormatter(fmt)

Bases: matplotlib.ticker.Formatter

Use an old-style (‘%’ operator) format string to format the tick.

The format string should have a single variable format (%) in it. It will be applied to the value (not the position) of the tick.

class matplotlib.ticker.StrMethodFormatter(fmt)

Bases: matplotlib.ticker.Formatter

Use a new-style format string (as used by str.format()) to format the tick.

The field used for the value must be labeled x and the field used for the position must be labeled pos.

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

Bases: matplotlib.ticker.Formatter

Format tick values as a number.

Tick value is interpreted as 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)

Replace hyphens with a unicode minus.

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_useMathText()

get_useOffset()

pprint_val(x)

set_locs(locs)

Set the locations of the ticks.

set_powerlimits(lims)

Sets size thresholds for scientific notation.

lims is a two-element sequence containing the powers of 10 that determine the switchover threshold. Numbers below 10**lims[0] and above 10**lims[1] will be displayed in scientific notation.

For example, 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

Method set_scientific()

set_scientific(b)

Turn scientific notation on or off.

See also

Method set_powerlimits()

set_useLocale(val)

set_useMathText(val)

set_useOffset(val)

useLocale

useMathText

useOffset

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 True.

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 minor tick labeling on or off.

labelOnlyBase=True to turn off minor ticks.

pprint_val(x, d)

set_locs(locs)

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 True.

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 True.

class matplotlib.ticker.IndexFormatter(labels)

Bases: matplotlib.ticker.Formatter

Format the position x to the nearest i-th label where i=int(x+0.5)

class matplotlib.ticker.LogFormatterSciNotation(base=10.0, labelOnlyBase=False)

Bases: matplotlib.ticker.LogFormatterMathtext

Format values following scientific notation in a logarithmic axis

class matplotlib.ticker.LogitFormatter

Bases: matplotlib.ticker.Formatter

Probability formatter (using Math text).

format_data_short(value)

return a short formatted string representation of a number

class matplotlib.ticker.EngFormatter(unit='', places=None)

Bases: matplotlib.ticker.Formatter

Formats axis values using engineering prefixes to represent powers of 1000, plus a specified unit, e.g., 10 MHz instead of 1e7.

unit is a string containing the abbreviated name of the unit, suitable for use with single-letter representations of powers of 1000. For example, ‘Hz’ or ‘m’.

places is the precision with which to display the number, specified in digits after the decimal point (there will be between one and three digits before the decimal point).

ENG_PREFIXES = {0: '', 3: 'k', 6: 'M', -24: 'y', 9: 'G', -21: 'z', 12: 'T', -18: 'a', 15: 'P', -15: 'f', 18: 'E', -12: 'p', 21: 'Z', -9: 'n', 24: 'Y', -6: 'μ', -3: 'm'}

format_eng(num)

Formats a number in engineering notation, appending a letter representing the power of 1000 of the original number. Some examples:

>>> format_eng(0)       # for self.places = 0
'0'

>>> format_eng(1000000) # for self.places = 1
'1.0 M'

>>> format_eng("-1e-6") # for self.places = 2
u'-1.00 μ'

num may be a numeric value or a string that can be converted to a numeric value with the decimal.Decimal constructor.

class matplotlib.ticker.PercentFormatter(xmax=100, decimals=None, symbol='%')

Bases: matplotlib.ticker.Formatter

Format numbers as a percentage.

How the number is converted into a percentage is determined by the xmax parameter. xmax is the data value that corresponds to 100%. Percentages are computed as x / xmax * 100. So if the data is already scaled to be percentages, xmax will be 100. Another common situation is where xmax is 1.0.

symbol is a string which will be appended to the label. It may be None or empty to indicate that no symbol should be used.

decimals is the number of decimal places to place after the point. If it is set to None (the default), the number will be computed automatically.

convert_to_pct(x)

format_pct(x, display_range)

Formats the number as a percentage number with the correct number of decimals and adds the percent symbol, if any.

If self.decimals is None, the number of digits after the decimal point is set based on the display_range of the axis as follows:

display_range	decimals	sample
>50	0	x = 34.5 => 35%
>5	1	x = 34.5 => 34.5%
>0.5	2	x = 34.5 => 34.50%
...	...	...

This method will not be very good for tiny axis ranges or extremely large ones. It assumes that the values on the chart are percentages displayed on a reasonable scale.

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

set_params(**kwargs)

Do nothing, and rase a warning. Any locator class not supporting the set_params() function will call this.

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, e.g., on every 5th point. It is assumed that you are doing index plotting; i.e., 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

set_params(base=None, offset=None)

Set parameters within this locator

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.

set_params(nbins=None)

Set parameters within this locator.

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

set_params(numticks=None, presets=None)

Set parameters within this locator.

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=None)

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)

set_params(base=None, subs=None, numdecs=None, numticks=None)

Set parameters within this locator.

subs(subs)

set the minor ticks for 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

set_params(base)

Set parameters within this locator.

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. If the string 'auto', the number of bins will be automatically determined based on the length of the axis.

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, provided at least min_n_ticks integers are found within the view limits.

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, primarily when rcParams['axes.autolimit_mode'] is 'round_numbers'. 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.

min_n_ticks

Relax nbins and integer constraints if necessary to obtain this minimum number of ticks.

bin_boundaries(vmin, vmax)

Deprecated since version 2.0: The bin_boundaries function was deprecated in version 2.0.

default_params = {'symmetric': False, 'steps': None, 'min_n_ticks': 2, 'prune': None, 'integer': False, 'nbins': 10}

set_params(**kwargs)

Set parameters within this locator.

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. The scale must be linear with major ticks 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)

class matplotlib.ticker.SymmetricalLogLocator(transform, subs=None)

Bases: matplotlib.ticker.Locator

Determine the tick locations for log axes

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

set_params(subs=None, numticks=None)

Set parameters within this locator.

tick_values(vmin, vmax)

view_limits(vmin, vmax)

Try to choose the view limits intelligently

class matplotlib.ticker.LogitLocator(minor=False)

Bases: matplotlib.ticker.Locator

Determine the tick locations for logit axes

place ticks on the logit locations

set_params(minor=None)

Set parameters within this locator.

tick_values(vmin, vmax)