like-sci-figures 0.0.0-stage → 1.0.0

package/scripts/chart_plugin.py

@@ -0,0 +1,153 @@
+#!/usr/bin/env python3
+"""Chart plugin base class for like-sci-figures.
+
+Why this exists
+---------------
+Before this file, adding a new chart type required editing 4 files:
+    1. scripts/fig_XXX.py       (rendering function)
+    2. scripts/gen_figure.py    (GENERATORS dict entry)
+    3. scripts/registry.py      (chart type registry entry)
+    4. examples/XXX.json        (example data file)
+
+With ChartPlugin, a new chart type is self-contained: subclass ChartPlugin,
+set `name`, implement `render()`, and the rest (auto-registration, palette
+integration, example lookup, documentation) happens automatically.
+
+Usage
+-----
+    # In fig_my_chart.py
+    from chart_plugin import ChartPlugin
+
+    class MyChart(ChartPlugin):
+        name = "my_chart"
+        zh = "我的图表"
+        kind = "specialized"
+
+        def render(self, data, ax, colors, cjk_fp, **kwargs):
+            # Your rendering logic here
+            ax.plot(data["x"], data["y"], color=colors[0])
+            return None  # colorbar artist if needed, else None
+
+    # Auto-registered when gen_figure.py imports this module.
+
+Plugin lifecycle
+----------------
+1. Module is loaded (by gen_figure.py's auto-discovery or explicit import).
+2. ChartPlugin subclass is instantiated (singleton per type).
+3. `register()` is called, adding the plugin to the GENERATORS dict.
+4. When `--type my_chart` is used, `render()` is called with the parsed data.
+
+Palette integration is automatic: `colors` is passed from the palette system,
+so any ChartPlugin subclass works with `--palette` without extra code.
+"""
+import os
+
+
+class ChartPlugin:
+    """Base class for chart types. Subclass and set `name` to register."""
+
+    # ── Override these ───────────────────────────────────────────────────
+    name = "base"               # canonical slug for --type
+    zh = "Base Chart"          # Chinese display name
+    kind = "specialized"       # statistics | relational | specialized
+    aliases = ()               # tuple of alias slugs
+
+    # ── Data schema hint (for documentation) ─────────────────────────────
+    required_keys = ()         # tuple of required data keys
+    optional_keys = ()         # tuple of optional data keys
+    data_format = "json"       # json | csv | both
+
+    # ── Rendering ────────────────────────────────────────────────────────
+    def render(self, data, ax, colors, cjk_fp, **kwargs):
+        """Render the chart on `ax`.
+
+        Args:
+            data:    parsed data dict (or list for subplots)
+            ax:      matplotlib axes object
+            colors:  list of hex colours from the current palette
+            cjk_fp:  CJK font path (str or None)
+            **kwargs: chart-specific flags (show_values, trend, etc.)
+
+        Returns:
+            Optional colorbar artist (for heatmaps/surfaces), else None.
+        """
+        raise NotImplementedError("ChartPlugin subclasses must implement render()")
+
+    # ── Validation ───────────────────────────────────────────────────────
+    def validate_data(self, data):
+        """Check that the data has the required keys.
+
+        Returns a list of error strings (empty = valid).
+        Override to add custom validation logic.
+        """
+        errors = []
+        if not isinstance(data, dict):
+            errors.append("Data must be a dict, got %s" % type(data).__name__)
+            return errors
+        for key in self.required_keys:
+            if key not in data:
+                errors.append("Missing required key: %r" % key)
+        return errors
+
+    # ── Auto-registration ────────────────────────────────────────────────
+    def register(self):
+        """Register this plugin with the GENERATORS dict.
+
+        Called automatically by gen_figure.py's discovery mechanism.
+        """
+        from gen_figure import GENERATORS
+        GENERATORS[self.name] = self
+        for alias in self.aliases:
+            GENERATORS[alias] = self
+
+    def __call__(self, data, ax, colors, cjk_fp, **kwargs):
+        """Make the plugin callable like a generator function."""
+        return self.render(data, ax, colors, cjk_fp, **kwargs)
+
+    def __repr__(self):
+        return "%s(name=%r, kind=%r)" % (
+            type(self).__name__, self.name, self.kind)
+
+
+def discover_plugins(plugins_dir=None):
+    """Auto-discover all ChartPlugin subclasses in scripts/fig_*.py.
+
+    Args:
+        plugins_dir: directory to scan (default: scripts/ directory)
+
+    Returns:
+        dict mapping chart type name -> ChartPlugin instance.
+    """
+    import importlib
+    import pkgutil
+    import sys
+
+    if plugins_dir is None:
+        plugins_dir = os.path.dirname(os.path.abspath(__file__))
+
+    plugins = {}
+    sys_path = sys.path[:]
+    sys.path.insert(0, plugins_dir)
+    try:
+        for module_info in pkgutil.iter_modules([plugins_dir]):
+            if not module_info.name.startswith("fig_"):
+                continue
+            try:
+                module = importlib.import_module(module_info.name)
+            except Exception:
+                continue  # skip broken modules
+            for attr_name in dir(module):
+                attr = getattr(module, attr_name)
+                if (isinstance(attr, type) and issubclass(attr, ChartPlugin)
+                        and attr is not ChartPlugin
+                        and hasattr(attr, 'name')
+                        and attr.name != "base"):
+                    # Skip duplicate registrations (alias already added)
+                    if attr.name in plugins:
+                        continue
+                    instance = attr()
+                    instance.register()
+                    plugins[attr.name] = instance
+    finally:
+        sys.path[:] = sys_path
+    return plugins

