matplotlib.ticker
¶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.
The default formatter identifies when the xdata 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 09 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.
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 semiautomatic tick locator is
MultipleLocator
. It is initialized with a base, e.g., 10, and it picks
axis limits and ticks that are multiples of that base.
The Locator subclasses defined here are
AutoLocator
MaxNLocator
with simple defaults. This is the default tick locator for
most plotting.MaxNLocator
LinearLocator
LogLocator
MultipleLocator
FixedLocator
IndexLocator
x = range(len(y))
).NullLocator
SymmetricalLogLocator
LogLocator
for the
part outside of the threshold and adds 0 if inside the limits.LogitLocator
OldAutoLocator
MultipleLocator
and dynamically reassign it for intelligent
ticking during navigation.AutoMinorLocator
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(xmajor_locator)
ax.xaxis.set_minor_locator(xminor_locator)
ax.yaxis.set_major_locator(ymajor_locator)
ax.yaxis.set_minor_locator(yminor_locator)
The default minor locator is NullLocator
, i.e., no minor ticks on by default.
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
IndexFormatter
FixedFormatter
FuncFormatter
StrMethodFormatter
format
method.FormatStrFormatter
ScalarFormatter
LogFormatter
LogFormatterExponent
exponent = log_base(value)
.LogFormatterMathtext
exponent = log_base(value)
using Math text.LogFormatterSciNotation
LogitFormatter
EngFormatter
PercentFormatter
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(xmajor_formatter)
ax.xaxis.set_minor_formatter(xminor_formatter)
ax.yaxis.set_major_formatter(ymajor_formatter)
ax.yaxis.set_minor_formatter(yminor_formatter)
See Major Minor Demo 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.
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)¶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 positionindependent long value.
get_offset
()¶locs
= []¶set_locs
(locs)¶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)¶matplotlib.ticker.
NullFormatter
¶Bases: matplotlib.ticker.Formatter
Always return the empty string.
matplotlib.ticker.
FuncFormatter
(func)¶Bases: matplotlib.ticker.Formatter
Use a userdefined 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.
matplotlib.ticker.
FormatStrFormatter
(fmt)¶Bases: matplotlib.ticker.Formatter
Use an oldstyle (‘%’ 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.
matplotlib.ticker.
StrMethodFormatter
(fmt)¶Bases: matplotlib.ticker.Formatter
Use a newstyle 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
.
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 twoelement 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
pre2007 default in which scientific notation is used for
numbers less than 1e3 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
¶matplotlib.ticker.
LogFormatter
(base=10.0, labelOnlyBase=False, minor_thresholds=None, linthresh=None)¶Bases: matplotlib.ticker.Formatter
Base class for formatting ticks on a log or symlog scale.
It may be instantiated directly, or subclassed.
Parameters:  base : float, optional, default: 10.
labelOnlyBase : bool, optional, default: False
minor_thresholds : (subset, all), optional, default: (1, 0.4)
linthresh : None or float, optional, default: None


Notes
The set_locs
method must be called to enable the subsetting
logic controlled by the minor_thresholds
parameter.
In some cases such as the colorbar, there is no distinction between
major and minor ticks; the tick locations might be set manually,
or by a locator that puts ticks at integer powers of base and
at intermediate locations. For this situation, disable the
minor_thresholds logic by using minor_thresholds=(np.inf, np.inf)
,
so that all ticks will be labeled.
To disable labeling of minor ticks when ‘labelOnlyBase’ is False,
use minor_thresholds=(0, 0)
. This is the default for the
“classic” style.
Examples
To label a subset of minor ticks when the view limits span up
to 2 decades, and all of the ticks when zoomed in to 0.5 decades
or less, use minor_thresholds=(2, 0.5)
.
To label all minor ticks when the view limits span up to 1.5
decades, use minor_thresholds=(1.5, 1.5)
.
base
(base)¶change the base
for labeling.
Warning
Should always match the base used for LogLocator
format_data
(value)¶Returns the full string representation of the value with the position unspecified.
format_data_short
(value)¶Return a short formatted string representation of a number.
label_minor
(labelOnlyBase)¶Switch minor tick labeling on or off.
Parameters:  labelOnlyBase : bool


pprint_val
(x, d)¶set_locs
(locs=None)¶Use axis view limits to control which ticks are labeled.
The locs
parameter is ignored in the present algorithm.
matplotlib.ticker.
LogFormatterExponent
(base=10.0, labelOnlyBase=False, minor_thresholds=None, linthresh=None)¶Bases: matplotlib.ticker.LogFormatter
Format values for log axis using exponent = log_base(value)
.
matplotlib.ticker.
LogFormatterMathtext
(base=10.0, labelOnlyBase=False, minor_thresholds=None, linthresh=None)¶Bases: matplotlib.ticker.LogFormatter
Format values for log axis using exponent = log_base(value)
.
matplotlib.ticker.
IndexFormatter
(labels)¶Bases: matplotlib.ticker.Formatter
Format the position x to the nearest ith label where i=int(x+0.5)
matplotlib.ticker.
LogFormatterSciNotation
(base=10.0, labelOnlyBase=False, minor_thresholds=None, linthresh=None)¶Bases: matplotlib.ticker.LogFormatterMathtext
Format values following scientific notation in a logarithmic axis
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
matplotlib.ticker.
EngFormatter
(unit='', places=None, sep=' ')¶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.
Parameters:  unit : str (default: “”)
places : int (default: None)
sep : str (default: ” “)


ENG_PREFIXES
= {24: 'y', 21: 'z', 18: 'a', 15: 'f', 12: 'p', 9: 'n', 6: 'μ', 3: 'm', 0: '', 3: 'k', 6: 'M', 9: 'G', 12: 'T', 15: 'P', 18: 'E', 21: 'Z', 24: 'Y'}¶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("1e6") # 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 float(num)
.
matplotlib.ticker.
PercentFormatter
(xmax=100, decimals=None, symbol='%', is_latex=False)¶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. LaTeX
special characters are escaped in symbol
whenever latex mode is
enabled, unless is_latex
is True
.
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.
symbol
¶The configured percent symbol as a string.
If LaTeX is enabled via rcParams["text.usetex"]
, the special characters
{'#', '$', '%', '&', '~', '_', '^', '\', '{', '}'}
are
automatically escaped in the string.
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
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 ith data points where (ioffset)%base==0
set_params
(base=None, offset=None)¶Set parameters within this locator
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]
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.
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.
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)¶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)¶Try to choose the view limits intelligently
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 locations : subs[j] * base**i
Parameters:  subs : None, string, or sequence of float, optional, default (1.0,)


