hedgehogs 0.0.1__py3-none-any.whl

hedgehogs/__init__.py

@@ -0,0 +1,66 @@
+"""Hedgehogs — publication-quality scientific visualisation and reporting utilities."""
+
+from .core.version import __version__, __date__
+from .core.constants import EPS
+from .core.palette import (
+    Palette,
+    get_palette,
+    build_color_map,
+    build_style_map,
+    register_palette,
+    save_palette,
+    load_palette,
+)
+from .plots.style import (
+    set_style,
+    reset_style,
+    journal_preset,
+    set_journal_style,
+    figsize,
+    subplots,
+)
+from .plots.helpers import (
+    finalize,
+    style_colorbar,
+    annotate_panels,
+    enable_minor_ticks,
+    apply_grid,
+)
+from . import plots
+from .tables import Table
+from .terminal import Progress
+from .terminal import echo, rule
+from .core.info import info
+
+__all__ = [
+    "EPS",
+    "Palette",
+    "get_palette",
+    "build_color_map",
+    "build_style_map",
+    "register_palette",
+    "save_palette",
+    "load_palette",
+    "set_style",
+    "reset_style",
+    "journal_preset",
+    "set_journal_style",
+    "figsize",
+    "subplots",
+    "finalize",
+    "style_colorbar",
+    "annotate_panels",
+    "enable_minor_ticks",
+    "apply_grid",
+    "plots",
+    "Table",
+    "Progress",
+    "echo",
+    "rule",
+    "info",
+]
+
+
+def __dir__() -> list[str]:
+    """List the supported public interface and package metadata."""
+    return sorted([*__all__, "__version__", "__date__"])

hedgehogs/core/__init__.py

@@ -0,0 +1 @@
+"""Shared metadata, palette and environment support."""

hedgehogs/core/constants.py

@@ -0,0 +1,6 @@
+"""Public numerical constants."""
+
+import sys
+
+
+EPS = sys.float_info.epsilon

hedgehogs/core/environment.py

@@ -0,0 +1,8 @@
+"""Runtime environment helpers."""
+
+import sys
+
+
+def _is_jupyter():
+    """Detect whether code is running inside a Jupyter / IPython kernel."""
+    return "ipykernel" in sys.modules

hedgehogs/core/info.py

@@ -0,0 +1,15 @@
+"""Package information utilities."""
+
+import matplotlib.pyplot as plt
+
+from .version import __version__, __date__
+
+
+def info():
+    """Print version and dependency info."""
+    text = (
+        f"Hedgehogs  v{__version__}  ({__date__})\n"
+        f"  matplotlib  {plt.matplotlib.__version__}"
+    )
+    print(text)
+    return text

hedgehogs/core/palette.py

