Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Improve docstrings of pyplot axis-related functions #10296

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Mar 16, 2018
Merged

Improve docstrings of pyplot axis-related functions #10296

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
e9163a8
improve docstrings of pyplot.xticks and pyplot.yticks
timhoffm Jan 21, 2018
fd33d87
improve docstrings of pyplot.xlim and pyplot.ylim
timhoffm Jan 21, 2018
7ad7c62
improve docstrings of pyplot.xlabel and pyplot.ylabel
timhoffm Jan 23, 2018
6f28a57
improve docstrings of pyplot.xscale and pyplot.yscale
timhoffm Jan 23, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 12 additions & 10 deletions lib/matplotlib/axes/_axes.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -211,19 +211,20 @@ def get_xlabel(self):

def set_xlabel(self, xlabel, fontdict=None, labelpad=None, **kwargs):
"""
Set the label for the xaxis.
Set the label for the x-axis.

Parameters
----------
xlabel : string
x label
xlabel : str
The label text.

labelpad : scalar, optional, default: None
spacing in points between the label and the x-axis
Spacing in points between the label and the x-axis.

Other Parameters
----------------
**kwargs : `~matplotlib.text.Text` properties
**kwargs : `.Text` properties
`.Text` properties control the appearance of the label.

See also
--------
Expand All @@ -242,19 +243,20 @@ def get_ylabel(self):

def set_ylabel(self, ylabel, fontdict=None, labelpad=None, **kwargs):
"""
Set the label for the yaxis
Set the label for the y-axis.

Parameters
----------
ylabel : string
y label
ylabel : str
The label text.

labelpad : scalar, optional, default: None
spacing in points between the label and the y-axis
Spacing in points between the label and the y-axis.

Other Parameters
----------------
**kwargs : `~matplotlib.text.Text` properties
**kwargs : `.Text` properties
`.Text` properties control the appearance of the label.

See also
--------
Expand Down
253 changes: 178 additions & 75 deletions lib/matplotlib/pyplot.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1505,65 +1505,60 @@ def axis(*v, **kwargs):

def xlabel(s, *args, **kwargs):
"""
Set the *x* axis label of the current axis.
Set the x-axis label of the current axes.

Default override is::

override = {
'fontsize' : 'small',
'verticalalignment' : 'top',
'horizontalalignment' : 'center'
}
Call signature::

.. seealso::
xlabel(label, fontdict=None, labelpad=None, **kwargs)

:func:`~matplotlib.pyplot.text`
For information on how override and the optional args work
This is the pyplot equivalent of calling `.set_xlabel` on the current axes.
See there for a full parameter description.
"""
return gca().set_xlabel(s, *args, **kwargs)


def ylabel(s, *args, **kwargs):
"""
Set the *y* axis label of the current axis.
Set the y-axis label of the current axes.

Defaults override is::

override = {
'fontsize' : 'small',
'verticalalignment' : 'center',
'horizontalalignment' : 'right',
'rotation'='vertical' : }
Call signature::

.. seealso::
ylabel(label, fontdict=None, labelpad=None, **kwargs)

:func:`~matplotlib.pyplot.text`
For information on how override and the optional args
work.
This is the pyplot equivalent of calling `.set_ylabel` on the current axes.
See there for a full parameter description.
"""
return gca().set_ylabel(s, *args, **kwargs)


