Skip to content

Tweak Axes3D docstrings that refer to 2D plotting methods. #22394

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 1 commit into from
Feb 4, 2022
Merged

Tweak Axes3D docstrings that refer to 2D plotting methods. #22394

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
4 changes: 2 additions & 2 deletions lib/matplotlib/axes/_base.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2705,11 +2705,11 @@ def margins(self, *margins, x=None, y=None, tight=True):
only the y-axis.

tight : bool or None, default: True
The *tight* parameter is passed to :meth:`autoscale_view`,
The *tight* parameter is passed to `autoscale_view`,
which is executed after a margin is changed; the default
here is *True*, on the assumption that when margins are
specified, no additional padding to match tick marks is
usually desired. Set *tight* to *None* will preserve
usually desired. Setting *tight* to *None* preserves
the previous setting.

Returns
Expand Down
86 changes: 24 additions & 62 deletions lib/mpl_toolkits/mplot3d/axes3d.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -510,41 +510,11 @@ def set_zmargin(self, m):

def margins(self, *margins, x=None, y=None, z=None, tight=True):
"""
Convenience method to set or retrieve autoscaling margins.
Set or retrieve autoscaling margins.

Call signatures::

margins()

returns xmargin, ymargin, zmargin

::

margins(margin)

margins(xmargin, ymargin, zmargin)

margins(x=xmargin, y=ymargin, z=zmargin)

margins(..., tight=False)

All forms above set the xmargin, ymargin and zmargin
parameters. All keyword parameters are optional. A single
positional argument specifies xmargin, ymargin and zmargin.
Passing both positional and keyword arguments for xmargin,
ymargin, and/or zmargin is invalid.

The *tight* parameter
is passed to :meth:`autoscale_view`, which is executed after
a margin is changed; the default here is *True*, on the
assumption that when margins are specified, no additional
padding to match tick marks is usually desired. Setting
*tight* to *None* will preserve the previous setting.

Specifying any margin changes only the autoscaling; for example,
if *xmargin* is not None, then *xmargin* times the X data
interval will be added to each end of that interval before
it is used in autoscaling.
See `.Axes.margins` for full documentation. Because this function
applies to 3D Axes, it also takes a *z* argument, and returns
``(xmargin, ymargin, zmargin)``.
"""
if margins and x is not None and y is not None and z is not None:
raise TypeError('Cannot pass both positional and keyword '
Expand Down Expand Up @@ -577,10 +547,10 @@ def margins(self, *margins, x=None, y=None, z=None, tight=True):
def autoscale(self, enable=True, axis='both', tight=None):
"""
Convenience method for simple axis view autoscaling.
See :meth:`matplotlib.axes.Axes.autoscale` for full explanation.
Note that this function behaves the same, but for all
three axes. Therefore, 'z' can be passed for *axis*,
and 'both' applies to all three axes.

See `.Axes.autoscale` for full documentation. Because this function
applies to 3D Axes, *axis* can also be set to 'z', and setting *axis*
to 'both' autoscales all three axes.
"""
if enable is None:
scalex = True
Expand Down Expand Up @@ -624,9 +594,9 @@ def autoscale_view(self, tight=None, scalex=True, scaley=True,
scalez=True):
"""
Autoscale the view limits using the data limits.
See :meth:`matplotlib.axes.Axes.autoscale_view` for documentation.
Note that this function applies to the 3D axes, and as such
adds the *scalez* to the function arguments.

See `.Axes.autoscale_view` for full documentation. Because this
function applies to 3D Axes, it also takes a *scalez* argument.
"""
# This method looks at the rectangular volume (see above)
# of data and decides how to scale the view portal to fit it.
Expand Down Expand Up @@ -694,7 +664,7 @@ def set_xlim3d(self, left=None, right=None, emit=True, auto=False,
"""
Set 3D x limits.

See :meth:`matplotlib.axes.Axes.set_xlim` for full documentation.
See `.Axes.set_xlim` for full documentation.
"""
if right is None and np.iterable(left):
left, right = left
Expand Down Expand Up @@ -751,7 +721,7 @@ def set_ylim3d(self, bottom=None, top=None, emit=True, auto=False,
"""
Set 3D y limits.

See :meth:`matplotlib.axes.Axes.set_ylim` for full documentation.
See `.Axes.set_ylim` for full documentation.
"""
if top is None and np.iterable(bottom):
bottom, top = bottom
Expand Down Expand Up @@ -809,7 +779,7 @@ def set_zlim3d(self, bottom=None, top=None, emit=True, auto=False,
"""
Set 3D z limits.

See :meth:`matplotlib.axes.Axes.set_ylim` for full documentation
See `.Axes.set_ylim` for full documentation
"""
if top is None and np.iterable(bottom):
bottom, top = bottom
Expand Down Expand Up @@ -1358,8 +1328,8 @@ def grid(self, visible=True, **kwargs):
.. note::

Currently, this function does not behave the same as
:meth:`matplotlib.axes.Axes.grid`, but it is intended to
eventually support that behavior.
`.axes.Axes.grid`, but it is intended to eventually support that
behavior.
"""
# TODO: Operate on each axes separately
if len(kwargs):
Expand All @@ -1372,13 +1342,9 @@ def tick_params(self, axis='both', **kwargs):
Convenience method for changing the appearance of ticks and
tick labels.

See :meth:`matplotlib.axes.Axes.tick_params` for more complete
documentation.

The only difference is that setting *axis* to 'both' will
mean that the settings are applied to all three axes. Also,
the *axis* parameter also accepts a value of 'z', which
would mean to apply to only the z-axis.
See `.Axes.tick_params` for full documentation. Because this function
applies to 3D Axes, *axis* can also be set to 'z', and setting *axis*
to 'both' autoscales all three axes.

Also, because of how Axes3D objects are drawn very differently
from regular 2D axes, some of these settings may have
Expand Down Expand Up @@ -2104,8 +2070,7 @@ def contour(self, X, Y, Z, *args,
Parameters
----------
X, Y, Z : array-like,
Input data. See `~matplotlib.axes.Axes.contour` for acceptable
data shapes.
Input data. See `.Axes.contour` for supported data shapes.
extend3d : bool, default: False
Whether to extend contour in 3D.
stride : int
Expand Down Expand Up @@ -2149,8 +2114,7 @@ def tricontour(self, *args,
Parameters
----------
X, Y, Z : array-like
Input data. See `~matplotlib.axes.Axes.tricontour` for acceptable
data shapes.
Input data. See `.Axes.tricontour` for supported data shapes.
extend3d : bool, default: False
Whether to extend contour in 3D.
stride : int
Expand Down Expand Up @@ -2208,8 +2172,7 @@ def contourf(self, X, Y, Z, *args, zdir='z', offset=None, **kwargs):
Parameters
----------
X, Y, Z : array-like
Input data. See `~matplotlib.axes.Axes.contourf` for acceptable
data shapes.
Input data. See `.Axes.contourf` for supported data shapes.
zdir : {'x', 'y', 'z'}, default: 'z'
The direction to use.
offset : float, optional
Expand Down Expand Up @@ -2247,8 +2210,7 @@ def tricontourf(self, *args, zdir='z', offset=None, **kwargs):
Parameters
----------
X, Y, Z : array-like
Input data. See `~matplotlib.axes.Axes.tricontourf` for acceptable
data shapes.
Input data. See `.Axes.tricontourf` for supported data shapes.
zdir : {'x', 'y', 'z'}, default: 'z'
The direction to use.
offset : float, optional
Expand Down Expand Up @@ -3056,7 +3018,7 @@ def errorbar(self, x, y, z, zerr=None, yerr=None, xerr=None, fmt='',
this. *lims*-arguments may be scalars, or array-likes of the same
length as the errors. To use limits with inverted axes,
`~.Axes.set_xlim` or `~.Axes.set_ylim` must be called before
:meth:`errorbar`. Note the tricky parameter names: setting e.g.
`errorbar`. Note the tricky parameter names: setting e.g.
*ylolims* to True means that the y-value is a *lower* limit of the
True value, so, only an *upward*-pointing arrow will be drawn!

Expand Down