like-sci-figures 0.0.0-stage → 1.0.0

package/scripts/fig_environ.py

@@ -0,0 +1,239 @@
+#!/usr/bin/env python3
+"""Environmental statistics suite: corr_matrix, hexbin, ecdf, bland_altman.
+
+These four chart types are the standard "environmental statistics toolkit"
+used in air/water/soil quality analysis, model-vs-observation evaluation,
+and measurement-method agreement studies:
+
+    corr_matrix    Pearson correlation matrix heatmap (variables x variables)
+    hexbin         Hexagonal binned density scatter (dense point clouds)
+    ecdf           Empirical cumulative distribution function (multi-group)
+    bland_altman   Bland-Altman agreement plot (two methods, bias + 1.96SD LoA)
+
+Each is implemented as a ChartPlugin subclass for automatic palette
+integration and registry consistency.
+"""
+import numpy as np
+from chart_plugin import ChartPlugin
+
+
+def _load_cjk_font(font_path):
+    if not font_path:
+        return None
+    try:
+        from matplotlib import font_manager as fm
+        return fm.FontProperties(fname=font_path)
+    except Exception:
+        return None
+
+
+class CorrMatrixPlot(ChartPlugin):
+    """Pearson correlation matrix heatmap.
+
+    Inputs (either form):
+        matrix: 2D array, rows = samples, columns = variables
+        series: dict {variable_name: [sample values, ...]}
+    Optionally `labels` names the variables (must match the variable count).
+    Rendering is symmetric in [-1, 1] with a diverging colormap (default
+    RdBu_r), so positive correlations are warm/red and negative cool/blue.
+    """
+    name = "corr_matrix"
+    zh = "相关矩阵"
+    kind = "relational"
+    required_keys = ()
+    optional_keys = ("matrix", "series", "labels", "method")
+    data_format = "both"
+
+    def render(self, data, ax, colors, cjk_fp, **kwargs):
+        labels = data.get("labels") or data.get("row_labels") or []
+
+        if "matrix" in data and data["matrix"] is not None:
+            mat = np.asarray(data["matrix"], dtype=float)
+            # rows = samples, cols = variables -> correlate over variables
+            if mat.ndim != 2 or mat.shape[1] < 2:
+                raise ValueError("corr_matrix: matrix needs >= 2 variable columns")
+            n_vars = mat.shape[1]
+            if not labels:
+                labels = ["V%d" % (i + 1) for i in range(n_vars)]
+            corr = np.corrcoef(mat, rowvar=False)
+        elif data.get("series"):
+            series = data["series"]
+            keys = list(series.keys())
+            arr = np.array([np.asarray(v, dtype=float) for v in series.values()])
+            if arr.ndim != 2 or arr.shape[0] < 2:
+                raise ValueError("corr_matrix: series needs >= 2 variables")
+            n_vars = arr.shape[0]
+            labels = labels or keys
+            # rows = variables, cols = samples -> correlate over samples
+            corr = np.corrcoef(arr, rowvar=True)
+        else:
+            raise ValueError("corr_matrix: provide 'matrix' or 'series'")
+
+        if len(labels) != n_vars:
+            labels = ["V%d" % (i + 1) for i in range(n_vars)]
+
+        cmap = kwargs.get("cmap") or "RdBu_r"
+        im = ax.imshow(corr, cmap=cmap, vmin=-1.0, vmax=1.0, aspect="auto")
+
+        # Annotate each cell; text colour contrasts against the diverging cmap.
+        for i in range(n_vars):
+            for j in range(n_vars):
+                v = corr[i, j]
+                color = "white" if abs(v) > 0.55 else "black"
+                ax.text(j, i, "%.2f" % v, ha="center", va="center",
+                        fontsize=8, fontweight="bold", color=color)
+
+        from fig_core import set_ticklabels
+        ax.set_xticks(range(n_vars))
+        ax.set_yticks(range(n_vars))
+        set_ticklabels(ax, labels, "x", cjk_fp, rotation=45)
+        set_ticklabels(ax, labels, "y", cjk_fp)
+
+        ax.set_xlabel("Variable")
+        ax.set_ylabel("Variable")
+        return im  # for colorbar
+
+
+class HexbinPlot(ChartPlugin):
+    """Hexagonal binned density scatter for dense point clouds.
+
+    Useful when a plain scatter is overplotted (tens of thousands of points):
+    the bin colour encodes local point density. A 1:1 dashed line and an
+    r / RMSE annotation make this a natural model-vs-observation plot.
+    """
+    name = "hexbin"
+    zh = "六边形分箱密度图"
+    kind = "relational"
+    required_keys = ("x", "y")
+    optional_keys = ("gridsize", "bins", "line", "stats", "xlabel", "ylabel")
+    data_format = "both"
+
+    def render(self, data, ax, colors, cjk_fp, **kwargs):
+        x = np.asarray(data["x"], dtype=float).ravel()
+        y = np.asarray(data["y"], dtype=float).ravel()
+        if len(x) < 2 or len(y) < 2 or len(x) != len(y):
+            raise ValueError("hexbin: x and y must be same-length arrays (>=2 points)")
+
+        gridsize = int(data.get("gridsize", 25))
+        cmap = kwargs.get("cmap") or "viridis"
+        hb = ax.hexbin(x, y, gridsize=gridsize, cmap=cmap, mincnt=1,
+                       linewidths=0.2, edgecolors="face")
+
+        # 1:1 reference line (model == observed)
+        if data.get("line", True):
+            lo = min(x.min(), y.min())
+            hi = max(x.max(), y.max())
+            ax.plot([lo, hi], [lo, hi], "r--", lw=1.2, alpha=0.8, label="1:1")
+
+        # Goodness-of-fit annotation
+        if data.get("stats", True):
+            r = float(np.corrcoef(x, y)[0, 1])
+            rmse = float(np.sqrt(np.mean((y - x) ** 2)))
+            fp = _load_cjk_font(cjk_fp)
+            ax.text(0.03, 0.97, "r = %.3f\nRMSE = %.3f" % (r, rmse),
+                    transform=ax.transAxes, va="top", ha="left", fontsize=8,
+                    fontproperties=fp,
+                    bbox=dict(boxstyle="round,pad=0.3", fc="white",
+                              ec="0.6", alpha=0.85))
+
+        ax.set_xlabel(data.get("xlabel", "X (measured)"))
+        ax.set_ylabel(data.get("ylabel", "Y (predicted)"))
+        return hb  # for colorbar
+
+
+class ECDFPlot(ChartPlugin):
+    """Empirical cumulative distribution function (multi-group).
+
+    Inputs (either form):
+        series: dict {group_name: [values, ...]}  -> one step curve per group
+        x:      single array of values             -> one step curve
+    Step curves ('steps-post') let you compare distributions without binning,
+    which is the standard tool for model validation / quantile comparisons.
+    """
+    name = "ecdf"
+    zh = "经验累积分布"
+    kind = "statistics"
+    required_keys = ()
+    optional_keys = ("series", "x", "labels", "xlabel", "ylabel")
+    data_format = "both"
+
+    def render(self, data, ax, colors, cjk_fp, **kwargs):
+        series = data.get("series")
+        if series:
+            keys = list(series.keys())
+            labels = data.get("labels") or keys
+            for i, key in enumerate(keys):
+                vals = np.sort(np.asarray(series[key], dtype=float).ravel())
+                if len(vals) == 0:
+                    continue
+                y = np.arange(1, len(vals) + 1) / len(vals)
+                color = colors[i % len(colors)] if colors else None
+                lbl = labels[i % len(labels)] if labels else str(key)
+                ax.plot(vals, y, drawstyle="steps-post", lw=1.6,
+                        color=color, label=str(lbl))
+        elif data.get("x") is not None:
+            vals = np.sort(np.asarray(data["x"], dtype=float).ravel())
+            if len(vals) == 0:
+                raise ValueError("ecdf: x is empty")
+            y = np.arange(1, len(vals) + 1) / len(vals)
+            ax.plot(vals, y, drawstyle="steps-post", lw=1.6,
+                    color=colors[0] if colors else None)
+        else:
+            raise ValueError("ecdf: provide 'series' or 'x'")
+
+        ax.set_xlabel(data.get("xlabel", "Value"))
+        ax.set_ylabel(data.get("ylabel", "Cumulative probability"))
+        ax.set_ylim(0, 1.05)
+        return None
+
+
+class BlandAltmanPlot(ChartPlugin):
+    """Bland-Altman agreement plot between two measurement methods.
+
+    Inputs (either form):
+        x / y:       two same-length arrays of paired measurements
+        method1/method2: alternative key names for the two methods
+    Plots the mean of the pair vs. their difference, with the mean bias
+    (solid line) and the 95% limits of agreement bias +/- 1.96 SD (dashed).
+    """
+    name = "bland_altman"
+    zh = "Bland-Altman图"
+    kind = "statistics"
+    required_keys = ()
+    optional_keys = ("x", "y", "method1", "method2", "xlabel", "ylabel")
+    data_format = "both"
+
+    def render(self, data, ax, colors, cjk_fp, **kwargs):
+        if data.get("x") is not None and data.get("y") is not None:
+            m1 = np.asarray(data["x"], dtype=float).ravel()
+            m2 = np.asarray(data["y"], dtype=float).ravel()
+        elif data.get("method1") is not None and data.get("method2") is not None:
+            m1 = np.asarray(data["method1"], dtype=float).ravel()
+            m2 = np.asarray(data["method2"], dtype=float).ravel()
+        else:
+            raise ValueError("bland_altman: provide 'x'+'y' or 'method1'+'method2'")
+        if len(m1) < 3 or len(m1) != len(m2):
+            raise ValueError("bland_altman: need >=3 same-length paired measurements")
+
+        mean = (m1 + m2) / 2.0
+        diff = m1 - m2
+        bias = float(np.mean(diff))
+        sd = float(np.std(diff, ddof=1))
+        loa_hi = bias + 1.96 * sd
+        loa_lo = bias - 1.96 * sd
+
+        color = colors[0] if colors else None
+        ax.scatter(mean, diff, s=40, color=color, edgecolors="black",
+                   linewidths=0.4, alpha=0.85)
+
+        ax.axhline(bias, color="#C0392B", lw=1.5, ls="-",
+                   label="Mean bias %.2f" % bias)
+        ax.axhline(loa_hi, color="#2C3E50", lw=1.0, ls="--",
+                   label="LoA +1.96SD %.2f" % loa_hi)
+        ax.axhline(loa_lo, color="#2C3E50", lw=1.0, ls="--",
+                   label="LoA -1.96SD %.2f" % loa_lo)
+        ax.axhline(0, color="gray", lw=0.8, ls=":")
+
+        ax.set_xlabel(data.get("xlabel", "Mean of two methods"))
+        ax.set_ylabel(data.get("ylabel", "Difference (method1 - method2)"))
+        return None

