hedgehogs 0.0.1__tar.gz

hedgehogs-0.0.1/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+## 0.0.1 — 8 October 2026
+
+Initial Hedgehogs development release, adapted from Onsaemiro. Includes figure styling and finishing, native tree and pair plots, notebook and terminal tables, palettes and progress reporting.
+
+`plots.save()` accepts a complete filename such as `figure.pdf`, or an extensionless path with `formats` for multiple outputs. Conflicting format selections raise `ValueError`.
+
+Figure finishing refines default typography and numeric tick density while preserving explicit font options, custom ticks and plotted values.
+
+Progress iteration uses `Progress(iterable, ...)`; delays use the standard `time.sleep()`. API references are grouped under `docs/api`.
+
+Figure saving uses `plots.save(filename, fig=None, ...)`; the former top-level `export_figure()` is removed. `Table.to_dataframe()` exports formatted rows to an optional pandas or Polars backend.
+
+Default outlines use bounded panel-area scaling independently of typography, retaining their weight across aspect ratios and preserving small marker faces.
+
+Default data lines follow the same stroke scaling. Automatic legend placement searches inside the axes; explicit positions and external anchors are retained.

hedgehogs-0.0.1/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 PentagonToy
+Copyright (c) 2026 Hanseul Kang
+
+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.

hedgehogs-0.0.1/MANIFEST.in

@@ -0,0 +1,6 @@
+include CHANGELOG.md
+recursive-include docs *.md *.svg
+recursive-include others *.svg
+recursive-include tutorials *.ipynb
+recursive-include tools *.py
+recursive-include tests *.py *.md

hedgehogs-0.0.1/PKG-INFO

