like-sci-figures 0.0.0-stage → 1.0.0

package/scripts/fig_sankey.py

@@ -0,0 +1,196 @@
+#!/usr/bin/env python3
+"""Sankey diagram generator (layered flows), pure matplotlib, no extra deps."""
+import numpy as np
+from collections import defaultdict
+from matplotlib.path import Path
+import matplotlib.patches as mpatches
+
+
+def gen_sankey(data, ax, colors, cjk_fp=None, **kwargs):
+    """Generate a Sankey diagram.
+
+    Data schema (JSON):
+      {
+        "nodes": ["Source A", "Source B", "Receptor", ...],
+        "links": [
+          {"source": "Source A", "target": "Receptor", "value": 30},
+          ...
+        ]
+      }
+    Node layers are inferred by longest-path from sources (no incoming links).
+    Link widths are proportional to their value; colors follow the source node.
+    """
+    nodes = data.get("nodes", [])
+    links = data.get("links", data.get("flows", []))
+    if not nodes or not links:
+        return None
+
+    idx = {name: i for i, name in enumerate(nodes)}
+    L = []
+    for lk in links:
+        if isinstance(lk, dict) and "source" in lk and "target" in lk:
+            s = lk["source"]; t = lk["target"]; v = float(lk.get("value", lk.get("weight", 1)))
+        else:
+            s, t, v = lk[0], lk[1], float(lk[2])
+        if isinstance(s, str): s = idx.get(s, 0)
+        if isinstance(t, str): t = idx.get(t, len(nodes) - 1)
+        L.append((int(s), int(t), v))
+    if not L:
+        return None
+
+    n = len(nodes)
+    ins = np.zeros(n); outs = np.zeros(n)
+    for s, t, v in L:
+        outs[s] += v; ins[t] += v
+    thru = np.maximum(ins, outs)
+    max_thru = thru.max() if thru.max() > 0 else 1.0
+
+    # Layer assignment (longest path from sources)
+    layer = [-1] * n
+    for i in range(n):
+        if ins[i] == 0:
+            layer[i] = 0
+    if all(l < 0 for l in layer):
+        layer = [0] * n
+    guard = 0
+    changed = True
+    while changed and guard < n + 3:
+        changed = False
+        for s, t, v in L:
+            if layer[s] >= 0 and (layer[t] < 0 or layer[t] < layer[s] + 1):
+                layer[t] = layer[s] + 1
+                changed = True
+        guard += 1
+    max_layer = max((l for l in layer if l >= 0), default=0)
+    for i in range(n):
+        if layer[i] < 0:
+            layer[i] = max_layer
+
+    by_layer = defaultdict(list)
+    for i in range(n):
+        by_layer[layer[i]].append(i)
+    n_layers = max(by_layer) + 1
+
+    height_unit = 1.0
+    gap = 0.18
+    nw = 0.03
+
+    def layer_height(li, order):
+        return sum(thru[i] * height_unit for i in order) + gap * (len(order) - 1)
+
+    # adjacency (for barycenter ordering)
+    preds = defaultdict(list); succs = defaultdict(list)
+    for s, t, v in L:
+        succs[s].append(t); preds[t].append(s)
+
+    # initial order: top-to-bottom as declared in `nodes`
+    order = {li: list(by_layer[li]) for li in range(n_layers)}
+    center = {}
+
+    def recompute_centers():
+        max_h_local = max((layer_height(li, order[li]) for li in range(n_layers)), default=1)
+        if max_h_local <= 0:
+            max_h_local = 1
+        for li in range(n_layers):
+            h = layer_height(li, order[li])
+            y = (max_h_local - h) / 2 + h
+            for i in order[li]:
+                center[i] = y - thru[i] * height_unit / 2
+                y -= (thru[i] * height_unit + gap)
+        return max_h_local
+
+    max_h = recompute_centers()
+
+    # barycenter sweeps (top = larger y) to minimise ribbon crossings
+    for _ in range(4):
+        for li in range(1, n_layers):
+            order[li].sort(
+                key=lambda i: -(sum(center[p] for p in preds[i]) / len(preds[i])
+                                if preds[i] else center[i])
+            )
+        recompute_centers()
+        for li in range(n_layers - 2, -1, -1):
+            order[li].sort(
+                key=lambda i: -(sum(center[t] for t in succs[i]) / len(succs[i])
+                                if succs[i] else center[i])
+            )
+        recompute_centers()
+
+    # node vertical extents (top-to-bottom per layer, centred)
+    node_y = {}
+    for li in range(n_layers):
+        h = layer_height(li, order[li])
+        y = (max_h - h) / 2 + h
+        for i in order[li]:
+            th = thru[i] * height_unit
+            node_y[i] = (y - th, y)
+            y -= (th + gap)
+
+    total_w = max(n_layers + (n_layers - 1) * 0.6, 1.0)
+    xs = [0.5 + li * (total_w / n_layers if n_layers > 1 else total_w) for li in range(n_layers)]
+
+    # Assign ribbon slots on both ends so ribbons do not cross:
+    #   outgoing at a node ordered by target vertical position (top first),
+    #   incoming at a node ordered by source vertical position (top first).
+    out_links = defaultdict(list); in_links = defaultdict(list)
+    for k, (s, t, v) in enumerate(L):
+        out_links[s].append(k); in_links[t].append(k)
+
+    y_bot_s = {}; y_bot_t = {}
+    for s, ks in out_links.items():
+        ks.sort(key=lambda k: -center[L[k][1]])
+        top = node_y[s][1]
+        for k in ks:
+            vh = L[k][2] / max_thru * max_h
+            y_bot_s[k] = top - vh
+            top -= vh
+    for t, ks in in_links.items():
+        ks.sort(key=lambda k: -center[L[k][0]])
+        top = node_y[t][1]
+        for k in ks:
+            vh = L[k][2] / max_thru * max_h
+            y_bot_t[k] = top - vh
+            top -= vh
+
+    # Draw links
+    for k, (s, t, v) in enumerate(L):
+        c = colors[s % len(colors)]
+        vh = v / max_thru * max_h
+        y0s = y_bot_s[k]
+        y0t = y_bot_t[k]
+        xs0 = xs[layer[s]] + nw
+        xt0 = xs[layer[t]]
+        xm = (xs0 + xt0) / 2.0
+        verts = [
+            (xs0, y0s),
+            (xm, y0s), (xm, y0t), (xt0, y0t),
+            (xt0, y0t + vh),
+            (xm, y0t + vh), (xm, y0s + vh), (xs0, y0s + vh),
+            (xs0, y0s),
+        ]
+        codes = [
+            Path.MOVETO, Path.CURVE4, Path.CURVE4, Path.CURVE4,
+            Path.LINETO, Path.CURVE4, Path.CURVE4, Path.CURVE4, Path.CLOSEPOLY,
+        ]
+        ax.add_patch(mpatches.PathPatch(Path(verts, codes), facecolor=c, alpha=0.4,
+                                        edgecolor='none', zorder=1))
+
+    # Draw nodes
+    for i in range(n):
+        li = layer[i]
+        x = xs[li]
+        b, tp = node_y[i]
+        ax.add_patch(mpatches.Rectangle((x, b), nw, tp - b, facecolor=colors[i % len(colors)],
+                                        edgecolor='white', linewidth=0.8, zorder=3))
+        # labels
+        if li == 0:
+            ax.text(x - 0.04, (b + tp) / 2, str(nodes[i]), ha='right', va='center', fontsize=9)
+        elif li == max_layer:
+            ax.text(x + nw + 0.04, (b + tp) / 2, str(nodes[i]), ha='left', va='center', fontsize=9)
+        else:
+            ax.text(x + nw / 2, tp + 0.05, str(nodes[i]), ha='center', va='bottom', fontsize=8)
+
+    ax.set_xlim(-0.1, total_w + 0.1)
+    ax.set_ylim(-0.2, max_h + 0.3)
+    ax.axis('off')
+    return None

