Added README.qmd

Author: max-models

README.md

@@ -1,27 +1,246 @@
 # maxplotlib
 
-This is a wrapper for matplotlib so I can produce figures with consistent formatting. It also has some pretty nice additions such as using layers and exporting to tikz.
+
+# maxplotlib
+
+A clean, expressive wrapper around **Matplotlib** 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, or camera-ready **TikZ** code for LaTeX.
 
 ## Install
 
-Create and activate python environment
+``` bash
+python -m venv env && source env/bin/activate
+pip install maxplotlibx
+```
+
+For development extras (tests, docs, linting):
 
+``` bash
+pip install "maxplotlibx[dev]"
 ```
-python -m venv env
-source env/bin/activate
-pip install --upgrade pip
+
+## Showcase
+
+``` python
+import numpy as np
+from maxplotlib import Canvas
+
+rng = np.random.default_rng(0)
+x   = np.linspace(0, 2 * np.pi, 300)
+
+canvas, axes = Canvas.subplots(nrows=2, ncols=2, width="18cm", ratio=0.65)
+
+# ── top-left: multi-line with legend ──────────────────────────────────────────
+ax = axes[0][0]
+ax.plot(x, np.sin(x),           color="royalblue",  linewidth=2, label=r"$\sin(x)$")
+ax.plot(x, np.cos(x),           color="tomato",     linewidth=2,
+        linestyle="dashed",     label=r"$\cos(x)$")
+ax.plot(x, np.sin(2 * x) * 0.5, color="seagreen",   linewidth=1.5,
+        linestyle="dotted",     label=r"$\frac{1}{2}\sin(2x)$")
+ax.set_xlabel("x")
+ax.set_ylabel("amplitude")
+ax.set_title("Line plots")
+ax.set_legend(True)
+ax.set_grid(True)
+
+# ── top-right: scatter coloured by distance ────────────────────────────────────
+ax = axes[0][1]
+n  = 250
+sx = rng.standard_normal(n)
+sy = rng.standard_normal(n)
+ax.scatter(sx, sy, c=np.hypot(sx, sy), s=25, alpha=0.8)
+ax.set_xlabel("x")
+ax.set_ylabel("y")
+ax.set_title("Scatter — coloured by distance")
+ax.set_aspect("equal")
+
+# ── bottom-left: bar chart ────────────────────────────────────────────────────
+ax     = axes[1][0]
+months = ["Jan", "Feb", "Mar", "Apr", "May", "Jun",
+          "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"]
+temps  = [3, 4, 8, 13, 18, 22, 24, 23, 18, 12, 7, 4]
+month_idx = np.arange(len(months))
+ax.bar(month_idx, temps, color="steelblue", width=0.7, label="avg °C")
+ax.set_xticks(month_idx, labels=months)
+ax.set_xlabel("month")
+ax.set_ylabel("temperature (°C)")
+ax.set_title("Bar chart")
+
+# ── bottom-right: fill_between confidence band ────────────────────────────────
+ax   = axes[1][1]
+mean = np.sin(x) * np.exp(-x / (2 * np.pi))
+std  = 0.15 + 0.1 * np.abs(np.cos(x))
+ax.plot(x, mean, color="darkorchid", linewidth=2, label="mean")
+ax.fill_between(x, mean - std, mean + std, alpha=0.25, color="darkorchid",
+                label="±1 σ")
+ax.set_xlabel("x")
+ax.set_ylabel("y")
+ax.set_title("Confidence band")
+ax.set_legend(True)
+ax.set_grid(True)
+
+canvas.suptitle("maxplotlib — four plot types, one canvas")
+fig, _ = canvas.plot()
+fig
 ```
 
-Install the code and requirements with pip
+<div id="fig-showcase">
+
+<div class="cell-output cell-output-display" execution_count="2">
+
+<div id="fig-showcase-1">
+
+<img src="README_files/figure-commonmark/fig-showcase-output-1.png"
+data-ref-parent="fig-showcase" />
+
+(a) maxplotlib showcase — four plot types, one canvas.
+
+</div>
+
+</div>
+
+<div class="cell-output cell-output-display">
+
+<div id="fig-showcase-2">
+
+<img src="README_files/figure-commonmark/fig-showcase-output-2.png"
+id="fig-showcase-2" data-ref-parent="fig-showcase" />
+
+(b)
+
+</div>
+
+</div>
+
+Figure 1
+
+</div>
+
+## Quick start
 
