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.