def xlim(*args, **kwargs):
"""
Get or set the *x* limits of the current axes.
Get or set the x limits of the current axes.

::
Call signatures::

xmin, xmax = xlim() # return the current xlim
xlim( (xmin, xmax) ) # set the xlim to xmin, xmax
xlim( xmin, xmax ) # set the xlim to xmin, xmax
xmin, xmax = xlim() # return the current xlim
xlim((xmin, xmax)) # set the xlim to xmin, xmax
xlim(xmin, xmax) # set the xlim to xmin, xmax

If you do not specify args, you can pass the xmin and xmax as
kwargs, e.g.::
If you do not specify args, you can pass *xmin* or *xmax* as kwargs, i.e.::

xlim(xmax=3) # adjust the max leaving min unchanged
xlim(xmin=1) # adjust the min leaving max unchanged
xlim(xmax=3) # adjust the max leaving min unchanged
xlim(xmin=1) # adjust the min leaving max unchanged

Setting limits turns autoscaling off for the x-axis.

The new axis limits are returned as a length 2 tuple.
Returns
-------
xmin, xmax
A tuple of the new x-axis limits.

Notes
-----
Calling this function with no arguments (e.g. ``xlim()``) is the pyplot
equivalent of calling `~.Axes.get_xlim` on the current axes.
Calling this function with arguments is the pyplot equivalent of calling
`~.Axes.set_xlim` on the current axes. All arguments are passed though.
"""
ax = gca()
if not args and not kwargs:
Expand All @@ -1574,23 +1569,33 @@ def xlim(*args, **kwargs):

def ylim(*args, **kwargs):
"""
Get or set the *y*-limits of the current axes.
Get or set the y-limits of the current axes.

::
Call signatures::

ymin, ymax = ylim() # return the current ylim
ylim( (ymin, ymax) ) # set the ylim to ymin, ymax
ylim( ymin, ymax ) # set the ylim to ymin, ymax
ymin, ymax = ylim() # return the current ylim
ylim((ymin, ymax)) # set the ylim to ymin, ymax
ylim(ymin, ymax) # set the ylim to ymin, ymax

If you do not specify args, you can pass the *ymin* and *ymax* as
kwargs, e.g.::
If you do not specify args, you can alternatively pass *ymin* or *ymax* as
kwargs, i.e.::

ylim(ymax=3) # adjust the max leaving min unchanged
ylim(ymin=1) # adjust the min leaving max unchanged
ylim(ymax=3) # adjust the max leaving min unchanged
ylim(ymin=1) # adjust the min leaving max unchanged

Setting limits turns autoscaling off for the y-axis.

The new axis limits are returned as a length 2 tuple.
Returns
-------
ymin, ymax
A tuple of the new y-axis limits.

Notes
-----
Calling this function with no arguments (e.g. ``ylim()``) is the pyplot
equivalent of calling `~.Axes.get_ylim` on the current axes.
Calling this function with arguments is the pyplot equivalent of calling
`~.Axes.set_ylim` on the current axes. All arguments are passed though.
"""
ax = gca()
if not args and not kwargs:
Expand All @@ -1602,13 +1607,23 @@ def ylim(*args, **kwargs):
@docstring.dedent_interpd
def xscale(*args, **kwargs):
"""
Set the scaling of the *x*-axis.
Set the scaling of the x-axis.

call signature::
Call signature::

xscale(scale, **kwargs)
xscale(scale, **kwargs)

The available scales are: %(scale)s
Parameters
----------
scale : [%(scale)s]
The scaling type.
**kwargs
Additional parameters depend on *scale*. See Notes.

Notes
-----
This is the pyplot equivalent of calling `~.Axes.set_xscale` on the
current axes.

Different keywords may be accepted, depending on the scale:

Expand All @@ -1620,13 +1635,23 @@ def xscale(*args, **kwargs):
@docstring.dedent_interpd
def yscale(*args, **kwargs):
"""
Set the scaling of the *y*-axis.
Set the scaling of the y-axis.

call signature::
Call signature::

yscale(scale, **kwargs)

yscale(scale, **kwargs)
Parameters
----------
scale : [%(scale)s]
The scaling type.
**kwargs
Additional parameters depend on *scale*. See Notes.

The available scales are: %(scale)s
Notes
-----
This is the pyplot equivalent of calling `~.Axes.set_yscale` on the
current axes.

Different keywords may be accepted, depending on the scale:

Expand All @@ -1637,24 +1662,63 @@ def yscale(*args, **kwargs):