+### One-liner with `Canvas.subplots()`
+
+`Canvas.subplots()` mirrors `plt.subplots()` but returns a `Canvas` and
+subplot axes that speak the maxplotlib API.
+
+``` python
+import numpy as np
+from maxplotlib import Canvas
+
+x = np.linspace(0, 2 * np.pi, 200)
+
+canvas, ax = Canvas.subplots(width="10cm", ratio=0.55)
+ax.plot(x, np.sin(x), color="royalblue", label=r"$\sin(x)$", linewidth=2)
+ax.plot(x, np.cos(x), color="tomato",    label=r"$\cos(x)$", linewidth=2,
+        linestyle="dashed")
+ax.set_xlabel("x")
+ax.set_ylabel("y")
+ax.set_legend(True)
+ax.set_grid(True)
+canvas.show()
+```
+
+### Canvas-level shortcut API
+
+For single-subplot figures every plot method is available directly on
+the `Canvas` object — no need to grab an axes handle:
+
+``` python
+canvas = Canvas(ratio=0.5, fontsize=12)
+canvas.add_line(x, np.sin(x), label="sin", color="steelblue")
+canvas.add_line(x, np.cos(x), label="cos", color="darkorange", linestyle="dashed")
+canvas.set_xlabel("angle (rad)")
+canvas.set_ylabel("amplitude")
+canvas.set_legend(True)
+canvas.show()
+```
+
+## Key features
+
+### Multiple backends — same API
+
+| Backend | How to use | Output |
+|----|----|----|
+| `matplotlib` (default) | `canvas.show()` | inline PNG / static file |
+| `plotly` | `fig = canvas.plot(backend='plotly')` | interactive HTML widget |
+| `tikzfigure` | `tz = canvas.plot(backend='tikzfigure')` | LaTeX `\draw` commands |
+
+``` python
+# Render as interactive Plotly figure
+fig = canvas.plot(backend="plotly")
+fig.show()
+
+# Export TikZ code for a LaTeX document
+tikz = canvas.plot(backend="tikzfigure")
+print(tikz.generate_tikz())
 ```
-pip install -e .
+
+### Layers
+
+Tag each plot call with a `layer=` integer. Then render any subset —
+handy for step-by-step derivations, lecture slides, or overlays.
+
+``` python
+canvas, ax = Canvas.subplots()
+ax.plot(x, np.sin(x), layer=0, label=r"$\sin(x)$",        color="steelblue")
+ax.plot(x, np.cos(x), layer=1, label=r"$\cos(x)$",        color="tomato")
+ax.plot(x, np.sin(x) * np.cos(x), layer=2,
+        label=r"$\sin(x)\cos(x)$", color="seagreen", linestyle="dashed")
+
+canvas.show(layers=[0])       # only sin
+canvas.show(layers=[0, 1])    # sin + cos
+canvas.show()                 # everything
 ```
 
-Additional dependencies for developers can be installed with
+### Size and typography
 
+Pass physical dimensions and a font size; maxplotlib converts to the
+correct `figsize` automatically.
+
+``` python
+canvas = Canvas(width="17cm", ratio=0.5, fontsize=11)
 ```
-pip install -e ".[dev]"
+
+`ratio` accepts a float **or** the string `"golden"` (default) for the
+golden ratio.
+
+### Saving figures
+
+``` python
+canvas.savefig("figure.pdf")     # vector PDF
+canvas.savefig("figure.png")     # raster PNG
+canvas.savefig("figure.svg")     # SVG
 ```
 
-Some examples can be found in `tutorials/`
+## Plot types
+
+| Method                            | Description                    |
+|-----------------------------------|--------------------------------|
+| `ax.plot(x, y)`                   | Line plot                      |
+| `ax.scatter(x, y)`                | Scatter plot                   |
+| `ax.bar(categories, values)`      | Bar chart                      |
+| `ax.fill_between(x, y1, y2)`      | Shaded band                    |
+| `ax.errorbar(x, y, yerr)`         | Error bars                     |
+| `ax.axhline(y)` / `ax.axvline(x)` | Reference lines                |
+| `ax.annotate(text, xy)`           | Annotation with optional arrow |
+
+## Tutorials
+
+Step-by-step Jupyter notebooks in `tutorials/`:
+
+| Notebook             | Topic                            |
+|----------------------|----------------------------------|
+| `tutorial_01`        | Quick start                      |
+| `tutorial_02`        | Multiple subplots                |
+| `tutorial_03`        | All plot types                   |
+| `tutorial_04`        | Colours, linestyles, markers     |
+| `tutorial_05`        | Axes, ticks, scales, annotations |
+| `tutorial_06`        | Layers                           |
+| `tutorial_07_tikz`   | TikZ backend                     |
+| `tutorial_08_plotly` | Plotly backend                   |
+
+## License
+
+MIT — see [`LICENSE`](LICENSE).