package/scripts/fig_scatter.py

@@ -0,0 +1,44 @@
+#!/usr/bin/env python3
+"""Scatter plot generator with trend line and grouping."""
+import numpy as np
+
+
+def gen_scatter(data, ax, colors, cjk_fp=None, **kwargs):
+    """Generate scatter plot with optional trend line and grouping."""
+    x_data = np.array(data.get("x", []), dtype=float)
+    y_data = np.array(data.get("y", []), dtype=float)
+    groups = data.get("groups", None)
+
+    if groups is None:
+        ax.scatter(x_data, y_data, s=60, color=colors[0],
+                   edgecolors='white', linewidth=0.5, alpha=0.7, zorder=3)
+    else:
+        from collections import OrderedDict
+        # Preserve insertion order of group labels
+        seen = {}
+        unique_groups = []
+        for g in groups:
+            if g not in seen:
+                seen[g] = True
+                unique_groups.append(g)
+
+        for i, g in enumerate(unique_groups):
+            mask = np.array([j for j in range(len(groups)) if groups[j] == g])
+            c = colors[i % len(colors)]
+            ax.scatter(x_data[mask], y_data[mask], s=60, c=c,
+                       edgecolors='white', linewidth=0.5, alpha=0.7,
+                       label=g, zorder=3)
+
+    # Trend line
+    if kwargs.get("trend", True) and len(x_data) >= 3:
+        z = np.polyfit(x_data, y_data, 1)
+        p = np.poly1d(z)
+        x_line = np.linspace(x_data.min(), x_data.max(), 100)
+        ax.plot(x_line, p(x_line), '--', color='gray', alpha=0.6, linewidth=1.2, zorder=2)
+        r = np.corrcoef(x_data, y_data)[0, 1]
+        ax.text(0.95, 0.05, f'r = {r:.3f}', transform=ax.transAxes,
+                ha='right', va='bottom', fontsize=9, fontstyle='italic', color='gray',
+                bbox=dict(boxstyle='round,pad=0.3', facecolor='white', alpha=0.8,
+                          edgecolor='lightgray'))
+
+    ax.xaxis.grid(True, alpha=0.3, linestyle='--')