@@ -0,0 +1,263 @@
+"""Colour palettes and colour mapping utilities."""
+
+import json
+from collections.abc import Iterable, Mapping
+from os import PathLike
+from pathlib import Path
+from numbers import Integral
+from typing import Any
+import warnings
+
+from matplotlib.colors import is_color_like
+
+
+_PALETTES = {
+    "tableau10": {
+        "colors": [
+            "#4e79a7", "#f28e2b", "#e15759", "#76b7b2", "#59a14f",
+            "#edc948", "#b07aa1", "#ff9da7", "#9c755f", "#bab0ac",
+        ],
+        "names": [
+            "blue", "orange", "red", "teal", "green",
+            "yellow", "purple", "pink", "brown", "grey",
+        ],
+    },
+    "okabe-ito": {
+        "colors": [
+            "#0072B2", "#E69F00", "#D55E00", "#009E73",
+            "#56B4E9", "#F0E442", "#CC79A7", "#000000",
+        ],
+        "names": [
+            "blue", "orange", "red", "green",
+            "cyan", "yellow", "purple", "black",
+        ],
+    },
+    "paul-tol-vibrant": {
+        "colors": [
+            "#0077BB", "#33BBEE", "#009988", "#EE7733",
+            "#CC3311", "#EE3377", "#BBBBBB",
+        ],
+        "names": [
+            "blue", "cyan", "teal", "orange",
+            "red", "magenta", "grey",
+        ],
+    },
+    "paul-tol-bright": {
+        "colors": [
+            "#4477AA", "#EE6677", "#228833", "#CCBB44",
+            "#66CCEE", "#AA3377", "#BBBBBB",
+        ],
+        "names": [
+            "blue", "red", "green", "yellow",
+            "cyan", "purple", "grey",
+        ],
+    },
+    "paul-tol-muted": {
+        "colors": [
+            "#332288", "#88CCEE", "#44AA99", "#117733",
+            "#999933", "#DDCC77", "#CC6677", "#882255", "#AA4499",
+        ],
+        "names": [
+            "indigo", "cyan", "teal", "green",
+            "olive", "sand", "rose", "wine", "purple",
+        ],
+    },
+    "ibm": {
+        "colors": ["#648FFF", "#785EF0", "#DC267F", "#FE6100", "#FFB000"],
+        "names": ["blue", "indigo", "magenta", "orange", "gold"],
+    },
+}
+
+
+class Palette:
+    """Colour palette with both name-based and index-based access."""
+
+    def __init__(self, names: Iterable[str], colors: Iterable[str]) -> None:
+        self._names = list(names)
+        self._colors = list(colors)
+        self._map = dict(zip(self._names, self._colors))
+
+    def __repr__(self) -> str:
+        pairs = ", ".join(f"{n}={c}" for n, c in zip(self._names, self._colors))
+        return f"Palette({pairs})"
+
+    def __getitem__(self, key: int | slice | str):
+        if isinstance(key, Integral) and not isinstance(key, bool):
+            index = int(key)
+            return self._colors[index % len(self._colors)]
+        if isinstance(key, slice):
+            return self._colors[key]
+        if isinstance(key, str):
+            return self._map[key.lower()]
+        raise KeyError(key)
+
+    def __contains__(self, key: object) -> bool:
+        if isinstance(key, str):
+            return key.lower() in self._map
+        if isinstance(key, Integral) and not isinstance(key, bool):
+            index = int(key)
+            return -len(self._colors) <= index < len(self._colors)
+        return False
+
+    def __iter__(self):
+        return iter(self._colors)
+
+    def __len__(self) -> int:
+        return len(self._colors)
+
+    def keys(self):
+        return self._map.keys()
+
+    def values(self):
+        return self._map.values()
+
+    def items(self):
+        return self._map.items()
+
+
+def _resolve_palette(name: object) -> str:
+    p = str(name).lower()
+    if p in _PALETTES:                  return p
+    if "vibrant" in p:                return "paul-tol-vibrant"
+    if "bright" in p:                 return "paul-tol-bright"
+    if "muted" in p:                  return "paul-tol-muted"
+    if "tol" in p or "paul" in p:     return "paul-tol-vibrant"
+    if "tab" in p or "tableau" in p:  return "tableau10"
+    if "ibm" in p:                    return "ibm"
+    if "okabe" in p or "ito" in p:    return "okabe-ito"
+    warnings.warn(
+        f"Unrecognised palette name {name!r}; falling back to 'okabe-ito'. "
+        f"Known palettes: {sorted(_PALETTES)}",
+        UserWarning,
+        stacklevel=3,
+    )
+    return "okabe-ito"
+
+
+def get_palette(palette: str | Palette = "okabe-ito", n: int | None = None) -> Palette:
+    """Return a Palette object. Supports fuzzy name matching."""
+    if isinstance(palette, Palette):
+        if n is None:
+            return palette
+        source = palette
+        if not isinstance(n, int) or isinstance(n, bool) or n < 1:
+            raise ValueError("n must be a positive integer or None.")
+        return Palette(list(source.keys())[:n], list(source.values())[:n])
+
+    if n is not None and (
+        not isinstance(n, int)
+        or isinstance(n, bool)
+        or n < 1
+    ):
+        raise ValueError("n must be a positive integer or None.")
+
+    key = _resolve_palette(palette)
+    entry = _PALETTES[key]
+    limit = len(entry["colors"]) if n is None else min(n, len(entry["colors"]))
+    return Palette(entry["names"][:limit], entry["colors"][:limit])
+
+
+def build_color_map(
+    labels: Iterable[Any],
+    palette: str | Palette = "okabe-ito",
+) -> dict[Any, str]:
+    """Map unique labels to palette colours."""
+    pal = get_palette(palette=palette)
+    unique_labels = dict.fromkeys(labels)
+    return {
+        label: pal[index]
+        for index, label in enumerate(unique_labels)
+    }
+
+
+def build_style_map(
+    labels: Iterable[Any],
+    palette: str | Palette = "okabe-ito",
+) -> dict[Any, dict[str, str]]:
+    """Map labels to distinct colour, line-style, and marker combinations."""
+    colours = get_palette(palette=palette)
+    line_styles = ("-", "--", "-.", ":")
+    markers = ("o", "s", "^", "D", "v", "P", "X")
+    return {
+        label: {
+            "color": colours[index],
+            "linestyle": line_styles[index % len(line_styles)],
+            "marker": markers[index % len(markers)],
+        }
+        for index, label in enumerate(dict.fromkeys(labels))
+    }
+
+
+def register_palette(
+    name: str,
+    colors: Mapping[str, str] | Iterable[str],
+    names: Iterable[str] | None = None,
+    *,
+    overwrite: bool = False,
+) -> Palette:
+    """Register a custom palette for use by :func:`get_palette`."""
+    key = str(name).strip().lower()
+    if not key:
+        raise ValueError("Palette name must not be empty.")
+    if key in _PALETTES and not overwrite:
+        raise ValueError(f"Palette {key!r} is already registered.")
+
+    if isinstance(colors, Mapping):
+        if names is not None:
+            raise ValueError("names must be omitted when colors is a mapping.")
+        palette_names = [str(value) for value in colors]
+        palette_colors = list(colors.values())
+    else:
+        palette_colors = list(colors)
+        palette_names = (
+            [f"color-{index + 1}" for index in range(len(palette_colors))]
+            if names is None
+            else [str(value) for value in names]
+        )
+
+    if not palette_colors:
+        raise ValueError("A palette must contain at least one colour.")
+    if len(palette_names) != len(palette_colors):
+        raise ValueError("Palette names and colors must have the same length.")
+    if len(set(palette_names)) != len(palette_names):
+        raise ValueError("Palette colour names must be unique.")
+
+    invalid = [value for value in palette_colors if not is_color_like(value)]
+    if invalid:
+        raise ValueError(f"Invalid Matplotlib colour values: {invalid!r}.")
+
+    _PALETTES[key] = {
+        "names": palette_names,
+        "colors": [str(value) for value in palette_colors],
+    }
+    return get_palette(key)
+
+
+def save_palette(name: str, path: str | PathLike[str]) -> Path:
+    """Save a registered palette as portable JSON."""
+    key = _resolve_palette(name)
+    destination = Path(path).expanduser()
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    destination.write_text(
+        json.dumps({"name": key, **_PALETTES[key]}, indent=2) + "\n",
+        encoding="utf-8",
+    )
+    return destination
+
+
+def load_palette(
+    path: str | PathLike[str],
+    *,
+    name: str | None = None,
+    overwrite: bool = False,
+) -> Palette:
+    """Load and register a palette saved by :func:`save_palette`."""
+    source = Path(path).expanduser()
+    payload = json.loads(source.read_text(encoding="utf-8"))
+    palette_name = name or payload.get("name") or source.stem
+    return register_palette(
+        palette_name,
+        payload["colors"],
+        names=payload.get("names"),
+        overwrite=overwrite,
+    )

