like-sci-figures 0.0.0-stage → 1.0.1

package/scripts/fig_biomed.py

@@ -0,0 +1,289 @@
+#!/usr/bin/env python3
+"""Biomedical chart types: volcano, manhattan, kaplan_meier, roc.
+
+These chart types are commonly used in genomics, GWAS, clinical trials, and
+machine learning diagnostics. Each is implemented as a ChartPlugin subclass
+so they auto-register with the palette and example systems.
+"""
+import numpy as np
+from chart_plugin import ChartPlugin
+from fig_core import set_axis_labels, set_title
+
+
+def _load_cjk_font(font_path):
+    """Load a CJK font and return the font properties, or None."""
+    if not font_path:
+        return None
+    try:
+        from matplotlib import font_manager as fm
+        fp = fm.FontProperties(fname=font_path)
+        return fp
+    except Exception:
+        return None
+
+
+class VolcanoPlot(ChartPlugin):
+    """Volcano plot for differential expression analysis.
+
+    X-axis: log2(fold change)
+    Y-axis: -log10(p-value)
+    Points colored by significance threshold.
+    """
+    name = "volcano"
+    zh = "火山图"
+    kind = "statistics"
+    required_keys = ("log2fc", "pvalue")
+    optional_keys = ("labels", "genes", "threshold_fc", "threshold_p")
+    data_format = "json"
+
+    def render(self, data, ax, colors, cjk_fp, **kwargs):
+        from matplotlib.lines import Line2D
+
+        x = np.asarray(data["log2fc"], dtype=float)
+        y = np.asarray(data["pvalue"], dtype=float)
+        labels = data.get("labels") or data.get("genes") or []
+        fc_thresh = float(data.get("threshold_fc", 1.0))
+        p_thresh = float(data.get("threshold_p", 0.05))
+        # Convert p-value to -log10 scale.
+        y_neglog = -np.log10(np.clip(y, 1e-300, 1.0))
+
+        # Significance thresholds.
+        up_mask = (x > fc_thresh) & (y < p_thresh)
+        down_mask = (x < -fc_thresh) & (y < p_thresh)
+        ns_mask = ~up_mask & ~down_mask
+
+        # Plot non-significant points first (background).
+        ax.scatter(x[ns_mask], y_neglog[ns_mask], s=20, alpha=0.6,
+                   color=colors[3] if len(colors) > 3 else "#999999",
+                   label="Non-significant")
+        # Plot significant points on top.
+        ax.scatter(x[up_mask], y_neglog[up_mask], s=40,
+                   color=colors[1] if len(colors) > 1 else "#D62728",
+                   edgecolors="black", linewidths=0.5, label="Up-regulated")
+        ax.scatter(x[down_mask], y_neglog[down_mask], s=40,
+                   color=colors[0] if len(colors) > 0 else "#1F77B4",
+                   edgecolors="black", linewidths=0.5, label="Down-regulated")
+
+        # Threshold lines.
+        p_line = -np.log10(p_thresh)
+        ax.axhline(p_line, color="grey", linestyle="--", linewidth=0.8, alpha=0.6)
+        ax.axvline(fc_thresh, color="grey", linestyle="--", linewidth=0.8, alpha=0.6)
+        ax.axvline(-fc_thresh, color="grey", linestyle="--", linewidth=0.8, alpha=0.6)
+
+        # Label top points.
+        if labels and len(labels) > 0:
+            top_n = 10
+            top_idx = np.argsort(y_neglog)[-top_n:]
+            fp = _load_cjk_font(cjk_fp)
+            for idx in top_idx:
+                ax.annotate(
+                    str(labels[idx]),
+                    (x[idx], y_neglog[idx]),
+                    textcoords="offset points", xytext=(5, 5),
+                    fontsize=7, fontproperties=fp,
+                )
+
+        ax.set_xlabel("log2(Fold Change)")
+        ax.set_ylabel("-log10(p-value)")
+        # Legend is placed outside the axes by finalize_and_save.
+        return None
+
+
+class ManhattanPlot(ChartPlugin):
+    """Manhattan plot for GWAS (Genome-Wide Association Study).
+
+    X-axis: genomic position (chr:position)
+    Y-axis: -log10(p-value)
+    Alternating chromosome coloring.
+    """
+    name = "manhattan"
+    zh = "曼哈顿图"
+    kind = "specialized"
+    required_keys = ("chr", "pos", "pvalue")
+    optional_keys = ("labels", "snp", "threshold")
+    data_format = "json"
+
+    def render(self, data, ax, colors, cjk_fp, **kwargs):
+        chr_arr = np.asarray(data["chr"])
+        pos_arr = np.asarray(data["pos"], dtype=float)
+        p_arr = np.asarray(data["pvalue"], dtype=float)
+        labels = data.get("labels") or data.get("snp") or []
+        thresh_p = float(data.get("threshold", 5e-8))
+
+        y_neglog = -np.log10(np.clip(p_arr, 1e-300, 1.0))
+
+        # Create cumulative x-axis: chr blocks with gaps.
+        chr_unique = np.unique(chr_arr)
+        chr_block_width = 1.0
+        gap = 0.1
+        x = np.zeros(len(chr_arr))
+        chr_start = {}
+        for i, chr_name in enumerate(chr_unique):
+            chr_start[chr_name] = i * (chr_block_width + gap)
+            mask = chr_arr == chr_name
+            pos_in_chr = pos_arr[mask]
+            pos_range = pos_in_chr.max() - pos_in_chr.min()
+            pos_scaled = (pos_in_chr - pos_in_chr.min()) / (pos_range + 1) * chr_block_width
+            x[mask] = chr_start[chr_name] + pos_scaled
+
+        # Color by chromosome (alternating).
+        for i, chr_name in enumerate(chr_unique):
+            mask = chr_arr == chr_name
+            color = colors[i % len(colors)] if colors else "#1F77B4"
+            ax.scatter(x[mask], y_neglog[mask], s=8, color=color,
+                       edgecolors="none", alpha=0.8)
+
+        # Threshold line.
+        thresh_line = -np.log10(thresh_p)
+        ax.axhline(thresh_line, color="red", linestyle="--", linewidth=1.0)
+
+        # Chromosome labels.
+        fp = _load_cjk_font(cjk_fp)
+        for i, chr_name in enumerate(chr_unique):
+            ax.text(chr_start[chr_name] + chr_block_width / 2, 0,
+                    str(chr_name), ha="center", va="bottom", fontsize=7,
+                    fontproperties=fp)
+
+        # Label top SNPs.
+        if labels and len(labels) > 0:
+            top_n = 15
+            top_idx = np.argsort(y_neglog)[-top_n:]
+            for idx in top_idx:
+                ax.annotate(
+                    str(labels[idx]),
+                    (x[idx], y_neglog[idx]),
+                    textcoords="offset points", xytext=(3, 3),
+                    fontsize=6, rotation=45, fontproperties=fp,
+                )
+
+        ax.set_xlabel("Genomic Position")
+        ax.set_ylabel("-log10(p-value)")
+        ax.set_yticks(ax.get_yticks())
+        return None
+
+
+class KaplanMeierCurve(ChartPlugin):
+    """Kaplan-Meier survival curve.
+
+    X-axis: time
+    Y-axis: survival probability
+    Step function with confidence bands.
+    """
+    name = "kaplan_meier"
+    zh = "KM生存曲线"
+    kind = "statistics"
+    required_keys = ("time", "event")
+    optional_keys = ("labels", "group", "group_labels", "ci")
+    data_format = "json"
+
+    def render(self, data, ax, colors, cjk_fp, **kwargs):
+        # If grouped, plot each group separately.
+        if "group" in data:
+            groups = data["group"]
+            group_labels = data.get("group_labels", [str(g) for g in sorted(set(groups))])
+            unique_groups = sorted(set(groups))
+            for i, grp in enumerate(unique_groups):
+                mask = np.array(groups) == grp
+                sub_data = {
+                    "time": np.asarray(data["time"])[mask],
+                    "event": np.asarray(data["event"])[mask],
+                }
+                self._plot_km(ax, sub_data, colors, i, group_labels[i % len(group_labels)])
+        else:
+            self._plot_km(ax, data, colors, 0, "Survival")
+
+        ax.set_xlabel("Time")
+        ax.set_ylabel("Survival Probability")
+        ax.set_ylim(0, 1.05)
+        # Legend is placed outside the axes by finalize_and_save.
+        return None
+
+    def _plot_km(self, ax, data, colors, color_idx, label):
+        """Compute and plot a single KM curve."""
+        time = np.asarray(data["time"], dtype=float)
+        event = np.asarray(data["event"], dtype=float)
+
+        # Sort by time.
+        sort_idx = np.argsort(time)
+        time_sorted = time[sort_idx]
+        event_sorted = event[sort_idx]
+
+        # Compute KM estimate.
+        n_at_risk = len(time_sorted)
+        survival = np.ones(n_at_risk)
+        ci_lower = np.ones(n_at_risk)
+        ci_upper = np.ones(n_at_risk)
+
+        for i in range(n_at_risk):
+            if i > 0:
+                at_risk = n_at_risk - i
+                events = event_sorted[i]
+                if at_risk > 0:
+                    survival[i] = survival[i - 1] * (1 - events / at_risk)
+                else:
+                    survival[i] = survival[i - 1]
+
+        # Step plot.
+        color = colors[color_idx % len(colors)] if colors else "#1F77B4"
+        ax.step(time_sorted, survival, where="post", color=color, linewidth=2, label=label)
+
+        # Confidence interval (approximate).
+        if n_at_risk > 5:
+            se = np.sqrt(survival * (1 - survival) / np.maximum(n_at_risk - np.arange(n_at_risk), 1))
+            ci = 1.96 * se
+            ax.fill_between(time_sorted, np.maximum(survival - ci, 0),
+                            np.minimum(survival + ci, 1),
+                            color=color, alpha=0.15)
+        return None
+
+
+class ROCCurve(ChartPlugin):
+    """ROC (Receiver Operating Characteristic) curve.
+
+    X-axis: False Positive Rate (FPR)
+    Y-axis: True Positive Rate (TPR)
+    Multiple curves for different classifiers, with AUC annotation.
+    """
+    name = "roc"
+    zh = "ROC曲线"
+    kind = "statistics"
+    required_keys = ("fpr", "tpr")
+    optional_keys = ("labels", "auc", "y_score", "y_true")
+    data_format = "json"
+
+    def render(self, data, ax, colors, cjk_fp, **kwargs):
+        # Handle single or multiple ROC curves.
+        fpr_data = data["fpr"]
+        tpr_data = data["tpr"]
+        labels = data.get("labels") or []
+        auc_data = data.get("auc") or []
+
+        # If fpr/tpr are dicts (multi-curve), iterate.
+        if isinstance(fpr_data, dict):
+            for i, (name, fpr_list) in enumerate(fpr_data.items()):
+                tpr_list = tpr_data.get(name, [])
+                auc_val = auc_data.get(name, None) if isinstance(auc_data, dict) else None
+                self._plot_roc(ax, fpr_list, tpr_list, colors, i, name, auc_val)
+        else:
+            # Single curve.
+            fpr_list = fpr_data
+            tpr_list = tpr_data
+            label = labels[0] if labels else "Classifier"
+            auc_val = auc_data[0] if isinstance(auc_data, list) and len(auc_data) > 0 else None
+            self._plot_roc(ax, fpr_list, tpr_list, colors, 0, label, auc_val)
+
+        ax.plot([0, 1], [0, 1], "k--", linewidth=0.8, alpha=0.6, label="Random")
+        ax.set_xlabel("False Positive Rate (FPR)")
+        ax.set_ylabel("True Positive Rate (TPR)")
+        ax.set_xlim(-0.01, 1.01)
+        ax.set_ylim(-0.01, 1.01)
+        # Legend is placed outside the axes by finalize_and_save.
+        return None
+
+    def _plot_roc(self, ax, fpr, tpr, colors, color_idx, label, auc_val):
+        """Plot a single ROC curve."""
+        color = colors[color_idx % len(colors)] if colors else "#1F77B4"
+        auc_text = f" AUC={auc_val:.3f}" if auc_val else ""
+        ax.plot(fpr, tpr, color=color, linewidth=2,
+                label=f"{label}{auc_text}")
+        return None