package/scripts/fig_errorbar.py

@@ -0,0 +1,49 @@
+#!/usr/bin/env python3
+"""Error-bar scatter generator (x-y points with optional xerr / yerr)."""
+import numpy as np
+
+
+def gen_errorbar(data, ax, colors, cjk_fp=None, **kwargs):
+    """Generate x-y error-bar plot.
+
+    Data schema (JSON):
+      {
+        "x":     [numbers],
+        "y":     [numbers],
+        "xerr":  [numbers] (optional),
+        "yerr":  [numbers] (optional),
+        "groups":[labels]  (optional)
+      }
+    At least one of xerr / yerr should be present; otherwise it falls back to a
+    plain scatter.
+    """
+    x = np.array(data.get("x", []), dtype=float)
+    y = np.array(data.get("y", []), dtype=float)
+    xerr = data.get("xerr")
+    yerr = data.get("yerr")
+    groups = data.get("groups")
+    fmt = kwargs.get("fmt", 'o')
+
+    xerr_a = np.array(xerr, dtype=float) if xerr is not None else None
+    yerr_a = np.array(yerr, dtype=float) if yerr is not None else None
+
+    if groups is None:
+        ax.errorbar(x, y, xerr=xerr_a, yerr=yerr_a, fmt=fmt, color=colors[0],
+                    ecolor='gray', capsize=3, elinewidth=1, markersize=6, zorder=3)
+    else:
+        seen, uniq = {}, []
+        for g in groups:
+            if g not in seen:
+                seen[g] = True
+                uniq.append(g)
+        for i, g in enumerate(uniq):
+            mask = np.array([j for j in range(len(groups)) if groups[j] == g])
+            xe = xerr_a[mask] if xerr_a is not None else None
+            ye = yerr_a[mask] if yerr_a is not None else None
+            c = colors[i % len(colors)]
+            ax.errorbar(x[mask], y[mask], xerr=xe, yerr=ye, fmt=fmt, color=c,
+                        ecolor=c, capsize=3, elinewidth=1, markersize=6,
+                        label=str(g), zorder=3)
+
+    ax.xaxis.grid(True, alpha=0.3, linestyle='--')
+    return None