package/scripts/data_loader.py

@@ -0,0 +1,260 @@
+#!/usr/bin/env python3
+"""Data loader: JSON, CSV, TSV with intelligent format detection."""
+import json, csv, os
+
+
+def _is_number(s):
+    """Check if string represents a number."""
+    try:
+        float(s)
+        return True
+    except (ValueError, TypeError):
+        return False
+
+
+def load_data(path, chart_type=None):
+    """
+    Load data from JSON or CSV/TSV.
+
+    Returns a dict appropriate for the chart type:
+    - bar/line: {"labels": [], "series": {}, "errors": {}}
+    - scatter: {"x": [], "y": [], "groups": []}
+    - heatmap: {"matrix": [[]], "row_labels": [], "col_labels": []}
+    - box/violin: {"labels": [], "series": {}}
+    - forest: {"labels": [], "estimates": [], "ci_low": [], "ci_high": []}
+    - pie: {"labels": [], "values": []}
+    - radar: {"labels": [], "series": {}}
+    - histogram: {"series": {}} or {"values": []}
+    - 3d: {"x": [], "y": [], "z": []} or {"matrix": [[]]}
+    - subplots: list of individual chart data dicts
+    """
+    ext = os.path.splitext(path)[1].lower()
+    if ext == '.json':
+        with open(path, 'r', encoding='utf-8') as f:
+            data = json.load(f)
+        return _validate_and_convert(data, chart_type)
+    elif ext in ('.csv', '.tsv'):
+        return _load_tabular(path, ext, chart_type)
+    else:
+        raise ValueError(f"Unsupported format: {ext}. Use .json, .csv, or .tsv")
+
+
+def _normalize_series_list(series):
+    """Convert list-of-objects series to dict format.
+
+    Handles: [{"name": "A", "values": [1,2], "errors": [0.1,0.2]}, ...]
+      -> ({"A": [1,2]}, {"A": [0.1,0.2]})
+    Also accepts: [{"label": "A", "data": [1,2]}, ...]
+    """
+    if not isinstance(series, list):
+        return series, {}
+    result = {}
+    errors = {}
+    for item in series:
+        if not isinstance(item, dict):
+            continue
+        name = item.get("name") or item.get("label") or item.get("key", f"Series {len(result)+1}")
+        values = item.get("values") or item.get("data") or item.get("y") or item.get("value", [])
+        if isinstance(values, list) and values:
+            result[name] = values
+        err = item.get("errors") or item.get("error") or item.get("std") or item.get("sem")
+        if err is not None:
+            errors[name] = err
+    return result if result else series, errors if errors else {}
+
+
+def _validate_and_convert(data, chart_type):
+    """Validate JSON data against chart type and fill missing fields."""
+    if not isinstance(data, dict):
+        return data  # Could be a list for subplots
+
+    # Check for common alternate keys and normalize
+    key_map = {
+        "x": ["x", "xs", "x_data", "x_values"],
+        "y": ["y", "ys", "y_data", "y_values"],
+        "z": ["z", "zs", "z_data", "z_values"],
+        "labels": ["labels", "label", "categories", "names", "x_labels"],
+        "series": ["series", "datasets", "data", "groups"],
+        "matrix": ["matrix", "data", "grid", "array"],
+        "estimates": ["estimates", "effects", "or", "rr", "hr"],
+        "ci_low": ["ci_low", "lower", "ci_lower", "lo"],
+        "ci_high": ["ci_high", "upper", "ci_upper", "hi"],
+        "errors": ["errors", "error", "std", "sem"],
+        "row_labels": ["row_labels", "y_labels", "rows", "y_ticks"],
+        "col_labels": ["col_labels", "x_labels", "cols", "x_ticks", "columns"],
+        "groups": ["groups", "group", "categories", "category", "color_by"],
+    }
+
+    normalized = {}
+    for canonical, aliases in key_map.items():
+        for alias in aliases:
+            if alias in data:
+                normalized[canonical] = data[alias]
+                break
+
+    # Keep any keys not in the alias map
+    for k, v in data.items():
+        found = False
+        for aliases in key_map.values():
+            if k in aliases:
+                found = True
+                break
+        if not found:
+            normalized[k] = v
+
+    # Convert list-of-objects series to dict format
+    if "series" in normalized and isinstance(normalized["series"], list):
+        series_dict, embedded_errors = _normalize_series_list(normalized["series"])
+        normalized["series"] = series_dict
+        if embedded_errors and "errors" not in normalized:
+            normalized["errors"] = embedded_errors
+        # Also normalize errors if they are in list-of-objects format
+        if "errors" in normalized and isinstance(normalized["errors"], list):
+            errs, _ = _normalize_series_list(normalized["errors"])
+            if errs:
+                normalized["errors"] = errs
+
+    return normalized
+
+
+def _load_tabular(path, ext, chart_type):
+    """Load CSV/TSV and auto-detect structure."""
+    delimiter = '\t' if ext == '.tsv' else ','
+    with open(path, 'r', encoding='utf-8') as f:
+        reader = csv.reader(f, delimiter=delimiter)
+        headers = next(reader)
+        rows = list(reader)
+
+    if not rows:
+        return {"labels": [], "series": {}}
+
+    # Identify numeric columns (>50% numeric threshold)
+    numeric_col_indices = []
+    for i, h in enumerate(headers):
+        if i == 0:
+            continue
+        num_count = sum(1 for r in rows if i < len(r) and _is_number(r[i]))
+        if num_count > len(rows) * 0.5:
+            numeric_col_indices.append(i)
+
+    # Filter bad rows (non-numeric in numeric columns)
+    bad_rows = set()
+    for i in numeric_col_indices:
+        for ri, r in enumerate(rows):
+            if ri < len(r) and not _is_number(r[i]):
+                bad_rows.add(ri)
+
+    good_rows = [ri for ri in range(len(rows)) if ri not in bad_rows]
+
+    # Build series
+    series = {}
+    for i in numeric_col_indices:
+        vals = [float(rows[ri][i]) for ri in good_rows if ri < len(rows)]
+        if vals:
+            series[headers[i]] = vals
+
+    labels = [rows[ri][0] for ri in good_rows if ri < len(rows)]
+
+    # --- Chart-specific conversions ---
+    if chart_type in ('scatter',) and series:
+        return _convert_to_scatter(headers, rows, good_rows, numeric_col_indices)
+
+    if chart_type in ('box', 'boxplot', 'violin') and series:
+        return _convert_to_grouped(headers, rows, good_rows, labels, numeric_col_indices)
+
+    if chart_type in ('heatmap',) and series:
+        matrix = list(series.values())
+        return {
+            "matrix": matrix,
+            "row_labels": list(series.keys()),
+            "col_labels": labels,
+        }
+
+    if chart_type in ('pie',) and series:
+        first_key = list(series.keys())[0]
+        return {"labels": labels, "values": series[first_key]}
+
+    if chart_type in ('histogram',) and series:
+        first_key = list(series.keys())
+        if len(first_key) == 1:
+            return {"values": series[first_key[0]], "name": first_key[0]}
+        return {"series": series}
+
+    if chart_type in ('radar',):
+        return {"labels": labels, "series": series}
+
+    # Default: bar/line format
+    return {"labels": labels, "series": series}
+
+
+def _convert_to_scatter(headers, rows, good_rows, numeric_col_indices):
+    """Convert tabular data to scatter format."""
+    all_numeric = []
+    for i, h in enumerate(headers):
+        num_count = sum(1 for ri in good_rows if ri < len(rows) and _is_number(rows[ri][i]))
+        if num_count > len(good_rows) * 0.5:
+            all_numeric.append((i, h))
+
+    if len(all_numeric) < 2:
+        col_i, col_name = all_numeric[0]
+        y_vals = [float(rows[ri][col_i]) for ri in good_rows if ri < len(rows)]
+        labels = [rows[ri][0] for ri in good_rows]
+        if labels and all(_is_number(l) for l in labels):
+            return {"x": [float(l) for l in labels], "y": y_vals}
+        return {"x": list(range(len(y_vals))), "y": y_vals}
+
+    col_i, col_x_name = all_numeric[0]
+    col_j, col_y_name = all_numeric[1]
+    x_vals = [float(rows[ri][col_i]) for ri in good_rows if ri < len(rows) and col_i < len(rows[ri])]
+    y_vals = [float(rows[ri][col_j]) for ri in good_rows if ri < len(rows) and col_j < len(rows[ri])]
+
+    # Try to find grouping column
+    groups = None
+    _group_hints = {'group', 'groups', 'category', 'categories', 'class', 'label', 'type'}
+    candidates = []
+    for i, h in enumerate(headers):
+        if i in [idx for idx, _ in all_numeric]:
+            continue
+        vals = [rows[ri][i] for ri in good_rows if ri < len(rows)]
+        unique = set(vals)
+        if 1 < len(unique) <= 20:
+            score = (0, len(unique), i)
+            if h.lower().strip() in _group_hints:
+                score = (-1, len(unique), i)
+            candidates.append((score, vals, h))
+
+    if candidates:
+        candidates.sort()
+        groups = candidates[0][1]
+
+    result = {"x": x_vals, "y": y_vals}
+    if groups:
+        result["groups"] = groups
+    return result
+
+
+def _convert_to_grouped(headers, rows, good_rows, labels, numeric_col_indices):
+    """Convert tabular to box/violin (grouped long-format) format."""
+    first_col_vals = [rows[ri][0] for ri in good_rows if ri < len(rows)]
+    unique_groups = list(dict.fromkeys(first_col_vals))
+
+    if len(unique_groups) < len(first_col_vals) * 0.8 and len(unique_groups) >= 2:
+        num_col_idx = numeric_col_indices[0] if numeric_col_indices else None
+        if num_col_idx is not None:
+            grouped = {g: [] for g in unique_groups}
+            for ri in good_rows:
+                if ri < len(rows) and num_col_idx < len(rows[ri]):
+                    g = rows[ri][0]
+                    v = rows[ri][num_col_idx]
+                    if _is_number(v):
+                        grouped[g].append(float(v))
+            if any(len(v) >= 2 for v in grouped.values()):
+                return {"labels": unique_groups, "series": grouped}
+
+    # Fallback: wide format
+    series = {}
+    for i in numeric_col_indices:
+        vals = [float(rows[ri][i]) for ri in good_rows if ri < len(rows)]
+        if vals:
+            series[headers[i]] = vals
+    return {"labels": labels if labels else list(series.keys()), "series": series}

