Add function plotting.percentage_ticks()

Author: rsundqvist

CHANGELOG.md

@@ -9,6 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 - Argument `include_module=False` for function `misc.tname()`.
+- New function `plotting.percentage_ticks()`
 
 ### Removed
 - Module `rics.ml.time_split`. use the `time-split` [![PyPI - Version](https://img.shields.io/pypi/v/time-split.svg)](https://pypi.python.org/pypi/time-split) package instead.

src/rics/plotting.py

@@ -4,12 +4,14 @@
 
 from matplotlib.axis import Axis as _Axis
 from matplotlib.axis import XAxis as _XAxis
+from matplotlib.axis import YAxis as _YAxis
 from matplotlib.ticker import FuncFormatter as _FuncFormatter
 from matplotlib.ticker import IndexLocator as _IndexLocator
 
 ERROR_BAR_CAPSIZE: float = 0.1
 
-HalfRep = _t.Literal["fraction", "decimal", "frac", "dec", "f", "d"]
+HalfRep = _t.Literal["fraction", "f", "decimal", "d"]
+Decimals = int | _t.Literal[False] | None
 
 
 class HasXAxis(_t.Protocol):
@@ -19,6 +21,13 @@ class HasXAxis(_t.Protocol):
     """X-Axis attribute."""
 
 
+class HasYAxis(_t.Protocol):
+    """Protocol class indicating something that as an Y-axis."""
+
+    yaxis: _YAxis
+    """Y-Axis attribute."""
+
+
 def configure() -> None:
     """Call all configure-functions in this module."""
     configure_matplotlib()
@@ -57,15 +66,10 @@ def configure_matplotlib() -> None:
         ModuleNotFoundError: If matplotlib is not installed.
 
     """
-    import functools
-
     import matplotlib.pyplot as plt
-    import matplotlib.ticker as mtick
 
     plt.rcParams["figure.figsize"] = (20, 5)
-    plt.subplots = functools.partial(plt.subplots, tight_layout=True)
-
-    mtick.PercentFormatter = functools.partial(mtick.PercentFormatter, xmax=1)  # type: ignore[misc, assignment]
+    plt.rcParams["figure.autolayout"] = True
 
 
 def pi_ticks(ax: _Axis | HasXAxis, half_rep: HalfRep | None = None) -> None:
@@ -81,13 +85,13 @@ def pi_ticks(ax: _Axis | HasXAxis, half_rep: HalfRep | None = None) -> None:
          - Example output
        * - ``None``
          - Show integer multiples only.
-         - `0, π, 2π, 3π..`
+         - `0, π, 2π, 3π, ...`
        * - `'f'` or `'fraction'`
          - Halves of `π` use fractional representation.
-         - `0/2π, 1/2π, 2/2π, 3/2π..`
+         - `0/2π, 1/2π, 2/2π, 3/2π, ...`
        * - `'d'` or `'decimal'`
          - Halves of `π` use decimal representation.
-         - `0.0π, 0.5π, 1.0π, 1.5π..`
+         - `0.0π, 0.5π, 1.0π, 1.5π, ...`
 
     Args:
         ax: An axis to decorate, or an object with an `xaxis` attribute.
@@ -131,7 +135,8 @@ def _parse_half_rep(
         if parsed_half.startswith("d"):
             return "dec"
 
-        raise TypeError(f"Argument {half_rep=} not in ('[f]raction', '[d]ecimal', None).")
+        msg = f"Argument {half_rep=} not in ('[f]raction', '[d]ecimal', None)."
+        raise TypeError(msg)
 
     def _format(self, x: float, _pos: int) -> str:
         n = round(x / self.PI, 1)
@@ -148,3 +153,31 @@ def _format(self, x: float, _pos: int) -> str:
             return f"{n}π"
 
         return f"{int(n * 2)}/2π"
+
+
+def percentage_ticks(
+    ax: _Axis | HasYAxis,
+    *,
+    sign: bool = False,
+    decimals: Decimals = 1,
+) -> None:
+    """Decorate an axis by formatting ticks as percentages.
+
+    Args:
+        ax: An axis to decorate, or an object with a `yaxis` attribute.
+        sign: If ``True``, show prepend `'+'` for positive ticks.
+        decimals: Number of decimals to keep.
+
+    Return:
+        The formatting string.
+    """
+    axis: _Axis = ax.yaxis if hasattr(ax, "yaxis") else ax
+
+    formatter = _make_percent_formatter(sign, decimals)
+    axis.set_major_formatter(formatter)
+
+
+def _make_percent_formatter(sign: bool, decimals: Decimals) -> str:
+    plus = "+" if sign else ""
+    decimals = decimals or 0
+    return "{" + f"x:{plus}.{decimals}%" + "}"

tests/test_plotting.py

@@ -2,7 +2,7 @@
 import numpy as np
 import pytest
 
-from rics.plotting import _PiTickHelper, pi_ticks
+from rics.plotting import _make_percent_formatter, _PiTickHelper, percentage_ticks, pi_ticks
 
 PI = _PiTickHelper.PI
 HALF_PI = PI / 2
@@ -42,3 +42,32 @@ def test_pi_tick_helper(half, start, start_rounded_to_pi, expected):
     # Test formatting
     actual = [helper._format(x, pos) for x, pos in values]
     assert actual == expected
+
+
+def test_percent_ticks_doesnt_crash():
+    ax = plt.axes()
+    ax.plot(range(10))
+    percentage_ticks(ax)
+    plt.close("all")
+
+
+@pytest.mark.parametrize(
+    "x, sign, decimals, expected",
+    [
+        (-0.111, False, 0, "-11%"),
+        (-0.111, False, 1, "-11.1%"),
+        (-0.111, True, 1, "-11.1%"),
+        (-0.000, False, 0, "-0%"),
+        (-0.000, False, 1, "-0.0%"),
+        (-0.000, True, 1, "-0.0%"),
+        (+0.000, False, 0, "0%"),
+        (+0.000, False, 1, "0.0%"),
+        (+0.000, True, 1, "+0.0%"),
+        (+0.111, False, 0, "11%"),
+        (+0.111, False, 1, "11.1%"),
+        (+0.111, True, 1, "+11.1%"),
+    ],
+)
+def test_percent_formatter(x, sign, decimals, expected):
+    actual = _make_percent_formatter(sign, decimals).format(x=x)
+    assert actual == expected