@@ -0,0 +1,133 @@
+Metadata-Version: 2.4
+Name: hedgehogs
+Version: 0.0.1
+Summary: Scientific presentation utilities for figures, notebooks, and terminals
+Author-email: Hanseul Kang <hanseul.kang@aalto.fi>
+License-Expression: MIT
+Project-URL: Repository, https://github.com/PentagonToy/Hedgehogs
+Project-URL: Issues, https://github.com/PentagonToy/Hedgehogs/issues
+Project-URL: Documentation, https://github.com/PentagonToy/Hedgehogs/blob/main/docs/README.md
+Project-URL: Changelog, https://github.com/PentagonToy/Hedgehogs/blob/main/CHANGELOG.md
+Keywords: matplotlib,scientific-visualisation,publication,plotting,jupyter
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: matplotlib>=3.6
+Requires-Dist: ipython>=8
+Requires-Dist: rich>=13.7
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == "dev"
+Requires-Dist: pytest>=8; extra == "dev"
+Dynamic: license-file
+
+# Hedgehogs
+
+<p align="center">
+  <a href="https://github.com/PentagonToy/Hedgehogs/blob/main/others/assets/icon.svg">
+    <img src="https://raw.githubusercontent.com/PentagonToy/Hedgehogs/main/others/assets/icon.svg?revision=b28effc0f83b" alt="Hedgehogs logo and wordmark, with orange and blue accents" width="270">
+  </a>
+</p>
+
+**Scientific figures and reports for Python.**
+
+Hedgehogs prepares Matplotlib figures and presents tables, progress and status messages in notebooks and terminals.
+
+- Journal-oriented figure presets for single- and double-column layouts.
+- Colour-blind-friendly palettes, including Okabe–Ito and Paul Tol schemes.
+- Consistent figure dimensions across local and remote notebook display and export.
+- Clear tables, status messages and progress bars in notebooks, terminals and redirected logs.
+
+## Installation
+
+Requires **Python 3.10+**. Install from a source checkout:
+
+```bash
+git clone https://github.com/PentagonToy/Hedgehogs.git
+cd Hedgehogs
+python -m pip install -e .
+```
+
+## Usage Example
+
+### Figures
+
+Choose the journal dimensions first, then draw with Matplotlib. The style supplies typography, line widths, marker sizes and outlines; finishing measures the complete figure and adjusts supported legend and bar-label placement.
+
+```python
+import numpy as np
+import matplotlib.pyplot as plt
+import hedgehogs as hdg
+
+fig_x, fig_y = hdg.figsize(name="science", column="single")
+palette = hdg.get_palette("okabe-ito")
+hdg.set_style(figure_size=(fig_x, fig_y), palette="okabe-ito")
+
+x = np.linspace(0, 1, 25)
+y = 2 * x + 0.1 * np.sin(20 * x)
+fitted = np.polyval(np.polyfit(x, y, 1), x)
+
+fig, ax = plt.subplots(figsize=(fig_x, fig_y))
+ax.scatter(x, y, color=palette["blue"], label="Data")
+ax.plot(x, fitted, color=palette["black"], label="Linear fit")
+ax.set(xlabel="x", ylabel="y")
+ax.legend()
+
+hdg.plots.save("linear_fit.pdf", bbox_inches=None)
+hdg.plots.show()
+```
+
+`figsize()` returns width and height in inches for `science`, `nature`, `ieee` or `aps`, with `single` or `double` columns. Presets provide starting dimensions; check the target journal's author instructions. Use an extensionless path with `formats=("pdf", "png")` for multiple outputs. Matplotlib arguments and artist properties remain editable.
+
+[Tree diagrams and pairplots](https://github.com/PentagonToy/Hedgehogs/blob/main/docs/api/plots.md) also return editable Matplotlib objects. Keep text readable at the final document width; select fewer variables or split crowded figures before reducing font size.
+
+### Tables
+
+Display the same table in a notebook or terminal, then export its formatted values to CSV and LaTeX.
+
+```python
+table = hdg.Table("Model comparison", columns=["Case", "RMSE"], formatters={"RMSE": ".3f"})
+table.add_row("baseline", 0.0412)
+table.add_row("model", 0.0184)
+table.show()
+table.to_csv("errors.csv")
+table.to_latex("errors.tex", caption="Model errors", label="tab:errors")
+```
+
+`Table.from_dataframe()` accepts existing **pandas** and **Polars** DataFrames. The LaTeX output requires `booktabs`. Tables or accompanying data provide precise values; figures communicate patterns and comparisons.
+
+### Progress
+
+Wrap an iterable with `Progress` to report progress in notebooks, terminals and redirected logs.
+
+```python
+import time
+
+for step in hdg.Progress(range(20), desc="Processing"):
+    time.sleep(0.05)
+```
+
+For manually advanced work, `Progress` supports `update()`, metric reporting through `set()` and a context manager. See the [progress reference](https://github.com/PentagonToy/Hedgehogs/blob/main/docs/api/terminal.md#progress).
+
+### Terminal output
+
+```python
+hdg.echo("Reading data", tone="info")
+hdg.echo("Run completed", tone="success")
+hdg.rule("Summary")
+```
+
+Terminal output includes colour where supported. Redirected output remains plain; `NO_COLOR` and `TERM=dumb` disable colour.
+
+## Documentation and tutorials
+
+Use the [documentation roadmap](https://github.com/PentagonToy/Hedgehogs/blob/main/docs/README.md) for guides, API references and developer documentation. Runnable tutorials cover [plots](https://github.com/PentagonToy/Hedgehogs/blob/main/tutorials/plots.ipynb), [tables](https://github.com/PentagonToy/Hedgehogs/blob/main/tutorials/tables.ipynb), and [CLI output](https://github.com/PentagonToy/Hedgehogs/blob/main/tutorials/cli.ipynb).
+
+Existing Onsaemiro code can replace its import with `import hedgehogs as hdg`. Wrap iterable work with `hdg.Progress(iterable, ...)` and use the standard `time.sleep()` for delays.

hedgehogs-0.0.1/README.md

@@ -0,0 +1,103 @@
+# Hedgehogs
+
+<p align="center">
+  <a href="https://github.com/PentagonToy/Hedgehogs/blob/main/others/assets/icon.svg">
+    <img src="https://raw.githubusercontent.com/PentagonToy/Hedgehogs/main/others/assets/icon.svg?revision=b28effc0f83b" alt="Hedgehogs logo and wordmark, with orange and blue accents" width="270">
+  </a>
+</p>
+
+**Scientific figures and reports for Python.**
+
+Hedgehogs prepares Matplotlib figures and presents tables, progress and status messages in notebooks and terminals.
+
+- Journal-oriented figure presets for single- and double-column layouts.
+- Colour-blind-friendly palettes, including Okabe–Ito and Paul Tol schemes.
+- Consistent figure dimensions across local and remote notebook display and export.
+- Clear tables, status messages and progress bars in notebooks, terminals and redirected logs.
+
+## Installation
+
+Requires **Python 3.10+**. Install from a source checkout:
+
+```bash
+git clone https://github.com/PentagonToy/Hedgehogs.git
+cd Hedgehogs
+python -m pip install -e .
+```
+
+## Usage Example
+
+### Figures
+
+Choose the journal dimensions first, then draw with Matplotlib. The style supplies typography, line widths, marker sizes and outlines; finishing measures the complete figure and adjusts supported legend and bar-label placement.
+
+```python
+import numpy as np
+import matplotlib.pyplot as plt
+import hedgehogs as hdg
+
+fig_x, fig_y = hdg.figsize(name="science", column="single")
+palette = hdg.get_palette("okabe-ito")
+hdg.set_style(figure_size=(fig_x, fig_y), palette="okabe-ito")
+
+x = np.linspace(0, 1, 25)
+y = 2 * x + 0.1 * np.sin(20 * x)
+fitted = np.polyval(np.polyfit(x, y, 1), x)
+
+fig, ax = plt.subplots(figsize=(fig_x, fig_y))
+ax.scatter(x, y, color=palette["blue"], label="Data")
+ax.plot(x, fitted, color=palette["black"], label="Linear fit")
+ax.set(xlabel="x", ylabel="y")
+ax.legend()
+
+hdg.plots.save("linear_fit.pdf", bbox_inches=None)
+hdg.plots.show()
+```
+
+`figsize()` returns width and height in inches for `science`, `nature`, `ieee` or `aps`, with `single` or `double` columns. Presets provide starting dimensions; check the target journal's author instructions. Use an extensionless path with `formats=("pdf", "png")` for multiple outputs. Matplotlib arguments and artist properties remain editable.
+
+[Tree diagrams and pairplots](https://github.com/PentagonToy/Hedgehogs/blob/main/docs/api/plots.md) also return editable Matplotlib objects. Keep text readable at the final document width; select fewer variables or split crowded figures before reducing font size.
+
+### Tables
+
+Display the same table in a notebook or terminal, then export its formatted values to CSV and LaTeX.
+
+```python
+table = hdg.Table("Model comparison", columns=["Case", "RMSE"], formatters={"RMSE": ".3f"})
+table.add_row("baseline", 0.0412)
+table.add_row("model", 0.0184)
+table.show()
+table.to_csv("errors.csv")
+table.to_latex("errors.tex", caption="Model errors", label="tab:errors")
+```
+
+`Table.from_dataframe()` accepts existing **pandas** and **Polars** DataFrames. The LaTeX output requires `booktabs`. Tables or accompanying data provide precise values; figures communicate patterns and comparisons.
+
+### Progress
+
+Wrap an iterable with `Progress` to report progress in notebooks, terminals and redirected logs.
+
+```python
+import time
+
+for step in hdg.Progress(range(20), desc="Processing"):
+    time.sleep(0.05)
+```
+
+For manually advanced work, `Progress` supports `update()`, metric reporting through `set()` and a context manager. See the [progress reference](https://github.com/PentagonToy/Hedgehogs/blob/main/docs/api/terminal.md#progress).
+
+### Terminal output
+
+```python
+hdg.echo("Reading data", tone="info")
+hdg.echo("Run completed", tone="success")
+hdg.rule("Summary")
+```
+
+Terminal output includes colour where supported. Redirected output remains plain; `NO_COLOR` and `TERM=dumb` disable colour.
+
+## Documentation and tutorials
+
+Use the [documentation roadmap](https://github.com/PentagonToy/Hedgehogs/blob/main/docs/README.md) for guides, API references and developer documentation. Runnable tutorials cover [plots](https://github.com/PentagonToy/Hedgehogs/blob/main/tutorials/plots.ipynb), [tables](https://github.com/PentagonToy/Hedgehogs/blob/main/tutorials/tables.ipynb), and [CLI output](https://github.com/PentagonToy/Hedgehogs/blob/main/tutorials/cli.ipynb).
+
+Existing Onsaemiro code can replace its import with `import hedgehogs as hdg`. Wrap iterable work with `hdg.Progress(iterable, ...)` and use the standard `time.sleep()` for delays.

hedgehogs-0.0.1/docs/README.md

@@ -0,0 +1,12 @@
+# Hedgehogs documentation
+
+The [project README](../README.md) introduces installation and usage; notebooks in [tutorials](../tutorials) contain worked examples.
+
+| Area | Purpose |
+| --- | --- |
+| [API reference](api/README.md) | Public names, signatures, parameters, returns and examples |
+| [Presentation rules](developer/presentation.md) | Typography, outlines, sizing and final publication proportions |
+| [Implementation ownership](developer/architecture.md) | Module responsibilities and rendering lifecycle |
+| [Release preparation](developer/release.md) | Build, verify and publish distributions |
+
+Each topic has one reference. Palette previews and journal dimensions are included in the API pages rather than separate guides.

hedgehogs-0.0.1/docs/api/README.md

@@ -0,0 +1,33 @@
+# Python API reference
+
+Hedgehogs configures scientific figures and presents results in notebooks and terminals. Examples use `import hedgehogs as hdg`; Matplotlib retains ownership of figures and artists.
+
+## Public namespace
+
+| Group | Public names | Purpose |
+| --- | --- | --- |
+| Figures | `set_style`, `reset_style`, `journal_preset`, `set_journal_style`, `figsize`, `subplots` | Configure and create figures |
+| Figure helpers | `finalize`, `annotate_panels`, `style_colorbar`, `apply_grid`, `enable_minor_ticks` | Adjust existing axes and panels |
+| Specialised plots | `plots.tree`, `plots.pairplot`, `plots.show`, `plots.save` | Draw, finish and save figures |
+| Palettes | `Palette`, `get_palette`, `build_color_map`, `build_style_map`, `register_palette`, `save_palette`, `load_palette` | Select and map colours |
+| Tables | `Table` | Format, display and export rows |
+| Terminal output | `Progress`, `echo`, `rule`, `info` | Report activity and inspect package versions |
+| Numerical support | `EPS` | Read floating-point machine epsilon |
+
+## Reference map
+
+| Task | Reference | Main API |
+| --- | --- | --- |
+| Style and size figures | [Figures](figures.md) | `set_style`, `figsize`, `subplots` |
+| Draw, finish and save plots | [Plots](plots.md) | `plots.tree`, `plots.pairplot`, `plots.show`, `plots.save` |
+| Select colours or define series styles | [Palettes](palettes.md) | `get_palette`, `build_style_map`, `register_palette` |
+| Format and export results | [Tables](tables.md) | `Table` |
+| Report progress and status | [Terminal output](terminal.md) | `Progress`, `echo`, `rule` |
+
+## Reference conventions
+
+API indices summarise purpose and return values. Signatures show keyword-only options after `*`; parameter tables describe defaults and constraints. `None` requests the documented inference or disables an optional behaviour. Paths accept `str` and `os.PathLike`.
+
+Figures and artists remain editable. `Table` and `Progress` update their state in place. Figure style affects global Matplotlib settings until `reset_style()` restores them. `EPS` equals `sys.float_info.epsilon`; it supplies a floating-point constant rather than a universal numerical tolerance.
+
+Read the [documentation roadmap](../README.md) for guides and tutorials, and [implementation ownership](../developer/architecture.md) for lifecycle and extension rules.

hedgehogs-0.0.1/docs/api/figures.md

@@ -0,0 +1,151 @@
+# Figure API
+
+Examples assume `import hedgehogs as hdg`.
+
+## API index
+
+| API | Purpose | Returns |
+| --- | --- | --- |
+| `hdg.set_style(...)` | Configure global presentation defaults | `None` |
+| `hdg.reset_style()` | Restore Matplotlib defaults and methods | `None` |
+| `hdg.journal_preset(...)` | Read a journal preset | `dict` |
+| `hdg.set_journal_style(...)` | Apply a journal preset | `dict` |
+| `hdg.figsize(...)` | Read physical figure dimensions | `(width, height)` |
+| `hdg.subplots(...)` | Create a figure and axes | `(Figure, axes)` |
+| `hdg.finalize(...)` | Adjust existing axes and legend styling | `None` |
+| `hdg.annotate_panels(...)` | Label panels | `None` |
+| `hdg.style_colorbar(...)` | Style a colour bar | `None` |
+| `hdg.apply_grid(...)` | Add a major grid | `None` |
+| `hdg.enable_minor_ticks(...)` | Add minor tick locators | `None` |
+
+## Styling and layout
+
+### `set_style`
+
+Apply global Matplotlib presentation defaults and enable proportional sizing for newly created figures.
+
+```python
+hdg.set_style(
+    base_fontsize=10.5, linewidth=1.1, figure_size=(2.24, 2.20),
+    subplot=None, use_tex=False, auto_scale=False,
+    scale_exponent=0.5, palette="okabe-ito",
+)
+```
+
+| Parameter | Type | Default | Constraint or meaning |
+| --- | --- | --- | --- |
+| `base_fontsize` | `float` | `10.5` | Body-text size in points before optional width scaling |
+| `linewidth` | `float` | `1.1` | Base stroke width before optional scaling |
+| `figure_size` | `tuple[float, float]` | `(2.24, 2.20)` | Reference canvas width and height in inches |
+| `subplot` | mapping or `None` | `None` | Overrides fixed `left`, `bottom`, `right`, or `top` fractions |
+| `use_tex` | `bool` | `False` | Enable Matplotlib TeX rendering |
+| `auto_scale` | `bool` | `False` | Apply the initial width-based calculation; automatic resizing operates independently |
+| `scale_exponent` | `float` | `0.5` | Width-scaling exponent |
+| `palette` | `str` | `"okabe-ito"` | Registered palette name |
+
+Returns `None`. Filled markers receive black outlines unless an edge colour is supplied; unfilled markers such as `"x"` use a single stroke colour. The style applies to new Matplotlib figures. Single panels scale relative to `figure_size`; subplot grids retain configured point sizes. See [Presentation proportions](../developer/presentation.md) for the scaling rules.
+
+### `reset_style`
+
+Stop automatic figure sizing and restore Matplotlib defaults.
+
+```python
+hdg.reset_style() -> None
+```
+
+Returns `None`.
+
+### `journal_preset`, `set_journal_style`, and `figsize`
+
+Read or apply a named journal preset.
+
+```python
+hdg.journal_preset(name="science", column="single") -> dict[str, object]
+hdg.set_journal_style(name="science", column="single", **overrides) -> dict[str, object]
+hdg.figsize(name="science", column="single") -> tuple[float, float]
+```
+
+Supported journal names are `nature`, `science`, `ieee`, and `aps`; supported column widths are `single` and `double`. Journal typography uses stable point sizes at both column widths. `journal_preset()` returns a new dictionary containing `figure_size`, `base_fontsize`, and `linewidth`; `set_journal_style()` applies and returns those options with any `set_style()` overrides. `figsize()` returns dimensions in inches. Unknown journal names or column selections raise `ValueError`.
+
+| Preset | Typical use | Single-column width | Double-column width |
+| --- | --- | ---: | ---: |
+| `nature` | Nature-family starting point | 3.50 in | 7.20 in |
+| `science` | Science-family starting point | 2.24 in | 4.76 in |
+| `ieee` | IEEE two-column papers | 3.50 in | 7.16 in |
+| `aps` | APS journals | 3.40 in | 7.00 in |
+
+| Parameter | Type | Default | Allowed values |
+| --- | --- | --- | --- |
+| `name` | `str` | `"science"` | `science`, `nature`, `ieee`, or `aps` |
+| `column` | `str` | `"single"` | `single` or `double` |
+| `**overrides` | keyword arguments | Empty | `set_style()` options; accepted by `set_journal_style()` only |
+
+### `subplots`
+
+Create a Matplotlib figure and its subplot axes.
+
+```python
+hdg.subplots(
+    nrows=1, ncols=1, *, figsize=None, journal=None, column="single",
+    subplot=None, gridspec_kw=None, widths=None, heights=None,
+    sharex=False, sharey=False, squeeze=True, layout=None, **ax_kw,
+)
+```
+
+Create ordinary Matplotlib objects. `widths` and `heights` are concise forms of GridSpec's `width_ratios` and `height_ratios`; do not supply both forms for the same dimension.
+
+| Parameter | Default | Meaning |
+| --- | --- | --- |
+| `nrows`, `ncols` | `1`, `1` | Subplot grid dimensions |
+| `figsize` | `None` | Explicit physical size in inches |
+| `journal`, `column` | `None`, `"single"` | Optional journal-derived size |
+| `subplot` | `None` | Fixed margin overrides |
+| `gridspec_kw` | `None` | Matplotlib GridSpec options |
+| `widths`, `heights` | `None` | Concise panel-ratio lists |
+| `sharex`, `sharey` | `False` | Matplotlib shared-axis configuration |
+| `squeeze` | `True` | Apply Matplotlib axes squeezing |
+| `layout` | `None` | Matplotlib layout engine name |
+| `**ax_kw` | Empty | Axes constructor options, passed as Matplotlib `subplot_kw` |
+
+Returns `(fig, axes)`; axes shape follows `nrows`, `ncols`, and `squeeze`. Combining `figsize` with `journal`, or a ratio alias with its matching GridSpec key, raises `ValueError`.
+
+For colour bars and nested axes, select `layout="constrained"`. Use `ax.set_box_aspect(1)` for a square plotting box.
+
+```python
+fig, axes = hdg.subplots(2, 2, layout="constrained")
+```
+
+### Figure finishing helpers
+
+Adjust existing axes and colour bars without changing the plotted data.
+
+```python
+hdg.finalize(ax=None, fix_origin=True, keep="x", grid=False, minor_ticks=False)
+hdg.annotate_panels(axes, labels=None, loc="upper left", offset=None, fontsize=None, fontweight="bold")
+hdg.style_colorbar(cb, label=None)
+hdg.apply_grid(ax=None, axis="both")
+hdg.enable_minor_ticks(ax=None, x=True, y=True)
+```
+
+| Helper | Parameters and defaults | Behaviour |
+| --- | --- | --- |
+| `finalize()` | `ax=None` selects current axes; also accepts an axes collection; `fix_origin=True`, `keep="x"`, `grid=False`, `minor_ticks=False` | Suppress one zero tick label when both ranges include zero, style existing legend frames, and optionally add grids or minor ticks |
+| `annotate_panels()` | Required `axes`; `labels=None` generates `(a)`, `(b)`, …; `loc="upper left"`; `offset=None`; `fontsize=None` uses the current font size; `fontweight="bold"` | Place labels in axes coordinates; `offset=(x, y)` overrides placement, and `loc` selects left or right alignment |
+| `style_colorbar()` | Required `cb`; `label=None` preserves the existing label | Apply configured outline and tick styling |
+| `apply_grid()` | `ax=None` selects current axes; `axis="both"` accepts `x`, `y`, or `both` | Add a dotted major grid beneath the plotted data |
+| `enable_minor_ticks()` | `ax=None` selects current axes; `x=True`, `y=True` | Install automatic minor locators for linear axes |
+
+All five helpers return `None`. `finalize()` styles an existing legend; it does not create one. With `keep="x"`, the y-axis zero label is suppressed; use `keep="y"` to retain the y-axis zero label. Supply one custom panel label per axes because labels and axes are paired with `zip()`.
+
+```python
+ax.legend()
+hdg.finalize(ax, grid=True)
+```
+
+## Palettes
+
+See [Palettes and series styles](palettes.md) for colour selection, series mapping and custom palette APIs.
+
+## Specialised plots
+
+See the [tree and pairplot reference](plots.md) for `hdg.plots.tree()` and `hdg.plots.pairplot()`.

hedgehogs-0.0.1/docs/api/palettes.md

@@ -0,0 +1,128 @@
+# Palette API
+
+Examples assume `import hedgehogs as hdg`.
+
+## API index
+
+| API | Purpose | Returns |
+| --- | --- | --- |
+| `hdg.Palette(...)` | Hold named, ordered colours | `Palette` |
+| `hdg.get_palette(...)` | Select a registered palette | `Palette` |
+| `hdg.build_color_map(...)` | Assign colours to labels | `dict` |
+| `hdg.build_style_map(...)` | Assign colour, marker and line styles | `dict` |
+| `hdg.register_palette(...)` | Register validated colours | `Palette` |
+| `hdg.save_palette(...)` | Write a palette to JSON | `Path` |
+| `hdg.load_palette(...)` | Read and register JSON colours | `Palette` |
+
+## Built-in palettes
+
+Hedgehogs provides six categorical palettes; Okabe–Ito is the default. Swatches follow the exact package order, from left to right. The summary lists HEX values in the same order; indices start at zero.
+
+| Palette | Colours | Preview | HEX values in index order |
+| --- | ---: | --- | --- |
+| `okabe-ito` | 8 | ![okabe-ito colours in index order](../../others/palettes/okabe-ito.svg) | `#0072B2` `#E69F00` `#D55E00`<br>`#009E73` `#56B4E9` `#F0E442`<br>`#CC79A7` `#000000` |
+| `tableau10` | 10 | ![tableau10 colours in index order](../../others/palettes/tableau10.svg) | `#4E79A7` `#F28E2B` `#E15759`<br>`#76B7B2` `#59A14F` `#EDC948`<br>`#B07AA1` `#FF9DA7` `#9C755F`<br>`#BAB0AC` |
+| `paul-tol-vibrant` | 7 | ![paul-tol-vibrant colours in index order](../../others/palettes/paul-tol-vibrant.svg) | `#0077BB` `#33BBEE` `#009988`<br>`#EE7733` `#CC3311` `#EE3377`<br>`#BBBBBB` |
+| `paul-tol-bright` | 7 | ![paul-tol-bright colours in index order](../../others/palettes/paul-tol-bright.svg) | `#4477AA` `#EE6677` `#228833`<br>`#CCBB44` `#66CCEE` `#AA3377`<br>`#BBBBBB` |
+| `paul-tol-muted` | 9 | ![paul-tol-muted colours in index order](../../others/palettes/paul-tol-muted.svg) | `#332288` `#88CCEE` `#44AA99`<br>`#117733` `#999933` `#DDCC77`<br>`#CC6677` `#882255` `#AA4499` |
+| `ibm` | 5 | ![ibm colours in index order](../../others/palettes/ibm.svg) | `#648FFF` `#785EF0` `#DC267F`<br>`#FE6100` `#FFB000` |
+
+Colour names belong to each palette; the same name can have different HEX values across palettes. These are discrete series colours. Select a Matplotlib colormap separately for continuous fields. Combine colours with markers or line styles for greyscale reproduction.
+
+## Select colours
+
+```python
+palette = hdg.get_palette("okabe-ito")
+ax.scatter(x, y, color=palette["blue"])
+ax.plot(x, prediction, color=palette[1])
+```
+
+`Palette` supports colour names, integer indices and slices. Integer indices cycle through the available colours; slices return colour lists. Available names depend on the selected palette. `len(palette)` reports the colour count; `keys()`, `values()` and `items()` expose names, colours and name–colour pairs. Built-in colour-name lookup ignores case. An unknown colour name raises `KeyError`.
+
+Apply a palette to the global figure style with `hdg.set_style(palette="okabe-ito")`. For a pairplot, `hdg.plots.pairplot(data, hue="species", palette="tableau10")` selects its palette explicitly.
+
+For the default palette, `palette[0]` and `palette["blue"]` both return `"#0072B2"`; `palette[8]` repeats the first colour. `palette[:3]` returns a list of the first three colours, while `hdg.get_palette("okabe-ito", n=3)` returns a three-colour `Palette`.
+
+## Assign series styles
+
+```python
+styles = hdg.build_style_map(["baseline", "model"])
+ax.plot(x, baseline, label="Baseline", **styles["baseline"])
+ax.plot(x, prediction, label="Model", **styles["model"])
+```
+
+`build_color_map()` assigns colours alone. `build_style_map()` combines colours, markers and line styles for Matplotlib lines. Both functions retain the first occurrence of each label. Their `palette` argument defaults to Okabe–Ito independently of the active figure style; pass it explicitly for another palette. Colours repeat when labels outnumber colours. Line styles cycle through `-`, `--`, `-.` and `:`; markers cycle through `o`, `s`, `^`, `D`, `v`, `P` and `X`. These cycles can eventually repeat complete style combinations.
+
+## Register and save
+
+```python
+hdg.register_palette("models", {"baseline": "#0072B2", "model": "#D55E00"})
+hdg.save_palette("models", "models.json")
+hdg.load_palette("models.json", name="imported-models")
+```
+
+Registration lasts for the current Python process. Mapping order determines colour order. For custom colour names, prefer lowercase keys because lookup converts names to lowercase. An iterable of colours can instead supply `names=[...]`; omit `names` when passing a mapping. Save a palette as JSON to reuse it in another session.
+
+`overwrite=True` replaces an existing registration. `load_palette()` uses an explicit `name`, then the stored JSON name, then the file stem. Saved JSON contains `name`, `names` and `colors`.
+
+## Maintaining the colour tables
+
+The tables mirror `core/palette.py`. After changing built-in colours, update their order and HEX values here, then regenerate swatches from the repository root:
+
+```bash
+python tools/docs/render_palette_swatches.py others/palettes
+```
+
+## Palette objects
+
+### `Palette`
+
+```python
+hdg.Palette(names, colors)
+```
+
+`names` and `colors` are ordered iterables. The object supports integer and colour-name access, slicing, iteration, `len()`, `keys()`, `values()` and `items()`. Integer indices cycle through the available colours; slices return lists. An unknown colour name raises `KeyError`. Construct validated custom palettes through `register_palette()`.
+
+### `get_palette`
+
+Read a registered palette or select colours from an existing `Palette`.
+
+```python
+hdg.get_palette(palette="okabe-ito", n=None) -> Palette
+```
+
+Return a palette with index, slice, and colour-name access. Built-in names include `okabe-ito`, `tableau10`, `paul-tol-vibrant`, `paul-tol-bright`, `paul-tol-muted`, and `ibm`.
+
+| Parameter | Default | Meaning |
+| --- | --- | --- |
+| `palette` | `"okabe-ito"` | Registered name or `Palette` object |
+| `n` | `None` | Positive integer limiting the number of colours; `None` retains all colours |
+
+An invalid `n` raises `ValueError`. A limit larger than the palette returns all available colours. Palette names ignore case and accept partial family names such as `tol` or `tableau`; an unrecognised name emits `UserWarning` and falls back to Okabe–Ito. Prefer the exact names in the tables for reproducible selection.
+
+## Series mapping
+
+### `build_color_map` and `build_style_map`
+
+Assign colours or combined visual styles to unique labels.
+
+```python
+hdg.build_color_map(labels, palette="okabe-ito") -> dict[object, str]
+hdg.build_style_map(labels, palette="okabe-ito") -> dict[object, dict[str, str]]
+```
+
+`labels` is an iterable of hashable labels; `palette="okabe-ito"` accepts a registered name or `Palette`. Both functions preserve first-occurrence order. `build_style_map()` returns keyword dictionaries accepted by `Axes.plot()`.
+
+## Custom palettes
+
+Register palettes for the current process or transfer them through JSON.
+
+```python
+hdg.register_palette(name, colors, names=None, *, overwrite=False) -> Palette
+hdg.save_palette(name, path) -> Path
+hdg.load_palette(path, *, name=None, overwrite=False) -> Palette
+```
+
+`colors` accepts a mapping of names to Matplotlib colours, or an iterable with optional `names`. Omitted names are generated as `color-1`, `color-2`, and so on. Empty palettes, invalid colours, duplicate colour names, and mismatched lengths raise `ValueError`. An existing palette requires `overwrite=True`. `save_palette()` writes JSON and returns its path; `load_palette()` reads the JSON, registers the palette, and returns a `Palette`.
+
+See the [figure guide](figures.md) for styling and export.