def xticks(*args, **kwargs):
"""
Get or set the *x*-limits of the current tick locations and labels.
Get or set the current tick locations and labels of the x-axis.

::
Call signatures::

# return locs, labels where locs is an array of tick locations and
# labels is an array of tick labels.
locs, labels = xticks()
locs, labels = xticks() # Get locations and labels

# set the locations of the xticks
xticks( arange(6) )
xticks(locs, [labels], **kwargs) # Set locations and labels

# set the locations and labels of the xticks
xticks( arange(5), ('Tom', 'Dick', 'Harry', 'Sally', 'Sue') )
Parameters
----------
locs : array_like
A list of positions at which ticks should be placed. You can pass an
empty list to disable xticks.

The keyword args, if any, are :class:`~matplotlib.text.Text`
properties. For example, to rotate long labels::
labels : array_like, optional
A list of explicit labels to place at the given *locs*.

xticks( arange(12), calendar.month_name[1:13], rotation=17 )
**kwargs
:class:`.Text` properties can be used to control the appearance of
the labels.

Returns
-------
locs
An array of label locations.
labels
A list of `.Text` objects.

Notes
-----
Calling this function with no arguments (e.g. ``xticks()``) is the pyplot
equivalent of calling `~.Axes.get_xticks` and `~.Axes.get_xticklabels` on
the current axes.
Calling this function with arguments is the pyplot equivalent of calling
`~.Axes.set_xticks` and `~.Axes.set_xticklabels` on the current axes.

Examples
--------
Get the current locations and labels:

>>> locs, labels = xticks()

Set label locations:

>>> xticks(np.arange(0, 1, step=0.2))

Set text labels:

>>> xticks(np.arange(5), ('Tom', 'Dick', 'Harry', 'Sally', 'Sue'))

Set text labels and properties:

>>> xticks(np.arange(12), calendar.month_name[1:13], rotation=20)

Disable xticks:

>>> xticks([])
"""
ax = gca()

Expand All @@ -1677,24 +1741,63 @@ def xticks(*args, **kwargs):

def yticks(*args, **kwargs):
"""
Get or set the *y*-limits of the current tick locations and labels.
Get or set the current tick locations and labels of the y-axis.

Call signatures::

locs, labels = yticks() # Get locations and labels

yticks(locs, [labels], **kwargs) # Set locations and labels

Parameters
----------
locs : array_like
A list of positions at which ticks should be placed. You can pass an
empty list to disable yticks.

labels : array_like, optional
A list of explicit labels to place at the given *locs*.

**kwargs
:class:`.Text` properties can be used to control the appearance of
the labels.

Returns
-------
locs
An array of label locations.
labels
A list of `.Text` objects.

Notes
-----
Calling this function with no arguments (e.g. ``yticks()``) is the pyplot
equivalent of calling `~.Axes.get_yticks` and `~.Axes.get_yticklabels` on
the current axes.
Calling this function with arguments is the pyplot equivalent of calling
`~.Axes.set_yticks` and `~.Axes.set_yticklabels` on the current axes.

Examples
--------
Get the current locations and labels:

>>> locs, labels = yticks()

Set label locations:

>>> yticks(np.arange(0, 1, step=0.2))

::
Set text labels:

# return locs, labels where locs is an array of tick locations and
# labels is an array of tick labels.
locs, labels = yticks()
>>> yticks(np.arange(5), ('Tom', 'Dick', 'Harry', 'Sally', 'Sue'))

# set the locations of the yticks
yticks( arange(6) )
Set text labels and properties:

# set the locations and labels of the yticks
yticks( arange(5), ('Tom', 'Dick', 'Harry', 'Sally', 'Sue') )
>>> yticks(np.arange(12), calendar.month_name[1:13], rotation=45)

The keyword args, if any, are :class:`~matplotlib.text.Text`
properties. For example, to rotate long labels::
Disable yticks:

yticks( arange(12), calendar.month_name[1:13], rotation=45 )
>>> yticks([])
"""
ax = gca()

Expand Down