package/scripts/fig_box.py

@@ -0,0 +1,60 @@
+#!/usr/bin/env python3
+"""Box plot and violin plot generator."""
+import numpy as np
+
+
+def gen_box(data, ax, colors, cjk_fp=None, **kwargs):
+    """Generate box plot with jitter points."""
+    labels = data.get("labels", [])
+    series = data.get("series", {})
+
+    positions = list(range(len(series)))
+    bp = ax.boxplot(list(series.values()), positions=positions, widths=0.5,
+                    patch_artist=True, showfliers=True, flierprops={'marker': 'o', 'alpha': 0.5})
+
+    for i, (patch, name) in enumerate(zip(bp['boxes'], series.keys())):
+        patch.set_facecolor(colors[i % len(colors)])
+        patch.set_alpha(0.6)
+
+    # Jitter points
+    rng = np.random.default_rng(42)
+    for i, (name, values) in enumerate(series.items()):
+        vals = np.array(values, dtype=float)
+        jitter_x = positions[i] + rng.normal(0, 0.06, len(vals))
+        ax.scatter(jitter_x, vals, s=18, c=colors[i % len(colors)], alpha=0.5,
+                   zorder=3, edgecolors='none')
+
+    ax.set_xticks(positions)
+    box_labels = labels if labels and len(labels) == len(series) else list(series.keys())
+    from fig_core import set_ticklabels
+    set_ticklabels(ax, box_labels, 'x', cjk_fp)
+
+
+def gen_violin(data, ax, colors, cjk_fp=None, **kwargs):
+    """Generate violin plot with inner box."""
+    labels = data.get("labels", [])
+    series = data.get("series", {})
+
+    positions = list(range(len(series)))
+    values_list = list(series.values())
+
+    vp = ax.violinplot(values_list, positions=positions, widths=0.6,
+                       showmeans=kwargs.get("show_means", True),
+                       showmedians=kwargs.get("show_medians", True),
+                       showextrema=kwargs.get("show_extrema", True))
+
+    for i, body in enumerate(vp['bodies']):
+        body.set_facecolor(colors[i % len(colors)])
+        body.set_alpha(0.6)
+        body.set_edgecolor(colors[i % len(colors)])
+        body.set_linewidth(1)
+
+    for part in ['cmeans', 'cmedians', 'cmins', 'cmaxes', 'cbars']:
+        if part in vp:
+            vp[part].set_color('#333333')
+            vp[part].set_linewidth(1)
+
+    ax.set_xticks(positions)
+    violin_labels = labels if labels and len(labels) == len(series) else list(series.keys())
+    from fig_core import set_ticklabels
+    set_ticklabels(ax, violin_labels, 'x', cjk_fp)

