camminady_matplotlib_theme 0.2.0__py3-none-any.whl

camminady_matplotlib_theme/__init__.py

@@ -0,0 +1,47 @@
+"""Minimal matplotlib styles: ``"camminady"`` and ``"camminady_dark"``.
+
+They match the Altair theme of ``camminady_altair_theme``. Use a style
+without importing this package::
+
+    import matplotlib.pyplot as plt
+
+    plt.style.use("camminady_matplotlib_theme.camminady")
+
+Importing the package also registers the short names ``"camminady"`` and
+``"camminady_dark"`` with matplotlib, without applying a style.
+
+.. include:: ../../README.md
+   :start-after: <!-- docs-start -->
+"""
+
+from importlib.metadata import version
+
+import matplotlib
+import matplotlib.style
+
+from camminady_matplotlib_theme.layout import install
+from camminady_matplotlib_theme.theme import (
+    OKABE_ITO,
+    TABLEAU10,
+    Config,
+    config,
+    config_dark,
+    rc_params,
+    to_mplstyle,
+)
+
+__all__ = [
+    "OKABE_ITO",
+    "TABLEAU10",
+    "Config",
+    "install",
+    "rc_params",
+    "to_mplstyle",
+]
+__version__ = version("camminady-matplotlib-theme")
+
+matplotlib.style.library["camminady"] = matplotlib.RcParams(rc_params(config))
+matplotlib.style.library["camminady_dark"] = matplotlib.RcParams(
+    rc_params(config_dark)
+)
+matplotlib.style.available[:] = sorted(matplotlib.style.library)

camminady_matplotlib_theme/camminady.mplstyle

@@ -0,0 +1,85 @@
+figure.dpi: 72
+savefig.dpi: 288
+figure.figsize: 11.777777777777779, 6.5
+figure.facecolor: white
+figure.edgecolor: white
+figure.titlesize: 20
+figure.titleweight: normal
+figure.labelsize: 14
+figure.labelweight: normal
+figure.constrained_layout.use: True
+figure.hooks: camminady_matplotlib_theme.layout:install
+font.family: sans-serif
+font.sans-serif: Helvetica, Arial, Liberation Sans, DejaVu Sans
+font.size: 12
+font.weight: normal
+text.color: dimgray
+axes.facecolor: white
+axes.edgecolor: 767676
+axes.linewidth: 1
+axes.spines.top: False
+axes.spines.right: False
+axes.grid: True
+axes.grid.axis: both
+axes.axisbelow: True
+axes.labelcolor: dimgray
+axes.labelsize: 14
+axes.labelweight: normal
+axes.labelpad: 4
+axes.titlecolor: dimgray
+axes.titlesize: 20
+axes.titleweight: normal
+axes.titlepad: 8
+axes.prop_cycle: cycler('color', ['4c78a8', 'f58518', 'e45756', '72b7b2', '54a24b', 'eeca3b', 'b279a2', 'ff9da6', '9d755d', 'bab0ac'])
+axes.autolimit_mode: round_numbers
+axes.xmargin: 0
+axes.ymargin: 0
+xaxis.labellocation: right
+yaxis.labellocation: top
+grid.color: dddddd
+grid.linewidth: 1
+grid.linestyle: (0, (3, 3))
+grid.alpha: 1
+xtick.color: 767676
+xtick.labelcolor: 767676
+xtick.labelsize: 12
+xtick.direction: out
+xtick.major.size: 5
+xtick.major.width: 1
+xtick.major.pad: 2
+xtick.minor.visible: False
+ytick.color: 767676
+ytick.labelcolor: 767676
+ytick.labelsize: 12
+ytick.direction: out
+ytick.major.size: 5
+ytick.major.width: 1
+ytick.major.pad: 2
+ytick.minor.visible: False
+lines.linewidth: 2
+lines.color: dimgray
+lines.solid_capstyle: round
+lines.markersize: 5.5
+patch.facecolor: 4c78a8
+patch.force_edgecolor: True
+patch.edgecolor: white
+patch.linewidth: 1
+legend.frameon: False
+legend.fontsize: 12
+legend.title_fontsize: 14
+legend.labelcolor: dimgray
+legend.borderpad: 0
+legend.labelspacing: 0.25
+legend.handlelength: 1.2
+legend.handletextpad: 0.5
+boxplot.patchartist: True
+boxplot.showcaps: False
+boxplot.boxprops.color: 4c78a8
+boxplot.whiskerprops.color: dimgray
+boxplot.whiskerprops.linewidth: 1
+boxplot.medianprops.color: white
+boxplot.medianprops.linewidth: 1
+boxplot.flierprops.marker: o
+boxplot.flierprops.markerfacecolor: none
+boxplot.flierprops.markeredgecolor: 4c78a8
+errorbar.capsize: 0

camminady_matplotlib_theme/camminady_dark.mplstyle

