You are reading an old version of the documentation (v1.4.3). For the latest version see https://matplotlib.org/stable/api/axis_api.html

We're updating the default styles for Matplotlib 2.0

Learn what to expect in the new updates

matplotlib

Table Of Contents

Previous topic

axes

Next topic

backends

This Page

axis

matplotlib.axis

Classes for the ticks and x and y axis

class matplotlib.axis.Axis(axes, pickradius=15)

Bases: matplotlib.artist.Artist

Public attributes

  • axes.transData - transform data coords to display coords
  • axes.transAxes - transform axis coords to display coords
  • labelpad - number of points between the axis and its label

Init the axis with the parent Axes instance

OFFSETTEXTPAD = 3
axis_date(tz=None)

Sets up x-axis ticks and labels that treat the x data as dates. tz is a tzinfo instance or a timezone string. This timezone is used to create date labels.

cla()

clear the current axis

convert_units(x)
draw(artist, renderer, *args, **kwargs)

Draw the axis lines, grid lines, tick lines and labels

get_children()
get_data_interval()

return the Interval instance for this axis data limits

get_gridlines()

Return the grid lines as a list of Line2D instance

get_label()

Return the axis label as a Text instance

get_label_text()

Get the text of the label

get_major_formatter()

Get the formatter of the major ticker

get_major_locator()

Get the locator of the major ticker

get_major_ticks(numticks=None)

get the tick instances; grow as necessary

get_majorticklabels()

Return a list of Text instances for the major ticklabels

get_majorticklines()

Return the major tick lines as a list of Line2D instances

get_majorticklocs()

Get the major tick locations in data coordinates as a numpy array

get_minor_formatter()

Get the formatter of the minor ticker

get_minor_locator()

Get the locator of the minor ticker

get_minor_ticks(numticks=None)

get the minor tick instances; grow as necessary

get_minorticklabels()

Return a list of Text instances for the minor ticklabels

get_minorticklines()

Return the minor tick lines as a list of Line2D instances

get_minorticklocs()

Get the minor tick locations in data coordinates as a numpy array

get_offset_text()

Return the axis offsetText as a Text instance

get_pickradius()

Return the depth of the axis used by the picker

get_scale()
get_smart_bounds()

get whether the axis has smart bounds

get_ticklabel_extents(renderer)

Get the extents of the tick labels on either side of the axes.

get_ticklabels(minor=False, which=None)

Get the x tick labels as a list of Text instances.

Parameters:

minor : bool

If True return the minor ticklabels, else return the major ticklabels

which : None, (‘minor’, ‘major’, ‘both’)

Overrides minor.

Selects which ticklabels to return

Returns:

ret : list

List of Text instances.

get_ticklines(minor=False)

Return the tick lines as a list of Line2D instances

get_ticklocs(minor=False)

Get the tick locations in data coordinates as a numpy array

get_tightbbox(renderer)

Return a bounding box that encloses the axis. It only accounts tick labels, axis label, and offsetText.

get_transform()
get_units()

return the units for axis

get_view_interval()

return the Interval instance for this axis view limits

grid(b=None, which=u'major', **kwargs)

Set the axis grid on or off; b is a boolean. Use which = ‘major’ | ‘minor’ | ‘both’ to set the grid for major or minor ticks.

If b is None and len(kwargs)==0, toggle the grid state. If kwargs are supplied, it is assumed you want the grid on and b will be set to True.

kwargs are used to set the line properties of the grids, e.g.,

xax.grid(color=’r’, linestyle=’-‘, linewidth=2)
have_units()
iter_ticks()

Iterate through all of the major and minor ticks.

limit_range_for_scale(vmin, vmax)
pan(numsteps)

Pan numsteps (can be positive or negative)

reset_ticks()
set_clip_path(clippath, transform=None)
set_data_interval()

set the axis data limits

set_default_intervals()

set the default limits for the axis data and view interval if they are not mutated

set_label_coords(x, y, transform=None)

Set the coordinates of the label. By default, the x coordinate of the y label is determined by the tick label bounding boxes, but this can lead to poor alignment of multiple ylabels if there are multiple axes. Ditto for the y coodinate of the x label.

You can also specify the coordinate system of the label with the transform. If None, the default coordinate system will be the axes coordinate system (0,0) is (left,bottom), (0.5, 0.5) is middle, etc

set_label_text(label, fontdict=None, **kwargs)

Sets the text value of the axis label

ACCEPTS: A string value for the label