package/scripts/fig_bubble.py

@@ -0,0 +1,65 @@
+#!/usr/bin/env python3
+"""Bubble chart generator: scatter with size-encoding of a third variable."""
+import numpy as np
+
+
+def gen_bubble(data, ax, colors, cjk_fp=None, **kwargs):
+    """Generate bubble chart.
+
+    Data schema (JSON):
+      {
+        "x":      [numbers],
+        "y":      [numbers],
+        "sizes":  [numbers],            # REQUIRED — drives point area
+        "groups": [labels] (optional),  # color coding
+        "labels": [text]   (optional)   # per-point text annotation
+      }
+    Point area is scaled linearly between a min/max pixel range so the largest
+    value gets the biggest bubble.
+    """
+    x = np.array(data.get("x", []), dtype=float)
+    y = np.array(data.get("y", []), dtype=float)
+    sizes = data.get("sizes")
+    groups = data.get("groups")
+    point_labels = data.get("labels")
+
+    if sizes is None:
+        sizes = np.ones_like(x) * 80
+    sizes = np.array(sizes, dtype=float)
+
+    # Map value -> display area (sqrt for perceptual linearity handled by s=area)
+    smin, smax = 30, 700
+    if sizes.size and (sizes.max() - sizes.min()) > 0:
+        s_norm = (sizes - sizes.min()) / (sizes.max() - sizes.min()) * (smax - smin) + smin
+    else:
+        s_norm = np.full_like(sizes, (smin + smax) / 2, dtype=float)
+
+    if groups is None:
+        ax.scatter(x, y, s=s_norm, color=colors[0], alpha=0.55,
+                   edgecolors='white', linewidth=0.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])
+            ax.scatter(x[mask], y[mask], s=s_norm[mask], color=colors[i % len(colors)],
+                       alpha=0.55, edgecolors='white', linewidth=0.6, label=str(g), zorder=3)
+
+    if point_labels is not None:
+        xmid = float(np.mean(x)) if x.size else 0.0
+        ymid = float(np.mean(y)) if y.size else 0.0
+        for xi, yi, lb in zip(x, y, point_labels):
+            # point labels inward on whichever side is closest to the edge
+            dx = 4 if xi <= xmid else -4
+            dy = 4 if yi <= ymid else -4
+            ax.annotate(str(lb), (xi, yi), textcoords='offset points', xytext=(dx, dy),
+                        ha='left' if dx > 0 else 'right',
+                        va='bottom' if dy > 0 else 'top',
+                        fontsize=7, color='gray')
+
+    ax.margins(0.12)   # headroom so large edge bubbles are not clipped
+    ax.xaxis.grid(True, alpha=0.3, linestyle='--')
+    return None