hedgehogs/core/version.py

@@ -0,0 +1,4 @@
+"""Hedgehogs version metadata."""
+
+__version__ = "0.0.1"
+__date__ = "08 Oct 2026"

hedgehogs/plots/__init__.py

@@ -0,0 +1,13 @@
+"""Specialised Matplotlib plots with Hedgehogs presentation defaults."""
+
+from .tree import tree
+from .pairplot import pairplot
+from .presentation import show
+from .output import save
+
+__all__ = ["tree", "pairplot", "show", "save"]
+
+
+def __dir__() -> list[str]:
+    """List the public plotting functions rather than implementation modules."""
+    return sorted(__all__)

hedgehogs/plots/helpers.py

@@ -0,0 +1,129 @@
+"""Matplotlib plotting helpers."""
+
+import math
+import matplotlib.pyplot as plt
+import matplotlib.ticker as mticker
+
+
+class _SkipZeroFormatter(mticker.ScalarFormatter):
+    def __call__(self, x, pos=None):
+        return "" if math.isclose(x, 0.0, rel_tol=1e-5, abs_tol=1e-8) else super().__call__(x, pos)
+
+
+def _to_axes_list(ax):
+    if ax is None:
+        return [plt.gca()]
+    if hasattr(ax, "ravel") and callable(ax.ravel):
+        return ax.ravel().tolist()
+    if hasattr(ax, "__iter__") and not hasattr(ax, "plot"):
+        return list(ax)
+    return [ax]
+
+
+def _fix_origin_overlap(ax=None, keep="x"):
+    if ax is None:
+        ax = plt.gca()
+    xlim, ylim = ax.get_xlim(), ax.get_ylim()
+    if not (xlim[0] <= 0 <= xlim[1] and ylim[0] <= 0 <= ylim[1]):
+        return
+    target = ax.yaxis if keep == "x" else ax.xaxis
+    current = target.get_major_formatter()
+    if isinstance(current, (mticker.ScalarFormatter, _SkipZeroFormatter)):
+        fmt = _SkipZeroFormatter()
+        try:
+            fmt.set_useOffset(current.get_useOffset())
+            fmt.set_useMathText(current.get_useMathText())
+        except AttributeError:
+            pass
+        target.set_major_formatter(fmt)
+
+
+def _apply_grid(ax=None, axis="both"):
+    if ax is None:
+        ax = plt.gca()
+    ax.grid(True, which="major", axis=axis,
+            linestyle=":", color="black", alpha=0.7)
+    ax.set_axisbelow(True)
+
+
+def _fix_legend_frame(ax=None):
+    if ax is None:
+        ax = plt.gca()
+    leg = ax.get_legend()
+    if leg is not None:
+        frame = leg.get_frame()
+        frame.set_linewidth(ax.spines["left"].get_linewidth())
+        frame.set_edgecolor(plt.rcParams.get("legend.edgecolor", "black"))
+
+
+def _enable_minor_ticks(ax=None, x=True, y=True):
+    if ax is None:
+        ax = plt.gca()
+    if x:
+        ax.xaxis.set_minor_locator(mticker.AutoMinorLocator())
+    if y:
+        ax.yaxis.set_minor_locator(mticker.AutoMinorLocator())
+    major_tick = ax.xaxis.get_major_ticks()[0].tick1line
+    lw = major_tick.get_markeredgewidth() * 0.6
+    sz = major_tick.get_markersize() * 0.5
+    ax.tick_params(which="minor", direction="out",
+                   length=sz, width=lw, top=True, right=True)
+
+
+def _style_colorbar(cb, label=None):
+    lw = cb.ax.spines["left"].get_linewidth()
+    cb.outline.set_linewidth(lw)
+    cb.outline.set_edgecolor("black")
+    cb.ax.tick_params(
+        direction="out",
+        width=cb.ax.yaxis.get_major_ticks()[0].tick1line.get_markeredgewidth(),
+        length=cb.ax.yaxis.get_major_ticks()[0].tick1line.get_markersize() * 0.7,
+    )
+    if label is not None:
+        cb.set_label(label)
+
+
+def _annotate_panels(axes, labels=None, loc="upper left",
+                     offset=None, fontsize=None, fontweight="bold"):
+    axes = _to_axes_list(axes)
+    if labels is None:
+        labels = [f"({chr(97 + i)})" for i in range(len(axes))]
+    if fontsize is None:
+        fontsize = plt.rcParams["font.size"]
+    if offset is not None:
+        ox, oy = offset
+    elif "right" in loc:
+        ox, oy = 0.94, 0.93
+    else:
+        ox, oy = 0.06, 0.93
+    ha = "right" if "right" in loc else "left"
+    for a, lbl in zip(axes, labels):
+        a.text(ox, oy, lbl, transform=a.transAxes,
+               fontsize=fontsize, fontweight=fontweight, va="top", ha=ha)
+
+
+def _finalize(ax=None, fix_origin=True, keep="x",
+              grid=False, minor_ticks=False):
+    for a in _to_axes_list(ax):
+        if fix_origin:
+            _fix_origin_overlap(a, keep=keep)
+        _fix_legend_frame(a)
+        if grid:
+            _apply_grid(a)
+        if minor_ticks:
+            _enable_minor_ticks(a)
+
+
+finalize           = _finalize
+
+
+style_colorbar     = _style_colorbar
+
+
+annotate_panels    = _annotate_panels
+
+
+enable_minor_ticks = _enable_minor_ticks
+
+
+apply_grid         = _apply_grid