package/scripts/fig_3d.py

@@ -0,0 +1,103 @@
+#!/usr/bin/env python3
+"""3D chart generator: surface, contour, 3D scatter, wireframe."""
+import numpy as np
+import matplotlib.pyplot as plt
+
+
+def gen_surface(data, ax, colors, cjk_fp=None, **kwargs):
+    """Generate 3D surface plot.
+
+    Accepts either:
+      - "matrix": 2D array (rows = y, cols = x). Optional "x"/"y" coordinate vectors.
+      - "z": 2D array directly (with optional "x"/"y"), or 1D grid values whose
+        length equals len(x)*len(y) in row-major order. Otherwise falls back to a
+        3D scatter plot.
+    """
+    matrix = data.get("matrix")
+    x = data.get("x")
+    y = data.get("y")
+    z = data.get("z")
+
+    if matrix is not None:
+        Z = np.array(matrix, dtype=float)
+        if x is not None and y is not None:
+            X, Y = np.meshgrid(np.array(x, dtype=float), np.array(y, dtype=float))
+        else:
+            X, Y = np.meshgrid(range(Z.shape[1]), range(Z.shape[0]))
+    elif z is not None:
+        Z = np.array(z, dtype=float)
+        if Z.ndim == 2:
+            if x is not None and y is not None:
+                X, Y = np.meshgrid(np.array(x, dtype=float), np.array(y, dtype=float))
+            else:
+                X, Y = np.meshgrid(range(Z.shape[1]), range(Z.shape[0]))
+        elif Z.ndim == 1 and x is not None and y is not None:
+            X = np.array(x, dtype=float)
+            Y = np.array(y, dtype=float)
+            if len(Z) == len(X) * len(Y):
+                # meshgrid default 'xy' indexing matches row-major (C-order) Z
+                X, Y = np.meshgrid(X, Y)
+                Z = Z.reshape(X.shape)
+            else:
+                return gen_scatter3d(data, ax, colors, cjk_fp, **kwargs)
+        else:
+            return gen_scatter3d(data, ax, colors, cjk_fp, **kwargs)
+    else:
+        # 3D scatter fallback — x, y, z vectors
+        return gen_scatter3d(data, ax, colors, cjk_fp, **kwargs)
+
+    cmap = kwargs.get("cmap", "viridis")
+    surf = ax.plot_surface(X, Y, Z, cmap=cmap, alpha=0.9, linewidth=0, antialiased=True,
+                           edgecolor='none')
+
+    # Contour projection on the floor
+    if kwargs.get("contour_floor", False):
+        ax.contour(X, Y, Z, zdir='z', offset=Z.min(), cmap=cmap, alpha=0.5, linewidths=0.5)
+
+    return surf
+
+
+def gen_contour(data, ax, colors, cjk_fp=None, **kwargs):
+    """Generate 2D contour plot."""
+    matrix = data.get("matrix")
+    if matrix is None:
+        return None
+    matrix = np.array(matrix, dtype=float)
+
+    x = data.get("x")
+    y = data.get("y")
+    if x is not None and y is not None:
+        X, Y = np.meshgrid(np.array(x, dtype=float), np.array(y, dtype=float))
+    else:
+        X, Y = np.meshgrid(range(matrix.shape[1]), range(matrix.shape[0]))
+
+    cmap = kwargs.get("cmap", "viridis")
+    levels = kwargs.get("contour_levels", 10)
+    filled = kwargs.get("filled", True)
+
+    if filled:
+        cf = ax.contourf(X, Y, matrix, levels=levels, cmap=cmap, alpha=0.9)
+        ax.contour(X, Y, matrix, levels=levels, colors='black', linewidths=0.3, alpha=0.4)
+    else:
+        cf = ax.contour(X, Y, matrix, levels=levels, cmap=cmap, linewidths=1.2)
+
+    ax.clabel(cf, inline=True, fontsize=8)
+    ax.set_aspect('equal')
+    return cf
+
+
+def gen_scatter3d(data, ax, colors, cjk_fp=None, **kwargs):
+    """Generate 3D scatter plot."""
+    x = np.array(data.get("x", []), dtype=float)
+    y = np.array(data.get("y", []), dtype=float)
+    z = np.array(data.get("z", []), dtype=float)
+    groups = data.get("groups", None)
+
+    if groups is None:
+        ax.scatter(x, y, z, s=40, c=colors[0], alpha=0.7)
+    else:
+        unique_groups = sorted(set(groups), key=list(groups).index)
+        for i, g in enumerate(unique_groups):
+            mask = np.array([j for j in range(len(groups)) if groups[j] == g])
+            ax.scatter(x[mask], y[mask], z[mask], s=40,
+                       c=colors[i % len(colors)], alpha=0.7, label=g)