@@ -0,0 +1,85 @@
+figure.dpi: 72
+savefig.dpi: 288
+figure.figsize: 11.777777777777779, 6.5
+figure.facecolor: 1e1e1e
+figure.edgecolor: 1e1e1e
+figure.titlesize: 20
+figure.titleweight: normal
+figure.labelsize: 14
+figure.labelweight: normal
+figure.constrained_layout.use: True
+figure.hooks: camminady_matplotlib_theme.layout:install
+font.family: sans-serif
+font.sans-serif: Helvetica, Arial, Liberation Sans, DejaVu Sans
+font.size: 12
+font.weight: normal
+text.color: a9a9a9
+axes.facecolor: 1e1e1e
+axes.edgecolor: 8c8c8c
+axes.linewidth: 1
+axes.spines.top: False
+axes.spines.right: False
+axes.grid: True
+axes.grid.axis: both
+axes.axisbelow: True
+axes.labelcolor: a9a9a9
+axes.labelsize: 14
+axes.labelweight: normal
+axes.labelpad: 4
+axes.titlecolor: a9a9a9
+axes.titlesize: 20
+axes.titleweight: normal
+axes.titlepad: 8
+axes.prop_cycle: cycler('color', ['4c78a8', 'f58518', 'e45756', '72b7b2', '54a24b', 'eeca3b', 'b279a2', 'ff9da6', '9d755d', 'bab0ac'])
+axes.autolimit_mode: round_numbers
+axes.xmargin: 0
+axes.ymargin: 0
+xaxis.labellocation: right
+yaxis.labellocation: top
+grid.color: 3a3a3a
+grid.linewidth: 1
+grid.linestyle: (0, (3, 3))
+grid.alpha: 1
+xtick.color: 8c8c8c
+xtick.labelcolor: 8c8c8c
+xtick.labelsize: 12
+xtick.direction: out
+xtick.major.size: 5
+xtick.major.width: 1
+xtick.major.pad: 2
+xtick.minor.visible: False
+ytick.color: 8c8c8c
+ytick.labelcolor: 8c8c8c
+ytick.labelsize: 12
+ytick.direction: out
+ytick.major.size: 5
+ytick.major.width: 1
+ytick.major.pad: 2
+ytick.minor.visible: False
+lines.linewidth: 2
+lines.color: a9a9a9
+lines.solid_capstyle: round
+lines.markersize: 5.5
+patch.facecolor: 4c78a8
+patch.force_edgecolor: True
+patch.edgecolor: 1e1e1e
+patch.linewidth: 1
+legend.frameon: False
+legend.fontsize: 12
+legend.title_fontsize: 14
+legend.labelcolor: a9a9a9
+legend.borderpad: 0
+legend.labelspacing: 0.25
+legend.handlelength: 1.2
+legend.handletextpad: 0.5
+boxplot.patchartist: True
+boxplot.showcaps: False
+boxplot.boxprops.color: 4c78a8
+boxplot.whiskerprops.color: a9a9a9
+boxplot.whiskerprops.linewidth: 1
+boxplot.medianprops.color: white
+boxplot.medianprops.linewidth: 1
+boxplot.flierprops.marker: o
+boxplot.flierprops.markerfacecolor: none
+boxplot.flierprops.markeredgecolor: 4c78a8
+errorbar.capsize: 0

camminady_matplotlib_theme/layout.py