package/scripts/fig_subplots.py

@@ -0,0 +1,124 @@
+#!/usr/bin/env python3
+"""Subplots / multi-panel figure generator."""
+import os, sys
+import matplotlib.pyplot as plt
+
+SCRIPT_DIR = os.path.dirname(os.path.abspath(__file__))
+sys.path.insert(0, SCRIPT_DIR)
+
+from fig_core import apply_base_style, set_axis_labels, set_title, set_ticklabels
+from fig_core import finalize_and_save, has_cjk
+
+
+def gen_subplots(subplot_data, fig, axes, colors, cjk_fp=None, **kwargs):
+    """
+    Generate multi-panel subplot figure.
+
+    subplot_data should be a list of dicts, each with:
+      - "type": chart type
+      - "data": data dict for that chart
+      - "title" (optional): subplot title
+      - "xlabel", "ylabel" (optional)
+      - "position" (optional): (row, col) tuple, auto-layout if not provided
+    """
+    layout = kwargs.get("layout", "auto")  # "auto", (rows, cols), or "1x3"
+    titles = kwargs.get("titles", [])
+    sharex = kwargs.get("sharex", False)
+    sharey = kwargs.get("sharey", False)
+
+    if isinstance(subplot_data, list) and len(subplot_data) > 0:
+
+        n = len(subplot_data)
+        # Determine layout
+        if isinstance(layout, tuple) and len(layout) == 2:
+            rows, cols = layout
+        elif layout == "auto":
+            rows = int(n ** 0.5)
+            cols = (n + rows - 1) // rows
+        else:
+            # Parse "RxC" format
+            try:
+                parts = layout.lower().replace("x", " ").split()
+                rows, cols = int(parts[0]), int(parts[1])
+            except Exception:
+                rows, cols = 1, n
+
+        fig2, axes2 = plt.subplots(rows, cols, figsize=(cols * 5, rows * 4))
+        if rows * cols == 1:
+            axes_arr = [axes2]
+        elif rows == 1 or cols == 1:
+            axes_arr = list(axes2) if hasattr(axes2, '__iter__') else [axes2]
+        else:
+            axes_arr = [axes2[r, c] for r in range(rows) for c in range(cols)]
+
+        # Radar panels require a polar axes; replace the plain axes at that slot
+        for idx, item in enumerate(subplot_data):
+            if idx >= len(axes_arr):
+                break
+            if item.get("type") == "radar":
+                old_ax = axes_arr[idx]
+                old_ax.remove()
+                axes_arr[idx] = fig2.add_subplot(rows, cols, idx + 1, polar=True)
+
+        # Import generators on demand
+        from fig_bar import gen_bar
+        from fig_heatmap import gen_heatmap
+        from fig_scatter import gen_scatter
+        from fig_line import gen_line
+        from fig_box import gen_box, gen_violin
+        from fig_forest import gen_forest
+        from fig_distribution import gen_histogram, gen_density
+        from fig_pie import gen_pie
+        from fig_radar import gen_radar
+        from fig_bubble import gen_bubble
+        from fig_area import gen_area
+        from fig_errorbar import gen_errorbar
+        from fig_venn import gen_venn
+
+        GEN_MAP = {
+            "bar": gen_bar, "grouped_bar": gen_bar,
+            "heatmap": gen_heatmap,
+            "scatter": gen_scatter,
+            "line": gen_line,
+            "box": gen_box, "boxplot": gen_box,
+            "violin": gen_violin,
+            "forest": gen_forest,
+            "histogram": gen_histogram, "density": gen_density,
+            "pie": gen_pie, "donut": gen_pie,
+            "radar": gen_radar,
+            "bubble": gen_bubble,
+            "area": gen_area,
+            "errorbar": gen_errorbar,
+            "venn": gen_venn,
+        }
+
+        for idx, item in enumerate(subplot_data):
+            if idx >= len(axes_arr):
+                break
+            ax = axes_arr[idx]
+            chart_type = item.get("type", "bar")
+            chart_data = item.get("data", {})
+
+            gen_func = GEN_MAP.get(chart_type)
+            if gen_func:
+                extra = gen_func(chart_data, ax, colors, cjk_fp)
+            else:
+                continue
+
+            if chart_type not in ("radar", "venn"):
+                apply_base_style(ax)
+            set_axis_labels(ax, item.get("xlabel", ""), item.get("ylabel", ""), cjk_fp)
+            set_title(ax, item.get("title", ""), cjk_fp)
+
+        # Hide unused axes
+        for idx in range(n, len(axes_arr)):
+            axes_arr[idx].set_visible(False)
+
+        # Tighten panel spacing so titles/labels do not overlap.
+        try:
+            fig2.tight_layout(pad=1.2, h_pad=1.5, w_pad=1.2)
+        except Exception:
+            pass
+
+        return fig2
+    return None