hedgehogs/plots/output.py

@@ -0,0 +1,75 @@
+"""Finish and save Matplotlib figures."""
+
+from collections.abc import Iterable, Mapping
+from os import PathLike
+from pathlib import Path
+from typing import Any
+
+import matplotlib.pyplot as plt
+from matplotlib.figure import Figure
+
+
+def save(
+    filename: str | PathLike[str],
+    *,
+    fig: Figure | None = None,
+    formats: Iterable[str] | None = None,
+    dpi: float = 300,
+    transparent: bool = False,
+    bbox_inches: str | None = "tight",
+    metadata: Mapping[str, Any] | None = None,
+    close: bool = False,
+    **savefig_kw: Any,
+) -> tuple[Path, ...]:
+    """Finish and save the current pyplot figure or an explicit ``fig``.
+
+    A filename extension selects one format. Without an extension, ``formats``
+    selects outputs and defaults to PDF and PNG. Return a tuple of written Paths.
+    An extension combined with formats raises ValueError; an absent current
+    figure also raises ValueError without creating an empty figure.
+
+    Examples: ``save("figure.pdf")`` or ``save("figure", fig=fig,
+    formats=("pdf", "png"))``. Explicit Matplotlib save options remain available.
+    """
+    base = Path(filename).expanduser()
+    requested: tuple[str, ...]
+    destinations: tuple[Path, ...]
+    if "format" in savefig_kw:
+        raise ValueError("Select the format with the filename extension or formats, not format.")
+    if base.suffix:
+        if formats is not None:
+            raise ValueError("A filename extension and formats cannot be supplied together.")
+        requested = (base.suffix[1:].lower(),)
+        destinations = (base,)
+    else:
+        selected = ("pdf", "png") if formats is None else formats
+        if isinstance(selected, str):
+            selected = (selected,)
+        requested = tuple(str(value).lower().lstrip(".") for value in selected)
+        if not requested or any(not value for value in requested):
+            raise ValueError("formats must contain at least one file format.")
+        destinations = tuple(base.with_suffix(f".{suffix}") for suffix in requested)
+    if fig is None:
+        if not plt.get_fignums():
+            raise ValueError("No current figure to save; create one or supply fig.")
+        fig = plt.gcf()
+    from .presentation import prepare
+    prepare(fig)
+    base.parent.mkdir(parents=True, exist_ok=True)
+
+    options = {
+        "dpi": dpi,
+        "transparent": transparent,
+        "bbox_inches": bbox_inches,
+        "metadata": metadata,
+        **savefig_kw,
+    }
+
+    with plt.rc_context({"pdf.fonttype": 42, "ps.fonttype": 42, "savefig.bbox": None}):
+        for destination, file_format in zip(destinations, requested):
+            fig.savefig(destination, format=file_format, **options)
+
+    if close:
+        plt.close(fig)
+
+    return destinations