@@ -0,0 +1,242 @@
+"""Place axis titles, legends and ticks like the camminady Altair theme.
+
+matplotlib has no rcParams for a horizontal y-axis title above the axis, for
+a legend outside the plot or for Vega's tick density, so the styles register
+`install` as a figure hook. It gives each figure created with ``plt.figure``
+or ``plt.subplots`` a constrained layout engine that, before every layout
+pass:
+
+- turns the y-axis title horizontal and moves it above the axis, aligned
+  with the axis line (a right y axis gets a right-aligned title),
+- lifts the title of the axes above that y-axis title,
+- moves a legend whose location was not chosen outside the plot, to the
+  right of it, with a left-aligned title,
+- replaces the default tick locator of linear axes with one that places
+  ticks and rounds the axis limits like Vega (see `ticks`),
+- removes grid lines across categorical axes (string data, or ticks with
+  fixed labels such as those of a boxplot), which Vega does not draw for
+  band scales, and across images.
+
+Figures created with another layout engine (``layout="tight"`` or
+``layout="none"``) are left alone. For figures not created through pyplot,
+call ``install(fig)`` yourself.
+"""
+
+import math
+from typing import Final
+
+import matplotlib as mpl
+from matplotlib.artist import Artist
+from matplotlib.axes import Axes
+from matplotlib.axis import Axis
+from matplotlib.backend_bases import RendererBase
+from matplotlib.category import StrCategoryConverter
+from matplotlib.figure import Figure
+from matplotlib.layout_engine import ConstrainedLayoutEngine
+from matplotlib.text import Text
+from matplotlib.ticker import AutoLocator, FixedFormatter
+from matplotlib.transforms import Bbox, ScaledTranslation
+
+from camminady_matplotlib_theme.ticks import PIXELS_PER_TICK, VegaLocator
+
+Y_TITLE_OFFSET: Final = 15.0
+"""Distance between the top of the plot and the baseline of the y title."""
+
+LEGEND_OFFSET: Final = 18.0
+"""Distance between the plot and a legend outside of it (Vega's default)."""
+
+
+class ThemeLayoutEngine(ConstrainedLayoutEngine):
+    """Constrained layout that first arranges titles, legends and ticks."""
+
+    def execute(self, fig: Figure) -> dict:  # ty: ignore[invalid-method-override]
+        """Arrange all axes of ``fig``, then run the constrained layout."""
+        for ax in fig.axes:
+            arrange(ax)
+        result = super().execute(fig)
+        # The tick count depends on the axis length, which the layout has
+        # just changed; lay out again with the new tick labels if needed.
+        # A list, not a generator: update every axes, do not short-circuit.
+        if any([_update_tick_count(ax) for ax in fig.axes]):  # noqa: C419
+            result = super().execute(fig)
+        return result
+
+
+def install(fig: Figure) -> None:
+    """Use the theme's layout for ``fig`` if it has a constrained layout.
+
+    Parameters
+    ----------
+    fig
+        A figure, typically one just created by ``plt.figure``.
+    """
+    engine = fig.get_layout_engine()
+    if type(engine) is not ConstrainedLayoutEngine:
+        return
+    fig.set_layout_engine(
+        ThemeLayoutEngine(
+            # `compress` is not part of the engine's public parameters.
+            compress=getattr(engine, "_compress", False),
+            **engine.get(),
+        )
+    )
+
+
+def arrange(ax: Axes) -> None:
+    """Place the axis titles, title, legend and ticks of ``ax``.
+
+    Parameters
+    ----------
+    ax
+        Axes to arrange. Only rectilinear axes are changed.
+    """
+    fig = ax.get_figure(root=True)
+    if ax.name != "rectilinear" or fig is None:
+        return
+    twins = _twins(ax)
+    _place_y_title(ax, fig)
+    _place_title(ax, fig, twins)
+    _place_legend(ax, fig, twins)
+    for axis in (ax.xaxis, ax.yaxis):
+        if ax.images or _is_categorical(axis):
+            axis.grid(False)
+        # Colorbars keep their own ticks, like Vega's gradient legends.
+        if ax.get_label() == "<colorbar>":
+            continue
+        if type(axis.get_major_locator()) is AutoLocator:
+            axis.set_major_locator(VegaLocator())
+            # Still the default, so that e.g. categorical data replaces it.
+            axis.isDefault_majloc = True
+            # Round the limits with the new locator; this does nothing if
+            # the limits were set explicitly.
+            ax.autoscale_view(scalex=axis is ax.xaxis, scaley=axis is ax.yaxis)
+    _update_tick_count(ax)
+
+
+def _is_categorical(axis: Axis) -> bool:
+    return isinstance(axis.get_converter(), StrCategoryConverter) or isinstance(
+        axis.get_major_formatter(), FixedFormatter
+    )
+
+
+def _update_tick_count(ax: Axes) -> bool:
+    """Set the tick count from the axis length; return whether it changed."""
+    fig = ax.get_figure(root=True)
+    if ax.name != "rectilinear" or fig is None:
+        return False
+    changed = False
+    position = ax.get_position()
+    width, height = fig.get_size_inches() * 72
+    for axis, length in (
+        (ax.xaxis, position.width * width),
+        (ax.yaxis, position.height * height),
+    ):
+        locator = axis.get_major_locator()
+        if isinstance(locator, VegaLocator):
+            count = math.ceil(length / PIXELS_PER_TICK)
+            changed |= locator.count != count
+            locator.count = count
+    return changed
+
+
+def _twins(ax: Axes) -> list[Axes]:
+    """Axes that share the plot area of ``ax``, including ``ax`` itself."""
+    fig = ax.get_figure(root=False)
+    if fig is None:
+        return [ax]
+    bounds = ax.get_position().bounds
+    return [a for a in fig.axes if a.get_position().bounds == bounds]
+
+
+def _offset(fig: Figure, dx: float = 0, dy: float = 0) -> ScaledTranslation:
+    """Translation by ``dx`` and ``dy`` points."""
+    return ScaledTranslation(dx / 72, dy / 72, fig.dpi_scale_trans)
+
+
+class _TitleExtent(Artist):
+    """Invisible artist that makes the layout reserve room for a y title.
+
+    Constrained layout only counts one pixel of the height of a y-axis
+    title (it expects a rotated title), so a horizontal title above the
+    axis would be cut off at the top of the figure.
+    """
+
+    def __init__(self, axis: Axis) -> None:
+        super().__init__()
+        self._title: Text = axis.label
+        self.set_label("_camminady_y_title_extent")
+
+    def get_window_extent(self, renderer: RendererBase | None = None) -> Bbox:
+        if not (self._title.get_visible() and self._title.get_text()):
+            return Bbox.null()
+        return self._title.get_window_extent(renderer)
+
+    def get_tightbbox(self, renderer: RendererBase | None = None) -> Bbox:
+        return self.get_window_extent(renderer)
+
+    def draw(self, renderer: RendererBase) -> None:
+        pass
+
+
+def _place_y_title(ax: Axes, fig: Figure) -> None:
+    label = ax.yaxis.label
+    # Leave titles alone that the user rotated to some other angle.
+    if label.get_rotation() not in (0, 90):
+        return
+    right = ax.yaxis.get_label_position() == "right"
+    ax.yaxis.set_label_coords(
+        1 if right else 0,
+        1,
+        transform=ax.transAxes + _offset(fig, dy=Y_TITLE_OFFSET),
+    )
+    label.set(
+        rotation=0,
+        horizontalalignment="right" if right else "left",
+        verticalalignment="baseline",
+    )
+    if not any(isinstance(a, _TitleExtent) for a in ax.artists):
+        extent = ax.add_artist(_TitleExtent(ax.yaxis))
+        # `add_artist` clips to the axes, which hides it from the layout.
+        extent.set_clip_on(False)
+    if ax.yaxis.get_ticks_position() == "right":
+        # A secondary y axis (`ax.twinx()`) gets the axis line that the
+        # style hides on the right.
+        ax.spines.right.set_visible(True)
+        ax.spines.left.set_visible(False)
+
+
+def _has_y_title(ax: Axes) -> bool:
+    label = ax.yaxis.label
+    return bool(label.get_visible() and label.get_text())
+
+
+def _place_title(ax: Axes, fig: Figure, twins: list[Axes]) -> None:
+    pad = mpl.rcParams["axes.titlepad"]
+    titled = [a for a in twins if _has_y_title(a)]
+    if titled:
+        size = max(
+            a.yaxis.label.get_fontproperties().get_size_in_points()
+            for a in titled
+        )
+        pad += Y_TITLE_OFFSET + size
+    ax.title.set_transform(ax.transAxes + _offset(fig, dy=pad))
+
+
+def _place_legend(ax: Axes, fig: Figure, twins: list[Axes]) -> None:
+    legend = ax.get_legend()
+    # `_loc_used_default` is True only while the location is the default
+    # one, i.e. neither passed to `legend()` nor set since; the legend is
+    # moved once.
+    if legend is None or not getattr(legend, "_loc_used_default", False):
+        return
+    if legend.get_bbox_to_anchor() is not ax.bbox:
+        return
+    # A secondary y axis would need the legend further right.
+    if any(a.yaxis.get_ticks_position() == "right" for a in twins):
+        return
+    legend.set_loc("upper left")
+    legend.set_bbox_to_anchor(
+        (1, 1), transform=ax.transAxes + _offset(fig, dx=LEGEND_OFFSET)
+    )
+    legend.borderaxespad = 0
+    legend.set_alignment("left")

