README.qmd

---
title: Maxlotlib
format: gfm
fig-dpi: 150
---

# Maxplotlib

A clean, expressive wrapper around **Matplotlib**, **Plotly**, **plotext**, and **tikzfigure**
for producing publication-quality figures with minimal boilerplate. Swap backends without
rewriting your data — render the same canvas as a crisp PNG, an interactive Plotly chart, a
terminal-native plotext figure, or camera-ready **TikZ** code for LaTeX.

## Install

```bash
pip install maxplotlibx
```

## Showcase

### Quickstart

```{python}
#| label: fig-showcase-1
#| fig-width: 9
#| fig-height: 6

import numpy as np
from maxplotlib import Canvas

x = np.linspace(0, 2 * np.pi, 200)
y = np.sin(x)

canvas, ax = Canvas.subplots()
ax.plot(x, y)
```

Plot the figure with the default (matplotlib) backend:

```{python}
canvas.show()
```

Use `canvas.plot(x, y)` to add data directly to a canvas. When you want to
explicitly render an already-built canvas, use `canvas.render(...)`. The older
`canvas.plot(backend=...)` spelling is still supported for compatibility, but
emits a `FutureWarning`.

Add several lines at once with shared styling:

```{python}
#| output: false
canvas.plot_many(
    [(x, np.sin(x)), (x, np.cos(x))],
    labels=["sin(x)", "cos(x)"],
    linewidth=2,
)
```

Common figure and axis settings can be grouped with `configure()`:

```{python}
#| output: false
canvas.configure(
    title="Trigonometry",
    xlabel="Angle",
    ylabel="Value",
    grid=True,
    facecolor="whitesmoke",
)
```

For Matplotlib-specific customization, pass method calls declaratively. Figure
methods run once and axes methods run for every subplot, providing access to
any Matplotlib API without requiring a maxplotlib wrapper:

```{python}
#| output: false
canvas.plot(matplotlib_customizations={
    "figure": {
        "suptitle": "My figure",
    },
    "axes": {
        "tick_params": {
            "axis": "both",
            "which": "major",
            "length": 6,
        },
    },
})
```

For dynamic customization, the same option also accepts a function:

```{python}
#| output: false
def customize(fig, axes):
    fig.suptitle("My figure")
    for ax in axes.flat:
        ax.tick_params(axis="both", which="major", length=6)

canvas.plot(matplotlib_customizations=customize)
```

### Axis Label and Tick Styling

Axis labels, titles, and tick appearance accept Matplotlib-style keyword
arguments:

```{python}
#| output: false
canvas.set_xlabel("Time", fontsize=12, fontweight="bold", labelpad=10)
canvas.set_ylabel("Duration", color="darkblue")
canvas.set_title("Runtime", fontsize=14, color="navy")
canvas.tick_params(
    axis="both",
    which="major",
    labelsize=10,
    colors="darkgreen",
    length=6,
)
```

Common axis controls and figure-level layout settings are also available:

```{python}
#| output: false
canvas.set_facecolor("whitesmoke")
canvas.set_axisbelow(True)
canvas.margins(x=0.05, y=0.1)
canvas.minorticks_on()
canvas.invert_yaxis()
canvas.supxlabel("Shared x label")
canvas.supylabel("Shared y label")
canvas.subplots_adjust(left=0.15, bottom=0.15)
canvas.tight_layout()
```

### Secondary Y-Axis

Use `Canvas.twinx()` to add a second y-axis that shares the primary x-axis:

```{python}
#| output: false
twin_canvas, primary = Canvas.subplots()
secondary = twin_canvas.twinx()

primary.plot(x, np.sin(x), color="tab:blue")
secondary.plot(x, 100 * np.cos(x), color="tab:red")
primary.set_ylabel("sin(x)", color="tab:blue")
secondary.set_ylabel("100 cos(x)", color="tab:red")

twin_canvas.show()
```

Secondary y-axes are currently supported by the Matplotlib and Plotly
backends.

### Plotly field plots and tables

Several Matplotlib field and annotation APIs map directly to interactive
Plotly traces, including pseudocolor plots, sparsity patterns, triangular
grids, and tables:

```{python}
#| output: false
plotly_canvas, plotly_ax = Canvas.subplots()
plotly_ax.pcolor(x, x, np.outer(np.sin(x), np.cos(x)))
plotly_ax.spy([[1, 0, 1], [0, 1, 0], [1, 0, 1]])
plotly_ax.table(cellText=[["A", "B"], ["1", "2"]])
plotly_canvas.show(backend="plotly")
```

Plotly raises `NotImplementedError` for primitives without a faithful
equivalent instead of silently dropping them. To render the supported parts
of a mixed canvas, explicitly opt into skipping unsupported primitives:

```{python}
#| output: false
plotly_canvas.render(backend="plotly", allow_unsupported=True)
```

Render the same line graph directly in the terminal with the `plotext` backend:

```{python}
terminal_fig = canvas.render(backend="plotext")
print(terminal_fig.build(keep_colors=False))
```

Or plot with the TikZ backend:

```{python}
canvas.show(backend="tikzfigure")
```

### Horizontal Subplots with TikZ Backend

The tikzfigure backend supports creating side-by-side subplots (1×n layouts):

```{python}
#| label: fig-showcase-subplots
#| fig-width: 9
#| fig-height: 6

x = np.linspace(0, 2 * np.pi, 200)
canvas, (ax1, ax2) = Canvas.subplots(ncols=2, width="10cm", ratio=0.3)

ax1.plot(x, np.sin(x), color="royalblue")
ax1.set_title("sin(x)")

ax2.plot(x, np.cos(x), color="tomato")
ax2.set_title("cos(x)")

canvas.suptitle("Trigonometric Functions")
canvas.show(backend="tikzfigure")  # Generates LaTeX subfigures
```

**Note:** Only horizontal layouts (1×n) are currently supported with the tikzfigure backend. Vertical/grid layouts will raise `NotImplementedError`. See the tutorials for more examples.

### Terminal Backend with plotext

The `plotext` backend is designed for terminal-first workflows. It currently supports line plots,
scatter plots, bars, filled regions, error bars, reference lines, text/annotations, labels/titles,
log axes, layers, matrix-style `imshow()` rendering, common patches, and multi-subplot canvases.

```{python}
x = np.linspace(1, 10, 40)

canvas, ax = Canvas.subplots()
ax.plot(x, np.sqrt(x), color="cyan", label="sqrt(x)")
ax.errorbar(x[::8], np.sqrt(x[::8]), yerr=0.15, color="yellow", label="samples")
ax.set_title("Terminal plot")
ax.set_xlabel("x")
ax.set_ylabel("y")
ax.set_xscale("log")
ax.set_legend(True)

canvas.show(backend="plotext")
```

### Layers

```{python}
#| label: fig-showcase-2
#| fig-width: 9
#| fig-height: 6

x = np.linspace(0, 2 * np.pi, 200)

canvas, ax = Canvas.subplots(width="10cm", ratio=0.55)

ax.plot(x, np.sin(x), color="steelblue", label=r"$\sin(x)$", layer=0)
ax.plot(x, np.cos(x), color="tomato", label=r"$\cos(x)$", layer=1)
ax.plot(
    x,
    np.sin(x) * np.cos(x),
    color="seagreen",
    label=r"$\sin(x)\cos(x)$",
    linestyle="dashed",
    layer=2,
)

ax.set_xlabel("x")
ax.set_legend(True)
```

Show layer 0 only, then layers 0 and 1, then everything:

```{python}
canvas.show(layers=[0])
```

Show all layers:

```{python}
canvas.show()
```