package/scripts/fig_core.py

@@ -0,0 +1,195 @@
+#!/usr/bin/env python3
+"""Core engine: unified figure creation, style application, and saving."""
+import os, sys
+import matplotlib
+matplotlib.use('Agg')
+import matplotlib.pyplot as plt
+import matplotlib.font_manager as fm
+import numpy as np
+
+SCRIPT_DIR = os.path.dirname(os.path.abspath(__file__))
+sys.path.insert(0, SCRIPT_DIR)
+
+from style_manager import setup_style, list_styles
+from font_detector import detect_cjk_font
+
+
+def has_cjk(text):
+    """Check if text contains CJK characters."""
+    if not text:
+        return False
+    return any('\u4e00' <= ch <= '\u9fff' or '\u3400' <= ch <= '\u4dbf' for ch in str(text))
+
+
+def load_cjk_font(font_path=None):
+    """Load CJK font. Returns (FontProperties, font_name) or (None, None)."""
+    if font_path:
+        if os.path.exists(font_path):
+            fm.fontManager.addfont(font_path)
+            fp = fm.FontProperties(fname=font_path)
+            return fp, fp.get_name()
+    else:
+        detected = detect_cjk_font()
+        if detected and os.path.exists(detected):
+            fm.fontManager.addfont(detected)
+            fp = fm.FontProperties(fname=detected)
+            return fp, fp.get_name()
+    return None, None
+
+
+def _scan_cjk(obj):
+    """Recursively scan any JSON-like structure for CJK text (dict keys included).
+
+    Covers every display field generically — labels, series names, titles,
+    nodes, variables, model names, subplot titles, etc. Number-only containers
+    short-circuit quickly.
+    """
+    if isinstance(obj, str):
+        return has_cjk(obj)
+    if isinstance(obj, dict):
+        return any(_scan_cjk(k) or _scan_cjk(v) for k, v in obj.items())
+    if isinstance(obj, (list, tuple)):
+        return any(_scan_cjk(v) for v in obj)
+    return False
+
+
+def needs_cjk(data, title="", xlabel="", ylabel=""):
+    """Auto-detect if any display text contains CJK characters."""
+    for t in [title, xlabel, ylabel]:
+        if t and has_cjk(t):
+            return True
+    return _scan_cjk(data)
+
+
+def apply_base_style(ax, grid=True):
+    """Apply common styling to axes."""
+    ax.spines["top"].set_visible(False)
+    ax.spines["right"].set_visible(False)
+    if grid:
+        ax.yaxis.grid(True, alpha=0.3, linestyle='--')
+
+
+def set_axis_labels(ax, xlabel, ylabel, cjk_fp=None):
+    """Set axis labels with optional CJK font."""
+    if xlabel:
+        ax.set_xlabel(xlabel, fontproperties=cjk_fp if cjk_fp and has_cjk(xlabel) else None)
+    if ylabel:
+        ax.set_ylabel(ylabel, fontproperties=cjk_fp if cjk_fp and has_cjk(ylabel) else None)
+
+
+def set_title(ax, title, cjk_fp=None):
+    """Set figure title with optional CJK font."""
+    if title:
+        title_text = title.replace('\\n', '\n')
+        ax.set_title(title_text, fontweight='bold', pad=12,
+                     fontproperties=cjk_fp if cjk_fp and has_cjk(title_text) else None)
+
+
+def set_ticklabels(ax, labels, axis='x', cjk_fp=None, rotation=0):
+    """Set tick labels with optional CJK font and rotation."""
+    use_cjk = cjk_fp and any(has_cjk(str(l)) for l in labels)
+    if axis == 'x':
+        ax.set_xticklabels(labels, fontproperties=cjk_fp if use_cjk else None, rotation=rotation)
+    else:
+        ax.set_yticklabels(labels, fontproperties=cjk_fp if use_cjk else None)
+
+
+def separate_labels(ax, texts, max_iter=80, clamp=None, gap=0.55):
+    """Best-effort 2D de-overlap of text labels using display-space bounding boxes.
+
+    Overlapping labels are pushed apart along the line joining their centres.
+    ``clamp`` optionally bounds the data coordinates, e.g.
+    ``[(0.02, 3.12), (0.0, None)]``. Silently no-ops when the backend exposes no
+    renderer (so it is always safe to call). Only works for ``ax.text`` artists
+    whose position is expressed in data coordinates.
+    """
+    texts = [t for t in texts if t is not None]
+    if len(texts) < 2:
+        return
+    try:
+        fig = ax.figure
+        fig.canvas.draw()
+        renderer = fig.canvas.get_renderer()
+    except Exception:
+        return
+    inv = ax.transData.inverted()
+    for _ in range(max_iter):
+        boxes = [t.get_window_extent(renderer) for t in texts]
+        moved = False
+        for a in range(len(texts)):
+            for b in range(a + 1, len(texts)):
+                ba, bb = boxes[a], boxes[b]
+                if not ba.overlaps(bb):
+                    continue
+                acx, acy = (ba.x0 + ba.x1) * 0.5, (ba.y0 + ba.y1) * 0.5
+                bcx, bcy = (bb.x0 + bb.x1) * 0.5, (bb.y0 + bb.y1) * 0.5
+                dx, dy = bcx - acx, bcy - acy
+                dist = (dx * dx + dy * dy) ** 0.5
+                if dist < 1e-6:
+                    dx, dy, dist = 0.0, 1.0, 1.0
+                ux, uy = dx / dist, dy / dist
+                step = gap * min(ba.height, bb.height)
+                for t, sgn in ((texts[a], -1.0), (texts[b], 1.0)):
+                    x_, y_ = t.get_position()
+                    disp = ax.transData.transform((x_, y_))
+                    nx, ny = inv.transform((disp[0] + sgn * ux * step,
+                                            disp[1] + sgn * uy * step))
+                    if clamp is not None:
+                        (lo0, hi0), (lo1, hi1) = clamp
+                        nx = min(max(nx, lo0), hi0) if hi0 is not None else max(nx, lo0)
+                        ny = min(max(ny, lo1), hi1) if hi1 is not None else max(ny, lo1)
+                    t.set_position((nx, ny))
+                moved = True
+        if not moved:
+            break
+        try:
+            fig.canvas.draw()
+        except Exception:
+            break
+
+
+def finalize_and_save(fig, ax, out_path, legend=True, colorbar_artist=None, cbar_label=None,
+                      cjk_fp=None, tight=True):
+    """Finalize figure: legend, colorbar, layout, save.
+
+    Legend policy: place outside the axes on the right by default. This avoids
+    the classic "legend overlaps data" problem that ``loc='best'`` creates for
+    dense or multi-series charts. ``bbox_inches='tight'`` at save time ensures
+    the legend is never clipped, even if the requested figure width is small.
+    """
+    # Respect a legend the generator already placed (e.g. windrose speed bins)
+    if legend and ax.get_legend() is None and ax.get_legend_handles_labels()[1]:
+        ax.legend(loc='upper left', bbox_to_anchor=(1.02, 1.0), borderaxespad=0,
+                  framealpha=0.9, prop=cjk_fp if cjk_fp else None)
+
+    if colorbar_artist is not None and hasattr(colorbar_artist, 'get_cmap'):
+        cbar = fig.colorbar(colorbar_artist, ax=ax, shrink=0.8)
+        if cbar_label:
+            cbar.set_label(cbar_label)
+
+    if tight:
+        try:
+            # If the figure has a twin axes (e.g. histogram + KDE density), reserve
+            # extra right margin so the secondary y-label is not clipped.
+            has_twinx = len(fig.axes) > 1
+            if has_twinx:
+                fig.tight_layout(rect=[0, 0, 0.88, 1])
+            else:
+                fig.tight_layout()
+        except Exception:
+            # scienceplots may produce very large bboxes in edge cases (e.g. forest),
+            # or MemoryError if elements fall outside axes bounds
+            plt.subplots_adjust(left=0.15, right=0.82 if len(fig.axes) > 1 else 0.85)
+
+    out_ext = os.path.splitext(out_path)[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(out_path, **save_kwargs)
+    plt.close(fig)
+
+    sz = os.path.getsize(out_path)
+    print(f"Saved: {out_path} ({sz:,} bytes)", file=sys.stderr)