Skip to content

Improve docstrings of ScalarFormatter #17592

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
Jun 9, 2020
Merged

Improve docstrings of ScalarFormatter #17592

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
88 changes: 83 additions & 5 deletions lib/matplotlib/ticker.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -484,11 +484,21 @@ class ScalarFormatter(Formatter):
"""
Format tick values as a 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))``, defaulting to :rc:`axes.formatter.limits`.
Parameters
----------
useOffset : bool or float, default: :rc:`axes.formatter.useoffset`
Whether to use offset notation. See `.set_useOffset`.
useMathText : bool, default: :rc:`axes.formatter.use_mathtext`
Whether to use fancy math formatting. See `.set_useMathText`.
useLocale : bool, default: :rc:`axes.formatter.use_locale`.
Whether to use locale settings for decimal sign and positive sign.
See `.set_useLocale`.

Notes
-----
In addition to the parameters above, the formatting of scientific vs.
floating point representation can be configured via `.set_scientific`
and `.set_powerlimits`).
"""

def __init__(self, useOffset=None, useMathText=None, useLocale=None):
Expand All @@ -514,9 +524,45 @@ def __init__(self, useOffset=None, useMathText=None, useLocale=None):
self._useLocale = useLocale

def get_useOffset(self):
"""
Return whether automatic mode for offset notation is active.

This returns True if ``set_useOffset(True)``; it returns False if an
explicit offset was set, e.g. ``set_useOffset(1000)``.

See Also
--------
ScalarFormatter.set_useOffset
"""
return self._useOffset

def set_useOffset(self, val):
"""
Set whether to use offset notation.

When formatting a set numbers whose value is large compared to their
range, the formatter can separate an additive constant. This can
shorten the formatted numbers so that they are less likely to overlap
when drawn on an axis.

Parameters
----------
val : bool or float
- If False, do not use offset notation.
- If True (=automatic mode), use offset notation if it can make
the residual numbers significantly shorter. The exact behavior
is controlled by :rc:`axes.formatter.offset_threshold`.
- If a number, force an offset of the given value.

Examples
--------
With active offset notation, the values

``100_000, 100_002, 100_004, 100_006, 100_008``

will be formatted as ``0, 2, 4, 6, 8`` plus an offset ``+1e5``, which
is written to the edge of the axis.
"""
if val in [True, False]:
self.offset = 0
self._useOffset = val
Expand All @@ -527,9 +573,24 @@ def set_useOffset(self, val):
useOffset = property(fget=get_useOffset, fset=set_useOffset)

def get_useLocale(self):
"""
Return whether locale settings are used for formatting.

See Also
--------
ScalarFormatter.set_useLocale
"""
return self._useLocale

def set_useLocale(self, val):
"""
Set whether to use locale settings for decimal sign and positive sign.

Parameters
----------
val : bool or None
*None* resets to :rc:`axes.formatter.use_locale`.
"""
if val is None:
self._useLocale = mpl.rcParams['axes.formatter.use_locale']
else:
Expand All @@ -538,9 +599,26 @@ def set_useLocale(self, val):
useLocale = property(fget=get_useLocale, fset=set_useLocale)

def get_useMathText(self):
"""
Return whether to use fancy math formatting.

See Also
--------
ScalarFormatter.set_useMathText
"""
return self._useMathText

def set_useMathText(self, val):
r"""
Set whether to use fancy math formatting.

If active, scientific notation is formatted as :math:`1.2 \times 10^3`.

Parameters
----------
val : bool or None
*None* resets to :rc:`axes.formatter.use_mathtext`.
"""
if val is None:
self._useMathText = mpl.rcParams['axes.formatter.use_mathtext']
else:
Expand Down