package/scripts/fig_forest.py

@@ -0,0 +1,54 @@
+#!/usr/bin/env python3
+"""Forest plot generator for meta-analysis."""
+import numpy as np
+
+
+def gen_forest(data, ax, colors, cjk_fp=None, **kwargs):
+    """Generate forest plot (meta-analysis style)."""
+    labels = data.get("labels", data.get("studies", []))
+    estimates = data.get("estimates", [])
+    ci_low = data.get("ci_low", [])
+    ci_high = data.get("ci_high", [])
+    overall = data.get("overall", None)
+    ref_line = data.get("ref_line", 0)
+
+    y_pos = list(range(len(labels)))
+
+    # Draw CI lines and point estimates
+    for i, (est, lo, hi) in enumerate(zip(estimates, ci_low, ci_high)):
+        ax.plot([lo, hi], [i, i], '-', color=colors[0], linewidth=1.5, zorder=2)
+        ax.scatter(est, i, c=colors[0], s=80, zorder=3, edgecolors='black', linewidth=0.5)
+
+    # Reference line
+    ax.axvline(x=ref_line, color='gray', linestyle='--', linewidth=1, alpha=0.6)
+
+    # Overall diamond
+    if overall:
+        oy = len(labels)
+        est_o, lo_o, hi_o = overall["estimate"], overall["ci_low"], overall["ci_high"]
+        diamond_x = [lo_o, est_o, hi_o, est_o, lo_o]
+        diamond_y = [oy, oy - 0.2, oy, oy + 0.2, oy]
+        ax.fill(diamond_x, diamond_y, color=colors[1] if len(colors) > 1 else colors[0],
+                alpha=0.7, zorder=4)
+
+    # Set y-axis labels (study names)
+    ax.set_yticks(list(y_pos) + ([len(labels)] if overall else []))
+    all_labels = list(labels) + (["Overall"] if overall else [])
+    from fig_core import set_ticklabels
+    set_ticklabels(ax, all_labels, 'y', cjk_fp)
+    ax.invert_yaxis()
+
+    # Place value annotations in a dedicated column to the right of the CI lines.
+    # We expand the x-axis so the column stays inside the axes area and is never
+    # clipped by the figure edge or tight_layout.
+    x_min, x_max = ax.get_xlim()
+    x_range = x_max - x_min
+    text_x = x_max + x_range * 0.02
+    for i, (est, lo, hi) in enumerate(zip(estimates, ci_low, ci_high)):
+        ax.text(text_x, i, f'{est:.2f} [{lo:.2f}, {hi:.2f}]',
+                va='center', fontsize=8, clip_on=False)
+    if overall:
+        ax.text(text_x, oy, f'Overall: {est_o:.2f} [{lo_o:.2f}, {hi_o:.2f}]',
+                va='center', fontsize=9, fontweight='bold', clip_on=False)
+    # Reserve ~40% of the x-range as an annotation gutter.
+    ax.set_xlim(x_min, x_max + x_range * 0.45)