camminady_matplotlib_theme/theme.py

@@ -0,0 +1,286 @@
+"""Design tokens and matplotlib rcParams of the camminady styles.
+
+The tokens and their defaults are those of the Altair theme in
+``camminady_altair_theme``, so that charts made with either library look
+alike. Sizes are in points; the styles set ``figure.dpi`` to 72, so that one
+point is one pixel on screen, as in Vega.
+"""
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Any, Final, Literal
+
+from cycler import Cycler, cycler
+
+FontWeight = Literal[
+    "normal",
+    "bold",
+    100,
+    200,
+    300,
+    400,
+    500,
+    600,
+    700,
+    800,
+    900,
+]
+
+TABLEAU10: Final[tuple[str, ...]] = (
+    "#4c78a8",
+    "#f58518",
+    "#e45756",
+    "#72b7b2",
+    "#54a24b",
+    "#eeca3b",
+    "#b279a2",
+    "#ff9da6",
+    "#9d755d",
+    "#bab0ac",
+)
+"""Vega's default ``tableau10`` category palette, used as the colour cycle."""
+
+OKABE_ITO: Final[tuple[str, ...]] = (
+    "#0072b2",  # blue
+    "#e69f00",  # orange
+    "#009e73",  # bluish green
+    "#cc79a7",  # reddish purple
+    "#56b4e9",  # sky blue
+    "#d55e00",  # vermillion
+    "#f0e442",  # yellow
+)
+"""Okabe-Ito palette (without black), ordered blue and orange first.
+
+The 3rd (red) and 5th (green) colour of the default cycle are nearly
+indistinguishable with deuteranopia. Use this palette when a chart has more
+than four categories, e.g. ``ax.set_prop_cycle(color=OKABE_ITO)``.
+"""
+
+SANS_SERIF: Final[tuple[str, ...]] = (
+    "Helvetica",
+    "Arial",
+    "Liberation Sans",
+    "DejaVu Sans",
+)
+"""Fonts closest to the ``sans-serif`` font that Vega uses in browsers."""
+
+HOOK: Final = "camminady_matplotlib_theme.layout:install"
+"""Figure hook that places axis titles and legends like the Altair theme."""
+
+# Space around a plot area of `width` x `height` for tick labels and axis
+# titles, so that a chart without a legend gets about that plot area.
+MARGIN_WIDTH: Final = 48
+MARGIN_HEIGHT: Final = 68
+
+
+@dataclass
+class Config:
+    """Design tokens from which a style is built.
+
+    Attributes
+    ----------
+    color_primary
+        Titles, axis titles, legends and text.
+    color_secondary
+        Tick labels, ticks and axis lines.
+    color_background
+        Background of the figure and the axes.
+    color_grid
+        Dashed grid lines.
+    color_rule
+        Lines without a colour of their own, such as ``ax.axhline`` and
+        boxplot whiskers.
+    font_weight
+        Weight of all text.
+    size_small
+        Font size of tick labels, legend labels and text in points.
+    size_medium
+        Font size of axis titles and legend titles in points.
+    size_large
+        Font size of titles in points.
+    height
+        Approximate height of the plot area of a single chart in points.
+    width
+        Approximate width of the plot area of a single chart in points.
+    """
+
+    color_primary: str = "dimgray"
+    # "gray" (#808080) has a contrast of 3.9:1 on white, below the 4.5:1 that
+    # WCAG AA requires for small text such as tick labels; #767676 passes.
+    color_secondary: str = "#767676"
+    color_background: str = "white"
+    color_grid: str = "#dddddd"
+    color_rule: str = "dimgray"
+    font_weight: FontWeight = "normal"
+    size_small: float = 12
+    size_medium: float = 14
+    size_large: float = 20
+    height: float = 400
+    width: float = 800
+
+
+config = Config()
+"""Tokens of the ``"camminady"`` style."""
+
+config_dark = Config(
+    color_primary="#a9a9a9",
+    color_secondary="#8c8c8c",
+    color_background="#1e1e1e",
+    color_grid="#3a3a3a",
+    color_rule="#a9a9a9",
+)
+"""Tokens of the ``"camminady_dark"`` style."""
+
+
+def rc_params(c: Config) -> dict[str, Any]:
+    """Return the matplotlib rcParams of a style built from ``c``.
+
+    Parameters
+    ----------
+    c
+        Colours, font sizes and dimensions of the style.
+
+    Returns
+    -------
+    dict[str, Any]
+        rcParams that can be passed to ``plt.style.use`` or
+        ``plt.style.context``.
+    """
+    ticks = {
+        "color": c.color_secondary,
+        "labelcolor": c.color_secondary,
+        "labelsize": c.size_small,
+        "direction": "out",
+        "major.size": 5,
+        "major.width": 1,
+        "major.pad": 2,
+        "minor.visible": False,
+    }
+    return {
+        # One point is one pixel on screen, as in Vega. Saved files get four pixels per point:
+        # at twice that (144 dpi) PNGs looked blurry once scaled up in documents.
+        "figure.dpi": 72,
+        "savefig.dpi": 288,
+        "figure.figsize": (
+            (c.width + MARGIN_WIDTH) / 72,
+            (c.height + MARGIN_HEIGHT) / 72,
+        ),
+        "figure.facecolor": c.color_background,
+        "figure.edgecolor": c.color_background,
+        "figure.titlesize": c.size_large,
+        "figure.titleweight": c.font_weight,
+        "figure.labelsize": c.size_medium,
+        "figure.labelweight": c.font_weight,
+        "figure.constrained_layout.use": True,
+        "figure.hooks": [HOOK],
+        "font.family": "sans-serif",
+        "font.sans-serif": list(SANS_SERIF),
+        "font.size": c.size_small,
+        "font.weight": c.font_weight,
+        "text.color": c.color_primary,
+        "axes.facecolor": c.color_background,
+        "axes.edgecolor": c.color_secondary,
+        "axes.linewidth": 1,
+        "axes.spines.top": False,
+        "axes.spines.right": False,
+        "axes.grid": True,
+        "axes.grid.axis": "both",
+        "axes.axisbelow": True,
+        "axes.labelcolor": c.color_primary,
+        "axes.labelsize": c.size_medium,
+        "axes.labelweight": c.font_weight,
+        "axes.labelpad": 4,
+        "axes.titlecolor": c.color_primary,
+        "axes.titlesize": c.size_large,
+        "axes.titleweight": c.font_weight,
+        "axes.titlepad": 8,
+        "axes.prop_cycle": _color_cycle(),
+        # Like Vega's "nice" scales: axes end at a tick, without padding.
+        "axes.autolimit_mode": "round_numbers",
+        "axes.xmargin": 0,
+        "axes.ymargin": 0,
+        # The y title is moved above the axis by the figure hook; without
+        # the hook it stays rotated at the top of the axis.
+        "xaxis.labellocation": "right",
+        "yaxis.labellocation": "top",
+        "grid.color": c.color_grid,
+        "grid.linewidth": 1,
+        # Vega draws 2-on-4-off dashes with round caps, which look like
+        # 3-on-3-off dashes with the butt caps matplotlib uses.
+        "grid.linestyle": (0, (3, 3)),
+        "grid.alpha": 1,
+        **{f"xtick.{key}": value for key, value in ticks.items()},
+        **{f"ytick.{key}": value for key, value in ticks.items()},
+        "lines.linewidth": 2,
+        "lines.color": c.color_rule,
+        "lines.solid_capstyle": "round",
+        # The area of a Vega point is 30 square pixels.
+        "lines.markersize": 5.5,
+        "patch.facecolor": TABLEAU10[0],
+        # Separate adjacent bars, such as histogram bins, like Vega's
+        # one-pixel bin spacing.
+        "patch.force_edgecolor": True,
+        "patch.edgecolor": c.color_background,
+        "patch.linewidth": 1,
+        "legend.frameon": False,
+        "legend.fontsize": c.size_small,
+        "legend.title_fontsize": c.size_medium,
+        "legend.labelcolor": c.color_primary,
+        "legend.borderpad": 0,
+        "legend.labelspacing": 0.25,
+        "legend.handlelength": 1.2,
+        "legend.handletextpad": 0.5,
+        "boxplot.patchartist": True,
+        "boxplot.showcaps": False,
+        "boxplot.boxprops.color": TABLEAU10[0],
+        "boxplot.whiskerprops.color": c.color_rule,
+        "boxplot.whiskerprops.linewidth": 1,
+        "boxplot.medianprops.color": "white",
+        "boxplot.medianprops.linewidth": 1,
+        "boxplot.flierprops.marker": "o",
+        "boxplot.flierprops.markerfacecolor": "none",
+        "boxplot.flierprops.markeredgecolor": TABLEAU10[0],
+        "errorbar.capsize": 0,
+    }
+
+
+def _color_cycle() -> Cycler:
+    return cycler(color=list(TABLEAU10))
+
+
+def to_mplstyle(rc: Mapping[str, Any]) -> str:
+    """Format rcParams as the contents of a ``.mplstyle`` file.
+
+    Parameters
+    ----------
+    rc
+        rcParams as returned by `rc_params`.
+
+    Returns
+    -------
+    str
+        One ``key: value`` line per parameter.
+    """
+    return "".join(f"{key}: {_format(value)}\n" for key, value in rc.items())
+
+
+def _format(value: object) -> str:
+    match value:
+        case bool() | int() | float():
+            return str(value)
+        case str() if value.startswith("#"):
+            # "#" starts a comment in style files.
+            return value[1:]
+        case str():
+            return value
+        case Cycler():
+            colors = ", ".join(
+                repr(_format(color)) for color in value.by_key()["color"]
+            )
+            return f"cycler('color', [{colors}])"
+        case (int(), tuple()):
+            return str(value)
+        case tuple() | list():
+            return ", ".join(_format(item) for item in value)
+        case _:
+            raise TypeError(f"cannot write {value!r} to a style file")