package/scripts/fig_area.py

@@ -0,0 +1,57 @@
+#!/usr/bin/env python3
+"""Area / stacked-area chart generator."""
+import numpy as np
+from fig_core import set_ticklabels
+
+
+def gen_area(data, ax, colors, cjk_fp=None, **kwargs):
+    """Generate area chart.
+
+    Data schema (JSON):
+      {
+        "labels":  [x categories or numbers],
+        "series":  {"name": [values], ...},
+        "stacked": true | false   (optional, default: passed via --stacked)
+      }
+    When stacked, series fill cumulatively; otherwise each is filled from zero.
+    """
+    labels = data.get("labels", [])
+    series = data.get("series", {})
+    stacked = data.get("stacked", kwargs.get("stacked", True))
+    markers = ['o', 's', 'D', '^', 'v', 'p', '*', 'h', '+', 'x']
+
+    numeric = all(
+        isinstance(l, (int, float)) or
+        (isinstance(l, str) and l.replace('.', '', 1).replace('-', '', 1).isdigit())
+        for l in labels
+    )
+    if numeric and labels:
+        x = np.array([float(l) for l in labels])
+    else:
+        x = np.arange(len(labels)) if labels else np.arange(
+            max((len(v) for v in series.values()), default=0))
+
+    names = list(series.keys())
+    if stacked:
+        bottom = np.zeros(len(x))
+        for i, name in enumerate(names):
+            vals = np.array(series[name], dtype=float)
+            c = colors[i % len(colors)]
+            ax.fill_between(x[:len(vals)], bottom, bottom + vals, color=c, alpha=0.6,
+                           label=name, zorder=2)
+            ax.plot(x[:len(vals)], bottom + vals, color=c, linewidth=1.2, zorder=3)
+            bottom = bottom + vals
+    else:
+        for i, name in enumerate(names):
+            vals = np.array(series[name], dtype=float)
+            c = colors[i % len(colors)]
+            ax.fill_between(x[:len(vals)], 0, vals, color=c, alpha=0.4, zorder=2)
+            ax.plot(x[:len(vals)], vals, marker=markers[i % len(markers)], color=c,
+                    linewidth=2, label=name, zorder=3)
+
+    if not numeric and labels:
+        ax.set_xticks(x)
+        set_ticklabels(ax, labels, 'x', cjk_fp)
+    if len(x):
+        ax.set_xlim(x.min(), x.max())
+    return None