package/scripts/fig_heatmap.py

@@ -0,0 +1,51 @@
+#!/usr/bin/env python3
+"""Heatmap generator with annotations."""
+import numpy as np
+import matplotlib.pyplot as plt
+
+
+def gen_heatmap(data, ax, colors, cjk_fp=None, **kwargs):
+    """Generate annotated heatmap."""
+    matrix = data.get("matrix")
+    if matrix is None:
+        series = data.get("series", {})
+        if series:
+            matrix = np.array(list(series.values()))
+        else:
+            matrix = np.array([])
+
+    matrix = np.array(matrix, dtype=float)
+    row_labels = data.get("row_labels", data.get("labels", []))
+    col_labels = data.get("col_labels", [])
+    if not col_labels and "series" in data:
+        col_labels = data.get("labels", list(data["series"].keys()))
+
+    cmap = kwargs.get("cmap", "RdBu_r")
+    vmin = kwargs.get("vmin", None)
+    vmax = kwargs.get("vmax", None)
+    annot_fmt = kwargs.get("annot_format", "{:+.1f}")
+    center = kwargs.get("center", None)
+
+    if vmin is None or vmax is None:
+        abs_max = max(abs(matrix.min()), abs(matrix.max()))
+        vmin = vmin if vmin is not None else -abs_max
+        vmax = vmax if vmax is not None else abs_max
+
+    im = ax.imshow(matrix, cmap=cmap, vmin=vmin, vmax=vmax, aspect='auto')
+
+    # Text annotations
+    for i in range(matrix.shape[0]):
+        for j in range(matrix.shape[1]):
+            v = matrix[i, j]
+            clim = abs(vmin) + abs(vmax) if vmin is not None and vmax is not None else 2
+            color = 'white' if abs(v) > clim / 2 * 0.7 else 'black'
+            ax.text(j, i, annot_fmt.format(v), ha='center', va='center',
+                    fontsize=9, fontweight='bold', color=color)
+
+    ax.set_xticks(range(len(col_labels)))
+    ax.set_yticks(range(len(row_labels)))
+    from fig_core import set_ticklabels
+    set_ticklabels(ax, col_labels, 'x', cjk_fp)
+    set_ticklabels(ax, row_labels, 'y', cjk_fp)
+
+    return im  # for colorbar

