From e2bebbec36b80eaefea3584d3486424188afa8d5 Mon Sep 17 00:00:00 2001
From: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com>
Date: Tue, 9 Jun 2020 03:33:05 +0200
Subject: [PATCH] Improve docstrings of ScalarFormatter
---
lib/matplotlib/ticker.py | 88 +++++++++++++++++++++++++++++++++++++---
1 file changed, 83 insertions(+), 5 deletions(-)
diff --git a/lib/matplotlib/ticker.py b/lib/matplotlib/ticker.py
index 89a653fa7cb5..192811d99c5b 100644
--- a/lib/matplotlib/ticker.py
+++ b/lib/matplotlib/ticker.py
@@ -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):
@@ -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
@@ -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:
@@ -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:
pFad - Phonifier reborn
Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.
Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.
Alternative Proxies:
Alternative Proxy
pFad Proxy
pFad v3 Proxy
pFad v4 Proxy