package/scripts/fig_taylor.py

@@ -0,0 +1,80 @@
+#!/usr/bin/env python3
+"""Taylor diagram generator (model-vs-observation skill evaluation)."""
+import numpy as np
+
+
+def gen_taylor(data, ax, colors, cjk_fp=None, **kwargs):
+    """Generate a Taylor diagram.
+
+    Data schema (JSON):
+      {
+        "obs_std": 1.0,                       # standard deviation of reference
+        "models": [
+          {"name": "M1", "std": 1.2, "corr": 0.85},
+          ...
+        ]
+      }
+    Polar axes: angle = arccos(correlation), radius = standard deviation.
+    The reference sits at (angle 0, radius obs_std). RMSD contours are drawn
+    around the reference point.
+    """
+    obs_std = float(data.get("obs_std", 1.0))
+    models = data.get("models", [])
+    if not models:
+        return None
+
+    refs = []
+    for m in models:
+        std = float(m.get("std", m.get("std_ratio", 1.0)))
+        corr = float(m.get("corr", m.get("R", 0.0)))
+        corr = max(min(corr, 1.0), -1.0)
+        refs.append((str(m.get("name", "")), std, np.arccos(corr)))
+
+    max_r = max(obs_std, max(r for _, r, _ in refs)) * 1.12
+
+    corr_ticks = [0.0, 0.2, 0.4, 0.6, 0.7, 0.8, 0.9, 0.95, 0.99, 1.0]
+    theta_ticks = [np.degrees(np.arccos(c)) for c in corr_ticks]
+    rticks = np.linspace(0, max_r, 5)[1:]
+
+    ax.set_rlim(0, max_r)
+    ax.set_thetamin(0)
+    ax.set_thetamax(180)
+    ax.set_thetagrids(theta_ticks, labels=[f"{c:g}" for c in corr_ticks])
+    ax.set_rgrids(rticks, labels=[f"{r:.1f}" for r in rticks], angle=45)
+
+    # Reference point
+    ax.plot([0], [obs_std], 'k*', markersize=13, zorder=5)
+    ref_text = ax.text(0.05, obs_std * 1.04, 'REF', ha='left', va='bottom',
+                       fontsize=10, fontweight='bold', zorder=6)
+
+    # RMSD contours centered at reference (r=obs_std, theta=0)
+    for rmsd in np.linspace(0.25, max_r, 4):
+        th = np.linspace(0, 2 * np.pi, 240)
+        cx, cy = obs_std, 0.0
+        xs = cx + rmsd * np.cos(th)
+        ys = cy + rmsd * np.sin(th)
+        R = np.sqrt(xs ** 2 + ys ** 2)
+        T = np.mod(np.arctan2(ys, xs), 2 * np.pi)
+        mask = (T >= 0) & (T <= np.pi)
+        if mask.sum() > 1:
+            pts = np.column_stack([T[mask], R[mask]])
+            pts = pts[np.argsort(pts[:, 0])]
+            ax.plot(pts[:, 0], pts[:, 1], color='lightgray', linewidth=0.8, zorder=1)
+
+    # Model points (labels placed just outside each marker, then de-overlapped
+    # so they never collide with each other or the correlation tick labels)
+    model_texts = []
+    for i, (name, r, theta) in enumerate(refs):
+        c = colors[i % len(colors)]
+        ax.plot([theta], [r], 'o', color=c, markersize=9, label=name, zorder=4)
+        if name:
+            t = ax.text(theta, r * 1.06, name, ha='center', va='bottom',
+                        fontsize=8, zorder=6)
+            model_texts.append(t)
+
+    from fig_core import separate_labels
+    separate_labels(ax, [ref_text] + model_texts,
+                    clamp=[(0.03, np.pi - 0.03), (0.02 * max_r, None)])
+
+    ax.set_title("Taylor Diagram", fontsize=11, fontweight='bold', pad=12)
+    return None