package/scripts/fig_line.py

@@ -0,0 +1,39 @@
+#!/usr/bin/env python3
+"""Line chart generator with error bands and markers."""
+import numpy as np
+
+
+def gen_line(data, ax, colors, cjk_fp=None, **kwargs):
+    """Generate line chart with optional error bands."""
+    labels = data.get("labels", [])
+    series = data.get("series", {})
+    error_data = data.get("errors", {})
+    markers = ['o', 's', 'D', '^', 'v', 'p', '*', 'h', '+', 'x']
+
+    # Determine x: use labels if numeric, otherwise use index
+    numeric_labels = all(isinstance(l, (int, float)) or (isinstance(l, str) and l.replace('.', '', 1).replace('-', '', 1).isdigit())
+                         for l in labels)
+    if numeric_labels 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()))
+
+    for i, (name, values) in enumerate(series.items()):
+        c = colors[i % len(colors)]
+        mk = markers[i % len(markers)]
+        lw = kwargs.get("linewidth", 2)
+        ax.plot(x[:len(values)], values, c=c, marker=mk, markersize=6,
+                linewidth=lw, label=name, zorder=3)
+
+        # Error band
+        if name in error_data and error_data[name]:
+            errs = error_data[name]
+            if isinstance(errs, list) and len(errs) == len(values):
+                lower = [v - e for v, e in zip(values, errs)]
+                upper = [v + e for v, e in zip(values, errs)]
+                ax.fill_between(x[:len(values)], lower, upper, color=c, alpha=0.15, zorder=2)
+
+    if not numeric_labels and labels:
+        ax.set_xticks(x)
+        from fig_core import set_ticklabels
+        set_ticklabels(ax, labels, 'x', cjk_fp)