base
(base)¶set the base of the log scaling (major tick every base**i, i integer)
nonsingular
(vmin, vmax)¶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)¶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)¶Try to choose the view limits intelligently
matplotlib.ticker.
AutoLocator
¶Bases: matplotlib.ticker.MaxNLocator
Dynamically find major tick positions. This is actually a subclass
of MaxNLocator
, with parameters nbins = ‘auto’
and steps = [1, 2, 2.5, 5, 10].
To know the values of the nonpublic parameters, please have a
look to the defaults of MaxNLocator
.
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)¶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
(dmin, dmax)¶Set the view limits to the nearest multiples of base that contain the data
matplotlib.ticker.
MaxNLocator
(*args, **kwargs)¶Bases: matplotlib.ticker.Locator
Select no more than N intervals at nice locations.
Keyword args:
'auto'
, the number of bins will be
automatically determined based on the length of the axis.min_n_ticks
integers are found within the
view limits.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.nbins
and integer
constraints if necessary to
obtain this minimum number of ticks.default_params
= {'integer': False, 'min_n_ticks': 2, 'nbins': 10, 'prune': None, 'steps': None, 'symmetric': False}¶set_params
(**kwargs)¶Set parameters within this locator.
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
(dmin, dmax)¶select a scale for the range from vmin to vmax
Normally this method is overridden by subclasses to change locator behaviour.
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)¶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]
matplotlib.ticker.
SymmetricalLogLocator
(transform=None, subs=None, linthresh=None, base=None)¶Bases: matplotlib.ticker.Locator
Determine the tick locations for symmetric 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)¶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)¶Try to choose the view limits intelligently
matplotlib.ticker.
LogitLocator
(minor=False)¶Bases: matplotlib.ticker.Locator
Determine the tick locations for logit axes
place ticks on the logit locations
nonsingular
(vmin, vmax)¶set_params
(minor=None)¶Set parameters within this locator.
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]