camminady_matplotlib_theme/ticks.py

@@ -0,0 +1,127 @@
+"""Tick positions and "nice" axis limits computed like Vega (d3-scale).
+
+Vega asks for about one tick per 40 pixels of axis length and rounds the
+domain of a linear scale outwards to multiples of 1, 2 or 5 times a power of
+ten. matplotlib's default `AutoLocator` allows at most 9 intervals and also
+uses steps of 2.5, so charts get fewer and differently spaced grid lines.
+"""
+
+import math
+from collections.abc import Sequence
+from typing import Final
+
+import matplotlib as mpl
+from matplotlib.ticker import Locator
+
+PIXELS_PER_TICK: Final = 40
+"""Vega's default tick count is ``ceil(length / 40)`` for an axis."""
+
+NICE_COUNT: Final = 10
+"""Vega rounds the domain (``nice: true``) with d3's default count of 10."""
+
+_E10: Final = math.sqrt(50)
+_E5: Final = math.sqrt(10)
+_E2: Final = math.sqrt(2)
+
+
+def _round(x: float) -> int:
+    """JavaScript's ``Math.round``: halves are rounded up, not to even."""
+    return math.floor(x + 0.5)
+
+
+def _tick_spec(
+    start: float, stop: float, count: float
+) -> tuple[int, int, float]:
+    """Port of ``tickSpec`` from d3-array."""
+    step = (stop - start) / max(0, count)
+    power = math.floor(math.log10(step))
+    error = step / 10**power
+    factor = (
+        10 if error >= _E10 else 5 if error >= _E5 else 2 if error >= _E2 else 1
+    )
+    if power < 0:
+        inc = 10 ** (-power) / factor
+        i1, i2 = _round(start * inc), _round(stop * inc)
+        if i1 / inc < start:
+            i1 += 1
+        if i2 / inc > stop:
+            i2 -= 1
+        inc = -inc
+    else:
+        inc = 10**power * factor
+        i1, i2 = _round(start / inc), _round(stop / inc)
+        if i1 * inc < start:
+            i1 += 1
+        if i2 * inc > stop:
+            i2 -= 1
+    if i2 < i1 and 0.5 <= count < 2:
+        return _tick_spec(start, stop, count * 2)
+    return i1, i2, inc
+
+
+def ticks(start: float, stop: float, count: float) -> list[float]:
+    """Port of ``ticks`` from d3-array, for ``start < stop``."""
+    if not (count > 0 and start < stop):
+        return [start] if start == stop else []
+    i1, i2, inc = _tick_spec(start, stop, count)
+    if i2 < i1:
+        return []
+    if inc < 0:
+        return [(i1 + i) / -inc for i in range(i2 - i1 + 1)]
+    return [(i1 + i) * inc for i in range(i2 - i1 + 1)]
+
+
+def nice(
+    start: float, stop: float, count: float = NICE_COUNT
+) -> tuple[float, float]:
+    """Port of ``linear.nice`` from d3-scale, for ``start < stop``."""
+    previous = None
+    for _ in range(10):
+        _, _, step = _tick_spec(start, stop, count)
+        if step == previous:
+            break
+        if step > 0:
+            start, stop = (
+                math.floor(start / step) * step,
+                math.ceil(stop / step) * step,
+            )
+        else:
+            start, stop = (
+                math.ceil(start * step) / step,
+                math.floor(stop * step) / step,
+            )
+        previous = step
+    return start, stop
+
+
+class VegaLocator(Locator):
+    """Locate ticks like Vega does on a linear axis.
+
+    Parameters
+    ----------
+    count
+        Desired number of ticks; the layout sets it from the axis length.
+    """
+
+    def __init__(self, count: float = NICE_COUNT) -> None:
+        self.count = count
+
+    def __call__(self) -> Sequence[float]:
+        """Return the tick locations within the view limits."""
+        if self.axis is None:
+            return []
+        vmin, vmax = self.axis.get_view_interval()
+        return self.tick_values(vmin, vmax)
+
+    def tick_values(self, vmin: float, vmax: float) -> Sequence[float]:
+        """Return the tick locations between ``vmin`` and ``vmax``."""
+        if vmax < vmin:
+            vmin, vmax = vmax, vmin
+        return self.raise_if_exceeds(ticks(vmin, vmax, self.count))
+
+    def view_limits(self, vmin: float, vmax: float) -> tuple[float, float]:
+        """Round the data limits outwards like a Vega scale with ``nice``."""
+        vmin, vmax = self.nonsingular(vmin, vmax)
+        if mpl.rcParams["axes.autolimit_mode"] != "round_numbers":
+            return vmin, vmax
+        return nice(vmin, vmax)