set_major_formatter(formatter)

Set the formatter of the major ticker

ACCEPTS: A Formatter instance

set_major_locator(locator)

Set the locator of the major ticker

ACCEPTS: a Locator instance

set_minor_formatter(formatter)

Set the formatter of the minor ticker

ACCEPTS: A Formatter instance

set_minor_locator(locator)

Set the locator of the minor ticker

ACCEPTS: a Locator instance

set_pickradius(pickradius)

Set the depth of the axis used by the picker

ACCEPTS: a distance in points

set_scale(*args, **kwargs)

Deprecated since version 1.3: The set_scale function was deprecated in version 1.3.

This should be a private function (moved to _set_scale)

set_smart_bounds(value)

set the axis to have smart bounds

set_tick_params(which=u'major', reset=False, **kw)

Set appearance parameters for ticks and ticklabels.

For documentation of keyword arguments, see matplotlib.axes.Axes.tick_params().

set_ticklabels(ticklabels, *args, **kwargs)

Set the text values of the tick labels. Return a list of Text instances. Use kwarg minor=True to select minor ticks. All other kwargs are used to update the text object properties. As for get_ticklabels, label1 (left or bottom) is affected for a given tick only if its label1On attribute is True, and similarly for label2. The list of returned label text objects consists of all such label1 objects followed by all such label2 objects.

The input ticklabels is assumed to match the set of tick locations, regardless of the state of label1On and label2On.

ACCEPTS: sequence of strings

set_ticks(ticks, minor=False)

Set the locations of the tick marks from sequence ticks

ACCEPTS: sequence of floats

set_units(u)

set the units for axis

ACCEPTS: a units tag

set_view_interval(vmin, vmax, ignore=False)
update_units(data)

introspect data for units converter and update the axis.converter instance if necessary. Return True if data is registered for unit conversion.

zoom(direction)

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

class matplotlib.axis.Tick(axes, loc, label, size=None, width=None, color=None, tickdir=None, pad=None, labelsize=None, labelcolor=None, zorder=None, gridOn=None, tick1On=True, tick2On=True, label1On=True, label2On=False, major=True)

Bases: matplotlib.artist.Artist

Abstract base class for the axis ticks, grid lines and labels

1 refers to the bottom of the plot for xticks and the left for yticks 2 refers to the top of the plot for xticks and the right for yticks

Publicly accessible attributes:

tick1line
a Line2D instance
tick2line
a Line2D instance
gridline
a Line2D instance
label1
a Text instance
label2
a Text instance
gridOn
a boolean which determines whether to draw the tickline
tick1On
a boolean which determines whether to draw the 1st tickline
tick2On
a boolean which determines whether to draw the 2nd tickline
label1On
a boolean which determines whether to draw tick label
label2On
a boolean which determines whether to draw tick label

bbox is the Bound2D bounding box in display coords of the Axes loc is the tick location in data coords size is the tick size in points

apply_tickdir(tickdir)

Calculate self._pad and self._tickmarkers

contains(mouseevent)

Test whether the mouse event occurred in the Tick marks.

This function always returns false. It is more useful to test if the axis as a whole contains the mouse rather than the set of tick marks.

draw(artist, renderer, *args, **kwargs)
get_children()
get_loc()

Return the tick location (data coords) as a scalar

get_pad()

Get the value of the tick label pad in points

get_pad_pixels()
get_view_interval()

return the view Interval instance for the axis this tick is ticking

set_clip_path(clippath, transform=None)

Set the artist’s clip path, which may be:

  • a Patch (or subclass) instance

  • a Path instance, in which case

    an optional Transform instance may be provided, which will be applied to the path before using it for clipping.

  • None, to remove the clipping path

For efficiency, if the path happens to be an axis-aligned rectangle, this method will set the clipping box to the corresponding rectangle and set the clipping path to None.

ACCEPTS: [ (Path, Transform) | Patch | None ]

set_label(s)

Set the text of ticklabel

ACCEPTS: str

set_label1(s)

Set the text of ticklabel

ACCEPTS: str

set_label2(s)

Set the text of ticklabel2

ACCEPTS: str

set_pad(val)

Set the tick label pad in points

ACCEPTS: float

class matplotlib.axis.Ticker
formatter = None
locator = None
class matplotlib.axis.XAxis(axes, pickradius=15)

Bases: matplotlib.axis.Axis

Init the axis with the parent Axes instance

axis_name = u'x'
contains(mouseevent)

