ticker.EngFormatter: base upon ScalarFormatter

doronbehar · doronbehar · commit ffe891474953 · 2024-07-01T23:42:04.000+03:00
Allows us to use many order of magnitude and offset related routines from ScalarFormatter, and removes a bit usetex related duplicated code. Solves #28463.
diff --git a/doc/users/next_whats_new/EngFormatter-offset.rst b/doc/users/next_whats_new/EngFormatter-offset.rst
@@ -0,0 +1,9 @@
+ticker.EngFormatter now computes offset by default
+--------------------------------------------------
+
+``ticker.EngFormatter`` was modified to act very similar to
+``ticker.ScalarFormatter``, such that it computes the best offset of the axis
+data, and shows the offset with the known SI quantity prefixes. To disable this
+new behavior, simply pass ``useOffset=False`` when you instantiate it. If offsets
+are disabled, or if there is no particular offset that fits your axis data, the
+formatter will reside to the old behavior.
diff --git a/lib/matplotlib/tests/test_ticker.py b/lib/matplotlib/tests/test_ticker.py
@@ -1594,6 +1594,18 @@ def test_engformatter_usetex_useMathText():
         assert x_tick_label_text == ['$0$', '$500$', '$1$ k']
 
 
+def test_engformatter_useOffset():
+    fig, ax = plt.subplots()
+    offset = int(1e7)
+    ydata = range(offset, offset+5)
+    ax.plot(ydata)
+    ax.set_yticks(ydata)
+    ax.yaxis.set_major_formatter(mticker.EngFormatter(useOffset=True, unit="Hz"))
+    fig.canvas.draw()
+    y_tick_label_text = [labl.get_text() for labl in ax.get_yticklabels()]
+    assert y_tick_label_text == (np.array(ydata)-offset).astype(str).tolist()
+
+
 class TestPercentFormatter:
     percent_data = [
         # Check explicitly set decimals over different intervals and values
diff --git a/lib/matplotlib/ticker.py b/lib/matplotlib/ticker.py
@@ -1338,7 +1338,7 @@ def format_data_short(self, value):
         return f"1-{1 - value:e}"
 
 
-class EngFormatter(Formatter):
+class EngFormatter(ScalarFormatter):
     """
     Format axis values using engineering prefixes to represent powers
     of 1000, plus a specified unit, e.g., 10 MHz instead of 1e7.
@@ -1370,7 +1370,7 @@ class EngFormatter(Formatter):
     }
 
     def __init__(self, unit="", places=None, sep=" ", *, usetex=None,
-                 useMathText=None):
+                 useMathText=None, useOffset=None):
         r"""
         Parameters
         ----------
@@ -1404,55 +1404,93 @@ def __init__(self, unit="", places=None, sep=" ", *, usetex=None,
         useMathText : bool, default: :rc:`axes.formatter.use_mathtext`
             To enable/disable the use mathtext for rendering the numbers in
             the formatter.
+        useOffset : bool or float, default: :rc:`axes.formatter.useoffset`
+            Whether to use offset notation. See `.set_useOffset`.
         """
         self.unit = unit
         self.places = places
         self.sep = sep
-        self.set_usetex(usetex)
-        self.set_useMathText(useMathText)
-
-    def get_usetex(self):
-        return self._usetex
-
-    def set_usetex(self, val):
-        if val is None:
-            self._usetex = mpl.rcParams['text.usetex']
-        else:
-            self._usetex = val
-
-    usetex = property(fget=get_usetex, fset=set_usetex)
-
-    def get_useMathText(self):
-        return self._useMathText
+        super().__init__(
+            useOffset=useOffset,
+            useMathText=useMathText,
+            useLocale=False,
+            usetex=usetex,
+        )
 
-    def set_useMathText(self, val):
-        if val is None:
-            self._useMathText = mpl.rcParams['axes.formatter.use_mathtext']
+    def __call__(self, x, pos=None):
+        """
+        Return the format for tick value *x* at position *pos*. If there is no
+        currently offset in the data, it returns the best engineering formatting
+        that fits the given argument, independently.
+        """
+        if len(self.locs) == 0 or self.offset == 0:
+            return self.fix_minus(self.format_data(x))
         else:
-            self._useMathText = val
+            xp = (x - self.offset) / (10. ** self.orderOfMagnitude)
+            if abs(xp) < 1e-8:
+                xp = 0
+            return self._format_maybe_minus_and_locale(self.format, xp)
 
-    useMathText = property(fget=get_useMathText, fset=set_useMathText)
+    def set_locs(self, locs):
+        # docstring inherited
+        self.locs = locs
+        if len(self.locs) > 0:
+            if self._useOffset:
+                self._compute_offset()
+            self._set_order_of_magnitude()
+            # This is what's different from ScalarFormatter: We search among
+            # the engineers' standard orders of magnitudes (0, -3, 3, -6, 6,
+            # -9, 9 etc) the oom closest to our self.orderOfMagnitude. Then we
+            # set our self.orderOfMagnitude to it.
+            c = abs(self.orderOfMagnitude)
+            for sciOom in itertools.count(0, 3):
+                if c <= sciOom:
+                    self.orderOfMagnitude = math.copysign(sciOom, self.orderOfMagnitude)
+                    break
+            self._set_format()
 
-    def __call__(self, x, pos=None):
-        s = f"{self.format_eng(x)}{self.unit}"
-        # Remove the trailing separator when there is neither prefix nor unit
-        if self.sep and s.endswith(self.sep):
-            s = s[:-len(self.sep)]
-        return self.fix_minus(s)
+    # Simplify a bit ScalarFormatter.get_offset: We always want to use
+    # self.format_data. We insert here the surrounding $...$ here, if tex /
+    # mathtext is set.
+    def get_offset(self):
+        # docstring inherited
+        if len(self.locs) == 0:
+            return ''
+        if self.orderOfMagnitude or self.offset:
+            offsetStr = ''
+            sciNotStr = ''
+            if self.offset:
+                offsetStr = self.format_data(self.offset)
+                if self.offset > 0:
+                    offsetStr = '+' + offsetStr
+            if self.orderOfMagnitude:
+                sciNotStr = self.format_data(10 ** self.orderOfMagnitude)
+            if self._useMathText or self._usetex:
+                if sciNotStr != '':
+                    sciNotStr = r'\times%s' % sciNotStr
+                s = fr'${sciNotStr}{offsetStr}$'
+            else:
+                s = ''.join((sciNotStr, offsetStr))
+            return self.fix_minus(s)
+        return ''
 
     def format_eng(self, num):
+        """Alias to EngFormatter.format_data"""
+        return self.format_data(num)
+
+    def format_data(self, value):
         """
         Format a number in engineering notation, appending a letter
         representing the power of 1000 of the original number.
         Some examples:
 
-        >>> format_eng(0)        # for self.places = 0
+        >>> format_data(0)        # for self.places = 0
         '0'
 
-        >>> format_eng(1000000)  # for self.places = 1
+        >>> format_data(1000000)  # for self.places = 1
         '1.0 M'
 
-        >>> format_eng(-1e-6)  # for self.places = 2
+        >>> format_data(-1e-6)  # for self.places = 2
         '-1.00 \N{MICRO SIGN}'
         """
         sign = 1
@@ -1482,13 +1520,15 @@ def format_eng(self, num):
             mant /= 1000
             pow10 += 3
 
-        prefix = self.ENG_PREFIXES[int(pow10)]
+        unitPrefix = self.ENG_PREFIXES[int(pow10)]
+        if self.unit or unitPrefix:
+            suffix = f"{self.sep}{unitPrefix}{self.unit}"
+        else:
+            suffix = ""
         if self._usetex or self._useMathText:
-            formatted = f"${mant:{fmt}}${self.sep}{prefix}"
+            return rf"${mant:{fmt}}${suffix}"
         else:
-            formatted = f"{mant:{fmt}}{self.sep}{prefix}"
-
-        return formatted
+            return rf"{mant:{fmt}}{suffix}"
 
 
 class PercentFormatter(Formatter):
diff --git a/lib/matplotlib/ticker.pyi b/lib/matplotlib/ticker.pyi
@@ -67,10 +67,6 @@ class ScalarFormatter(Formatter):
         usetex: bool | None = ...,
     ) -> None: ...
     offset: float
-    def get_usetex(self) -> bool: ...
-    def set_usetex(self, val: bool | float) -> None: ...
-    @property
-    def usetex(self) -> bool: ...
     def get_useOffset(self) -> bool: ...
     def set_useOffset(self, val: bool | float) -> None: ...
     @property
@@ -130,7 +126,7 @@ class LogitFormatter(Formatter):
     def set_minor_number(self, minor_number: int) -> None: ...
     def format_data_short(self, value: float) -> str: ...
 
-class EngFormatter(Formatter):
+class EngFormatter(ScalarFormatter):
     ENG_PREFIXES: dict[int, str]
     unit: str
     places: int | None
@@ -142,20 +138,9 @@ class EngFormatter(Formatter):
         sep: str = ...,
         *,
         usetex: bool | None = ...,
-        useMathText: bool | None = ...
+        useMathText: bool | None = ...,
+        useOffset: bool | float | None = ...,
     ) -> None: ...
-    def get_usetex(self) -> bool: ...
-    def set_usetex(self, val: bool | None) -> None: ...
-    @property
-    def usetex(self) -> bool: ...
-    @usetex.setter
-    def usetex(self, val: bool | None) -> None: ...
-    def get_useMathText(self) -> bool: ...
-    def set_useMathText(self, val: bool | None) -> None: ...
-    @property
-    def useMathText(self) -> bool: ...
-    @useMathText.setter
-    def useMathText(self, val: bool | None) -> None: ...
     def format_eng(self, num: float) -> str: ...
 
 class PercentFormatter(Formatter):