package/scripts/fig_venn.py

@@ -0,0 +1,80 @@
+#!/usr/bin/env python3
+"""Venn / Euler diagram generator (2- and 3-set) — pure matplotlib, no extra deps."""
+import numpy as np
+from matplotlib.patches import Circle
+
+
+def gen_venn(data, ax, colors, cjk_fp=None, **kwargs):
+    """Generate a 2- or 3-set Venn diagram.
+
+    Data schema (JSON):
+      {
+        "regions": {"A": n, "B": n, "AB": n}                       # 2-set
+        "regions": {"A":, "B":, "C":, "AB":, "AC":, "BC":, "ABC":} # 3-set
+        "labels":  ["A", "B"(, "C")]  (optional)
+      }
+    The number of sets is inferred from the presence of key "C"/"ABC".
+    """
+    regions = data.get("regions", {})
+    labels = data.get("labels")
+
+    if "C" in regions or "ABC" in regions:
+        _venn3(ax, regions, (labels or ["A", "B", "C"]), colors)
+    else:
+        _venn2(ax, regions, (labels or ["A", "B"]), colors)
+
+    ax.set_aspect('equal')
+    ax.axis('off')
+    return None
+
+
+def _circle(ax, center, r, color):
+    c = Circle(center, r, fill=True, color=color, alpha=0.5,
+               edgecolor='white', linewidth=1.2, zorder=1)
+    ax.add_patch(c)
+
+
+def _venn2(ax, r, labels, colors):
+    ca, cb = colors[0], colors[1 % len(colors)]
+    _circle(ax, (-0.5, 0), 1.0, ca)
+    _circle(ax, (0.5, 0), 1.0, cb)
+    ax.text(-1.15, 0.0, str(r.get("A", 0)), ha='center', va='center', fontsize=12)
+    ax.text(1.15, 0.0, str(r.get("B", 0)), ha='center', va='center', fontsize=12)
+    ax.text(0.0, 0.0, str(r.get("AB", 0)), ha='center', va='center', fontsize=12)
+    ax.text(-0.5, 1.2, str(labels[0]), ha='center', va='bottom', fontsize=12, fontweight='bold')
+    ax.text(0.5, 1.2, str(labels[1]), ha='center', va='bottom', fontsize=12, fontweight='bold')
+    ax.set_xlim(-1.7, 1.7)
+    ax.set_ylim(-1.25, 1.5)
+
+
+def _venn3(ax, r, labels, colors):
+    # triangle of circles
+    centers = {
+        'A': (0.0, 0.65),
+        'B': (-0.55, -0.4),
+        'C': (0.55, -0.4),
+    }
+    for k, c in centers.items():
+        _circle(ax, c, 1.0, colors[list('ABC').index(k) % len(colors)])
+    # region label positions (approximate standard 3-set Venn layout)
+    pos = {
+        'A': (0.0, 1.25),
+        'B': (-1.15, -0.55),
+        'C': (1.15, -0.55),
+        'AB': (-0.32, 0.30),
+        'AC': (0.32, 0.30),
+        'BC': (0.0, -0.62),
+        'ABC': (0.0, -0.08),
+    }
+    for key, (px, py) in pos.items():
+        if key in r:
+            ax.text(px, py, str(r[key]), ha='center', va='center', fontsize=11)
+    # set labels placed just outside each circle (above A, lower-corner B/C)
+    label_pos = {'A': (0.0, 1.75), 'B': (-1.5, -1.25), 'C': (1.5, -1.25)}
+    for i, k in enumerate('ABC'):
+        if i < len(labels):
+            lx, ly = label_pos[k]
+            ax.text(lx, ly, str(labels[i]), ha='center', va='center',
+                    fontsize=12, fontweight='bold')
+    ax.set_xlim(-1.9, 1.9)
+    ax.set_ylim(-1.5, 1.9)