Test whether the mouse event occured in the x axis.

get_data_interval()

return the Interval instance for this axis data limits

get_label_position()

Return the label position (top or bottom)

get_minpos()
get_text_heights(renderer)

Returns the amount of space one should reserve for text above and below the axes. Returns a tuple (above, below)

get_ticks_position()

Return the ticks position (top, bottom, default or unknown)

get_view_interval()

return the Interval instance for this axis view limits

set_data_interval(vmin, vmax, ignore=False)

set the axis data limits

set_default_intervals()

set the default limits for the axis interval if they are not mutated

set_label_position(position)

Set the label position (top or bottom)

ACCEPTS: [ ‘top’ | ‘bottom’ ]

set_ticks_position(position)

Set the ticks position (top, bottom, both, default or none) both sets the ticks to appear on both positions, but does not change the tick labels. ‘default’ resets the tick positions to the default: ticks on both positions, labels at bottom. ‘none’ can be used if you don’t want any ticks. ‘none’ and ‘both’ affect only the ticks, not the labels.

ACCEPTS: [ ‘top’ | ‘bottom’ | ‘both’ | ‘default’ | ‘none’ ]

set_view_interval(vmin, vmax, ignore=False)

If ignore is False, the order of vmin, vmax does not matter; the original axis orientation will be preserved. In addition, the view limits can be expanded, but will not be reduced. This method is for mpl internal use; for normal use, see set_xlim().

tick_bottom()

use ticks only on bottom

tick_top()

use ticks only on top

class matplotlib.axis.XTick(axes, loc, label, size=None, width=None, color=None, tickdir=None, pad=None, labelsize=None, labelcolor=None, zorder=None, gridOn=None, tick1On=True, tick2On=True, label1On=True, label2On=False, major=True)

Bases: matplotlib.axis.Tick

Contains all the Artists needed to make an x tick - the tick line, the label text and the grid line

bbox is the Bound2D bounding box in display coords of the Axes loc is the tick location in data coords size is the tick size in points

apply_tickdir(tickdir)
get_view_interval()

return the Interval instance for this axis view limits

update_position(loc)

Set the location of tick in data coords with scalar loc

class matplotlib.axis.YAxis(axes, pickradius=15)

Bases: matplotlib.axis.Axis

Init the axis with the parent Axes instance

axis_name = u'y'
contains(mouseevent)

Test whether the mouse event occurred in the y axis.

Returns True | False

get_data_interval()

return the Interval instance for this axis data limits

get_label_position()

Return the label position (left or right)

get_minpos()
get_text_widths(renderer)
get_ticks_position()

Return the ticks position (left, right, both or unknown)

get_view_interval()

return the Interval instance for this axis view limits

set_data_interval(vmin, vmax, ignore=False)

set the axis data limits

set_default_intervals()

set the default limits for the axis interval if they are not mutated

set_label_position(position)

Set the label position (left or right)

ACCEPTS: [ ‘left’ | ‘right’ ]

set_offset_position(position)
set_ticks_position(position)

Set the ticks position (left, right, both, default or none) ‘both’ sets the ticks to appear on both positions, but does not change the tick labels. ‘default’ resets the tick positions to the default: ticks on both positions, labels at left. ‘none’ can be used if you don’t want any ticks. ‘none’ and ‘both’ affect only the ticks, not the labels.

ACCEPTS: [ ‘left’ | ‘right’ | ‘both’ | ‘default’ | ‘none’ ]

set_view_interval(vmin, vmax, ignore=False)

If ignore is False, the order of vmin, vmax does not matter; the original axis orientation will be preserved. In addition, the view limits can be expanded, but will not be reduced. This method is for mpl internal use; for normal use, see set_ylim().

tick_left()

use ticks only on left

tick_right()

use ticks only on right

class matplotlib.axis.YTick(axes, loc, label, size=None, width=None, color=None, tickdir=None, pad=None, labelsize=None, labelcolor=None, zorder=None, gridOn=None, tick1On=True, tick2On=True, label1On=True, label2On=False, major=True)

Bases: matplotlib.axis.Tick

Contains all the Artists needed to make a Y tick - the tick line, the label text and the grid line

bbox is the Bound2D bounding box in display coords of the Axes loc is the tick location in data coords size is the tick size in points

apply_tickdir(tickdir)
get_view_interval()

return the Interval instance for this axis view limits

update_position(loc)

Set the location of tick in data coords with scalar loc