camminady_matplotlib_theme-0.2.0.dist-info/METADATA

@@ -0,0 +1,177 @@
+Metadata-Version: 2.5
+Name: camminady_matplotlib_theme
+Version: 0.2.0
+Summary: A minimal matplotlib style that matches camminady_altair_theme: muted gray text, dashed grid lines and horizontal axis titles.
+Project-URL: Homepage, https://github.com/thomascamminady/camminady_matplotlib_theme
+Project-URL: Documentation, https://camminady.dev/camminady_matplotlib_theme/
+Project-URL: Repository, https://github.com/thomascamminady/camminady_matplotlib_theme
+Project-URL: Issues, https://github.com/thomascamminady/camminady_matplotlib_theme/issues
+Author-email: Thomas Camminady <0milieux_member@icloud.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: charts,matplotlib,style,theme,visualization
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: Matplotlib
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: matplotlib>=3.10
+Description-Content-Type: text/markdown
+
+# camminady_matplotlib_theme
+
+A minimal [matplotlib](https://matplotlib.org) style that matches
+[camminady_altair_theme](https://github.com/thomascamminady/camminady_altair_theme):
+muted gray text, dashed grid lines, no frame around the plot, and horizontal
+axis titles at the end of each axis. It comes in a light (`camminady`) and a
+dark (`camminady_dark`) variant.
+
+![Light style](https://raw.githubusercontent.com/thomascamminady/camminady_matplotlib_theme/main/assets/camminady.png)
+
+<!-- docs-start -->
+
+## Installation
+
+```bash
+uv add camminady-matplotlib-theme
+# or
+pip install camminady-matplotlib-theme
+```
+
+Requires Python 3.11+ and matplotlib 3.10+.
+
+## Usage
+
+```python
+import matplotlib.pyplot as plt
+
+plt.style.use("camminady_matplotlib_theme.camminady")  # or ".camminady_dark"
+```
+
+There is no need to import the package. After
+`import camminady_matplotlib_theme`, the short names `"camminady"` and
+`"camminady_dark"` work as well; importing does not apply a style.
+
+To use the style for some figures only:
+
+```python
+with plt.style.context("camminady_matplotlib_theme.camminady"):
+    fig, ax = plt.subplots()
+    ...
+    fig.savefig("chart.png")
+```
+
+## Example
+
+A complete script that draws a line chart of stock prices. The data comes
+from [vega_datasets](https://github.com/altair-viz/vega_datasets)
+(`uv add vega_datasets`), which ships it, so the script runs offline.
+
+```python
+import matplotlib.pyplot as plt
+from vega_datasets import data
+
+plt.style.use("camminady_matplotlib_theme.camminady")
+
+stocks = data.stocks()
+fig, ax = plt.subplots()
+for symbol, group in stocks.groupby("symbol"):
+    ax.plot(group["date"], group["price"], label=symbol)
+ax.set(title="Stock prices", xlabel="date", ylabel="Price (USD)")
+ax.legend(title="symbol")
+fig.savefig("stock_prices.png")
+```
+
+![Light style](https://raw.githubusercontent.com/thomascamminady/camminady_matplotlib_theme/main/assets/camminady.png)
+
+With `"camminady_matplotlib_theme.camminady_dark"`:
+
+![Dark style](https://raw.githubusercontent.com/thomascamminady/camminady_matplotlib_theme/main/assets/camminady_dark.png)
+
+The same chart made with Altair and the Altair theme (top) and with this
+style (bottom):
+
+![Altair and matplotlib](https://raw.githubusercontent.com/thomascamminady/camminady_matplotlib_theme/main/assets/comparison.png)
+
+## Matching the Altair theme
+
+The style uses the design tokens of the Altair theme (colours, font sizes and
+the 800 × 400 plot area) and Vega's default colour palette. It sets
+`figure.dpi` to 72 so that one point is one pixel on screen, as in Vega;
+`savefig` writes at 288 dpi (four pixels per point), so saved PNGs stay sharp
+when scaled up. Pass `dpi=` to `savefig` to override it.
+
+Some of the look cannot be expressed in a style file. The style therefore
+registers a figure hook that gives each figure created through pyplot a
+constrained layout which, before drawing:
+
+- turns the y-axis title horizontal and places it above the axis, aligned
+  with the axis line (titles of `ax.twinx()` go to the right end),
+- moves the axes title above that y-axis title,
+- places a legend outside the plot on the right, unless you pass a location
+  (`ax.legend(loc="lower right")` stays where you put it),
+- places ticks and rounds axis limits like Vega: about one tick per 40
+  points, at multiples of 1, 2 or 5 times a power of ten,
+- removes grid lines across categorical axes and images.
+
+The hook leaves figures alone that use another layout
+(`plt.subplots(layout="tight")`). For a figure created without pyplot, call
+`camminady_matplotlib_theme.install(fig)`.
+
+Two differences remain: Vega-Lite includes zero in quantitative axes and
+draws points as hollow circles; matplotlib does neither by default.
+
+## Customising
+
+All colours, font sizes and the plot size are fields of `Config`, with the
+same names and defaults as in the Altair theme:
+
+```python
+import matplotlib.pyplot as plt
+from camminady_matplotlib_theme import Config, rc_params
+
+plt.style.use(rc_params(Config(width=400, height=250)))
+```
+
+`to_mplstyle(rc_params(...))` returns the contents of a `.mplstyle` file.
+
+## Colour-blind safety
+
+The default palette is Vega's `tableau10`. Its third (red) and fifth (green)
+colours are nearly indistinguishable for people with deuteranopia, so for five
+or more categories use the bundled Okabe-Ito palette:
+
+```python
+from camminady_matplotlib_theme import OKABE_ITO
+
+ax.set_prop_cycle(color=OKABE_ITO)
+```
+
+## Development
+
+```bash
+uv sync
+uv run pytest
+uv run ruff check . && uv run ruff format --check .
+uv run ty check
+uv run python create_charts.py  # regenerate the images above
+```
+
+The `.mplstyle` files are generated from `Config`; after changing a token,
+rewrite them with:
+
+```bash
+uv run python -c "
+from importlib.resources import files
+from camminady_matplotlib_theme import theme
+for name, c in {'camminady': theme.config, 'camminady_dark': theme.config_dark}.items():
+    (files('camminady_matplotlib_theme') / f'{name}.mplstyle').write_text(
+        theme.to_mplstyle(theme.rc_params(c)))
+"
+```

camminady_matplotlib_theme-0.2.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+camminady_matplotlib_theme/__init__.py,sha256=6y6Uqwth4PLpHgTw2ubYFFDNe_BxSRfRtl_c1EYht5c,1178
+camminady_matplotlib_theme/camminady.mplstyle,sha256=fjr74UorYSUb40c0zG22H5uB7-vbPy4Fs72dsw7L3T0,2196
+camminady_matplotlib_theme/camminady_dark.mplstyle,sha256=R5PuzxnF2-_0W5kn9XLBXJ975GCRIxnQgaj-ZFdn1rs,2194
+camminady_matplotlib_theme/layout.py,sha256=dXXJ8xu7m0RKZnNNHzZoEgjRnhPM80_J2oYQ6rGxfnk,8973
+camminady_matplotlib_theme/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+camminady_matplotlib_theme/theme.py,sha256=vicp79WPYi0l3UQtRBBy5Uy8Kf6_rtGkX2fzt2WI4sk,8964
+camminady_matplotlib_theme/ticks.py,sha256=31zul5zOSXa0wJrq1okkJpMMQtmmCe6BfFCgPMlhHr8,4082
+camminady_matplotlib_theme-0.2.0.dist-info/METADATA,sha256=IFuX89sK75j4mNaGOoYOTAv9jKqHVTYEazrjc30hC8U,6310
+camminady_matplotlib_theme-0.2.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+camminady_matplotlib_theme-0.2.0.dist-info/licenses/LICENSE,sha256=CpyBxdriK2olyq3pzrDG86x-8BgMm6kHEnLsjhrnq9I,1074
+camminady_matplotlib_theme-0.2.0.dist-info/RECORD,,

camminady_matplotlib_theme-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

camminady_matplotlib_theme-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026, Thomas Camminady
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.