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

Skip to content

[DOC] Clarify some tick-related docstrings #26619

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
Aug 30, 2023
Merged

[DOC] Clarify some tick-related docstrings #26619

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
65 changes: 39 additions & 26 deletions lib/matplotlib/axes/_base.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2019,26 +2019,30 @@ def axis(self, arg=None, /, *, emit=True, **kwargs):
If a bool, turns axis lines and labels on or off. If a string,
possible values are:

======== ==========================================================
Value Description
======== ==========================================================
'on' Turn on axis lines and labels. Same as ``True``.
'off' Turn off axis lines and labels. Same as ``False``.
'equal' Set equal scaling (i.e., make circles circular) by
changing axis limits. This is the same as
``ax.set_aspect('equal', adjustable='datalim')``.
Explicit data limits may not be respected in this case.
'scaled' Set equal scaling (i.e., make circles circular) by
changing dimensions of the plot box. This is the same as
``ax.set_aspect('equal', adjustable='box', anchor='C')``.
Additionally, further autoscaling will be disabled.
'tight' Set limits just large enough to show all data, then
disable further autoscaling.
'auto' Automatic scaling (fill plot box with data).
'image' 'scaled' with axis limits equal to data limits.
'square' Square plot; similar to 'scaled', but initially forcing
``xmax-xmin == ymax-ymin``.
======== ==========================================================
================ ===========================================================
Value Description
================ ===========================================================
'off' or `False` Hide all axis decorations, i.e. axis labels, spines,
tick marks, tick labels, and grid lines.
This is the same as `~.Axes.set_axis_off()`.
'on' or `True` Do not hide all axis decorations, i.e. axis labels, spines,
tick marks, tick labels, and grid lines.
This is the same as `~.Axes.set_axis_on()`.
'equal' Set equal scaling (i.e., make circles circular) by
changing the axis limits. This is the same as
``ax.set_aspect('equal', adjustable='datalim')``.
Explicit data limits may not be respected in this case.
'scaled' Set equal scaling (i.e., make circles circular) by
changing dimensions of the plot box. This is the same as
``ax.set_aspect('equal', adjustable='box', anchor='C')``.
Additionally, further autoscaling will be disabled.
'tight' Set limits just large enough to show all data, then
disable further autoscaling.
'auto' Automatic scaling (fill plot box with data).
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

what does fill plot box (Axes?) with data mean?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As above: scaling is not in the scope of the PR

'image' 'scaled' with axis limits equal to data limits.
'square' Square plot; similar to 'scaled', but initially forcing
``xmax-xmin == ymax-ymin``.
Comment on lines +2043 to +2044
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

should this maybe be moved under scaled then?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As above: scaling is not in the scope of the PR

================ ===========================================================

emit : bool, default: True
Whether observers are notified of the axis limit change.
Expand Down Expand Up @@ -3423,18 +3427,25 @@ def tick_params(self, axis='both', **kwargs):

def set_axis_off(self):
"""
Turn the x- and y-axis off.
Hide all visual components of the x- and y-axis.

This affects the axis lines, ticks, ticklabels, grid and axis labels.
This sets a flag to suppress drawing of all axis decorations, i.e.
axis labels, axis spines, and the axis tick component (tick markers,
tick labels, and grid lines). Individual visibility settings of these
components are ignored as long as `set_axis_off()` is in effect.
"""
self.axison = False
self.stale = True

def set_axis_on(self):
"""
Turn the x- and y-axis on.
Do not hide all visual components of the x- and y-axis.

This affects the axis lines, ticks, ticklabels, grid and axis labels.
This reverts the effect of a prior `.set_axis_off()` call. Whether the
individual axis decorations are drawn is controlled by their respective
visibility settings.

This is on by default.
"""
self.axison = True
self.stale = True
Expand Down Expand Up @@ -3681,7 +3692,8 @@ def set_xlim(self, left=None, right=None, *, emit=True, auto=False,
get_xscale = _axis_method_wrapper("xaxis", "get_scale")
set_xscale = _axis_method_wrapper("xaxis", "_set_axes_scale")
get_xticks = _axis_method_wrapper("xaxis", "get_ticklocs")
set_xticks = _axis_method_wrapper("xaxis", "set_ticks")
set_xticks = _axis_method_wrapper("xaxis", "set_ticks",
doc_sub={'set_ticks': 'set_xticks'})
get_xmajorticklabels = _axis_method_wrapper("xaxis", "get_majorticklabels")
get_xminorticklabels = _axis_method_wrapper("xaxis", "get_minorticklabels")
get_xticklabels = _axis_method_wrapper("xaxis", "get_ticklabels")
Expand Down Expand Up @@ -3912,7 +3924,8 @@ def set_ylim(self, bottom=None, top=None, *, emit=True, auto=False,
get_yscale = _axis_method_wrapper("yaxis", "get_scale")
set_yscale = _axis_method_wrapper("yaxis", "_set_axes_scale")
get_yticks = _axis_method_wrapper("yaxis", "get_ticklocs")
set_yticks = _axis_method_wrapper("yaxis", "set_ticks")
set_yticks = _axis_method_wrapper("yaxis", "set_ticks",
doc_sub={'set_ticks': 'set_yticks'})
get_ymajorticklabels = _axis_method_wrapper("yaxis", "get_majorticklabels")
get_yminorticklabels = _axis_method_wrapper("yaxis", "get_minorticklabels")
get_yticklabels = _axis_method_wrapper("yaxis", "get_ticklabels")
Expand Down
11 changes: 8 additions & 3 deletions lib/matplotlib/axis.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2090,7 +2090,7 @@ def _set_tick_locations(self, ticks, *, minor=False):

def set_ticks(self, ticks, labels=None, *, minor=False, **kwargs):
"""
Set this Axis' tick locations and optionally labels.
Set this Axis' tick locations and optionally tick labels.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Set this Axis' tick locations and optionally tick labels.
Set tick locations and optionally tick labels.

I think this Axis is given by these being a method on an Axis

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"this Axis" is a special term that gets replaced by axis_method_wrapper() so that set_xticks reuses the docstring but with "the xaxis" instead of "this Axis".

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure it's needed but that at least makes more sense

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The function is then Axes.set_yticks. While "y" is in the function name, it's nice to mention the axis in the docstring explicitly, because Axes has more than one axis.


If necessary, the view limits of the Axis are expanded so that all
given ticks are visible.
Expand All @@ -2103,14 +2103,19 @@ def set_ticks(self, ticks, labels=None, *, minor=False, **kwargs):

The values may be either floats or in axis units.

Pass an empty list to remove all ticks::

set_ticks([])

Some tick formatters will not label arbitrary tick positions;
e.g. log formatters only label decade ticks by default. In
such a case you can set a formatter explicitly on the axis
using `.Axis.set_major_formatter` or provide formatted
*labels* yourself.
labels : list of str, optional
List of tick labels. If not set, the labels are generated with
the axis tick `.Formatter`.
Tick labels for each location in *ticks*. *labels* must be of the same
length as *ticks*. If not set, the labels are generate using the axis
tick `.Formatter`.
minor : bool, default: False
If ``False``, set the major ticks; if ``True``, the minor ticks.
**kwargs
Expand Down