package/scripts/fig_windrose.py

@@ -0,0 +1,82 @@
+#!/usr/bin/env python3
+"""Wind rose generator (polar stacked bars by direction sector and speed bin)."""
+import numpy as np
+
+
+def gen_windrose(data, ax, colors, cjk_fp=None, **kwargs):
+    """Generate a wind rose.
+
+    Two input modes:
+
+    Mode A — raw observations (most flexible):
+      {
+        "direction": [degrees, ...],     # 0=N, 90=E ...
+        "speed":     [m/s, ...],
+        "speed_bins":[0, 3, 6, 9, 12, 999] (optional, default shown),
+        "sectors":   16 (optional),
+        "normalize": true (optional -> show % instead of counts)
+      }
+
+    Mode B — pre-aggregated:
+      {
+        "directions": ["N","NNE",...] or [names],
+        "matrix":     [[count per speed-bin], ...]  # len(directions) x n_bins
+      }
+    """
+    sectors = int(data.get("sectors", kwargs.get("sectors") or 16))
+    speed_bins = data.get("speed_bins") or [0, 3, 6, 9, 12, 1e9]
+    normalize = bool(data.get("normalize", False))
+
+    directions = data.get("direction")
+    speeds = data.get("speed")
+
+    if directions is not None and speeds is not None:
+        directions = np.array(directions, dtype=float)
+        speeds = np.array(speeds, dtype=float)
+        bin_idx = np.digitize(speeds, speed_bins[1:-1])      # 0 .. n_bins-1
+        n_bins = len(speed_bins) - 1
+        seg = 2 * np.pi / sectors
+        counts = np.zeros((sectors, n_bins))
+        for d, b in zip(directions, bin_idx):
+            theta = np.deg2rad((90.0 - d) % 360.0)           # N up, CW
+            sec = int(theta // seg) % sectors
+            counts[sec, b] += 1
+    else:
+        dirs = data.get("directions", [])
+        matrix = np.array(data.get("matrix", []), dtype=float)
+        sectors = len(dirs)
+        n_bins = matrix.shape[1] if matrix.ndim == 2 else 1
+        counts = matrix if matrix.ndim == 2 else matrix.reshape(-1, 1)
+
+    if normalize:
+        total = counts.sum()
+        if total > 0:
+            counts = counts / total * 100.0
+
+    # Speed-bin legend labels
+    if len(speed_bins) - 1 == n_bins:
+        bin_names = []
+        for b in range(n_bins):
+            lo, hi = speed_bins[b], speed_bins[b + 1]
+            bin_names.append(f"≥{lo:g}" if hi >= 1e8 else f"{lo:g}–{hi:g}")
+    else:
+        bin_names = [f"Bin {b + 1}" for b in range(n_bins)]
+
+    seg = 2 * np.pi / sectors
+    theta = (np.arange(sectors) + 0.5) * seg
+    width = seg * 0.9
+    bottom = np.zeros(sectors)
+    for b in range(n_bins):
+        vals = counts[:, b]
+        ax.bar(theta, vals, width=width, bottom=bottom, color=colors[b % len(colors)],
+               edgecolor='white', linewidth=0.3, zorder=2, label=bin_names[b])
+        bottom = bottom + vals
+
+    ax.set_theta_zero_location('N')
+    ax.set_theta_direction(-1)
+    if normalize:
+        ax.set_rlabel_position(90)
+    # speed-bin legend, placed outside the polar area
+    ax.legend(loc='upper left', bbox_to_anchor=(1.02, 1.0), fontsize=8,
+              framealpha=0.9, title="m/s")
+    return None

package/scripts/font_detector.py

@@ -0,0 +1,85 @@
+#!/usr/bin/env python3
+"""Auto-detect CJK and special fonts for matplotlib. Returns font path or None."""
+import subprocess, os, json
+
+CJK_FONT_PRIORITY = [
+    # Noto CJK (most Linux distros)
+    "/usr/share/fonts/opentype/noto/NotoSansCJK-Regular.ttc",
+    "/usr/share/fonts/opentype/noto/NotoSansSC-Regular.otf",
+    "/usr/share/fonts/opentype/noto/NotoSansCJK-Bold.ttc",
+    "/usr/share/fonts/opentype/noto/NotoSerifCJK-Regular.ttc",
+    # macOS
+    "/System/Library/Fonts/PingFang.ttc",
+    "/System/Library/Fonts/STHeiti Medium.ttc",
+    "/Library/Fonts/Arial Unicode.ttf",
+    # Windows
+    "C:/Windows/Fonts/msyh.ttc",       # Microsoft YaHei
+    "C:/Windows/Fonts/simhei.ttf",      # SimHei
+    "C:/Windows/Fonts/simsun.ttc",      # SimSun
+    # Common Linux
+    "/usr/share/fonts/truetype/wqy/wqy-microhei.ttc",
+    "/usr/share/fonts/truetype/wqy/wqy-zenhei.ttc",
+    "/usr/share/fonts/truetype/arphic/uming.ttc",
+    "/usr/share/fonts/truetype/droid/DroidSansFallbackFull.ttf",
+    "/usr/share/fonts/truetype/noto/NotoSansCJK-Regular.ttc",
+]
+
+# Additional serif/math fonts for scienceplots styles
+SERIF_FONT_PRIORITY = [
+    "C:/Windows/Fonts/times.ttf",
+    "/usr/share/fonts/truetype/liberation/LiberationSerif-Regular.ttf",
+    "/System/Library/Fonts/Times New Roman.ttf",
+]
+
+SANS_FONT_PRIORITY = [
+    "C:/Windows/Fonts/arial.ttf",
+    "/usr/share/fonts/truetype/liberation/LiberationSans-Regular.ttf",
+    "/System/Library/Fonts/Helvetica.ttf",
+]
+
+
+def detect_cjk_font():
+    """Return path to first available CJK font, or None."""
+    for p in CJK_FONT_PRIORITY:
+        if os.path.exists(p):
+            return p
+    # Fallback: fc-list
+    try:
+        result = subprocess.run(
+            ["fc-list", ":lang=zh", "file"],
+            capture_output=True, text=True, timeout=5
+        )
+        if result.stdout.strip():
+            for line in result.stdout.strip().split('\n'):
+                if ':' in line:
+                    return line.split(':')[0].strip()
+    except Exception:
+        pass
+    return None
+
+
+def detect_serif_font():
+    """Return path to first available serif font, or None."""
+    for p in SERIF_FONT_PRIORITY:
+        if os.path.exists(p):
+            return p
+    return None
+
+
+def detect_sans_font():
+    """Return path to first available sans-serif font, or None."""
+    for p in SANS_FONT_PRIORITY:
+        if os.path.exists(p):
+            return p
+    return None
+
+
+if __name__ == "__main__":
+    cjk = detect_cjk_font()
+    serif = detect_serif_font()
+    sans = detect_sans_font()
+    print(json.dumps({
+        "cjk": {"found": cjk is not None, "path": cjk},
+        "serif": {"found": serif is not None, "path": serif},
+        "sans": {"found": sans is not None, "path": sans},
+    }))