Enhance bar chart functionality: support grouped bars, log scale, and update API for matplotlib alignment

Author: CSSFrancis

Examples/plot_bar.py

@@ -2,23 +2,159 @@
 Bar Chart
 =========
 
-Demonstrate :meth:`~anyplotlib.figure_plots.Axes.bar` with vertical and
-horizontal orientations, per-bar colours, category labels, and live data
-updates via :meth:`~anyplotlib.figure_plots.PlotBar.update`.
+Demonstrate :meth:`~anyplotlib.figure_plots.Axes.bar` with:
 
-Three separate figures are shown:
-
-1. **Vertical bar chart** – monthly sales data with a uniform colour.
-2. **Horizontal bar chart** – ranked items with per-bar colours and value
-   labels.
-3. **Side-by-side comparison** – two panels sharing the same figure; one
-   panel updates its data to show a different quarter.
+* **Matplotlib-aligned API** — ``ax.bar(x, height, width, bottom, …)``
+* Vertical and horizontal orientations, per-bar colours, category labels
+* **Grouped bars** — pass a 2-D *height* array ``(N, G)``
+* **Log-scale value axis** — ``log_scale=True``
+* Live data updates via :meth:`~anyplotlib.figure_plots.PlotBar.update`
 """
 import numpy as np
 import anyplotlib as vw
 
 rng = np.random.default_rng(7)
 
+# ── 1. Vertical bar chart — monthly sales ────────────────────────────────────
+# The first positional argument is now *x* (positions or labels), matching
+# ``matplotlib.pyplot.bar(x, height, width=0.8, bottom=0.0, ...)``.
+months = ["Jan", "Feb", "Mar", "Apr", "May", "Jun",
+          "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"]
+sales = np.array([42, 55, 48, 63, 71, 68, 74, 81, 66, 59, 52, 78],
+                 dtype=float)
+
+fig1, ax1 = vw.subplots(1, 1, figsize=(640, 340))
+bar1 = ax1.bar(
+    months,           # x  — category strings become x_labels automatically
+    sales,            # height
+    width=0.6,
+    color="#4fc3f7",
+    show_values=True,
+    units="Month",
+    y_units="Units sold",
+)
+fig1
+
+# %%
+# Horizontal bar chart — ranked items
+# -------------------------------------
+# Set ``orient="h"`` for a horizontal layout.  Pass a list of CSS colours
+# to ``colors`` to give each bar its own colour.
+
+categories = ["NumPy", "SciPy", "Matplotlib", "Pandas", "Scikit-learn",
+              "PyTorch", "TensorFlow", "JAX", "Polars", "Dask"]
+scores = np.array([95, 88, 91, 87, 83, 79, 76, 72, 68, 65], dtype=float)
+
+palette = [
+    "#ef5350", "#ec407a", "#ab47bc", "#7e57c2", "#42a5f5",
+    "#26c6da", "#26a69a", "#66bb6a", "#d4e157", "#ffa726",
+]
+
+fig2, ax2 = vw.subplots(1, 1, figsize=(540, 400))
+bar2 = ax2.bar(
+    categories,
+    scores,
+    orient="h",
+    colors=palette,
+    width=0.65,
+    show_values=True,
+    y_units="Popularity score",
+)
+fig2
+
+# %%
+# Grouped bar chart — quarterly comparison
+# -----------------------------------------
+# Pass a 2-D *height* array of shape ``(N, G)`` to draw *G* bars side by
+# side for each category.  Provide ``group_labels`` to show a legend and
+# ``group_colors`` to customise each group's colour.
+
+quarters = ["Jan", "Feb", "Mar", "Apr", "May", "Jun"]
+q_data = np.array([
+    [42, 58, 51],   # Jan — Q1, Q2, Q3
+    [55, 61, 59],   # Feb
+    [48, 70, 65],   # Mar
+    [63, 75, 71],   # Apr
+    [71, 69, 80],   # May
+    [68, 83, 77],   # Jun
+], dtype=float)     # shape (6, 3) → 6 categories, 3 groups
+
+fig3, ax3 = vw.subplots(1, 1, figsize=(680, 340))
+bar3 = ax3.bar(
+    quarters,
+    q_data,
+    width=0.8,
+    group_labels=["Q1", "Q2", "Q3"],
+    group_colors=["#4fc3f7", "#ff7043", "#66bb6a"],
+    show_values=False,
+    y_units="Sales",
+)
+fig3
+
+# %%
+# Log-scale value axis
+# ---------------------
+# Set ``log_scale=True`` for a logarithmic value axis.  Non-positive values
+# are clamped to ``1e-10`` — no error is raised.  Tick marks are placed at
+# each decade (10⁰, 10¹, 10², …) with faint minor gridlines at 2×, 3×, 5×
+# multiples.
+
+log_labels = ["A", "B", "C", "D", "E"]
+log_vals   = np.array([1, 10, 100, 1_000, 10_000], dtype=float)
+
+fig4, ax4 = vw.subplots(1, 1, figsize=(500, 340))
+bar4 = ax4.bar(
+    log_labels,
+    log_vals,
+    log_scale=True,
+    color="#ab47bc",
+    show_values=True,
+    y_units="Count (log scale)",
+)
+fig4
+
+# %%
+# Side-by-side comparison — update data live
+# -------------------------------------------
+# Place two :class:`~anyplotlib.figure_plots.PlotBar` panels in one figure.
+# Call :meth:`~anyplotlib.figure_plots.PlotBar.update` to swap in Q2 data —
+# the value-axis range recalculates automatically.
+
+q1 = np.array([42, 55, 48, 63, 71, 68, 74, 81, 66, 59, 52, 78], dtype=float)
+q2 = np.array([58, 61, 70, 75, 69, 83, 90, 88, 77, 64, 71, 95], dtype=float)
+all_months = ["Jan", "Feb", "Mar", "Apr", "May", "Jun",
+              "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"]
+
+fig5, (ax_left, ax_right) = vw.subplots(1, 2, figsize=(820, 320))
+bar_left = ax_left.bar(
+    all_months, q1, width=0.6,
+    color="#4fc3f7", show_values=False, y_units="Q1 sales",
+)
+bar_right = ax_right.bar(
+    all_months, q1, width=0.6,
+    color="#ff7043", show_values=False, y_units="Q2 sales",
+)
+bar_right.update(q2)    # swap in Q2 — axis range recalculates automatically
+
+fig5
+
+# %%
+# Mutate colours, annotations, and scale at runtime
+# --------------------------------------------------
+# :meth:`~anyplotlib.figure_plots.PlotBar.set_color` repaints all bars,
+# :meth:`~anyplotlib.figure_plots.PlotBar.set_show_values` toggles labels,
+# :meth:`~anyplotlib.figure_plots.PlotBar.set_log_scale` switches the
+# value-axis between linear and logarithmic.
+
+bar1.set_color("#ff7043")
+bar1.set_show_values(False)
+fig1
+
+import numpy as np
+import anyplotlib as vw
+
+rng = np.random.default_rng(7)
+
 # ── 1. Vertical bar chart — monthly sales ────────────────────────────────────
 months = ["Jan", "Feb", "Mar", "Apr", "May", "Jun",
           "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"]

anyplotlib/FIGURE_ESM.md

@@ -294,30 +294,64 @@ Writes to `model.event_json` + `save_changes()`.
 
 ---
 
-### Bar chart (lines 2343–2697)
+### Bar chart (lines 2803–2970)
 
 State fields:
 ```
-st.values, st.x_centers, st.x_labels
-st.bar_color, st.bar_colors, st.bar_width
+st.values        [[g0,g1,...], ...]  always 2-D (N×G) list; G=1 for ungrouped
+st.groups        int — number of bar groups per category slot (≥1)
+st.x_centers, st.x_labels
+st.bar_color, st.bar_colors   (ungrouped: per-bar colours)
+st.group_colors  list[str], length G — colour per group; overrides bar_color
+st.group_labels  list[str], length G — legend labels (shown when groups > 1)
+st.bar_width     fraction of slot occupied by all bars in the slot (0–1)
 st.orient        'v' (default) | 'h'
-st.baseline      value axis zero line
-st.data_min/max  current visible value-axis range — modified by zoom/pan
+st.baseline      value-axis root; skipped for log scale
+st.log_scale     bool — logarithmic value axis; non-positive values clamped to 1e-10
+st.data_min/max  current visible value-axis range
 st.x_axis, st.view_x0/x1   widget coordinate system (category axis)
 st.overlay_widgets
 ```
 
 | Function | Lines | Purpose |
 |----------|-------|---------|
-| `_barGeom(st,r)` | 2347 | Per-bar geometry: slot/bar px, `xToPx`/`yToPx`, baseline px |
-| `drawBar(p)` | 2376 | **Main bar render**: grid, bars (clipped), value labels, axis, ticks; calls `drawOverlay1d` |
-| `_attachEventsBar(p)` | 2581 | **Full interaction**: wheel zoom on `data_min/max`, left-drag pan on value axis, widget drag via `_ovHitTest1d`/`_doDrag1d`, 'r' reset, per-widget cursors, status bar, bar hover + tooltip, `on_click` |
-
-#### Bar zoom/pan model
-Unlike 1D (which zooms `view_x0/x1`), bar zooms and pans the **value axis** by
-modifying `st.data_min`/`st.data_max` directly. `view_x0/x1` stays fixed at
-0/1 so overlay widgets (vlines, hlines) keep correct positions throughout.
-`origDataMin/Max` are captured on first interaction (JS closure) for 'r' reset.
+| `_barGeom(st,r)` | ~2808 | Per-bar geometry: slot/group pixel sizes, `xToPx`/`yToPx`, `groupOffsetPx(g)`, `getVal(i,g)`, log-scale coordinate mappers, `basePx` |
+| `drawBar(p)` | ~2870 | **Main bar render**: log/linear grid, grouped bars (clipped), value labels, axis borders, log/linear ticks, group legend |
+| `_attachEventsBar(p)` | ~2977 | **Full interaction**: widget drag, hover/tooltip (shows group label), `on_click` (emits `bar_index`, `group_index`, `value`, `group_value`), keyboard |
+
+#### `_barGeom` — grouped geometry
+
+For *G* groups per category and bar-width fraction *w*:
+```
+slotPx  = (r.w or r.h) / n              — pixel width of one category slot
+barPx   = slotPx * w / G               — pixel width of a single bar
+groupOffsetPx(g) = (g - (G-1)/2) * barPx  — centre offset for group g
+```
+`getVal(i, g)` reads from `st.values[i][g]` (2-D) or legacy `st.values[i]`
+(scalar) so old 1-D state still renders correctly.
+
+#### Log scale
+
+When `st.log_scale` is true `yToPx`/`xToPx` use `Math.log10` internally:
+```js
+lv = Math.log10(Math.max(1e-10, v))
+py = r.y + r.h - ((lv - lMin) / (lMax - lMin)) * r.h
+```
+Grid lines: faint minor lines at 2×, 3×, 5× per decade; full-opacity major
+lines at each power of 10.  Tick labels use superscript notation (`10^N`).
+
+#### Bar zoom/pan model (unchanged)
+Unlike 1D (which zooms `view_x0/x1`), bar zooms/pans the **value axis** by
+modifying `st.data_min`/`st.data_max` directly.  `view_x0/x1` stays fixed
+at 0/1 so overlay widgets keep correct positions throughout.
+
+#### `on_click` event payload
+```js
+{ bar_index, group_index, value, group_value, x_center, x_label }
+```
+`group_index` is always 0 for ungrouped charts.  `group_value` equals
+`value` (alias for convenience).
+
 
 ---
 

anyplotlib/_repr_utils.py

@@ -136,7 +136,12 @@ def _widget_px(widget) -> tuple[int, int]:
   const _anyCbs = [];
   return {{
     get(key)          {{ return _data[key]; }},
-    set(key, val)     {{ _data[key] = val; }},
+    set(key, val)     {{
+      _data[key] = val;
+      const ev = 'change:' + key;
+      if (_cbs[ev]) for (const cb of [..._cbs[ev]]) try {{ cb({{ new: val }}); }} catch(_) {{}}
+      for (const cb of [..._anyCbs]) try {{ cb(); }} catch(_) {{}}
+    }},
     save_changes()    {{
       for (const [ev, cbs] of Object.entries(_cbs))
         for (const cb of cbs) try {{ cb({{ new: _data[ev.slice(7)] }}); }} catch(_) {{}}