package/scripts/fig_pca.py

@@ -0,0 +1,101 @@
+#!/usr/bin/env python3
+"""PCA biplot generator (sample scores + variable loadings), numpy-only."""
+import numpy as np
+
+
+def gen_pca(data, ax, colors, cjk_fp=None, **kwargs):
+    """Generate a PCA biplot.
+
+    Data schema (JSON):
+      {
+        "variables":     ["V1", "V2", ...],      # column names
+        "samples":       [[...], [...], ...],     # row-wise observations
+        "groups":        [labels]   (optional),   # color coding of samples
+        "sample_labels": [text]     (optional)    # per-sample annotation
+      }
+    Columns are z-scored; SVD yields scores (samples) and loadings (variables).
+    PC1/PC2 variance explained is shown on the axes.
+    """
+    variables = data.get("variables", [])
+    samples = np.array(data.get("samples", []), dtype=float)
+    groups = data.get("groups")
+    sample_labels = data.get("sample_labels")
+    n_comp = int(kwargs.get("components", 2))
+
+    if samples.ndim != 2 or samples.shape[1] < 2:
+        return None
+    n, p = samples.shape
+    if not variables:
+        variables = [f"V{i+1}" for i in range(p)]
+
+    mean = samples.mean(axis=0)
+    std = samples.std(axis=0, ddof=0)
+    std[std == 0] = 1.0
+    Z = (samples - mean) / std
+
+    # SVD of standardized data
+    U, S, Vt = np.linalg.svd(Z, full_matrices=False)
+    scores = Z @ Vt.T                       # n x p, columns = PC1, PC2, ...
+    loadings = Vt.T * S                     # p x p, columns = component loadings
+    explained = (S ** 2) / (S ** 2).sum()
+
+    pc1 = scores[:, 0]
+    pc2 = scores[:, 1]
+    max_score = max(np.abs(scores[:, :2]).max(), 1e-9)
+    max_loading = np.abs(loadings[:, :2]).max() if p > 0 else 1e-9
+    scale = 0.8 * max_score / max_loading if max_loading > 0 else 1.0
+
+    if groups is None:
+        ax.scatter(pc1, pc2, s=55, color=colors[0], edgecolors='white', alpha=0.85, zorder=3)
+    else:
+        seen, uniq = {}, []
+        for g in groups:
+            if g not in seen:
+                seen[g] = True
+                uniq.append(g)
+        for i, g in enumerate(uniq):
+            mask = np.array([j for j in range(len(groups)) if groups[j] == g])
+            ax.scatter(pc1[mask], pc2[mask], s=55, color=colors[i % len(colors)],
+                       edgecolors='white', alpha=0.85, label=str(g), zorder=3)
+
+    texts = []
+    if sample_labels is not None:
+        for xi, yi, lb in zip(pc1, pc2, sample_labels):
+            t = ax.annotate(str(lb), (xi, yi), textcoords='offset points', xytext=(3, 3),
+                        fontsize=6, color='gray')
+            texts.append(t)
+
+    # variable loadings as arrows
+    for j, var in enumerate(variables):
+        lx = loadings[j, 0] * scale
+        ly = loadings[j, 1] * scale
+        ax.arrow(0, 0, lx, ly, color='#333333', width=0.008, head_width=0.05,
+                 length_includes_head=True, zorder=2)
+        # anchor label just beyond the arrow tip, pushed a little further outward
+        norm = float(np.hypot(lx, ly))
+        if norm > 0:
+            ox, oy = lx * (1 + 0.08 / norm), ly * (1 + 0.08 / norm)
+        else:
+            ox, oy = lx, ly
+        ha = 'left' if lx >= 0 else 'right'
+        t = ax.text(ox, oy, str(var), fontsize=9, color='#333333',
+                    ha=ha, va='center', zorder=4)
+        texts.append(t)
+
+    from fig_core import separate_labels
+    separate_labels(ax, texts)
+
+    # Add an extra margin so pushed labels are not clipped by the axes edge.
+    xlim = ax.get_xlim()
+    ylim = ax.get_ylim()
+    xpad = (xlim[1] - xlim[0]) * 0.08
+    ypad = (ylim[1] - ylim[0]) * 0.08
+    ax.set_xlim(xlim[0] - xpad, xlim[1] + xpad)
+    ax.set_ylim(ylim[0] - ypad, ylim[1] + ypad)
+
+    ax.axhline(0, color='gray', linewidth=0.6, alpha=0.5, zorder=1)
+    ax.axvline(0, color='gray', linewidth=0.6, alpha=0.5, zorder=1)
+    ax.set_xlabel(f"PC1 ({explained[0]*100:.1f}%)")
+    ax.set_ylabel(f"PC2 ({explained[1]*100:.1f}%)")
+    ax.xaxis.grid(True, alpha=0.3, linestyle='--')
+    return None

