like-sci-figures 0.0.0-stage → 1.0.0

package/scripts/gen_figure.py

@@ -0,0 +1,583 @@
+#!/usr/bin/env python3
+"""
+like-sci-figures: Publication-quality academic figure generator.
+Powered by scienceplots + matplotlib.
+
+Supports 36 chart types with 11 journal styles and 10 curated color palettes,
+CJK auto-detection, multi-panel subplots, and high-DPI output.
+
+Usage:
+  python gen_figure.py --type bar --data data.json --out figure.png --style nature
+  python gen_figure.py --type heatmap --data data.csv --out figure.svg --style ieee
+  python gen_figure.py --type surface --data data.json --out figure.png --style science
+  python gen_figure.py --type bar --data data.json --out fig.png --palette wx06_amber_navy
+  python gen_figure.py --type heatmap --data data.json --out fig.png --palette p1
+  python gen_figure.py --list-palettes
+"""
+
+# Fix Windows OpenBLAS threading conflict (must be set before numpy/matplotlib imports)
+import os as _os
+if _os.name == 'nt':  # Windows
+    _os.environ.setdefault('OPENBLAS_NUM_THREADS', '1')
+    _os.environ.setdefault('OMP_NUM_THREADS', '1')
+
+import argparse, json, os, sys, subprocess, tempfile, time
+
+SCRIPT_DIR = os.path.dirname(os.path.abspath(__file__))
+sys.path.insert(0, SCRIPT_DIR)
+
+# ── Dependency check: friendly error instead of raw ImportError ───────────
+def _check_deps():
+    import importlib.util
+    required = [("numpy", "numpy"), ("matplotlib", "matplotlib"),
+                ("scipy", "scipy"), ("PIL", "pillow")]
+    missing = [pip for mod, pip in required
+               if importlib.util.find_spec(mod) is None]
+    if missing:
+        sys.stderr.write(
+            "\n[like-sci-figures] 缺少运行依赖: %s\n" % ", ".join(missing) +
+            "请先安装:  pip install %s\n" % " ".join(missing) +
+            "(scienceplots 为可选增强:  pip install scienceplots)\n")
+        sys.exit(1)
+_check_deps()
+
+import matplotlib.pyplot as plt
+
+from data_loader import load_data
+from style_manager import setup_style, list_styles
+from palettes import list_palettes, get_palette, palette_colormap, palette_info, PALETTES
+from fig_core import (
+    load_cjk_font, needs_cjk, apply_base_style,
+    set_axis_labels, set_title, finalize_and_save
+)
+
+# ── Import all generators ────────────────────────────────────────────────
+from fig_bar import gen_bar, gen_stacked_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_3d import gen_surface, gen_contour, gen_scatter3d
+from fig_bubble import gen_bubble
+from fig_area import gen_area
+from fig_errorbar import gen_errorbar
+from fig_venn import gen_venn
+from fig_pca import gen_pca
+from fig_windrose import gen_windrose
+from fig_taylor import gen_taylor
+from fig_sankey import gen_sankey
+from fig_subplots import gen_subplots
+
+# Biomedical chart types (ChartPlugin subclasses).
+from fig_biomed import VolcanoPlot, ManhattanPlot, KaplanMeierCurve, ROCCurve
+_volcano = VolcanoPlot()
+_manhattan = ManhattanPlot()
+_km = KaplanMeierCurve()
+_roc = ROCCurve()
+
+# Data science chart types (ChartPlugin subclasses).
+from fig_datasci import RidgePlot, TernaryPlot, DotPlot, DendrogramPlot
+_ridge = RidgePlot()
+_ternary = TernaryPlot()
+_dot_plot = DotPlot()
+_dendrogram = DendrogramPlot()
+
+# Engineering/finance chart types (ChartPlugin subclasses).
+from fig_engineering import SlopeChart, WaterfallChart, BodePlot, PeriodogramPlot
+_slope = SlopeChart()
+_waterfall = WaterfallChart()
+_bode = BodePlot()
+_periodogram = PeriodogramPlot()
+
+# Environmental statistics suite (ChartPlugin subclasses).
+from fig_environ import CorrMatrixPlot, HexbinPlot, ECDFPlot, BlandAltmanPlot
+_corr_matrix = CorrMatrixPlot()
+_hexbin = HexbinPlot()
+_ecdf = ECDFPlot()
+_bland_altman = BlandAltmanPlot()
+
+# ── Generator registry ────────────────────────────────────────────────────
+GENERATORS = {
+    "bar": gen_bar,
+    "grouped_bar": gen_bar,
+    "stacked_bar": gen_stacked_bar,
+    "stacked": gen_stacked_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,
+    "surface": gen_surface,
+    "contour": gen_contour,
+    "scatter3d": gen_scatter3d,
+    "bubble": gen_bubble,
+    "area": gen_area,
+    "errorbar": gen_errorbar,
+    "venn": gen_venn,
+    "pca": gen_pca,
+    "windrose": gen_windrose,
+    "taylor": gen_taylor,
+    "sankey": gen_sankey,
+    # Biomedical charts (ChartPlugin instances)
+    "volcano": _volcano,
+    "manhattan": _manhattan,
+    "kaplan_meier": _km,
+    "roc": _roc,
+    # Data science charts (ChartPlugin instances)
+    "ridge": _ridge,
+    "ternary": _ternary,
+    "dot_plot": _dot_plot,
+    "dendrogram": _dendrogram,
+    # Engineering/finance charts (ChartPlugin instances)
+    "slope": _slope,
+    "waterfall": _waterfall,
+    "bode": _bode,
+    "periodogram": _periodogram,
+    # Environmental statistics suite (ChartPlugin instances)
+    "corr_matrix": _corr_matrix,
+    "hexbin": _hexbin,
+    "ecdf": _ecdf,
+    "bland_altman": _bland_altman,
+}
+
+# Chart types that need 3D axes
+_3D_TYPES = {"surface", "scatter3d"}
+
+# Chart types that need polar axes
+_POLAR_TYPES = {"radar", "windrose", "taylor"}
+
+# Chart types that need specific figure size
+_SPECIAL_TYPES = {"subplots"}
+
+# Chart types that should NOT receive a y-axis grid overlay
+# (grid lines would clutter heatmaps, pies, forest CI plots, venn & sankey)
+_NO_GRID = {"heatmap", "pie", "forest", "venn", "sankey", "corr_matrix"}
+
+# Chart types that use a continuous colormap (palette -> cmap)
+_CMAP_TYPES = {"heatmap", "contour", "surface", "corr_matrix", "hexbin"}
+
+
+def infer_n_series(data, chart_type):
+    """Best-effort count of the number of series/groups in the data."""
+    if not isinstance(data, dict):
+        return None
+    for key in ("series", "groups", "datasets"):
+        v = data.get(key)
+        if isinstance(v, dict):
+            return len(v)
+        if isinstance(v, list):
+            return len(v)
+    if chart_type in ("pie", "donut"):
+        for key in ("values", "sizes"):
+            v = data.get(key)
+            if isinstance(v, (list, dict)):
+                return len(v)
+    if isinstance(data.get("labels"), list) and len(data["labels"]) > 0:
+        # labels may enumerate categories (box/violin) — count only if values are nested
+        vals = data.get("values")
+        if isinstance(vals, dict):
+            return len(vals)
+    return None
+
+
+# ── Batch verification of every example ────────────────────────────────────
+# Chart-type → example-file mapping lives in registry.py (the single source of
+# truth). _example_type() inverts it so verify_all can map a file path back to
+# its chart type without re-declaring the table here.
+from registry import CHART_EXAMPLES, resolve
+from render_utils import read_palette_state, AUTO_SENTINEL
+
+_EXAMPLE_TO_TYPE = {
+    os.path.splitext(v)[0]: k
+    for k, v in CHART_EXAMPLES.items()
+}
+
+
+def _example_type(path):
+    """Infer the chart type for one example file (or None if not recognized)."""
+    stem = os.path.splitext(os.path.basename(path))[0]
+    return _EXAMPLE_TO_TYPE.get(stem)
+
+
+def verify_all(style="nature", palette=None, quiet=False):
+    """Render every example file and report pass/fail per type.
+
+    Returns a truthy value (0 = all passed, 1 = some failed) suitable for use
+    as a process exit code via `return verify_all(...) or 0`.
+    """
+    examples_dir = os.path.join(SCRIPT_DIR, "..", "examples")
+    if not os.path.isdir(examples_dir):
+        print("ERROR: examples/ directory not found at %s" % examples_dir,
+              file=sys.stderr)
+        return 1
+
+    todo = []
+    for name in sorted(os.listdir(examples_dir)):
+        path = os.path.join(examples_dir, name)
+        if not os.path.isfile(path):
+            continue
+        chart_type = _example_type(path)
+        if chart_type is None:
+            continue  # not a chart example (e.g. README)
+        todo.append((chart_type, path))
+
+    if not todo:
+        print("No example files recognised in %s" % examples_dir,
+              file=sys.stderr)
+        return 1
+
+    tmpdir = tempfile.mkdtemp(prefix="sf_verify_")
+    passed, failed = [], []
+    t0 = time.time()
+
+    for chart_type, path in todo:
+        out = os.path.join(tmpdir, "%s.png" % chart_type)
+        cmd = [sys.executable, os.path.abspath(__file__),
+               "--type", chart_type, "--data", path, "--out", out,
+               "--style", style,
+               "--width", "4", "--height", "3", "--dpi", "100"]
+        if palette:
+            cmd += ["--palette", palette]
+        try:
+            proc = subprocess.run(cmd, capture_output=True, text=True,
+                                  timeout=120)
+            ok = proc.returncode == 0 and os.path.exists(out) and \
+                 os.path.getsize(out) > 0
+        except Exception as exc:
+            proc = None
+            ok = False
+        label = "%-12s %s" % (chart_type, os.path.basename(path))
+        if ok:
+            passed.append(label)
+            if not quiet:
+                print("  OK   %s" % label)
+        else:
+            failed.append((label, proc))
+            if not quiet:
+                tail = ""
+                if proc is not None:
+                    tail = (proc.stderr or proc.stdout or "").strip().splitlines()
+                    tail = " | ".join(tail[-2:])
+                print("  FAIL %s%s" % (label, (" — " + tail) if tail else ""))
+
+    total = time.time() - t0
+    print("")
+    print("Verify summary: %d passed, %d failed (%.1fs, style=%s%s)"
+          % (len(passed), len(failed), total, style,
+             ", palette=" + palette if palette else ""))
+    if failed:
+        for label, proc in failed:
+            if proc is not None:
+                print("  FAIL %s" % label)
+                for line in (proc.stderr or "").strip().splitlines()[-3:]:
+                    print("        " + line)
+        return 1
+    return 0
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="like-sci-figures: Publication-quality academic figure generator (scienceplots-based)"
+    )
+    parser.add_argument("--type", "-t", choices=sorted(list(GENERATORS.keys()) + ["subplots"]),
+                        help="Figure type")
+    parser.add_argument("--data", "-d", help="Input data file (JSON or CSV)")
+    parser.add_argument("--out", "-o", help="Output file path (.png/.svg/.pdf)")
+    parser.add_argument("--title", default="", help="Figure title (use \\n for newline)")
+    parser.add_argument("--xlabel", default="", help="X-axis label")
+    parser.add_argument("--ylabel", default="", help="Y-axis label")
+    parser.add_argument("--style", "-s", default="nature", choices=list_styles(),
+                        help="Journal style (from scienceplots)")
+    parser.add_argument("--palette", "-p", default=None,
+                        help="Color palette override: slug (wx01_blue_red), "
+                             "alias (p1/wx1/1), or raw hex list \"#F26A1D,#1E5FA8\". "
+                             "If omitted, reads from .workbuddy/like-sci-figures/palette.json")
+    parser.add_argument("--no-pref", action="store_true",
+                        help="Do not read palette preference from disk")
+    parser.add_argument("--palette-n", type=int, default=None,
+                        help="Number of colors to evenly sample from --palette")
+    parser.add_argument("--palette-reverse", action="store_true",
+                        help="Reverse the palette order (e.g. make heatmap high=red)")
+    parser.add_argument("--list-palettes", action="store_true",
+                        help="List available palettes and exit")
+    parser.add_argument("--cjk", action="store_true", help="Force enable CJK font")
+    parser.add_argument("--cjk-font", default=None, help="Specific CJK font path")
+    parser.add_argument("--width", type=float, default=None, help="Figure width (inches)")
+    parser.add_argument("--height", type=float, default=None, help="Figure height (inches)")
+    parser.add_argument("--legend", action="store_true", default=True, help="Show legend")
+    parser.add_argument("--no-legend", action="store_true", help="Hide legend")
+
+    # Bar-specific
+    parser.add_argument("--show-values", action="store_true", help="Show value labels on bars")
+
+    # Scatter-specific
+    parser.add_argument("--trend", action="store_true", default=True, help="Show trend line (scatter)")
+    parser.add_argument("--no-trend", action="store_true", help="Hide trend line")
+
+    # Heatmap-specific
+    parser.add_argument("--cmap", default=None, help="Colormap for heatmap/contour/surface")
+    parser.add_argument("--vmin", type=float, default=None, help="Heatmap vmin")
+    parser.add_argument("--vmax", type=float, default=None, help="Heatmap vmax")
+    parser.add_argument("--center", type=float, default=None, help="Center value for divergence colormaps")
+
+    # Distribution-specific
+    parser.add_argument("--kde", action="store_true", default=True, help="Show KDE overlay (histogram)")
+    parser.add_argument("--no-kde", action="store_true", help="Hide KDE overlay")
+    parser.add_argument("--bins", default="auto", help="Histogram bins (int or 'auto')")
+    parser.add_argument("--density", action="store_true", help="Normalize histogram to density")
+
+    # Pie-specific
+    parser.add_argument("--donut", action="store_true", help="Draw as donut chart (when --type pie)")
+    parser.add_argument("--show-pct", action="store_true", default=True, help="Show percentages on pie")
+    parser.add_argument("--no-pct", action="store_true", help="Hide percentages")
+
+    # 3D-specific
+    parser.add_argument("--contour-floor", action="store_true", help="Show contour project floor (surface)")
+    parser.add_argument("--filled", action="store_true", default=True, help="Filled contour (contour)")
+    parser.add_argument("--no-filled", action="store_true", help="Line-only contour")
+
+    # Area-specific
+    parser.add_argument("--stacked", dest="stacked", action="store_true", default=True,
+                        help="Stack area chart (area)")
+    parser.add_argument("--no-stacked", dest="stacked", action="store_false",
+                        help="Do not stack area chart (area)")
+
+    # Wind rose / PCA
+    parser.add_argument("--sectors", type=int, default=None, help="Wind rose sector count")
+    parser.add_argument("--components", type=int, default=2, help="PCA components to plot (pca)")
+
+    # Subplots
+    parser.add_argument("--layout", default="auto", help="Subplot layout: auto, RxC, or rows,cols (e.g. 2x3)")
+
+    parser.add_argument("--dpi", type=int, default=300, help="Output DPI (default: 300)")
+    parser.add_argument("--list-styles", action="store_true", help="List available styles and exit")
+    parser.add_argument("--verify-all", action="store_true",
+                        help="Render every example file in examples/ with its inferred "
+                             "chart type and report per-example pass/fail. Exits 0 only "
+                             "if every example renders cleanly.")
+    parser.add_argument("--verify-style", default="nature",
+                        help="Journal style used by --verify-all (default: %(default)s)")
+    parser.add_argument("--verify-palette", default=None,
+                        help="Optional palette slug to exercise under --verify-all")
+
+    args = parser.parse_args()
+
+    if args.list_styles:
+        print("Available styles: " + ", ".join(list_styles()))
+        return
+
+    if args.list_palettes:
+        print("Available palettes:\n")
+        for slug, meta in PALETTES.items():
+            print(f"  {slug}  [{meta['kind']}]  {meta['zh']}")
+            print("      " + " ".join(meta["colors"]))
+        return
+
+    if args.verify_all:
+        # Auto-read palette preference unless --verify-palette or --no-pref
+        v_palette = args.verify_palette
+        if not v_palette and not args.no_pref:
+            stored, _ = read_palette_state()
+            if stored and stored != AUTO_SENTINEL:
+                v_palette = stored
+                print("Verify palette (from preference): %s" % stored,
+                      file=sys.stderr)
+        return verify_all(style=args.verify_style,
+                          palette=v_palette) or 0
+
+    # ── Style setup ──────────────────────────────────────────────────────
+    custom_rc = {}
+    if args.width:
+        custom_rc["figure.figsize"] = (args.width, args.height or args.width * 0.65)
+    elif args.height:
+        custom_rc["figure.figsize"] = (args.height * 1.5, args.height)
+    if args.dpi:
+        custom_rc["savefig.dpi"] = args.dpi
+
+    style_info = setup_style(args.style, custom_rc)
+    colors = style_info["colors"]
+    palette_cmap = None
+
+    # ── Load data ─────────────────────────────────────────────────────────
+    if args.type == "subplots":
+        with open(args.data, 'r', encoding='utf-8') as f:
+            data = json.load(f)
+    else:
+        data = load_data(args.data, chart_type=args.type)
+
+    if args.type == "subplots":
+        if not data or not isinstance(data, list):
+            print("ERROR: Subplots data must be a non-empty JSON array.", file=sys.stderr)
+            sys.exit(1)
+    else:
+        if not data or not isinstance(data, dict):
+            print("ERROR: Data file is empty or invalid.", file=sys.stderr)
+            sys.exit(1)
+
+        has_data = any(data.get(k) for k in
+                       ["series", "matrix", "x", "y", "estimates", "values",
+                        "direction", "speed", "regions", "nodes", "links",
+                        "models", "obs_std", "samples", "variables",
+                        "sizes", "xerr", "yerr",
+                        # Biomedical charts
+                        "log2fc", "pvalue", "chr", "pos", "time", "event",
+                        "group", "fpr", "tpr",
+                        # Data science charts
+                        "points", "leaves", "merges",
+                        # Engineering/finance charts
+                        "before", "after", "freq", "mag", "phase", "psd",
+                        # Environmental statistics suite
+                        "method1", "method2", "gridsize"])
+        if not has_data:
+            print("ERROR: No data fields found.", file=sys.stderr)
+            sys.exit(1)
+
+    # ── Palette override (from palettes.py) ───────────────────────────────
+    # If --palette was not given, auto-read the task-scoped preference stored
+    # by palette_pref.py. The "auto" sentinel means the user explicitly opted
+    # out: skip the palette override and let the journal style supply its
+    # own colours.
+    effective_palette = args.palette
+    if not effective_palette and not args.no_pref:
+        stored, state_file = read_palette_state()
+        if stored and stored != AUTO_SENTINEL:
+            effective_palette = stored
+            print("Palette (from preference): %s  (%s)" % (stored, state_file),
+                  file=sys.stderr)
+        elif stored == AUTO_SENTINEL:
+            print("Palette preference: auto (skipped, using style colours)",
+                  file=sys.stderr)
+
+    if effective_palette:
+        try:
+            n = args.palette_n
+            if n is None and args.type not in _CMAP_TYPES:
+                # For categorical charts, sample one color per series so a long
+                # palette spreads across the groups (matching the poster style).
+                n = infer_n_series(data if args.type != "subplots" else None, args.type)
+            colors = get_palette(effective_palette, n)
+        except ValueError as e:
+            print(f"ERROR: {e}", file=sys.stderr)
+            sys.exit(2)
+        print(f"Palette: {effective_palette} -> {' '.join(colors)}", file=sys.stderr)
+        if args.palette_reverse:
+            colors = list(reversed(colors))
+        if args.type in _CMAP_TYPES and not args.cmap:
+            palette_cmap = palette_colormap(effective_palette)
+            if palette_cmap is not None and args.palette_reverse:
+                palette_cmap = palette_cmap.reversed()
+
+    # ── CJK font ──────────────────────────────────────────────────────────
+    cjk_fp = None
+    if args.cjk or args.cjk_font or needs_cjk(data, args.title, args.xlabel, args.ylabel):
+        cjk_fp, cjk_name = load_cjk_font(args.cjk_font)
+        if cjk_name:
+            plt.rcParams['font.sans-serif'] = [cjk_name, 'DejaVu Sans'] + \
+                                               plt.rcParams.get('font.sans-serif', [])
+        plt.rcParams['axes.unicode_minus'] = False
+        if cjk_fp:
+            print(f"CJK font loaded: {cjk_name}", file=sys.stderr)
+        else:
+            print("WARNING: No CJK font found, CJK characters may not render", file=sys.stderr)
+
+    # ── Create figure ─────────────────────────────────────────────────────
+    kw_width = args.width if args.width else plt.rcParams.get("figure.figsize", (8, 5))[0]
+    kw_height = args.height if args.height else plt.rcParams.get("figure.figsize", (8, 5))[1]
+
+    # Special axes types
+    if args.type in _3D_TYPES:
+        fig = plt.figure(figsize=(kw_width, kw_height))
+        ax = fig.add_subplot(111, projection='3d')
+    elif args.type in _POLAR_TYPES:
+        fig = plt.figure(figsize=(kw_width, kw_height))
+        ax = fig.add_subplot(111, polar=True)
+    elif args.type == "subplots":
+        fig, ax = plt.subplots(figsize=(kw_width, kw_height))
+        new_fig = gen_subplots(data, fig, ax, colors, cjk_fp,
+                               layout=args.layout)
+        if new_fig is not None:
+            fig = new_fig
+        # For subplots, save directly
+        out_ext = os.path.splitext(args.out)[1].lower()
+        save_kwargs = {"bbox_inches": "tight", "facecolor": "white", "edgecolor": "none"}
+        if out_ext == ".svg":
+            save_kwargs["format"] = "svg"
+        elif out_ext == ".pdf":
+            save_kwargs["format"] = "pdf"
+        fig.savefig(args.out, **save_kwargs)
+        plt.close(fig)
+        sz = os.path.getsize(args.out)
+        print(f"Saved: {args.out} ({sz:,} bytes)", file=sys.stderr)
+        return
+    else:
+        fig, ax = plt.subplots(figsize=(kw_width, kw_height))
+
+    # ── Generate ──────────────────────────────────────────────────────────
+    gen_func = GENERATORS[args.type]
+    # Parse bins: convert to int if numeric string, otherwise keep as "auto"
+    bins_val = args.bins
+    if isinstance(bins_val, str) and bins_val.isdigit():
+        bins_val = int(bins_val)
+
+    gen_kwargs = {
+        "show_values": args.show_values,
+        "trend": args.trend and not args.no_trend,
+        "cmap": args.cmap or palette_cmap,
+        "vmin": args.vmin,
+        "vmax": args.vmax,
+        "center": args.center,
+        "kde": args.kde and not args.no_kde,
+        "bins": bins_val,
+        "density": args.density,
+        "show_pct": args.show_pct and not args.no_pct,
+        # `--type donut` must behave like `--type pie --donut` (docs advertise
+        # donut as its own type); otherwise a plain pie is silently drawn.
+        "donut": args.donut or args.type == "donut",
+        "contour_floor": args.contour_floor,
+        "filled": args.filled and not args.no_filled,
+        "stacked": args.stacked,
+        "sectors": args.sectors,
+        "components": args.components,
+    }
+    extra = gen_func(data, ax, colors, cjk_fp, **gen_kwargs)
+
+    # ── Style & labels ────────────────────────────────────────────────────
+    if args.type not in _3D_TYPES and args.type not in _POLAR_TYPES:
+        apply_base_style(ax, grid=args.type not in _NO_GRID)
+    elif args.type in _3D_TYPES:
+        # 3D axes: make panes transparent
+        ax.xaxis.pane.fill = False
+        ax.yaxis.pane.fill = False
+        ax.zaxis.pane.fill = False
+        ax.xaxis.pane.set_edgecolor('white')
+        ax.yaxis.pane.set_edgecolor('white')
+        ax.zaxis.pane.set_edgecolor('white')
+
+    set_title(ax, args.title, cjk_fp)
+    if args.type not in _3D_TYPES:
+        set_axis_labels(ax, args.xlabel, args.ylabel, cjk_fp)
+    else:
+        if args.xlabel:
+            ax.set_xlabel(args.xlabel)
+        if args.ylabel:
+            ax.set_ylabel(args.ylabel)
+
+    # ── Finalize ──────────────────────────────────────────────────────────
+    legend = args.legend and not args.no_legend
+    finalize_and_save(fig, ax, args.out, legend=legend,
+                      colorbar_artist=extra, cbar_label=None, cjk_fp=cjk_fp)
+
+
+if __name__ == "__main__":
+    main()