package/scripts/fig_bar.py

@@ -0,0 +1,117 @@
+#!/usr/bin/env python3
+"""Bar chart generator: grouped bar charts with error bars and significance markers."""
+import numpy as np
+
+
+def gen_bar(data, ax, colors, cjk_fp=None, **kwargs):
+    """Generate grouped bar chart."""
+    labels = data.get("labels", [])
+    series = data.get("series", {})
+    error_data = data.get("errors", {})
+    significance = data.get("significance", {})
+
+    n_groups = len(labels)
+    n_series = len(series)
+    x = np.arange(n_groups)
+    w = 0.8 / max(n_series, 1)
+
+    for i, (name, values) in enumerate(series.items()):
+        offset = (i - (n_series - 1) / 2) * w
+        errs = error_data.get(name, None)
+        if isinstance(errs, list):
+            if len(errs) != len(values):
+                errs = None
+        elif isinstance(errs, (int, float)):
+            errs = [errs] * len(values)
+
+        bars = ax.bar(x + offset, values, w, yerr=errs,
+                      color=colors[i % len(colors)], edgecolor='white', linewidth=0.5,
+                      capsize=3, error_kw={'linewidth': 1}, label=name)
+
+        if kwargs.get("show_values", False):
+            for j, v in enumerate(values):
+                err = errs[j] if errs and j < len(errs) else 0
+                ax.text(x[j] + offset, v + err + np.nanmax(values) * 0.01,
+                        f'{v:.1f}', ha='center', va='bottom', fontsize=7,
+                        color=colors[i % len(colors)])
+
+    # Significance brackets
+    if significance:
+        _draw_significance(ax, x, significance)
+
+    ax.set_xticks(x)
+    from fig_core import set_ticklabels
+    set_ticklabels(ax, labels, 'x', cjk_fp)
+
+
+def _draw_significance(ax, x, significance):
+    """Draw significance annotations.
+
+    - key "i,j" -> a bracket spanning group i and group j, with the label
+      centered above; multiple brackets stack automatically.
+    - key "i"    -> a standalone label above group i (legacy/fallback).
+    Labels "NS"/"ns"/"n.s." are drawn in gray (non-significant).
+    """
+    ymax = ax.get_ylim()[1]
+    ax.set_ylim(top=ymax * 1.18)  # headroom for brackets
+    ymax = ax.get_ylim()[1]
+    h = ymax * 0.025  # bracket tick height
+    level = 0
+    for key, label in significance.items():
+        parts = [p.strip() for p in key.split(",")]
+        is_sig = label not in ('NS', 'ns', 'n.s.')
+        fc = '#C0392B' if is_sig else 'gray'
+        fw = 'bold' if is_sig else 'normal'
+        if len(parts) >= 2:
+            try:
+                i, j = int(parts[0]), int(parts[1])
+            except ValueError:
+                continue
+            if i >= len(x) or j >= len(x):
+                continue
+            y = ymax * (0.86 - 0.07 * level)
+            x0, x1 = x[i], x[j]
+            ax.plot([x0, x0, x1, x1], [y - h, y, y, y - h], lw=1, color='#333333')
+            ax.text((x0 + x1) / 2, y + h, label, ha='center', va='bottom',
+                    fontsize=9, fontweight=fw, color=fc)
+            level += 1
+        else:
+            try:
+                idx = int(parts[0])
+            except ValueError:
+                continue
+            if idx >= len(x):
+                continue
+            ax.annotate(label, (x[idx], ymax * 0.92), ha='center', va='bottom',
+                        fontsize=9, fontweight=fw, color=fc)
+
+
+def gen_stacked_bar(data, ax, colors, cjk_fp=None, **kwargs):
+    """Generate stacked bar chart (one bar per group, series stacked)."""
+    labels = data.get("labels", [])
+    series = data.get("series", {})
+    error_data = data.get("errors", {})
+    x = np.arange(len(labels))
+    w = 0.6
+    bottom = np.zeros(len(labels))
+
+    for i, (name, values) in enumerate(series.items()):
+        vals = np.array(values, dtype=float)
+        ax.bar(x, vals, w, bottom=bottom, label=name,
+               color=colors[i % len(colors)], edgecolor='white', linewidth=0.5)
+        if kwargs.get("show_values", False):
+            for j, v in enumerate(vals):
+                ax.text(x[j], bottom[j] + v / 2, f'{v:.1f}', ha='center', va='center',
+                        fontsize=7, color='white' if i == 0 else 'black')
+        # optional error bars on the stacked total
+        errs = error_data.get(name)
+        if isinstance(errs, list) and len(errs) == len(vals):
+            ax.errorbar(x, bottom + vals, yerr=errs, fmt='none',
+                        ecolor='#333333', capsize=3, lw=1)
+        bottom = bottom + vals
+
+    ax.set_xticks(x)
+    from fig_core import set_ticklabels
+    set_ticklabels(ax, labels, 'x', cjk_fp)
+    if len(bottom) > 0:
+        ax.set_ylim(0, bottom.max() * 1.1)