package/scripts/fig_pie.py

@@ -0,0 +1,52 @@
+#!/usr/bin/env python3
+"""Pie chart and donut chart generator."""
+import numpy as np
+
+
+def gen_pie(data, ax, colors, cjk_fp=None, **kwargs):
+    """Generate pie chart or donut chart."""
+    labels = data.get("labels", [])
+    values = data.get("values", [])
+
+    if not values and data.get("series"):
+        first_key = list(data["series"].keys())[0]
+        values = data["series"][first_key]
+
+    if not values:
+        return
+
+    donut = kwargs.get("donut", False)
+    wedgeprops = {"width": 0.4, "edgecolor": "white", "linewidth": 1} if donut else \
+                 {"edgecolor": "white", "linewidth": 1}
+
+    show_pct = kwargs.get("show_pct", True)
+    show_labels = kwargs.get("show_labels", True)
+    pctdistance = 0.8 if donut else 0.6
+    textprops = {"fontsize": 9}
+
+    if cjk_fp:
+        textprops["fontproperties"] = cjk_fp
+
+    autopct = '%1.1f%%' if show_pct else None
+    if autopct:
+        wedges, texts, autotexts = ax.pie(
+            values, labels=labels if show_labels else None,
+            autopct=autopct, startangle=90,
+            colors=colors[:len(values)],
+            wedgeprops=wedgeprops,
+            pctdistance=pctdistance,
+            textprops=textprops
+        )
+        for t in autotexts:
+            t.set_fontsize(8)
+    else:
+        wedges, texts = ax.pie(
+            values, labels=labels if show_labels else None,
+            startangle=90,
+            colors=colors[:len(values)],
+            wedgeprops=wedgeprops,
+            textprops=textprops
+        )[:2]
+
+    # Equal aspect ratio
+    ax.set_aspect('equal')

package/scripts/fig_radar.py

@@ -0,0 +1,32 @@
+#!/usr/bin/env python3
+"""Radar chart (spider/radar plot) generator."""
+import numpy as np
+
+
+def gen_radar(data, ax, colors, cjk_fp=None, **kwargs):
+    """Generate radar/spider chart."""
+    labels = data.get("labels", [])
+    series = data.get("series", {})
+
+    if not labels or not series:
+        return
+
+    n_vars = len(labels)
+    angles = np.linspace(0, 2 * np.pi, n_vars, endpoint=False).tolist()
+    angles += angles[:1]  # close the loop
+
+    # Convert to polar
+    ax.set_theta_offset(np.pi / 2)
+    ax.set_theta_direction(-1)
+
+    for i, (name, values) in enumerate(series.items()):
+        vals = list(values) + [values[0]]  # close the loop
+        c = colors[i % len(colors)]
+        ax.fill(angles, vals, alpha=0.15, color=c)
+        ax.plot(angles, vals, 'o-', linewidth=1.5, color=c, label=name, markersize=4)
+        ax.fill(angles, vals, alpha=0.05, color=c)
+
+    ax.set_xticks(angles[:-1])
+    from fig_core import set_ticklabels
+    set_ticklabels(ax, labels, 'x', cjk_fp)
+    ax.set_ylim(bottom=0)