like-sci-figures 0.0.0-stage → 1.0.0

package/scripts/fig_datasci.py

@@ -0,0 +1,276 @@
+#!/usr/bin/env python3
+"""Data science chart types: ridge, ternary, dot_plot, dendrogram.
+
+These chart types are commonly used in data science, ecology, materials
+science, and clustering analysis. Each is implemented as a ChartPlugin
+subclass for automatic palette integration.
+"""
+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 RidgePlot(ChartPlugin):
+    """Ridge plot (joyplot) for comparing multiple distributions.
+
+    Overlaid density curves offset vertically, one per group.
+    """
+    name = "ridge"
+    zh = "岭图"
+    kind = "statistics"
+    required_keys = ("series",)
+    optional_keys = ("labels", "bandwidth", "fill")
+    data_format = "json"
+
+    def render(self, data, ax, colors, cjk_fp, **kwargs):
+        series = data["series"]
+        labels = data.get("labels") or list(series.keys())
+        bandwidth = float(data.get("bandwidth", 0.5))
+        fill = data.get("fill", True)
+
+        keys = list(series.keys())
+        n = len(keys)
+        if n == 0:
+            return None
+
+        # Plot each distribution, offset vertically.
+        for i, key in enumerate(keys):
+            values = np.asarray(series[key], dtype=float)
+            if len(values) < 2:
+                continue
+            # Compute KDE (simple Gaussian kernel).
+            x_range = np.linspace(values.min() - bandwidth,
+                                  values.max() + bandwidth, 200)
+            kde = np.array([_gaussian_kde(v, x_range, bandwidth) for v in values])
+            kde_sum = kde.sum(axis=0)
+
+            color = colors[i % len(colors)] if colors else "#1F77B4"
+            ax.fill_between(x_range, i, i + kde_sum, alpha=0.3 if fill else 0,
+                            color=color)
+            ax.plot(x_range, i + kde_sum, color=color, linewidth=1.5)
+            fp = _load_cjk_font(cjk_fp)
+            ax.text(x_range.min() - 0.1, i, labels[i % len(labels)],
+                    ha="right", va="center", fontsize=8, fontproperties=fp)
+
+        ax.set_yticks([])
+        ax.set_xlabel("Value")
+        ax.invert_yaxis()
+        return None
+
+
+def _gaussian_kde(values, x_range, bandwidth):
+    """Simple 1D Gaussian kernel density estimate."""
+    return np.exp(-0.5 * ((x_range - values) / bandwidth) ** 2) / \
+        (bandwidth * np.sqrt(2 * np.pi))
+
+
+class TernaryPlot(ChartPlugin):
+    """Ternary plot for three-component compositions (A + B + C = 1).
+
+    Each point is (A, B, C) where A+B+C=1. Used in geology, materials science,
+    and mixture analysis.
+    """
+    name = "ternary"
+    zh = "三元相图"
+    kind = "specialized"
+    required_keys = ("points",)
+    optional_keys = ("labels", "A_label", "B_label", "C_label")
+    data_format = "json"
+
+    def render(self, data, ax, colors, cjk_fp, **kwargs):
+        points = data["points"]
+        labels = data.get("labels") or []
+        a_label = data.get("A_label", "A")
+        b_label = data.get("B_label", "B")
+        c_label = data.get("C_label", "C")
+
+        fp = _load_cjk_font(cjk_fp)
+
+        # Convert ternary coordinates to Cartesian.
+        # A = (0, 1), B = (1, 0), C = (0.5, 0) (equilateral triangle).
+        ax.set_xlim(0, 1)
+        ax.set_ylim(0, 1)
+        ax.set_aspect("equal")
+        ax.axis("off")
+
+        # Draw triangle.
+        triangle = [(0, 0), (1, 0), (0.5, 1), (0, 0)]
+        xs = [p[0] for p in triangle]
+        ys = [p[1] for p in triangle]
+        ax.plot(xs, ys, "k-", linewidth=1.5)
+
+        # Grid lines.
+        for i in range(1, 5):
+            frac = i / 5
+            ax.plot([frac * 0.5, 1 - frac * 0.5], [frac, frac], "k-",
+                    linewidth=0.5, alpha=0.3)
+
+        # Label corners.
+        ax.text(0.5, 1.02, a_label, ha="center", va="bottom", fontsize=10,
+                fontproperties=fp)
+        ax.text(1.02, -0.02, b_label, ha="left", va="center", fontsize=10,
+                fontproperties=fp)
+        ax.text(-0.02, -0.02, c_label, ha="right", va="center", fontsize=10,
+                fontproperties=fp)
+
+        # Plot points.
+        if isinstance(points, dict):
+            # Grouped points: {group_name: [(a, b, c), ...]}
+            groups = list(points.keys())
+            for gi, group in enumerate(groups):
+                pts = points[group]
+                color = colors[gi % len(colors)] if colors else "#1F77B4"
+                for j, pt in enumerate(pts):
+                    a, b, c = pt[0], pt[1], pt[2]
+                    # Ternary to Cartesian: x = b + a/2, y = a*sqrt(3)/2
+                    x = b + a / 2
+                    y = a * np.sqrt(3) / 2
+                    ax.scatter(x, y, s=50, color=color,
+                              edgecolors="black", linewidths=0.5)
+                    if labels and j < len(labels[group]):
+                        ax.annotate(str(labels[group][j]), (x, y),
+                                   textcoords="offset points", xytext=(5, 5),
+                                   fontsize=7, fontproperties=fp)
+        else:
+            # Single group of points: [(a, b, c), ...]
+            for j, pt in enumerate(points):
+                a, b, c = pt[0], pt[1], pt[2]
+                x = b + a / 2
+                y = a * np.sqrt(3) / 2
+                ax.scatter(x, y, s=50, color=colors[0] if colors else "#1F77B4",
+                          edgecolors="black", linewidths=0.5)
+                if labels and j < len(labels):
+                    ax.annotate(str(labels[j]), (x, y),
+                               textcoords="offset points", xytext=(5, 5),
+                               fontsize=7, fontproperties=fp)
+        return None
+
+
+class DotPlot(ChartPlugin):
+    """Dot plot (strip plot) for showing distributions as individual points.
+
+    Used in ecology, bioinformatics, and sequence alignment visualization.
+    """
+    name = "dot_plot"
+    zh = "点图"
+    kind = "statistics"
+    required_keys = ("x", "y")
+    optional_keys = ("labels", "group", "size", "color_by")
+    data_format = "json"
+
+    def render(self, data, ax, colors, cjk_fp, **kwargs):
+        x = np.asarray(data["x"])
+        y = np.asarray(data["y"])
+        labels = data.get("labels") or []
+        group = data.get("group")
+        sizes = data.get("size") or [50] * len(x)
+        color_by = data.get("color_by")
+
+        if group and color_by:
+            # Color by group.
+            unique_groups = sorted(set(group))
+            for i, grp in enumerate(unique_groups):
+                mask = np.array(group) == grp
+                color = colors[i % len(colors)] if colors else "#1F77B4"
+                ax.scatter(x[mask], y[mask], s=sizes, color=color,
+                           edgecolors="black", linewidths=0.5,
+                           label=str(grp))
+            # Legend is placed outside the axes by finalize_and_save.
+        elif group:
+            # Jitter x by group.
+            unique_groups = sorted(set(group))
+            for i, grp in enumerate(unique_groups):
+                mask = np.array(group) == grp
+                jitter = np.random.uniform(-0.1, 0.1, size=len(x[mask]))
+                color = colors[i % len(colors)] if colors else "#1F77B4"
+                ax.scatter(x[mask] + jitter, y[mask], s=sizes,
+                           color=color, edgecolors="black", linewidths=0.5)
+        else:
+            # Single color.
+            ax.scatter(x, y, s=sizes, color=colors[0] if colors else "#1F77B4",
+                       edgecolors="black", linewidths=0.5)
+
+        # Label points.
+        if labels and len(labels) > 0:
+            for i, label in enumerate(labels):
+                if i < len(x):
+                    fp = _load_cjk_font(cjk_fp)
+                    ax.annotate(str(label), (x[i], y[i]),
+                               textcoords="offset points", xytext=(5, 5),
+                               fontsize=7, fontproperties=fp)
+
+        ax.set_xlabel("X")
+        ax.set_ylabel("Y")
+        return None
+
+
+class DendrogramPlot(ChartPlugin):
+    """Dendrogram for hierarchical clustering visualization.
+
+    Data format:
+        leaves: list of leaf labels
+        merges: list of [left_idx, right_idx, height] tuples
+                - indices < n_leaves refer to leaves
+                - indices >= n_leaves refer to internal nodes (0-based from merges)
+    """
+    name = "dendrogram"
+    zh = "树状图"
+    kind = "specialized"
+    required_keys = ("leaves", "merges")
+    optional_keys = ("threshold",)
+    data_format = "json"
+
+    def render(self, data, ax, colors, cjk_fp, **kwargs):
+        leaves = data["leaves"]
+        merges = data["merges"]
+        threshold = data.get("threshold", None)
+        n_leaves = len(leaves)
+        fp = _load_cjk_font(cjk_fp)
+
+        # Assign x positions to leaves.
+        leaf_x = {i: i + 1 for i in range(n_leaves)}
+        # x positions for internal nodes (computed after merge).
+        node_x = {}
+
+        max_h = max(m[2] for m in merges) if merges else 1.0
+        ax.set_xlim(0.5, n_leaves + 0.5)
+        ax.set_ylim(0, max_h * 1.15)
+
+        # Draw leaves.
+        for i, label in enumerate(leaves):
+            x = leaf_x[i]
+            ax.plot([x, x], [0, 0.01], "k-", linewidth=0.5)
+            ax.text(x, -0.02, str(label), ha="center", va="top",
+                    fontsize=7, fontproperties=fp, rotation=45)
+
+        # Draw merges bottom-up.
+        for mi, (left, right, h) in enumerate(merges):
+            # Resolve x positions for children.
+            lx = leaf_x.get(left, node_x.get(left, 0))
+            rx = leaf_x.get(right, node_x.get(right, 0))
+            # Assign x for this internal node (midpoint).
+            node_x[mi] = (lx + rx) / 2
+            # Draw U-shape.
+            ax.plot([lx, lx], [0, h], "k-", linewidth=1.0)
+            ax.plot([rx, rx], [0, h], "k-", linewidth=1.0)
+            ax.plot([lx, rx], [h, h], "k-", linewidth=1.5)
+
+        # Threshold line.
+        if threshold is not None:
+            ax.axhline(threshold, color="red", linestyle="--",
+                       linewidth=1.0, alpha=0.7)
+
+        ax.set_xlabel("Cluster")
+        ax.set_ylabel("Distance")
+        ax.set_yticks([])
+        ax.tick_params(axis="x", length=0)
+        return None

package/scripts/fig_distribution.py

@@ -0,0 +1,59 @@
+#!/usr/bin/env python3
+"""Distribution chart generator: histogram and density/KDE plots."""
+import numpy as np
+from scipy import stats
+
+
+def gen_histogram(data, ax, colors, cjk_fp=None, **kwargs):
+    """Generate histogram with optional KDE overlay."""
+    series = data.get("series", {})
+    values = data.get("values", [])
+
+    if not values and series:
+        # Take first series
+        values = list(series.values())[0] if series else []
+
+    if not values:
+        return
+
+    values = np.array(values, dtype=float)
+    bins = kwargs.get("bins", "auto")
+    density = kwargs.get("density", False)
+    alpha = kwargs.get("alpha", 0.7)
+
+    ax.hist(values, bins=bins, density=density, alpha=alpha, color=colors[0],
+            edgecolor='white', linewidth=0.5, label=data.get("name", ""))
+
+    # KDE overlay
+    if kwargs.get("kde", True) and len(values) >= 3:
+        kde_x = np.linspace(values.min(), values.max(), 200)
+        try:
+            kde = stats.gaussian_kde(values)
+            ax2 = ax.twinx()
+            # Move the right spine outward so its label is not clipped.
+            ax2.spines['right'].set_position(('outward', 12))
+            ax2.plot(kde_x, kde(kde_x), color=colors[1] if len(colors) > 1 else '#333333',
+                     linewidth=2, alpha=0.8)
+            ax2.set_ylabel('Density', fontsize=8)
+            ax2.yaxis.label.set_color(colors[1] if len(colors) > 1 else '#333333')
+        except Exception:
+            pass
+
+
+def gen_density(data, ax, colors, cjk_fp=None, **kwargs):
+    """Generate density/KDE plot for one or more series."""
+    series = data.get("series", {})
+    values_list = data.get("values", [])
+
+    if values_list and not series:
+        series = {"Data": values_list}
+
+    for i, (name, values) in enumerate(series.items()):
+        vals = np.array(values, dtype=float)
+        xs = np.linspace(vals.min() - (vals.std() or 1), vals.max() + (vals.std() or 1), 200)
+        try:
+            kde = stats.gaussian_kde(vals)
+            ax.plot(xs, kde(xs), color=colors[i % len(colors)], linewidth=2, label=name)
+            ax.fill_between(xs, kde(xs), color=colors[i % len(colors)], alpha=0.15)
+        except Exception:
+            pass

package/scripts/fig_engineering.py

@@ -0,0 +1,224 @@
+#!/usr/bin/env python3
+"""Engineering/finance chart types: slope, waterfall, bode, periodogram.
+
+These chart types are commonly used in finance (waterfall, slope), control
+systems (bode), and signal processing (periodogram). Each is implemented as
+a ChartPlugin subclass for automatic palette integration.
+"""
+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 SlopeChart(ChartPlugin):
+    """Slope chart for comparing values across two time points.
+
+    Simple but effective for showing change over time between two categories.
+    """
+    name = "slope"
+    zh = "斜率图"
+    kind = "relational"
+    required_keys = ("labels", "before", "after")
+    optional_keys = ("x_labels", "y_min", "y_max")
+    data_format = "json"
+
+    def render(self, data, ax, colors, cjk_fp, **kwargs):
+        labels = data["labels"]
+        before = np.asarray(data["before"], dtype=float)
+        after = np.asarray(data["after"], dtype=float)
+        x_labels = data.get("x_labels", ["Before", "After"])
+        y_min = data.get("y_min", None)
+        y_max = data.get("y_max", None)
+
+        fp = _load_cjk_font(cjk_fp)
+        n = len(labels)
+        if n == 0:
+            return None
+
+        for i in range(n):
+            color = colors[i % len(colors)] if colors else "#1F77B4"
+            ax.plot([0, 1], [before[i], after[i]], color=color,
+                    linewidth=2, alpha=0.8)
+            # Labels on left (before).
+            ax.text(-0.02, before[i], str(labels[i]), ha="right",
+                    va="center", fontsize=8, fontproperties=fp, color=color)
+            # Labels on right (after).
+            ax.text(1.02, after[i], str(labels[i]), ha="left",
+                    va="center", fontsize=8, fontproperties=fp, color=color)
+            # Value labels.
+            ax.text(0, before[i], " %s" % format(before[i], ".1f"),
+                    ha="left", va="center", fontsize=7, color=color,
+                    fontproperties=fp)
+            ax.text(1, after[i], format(after[i], ".1f"),
+                    ha="right", va="center", fontsize=7, color=color,
+                    fontproperties=fp)
+
+        ax.set_xticks([0, 1])
+        ax.set_xticklabels(x_labels, fontsize=10)
+        if y_min is not None:
+            ax.set_ylim(y_min, y_max)
+
+        ax.set_xlim(-0.15, 1.15)
+        ax.set_ylabel("Value")
+        return None
+
+
+class WaterfallChart(ChartPlugin):
+    """Waterfall chart showing cumulative changes from a starting value.
+
+    Used in finance (P&L bridge), project management, and financial reporting.
+    """
+    name = "waterfall"
+    zh = "瀑布图"
+    kind = "statistics"
+    required_keys = ("labels", "values")
+    optional_keys = ("total_label", "show_values")
+    data_format = "json"
+
+    def render(self, data, ax, colors, cjk_fp, **kwargs):
+        labels = data["labels"]
+        values = np.asarray(data["values"], dtype=float)
+        show_values = data.get("show_values", True)
+        fp = _load_cjk_font(cjk_fp)
+        n = len(labels)
+        if n == 0:
+            return None
+
+        # Compute cumulative positions.
+        cumsum = np.cumsum(values)
+        start = np.zeros(n)
+        start[1:] = cumsum[:-1]
+
+        # Colors: positive = green-ish, negative = red-ish, total = blue-ish.
+        pos_color = colors[0] if colors else "#2CA02C"
+        neg_color = colors[1] if len(colors) > 1 else "#D62728"
+        total_color = colors[2] if len(colors) > 2 else "#1F77B4"
+
+        for i in range(n):
+            v = values[i]
+            if i == n - 1 and abs(v) < 0.01:
+                # Last bar might be the total.
+                color = total_color
+            elif v >= 0:
+                color = pos_color
+            else:
+                color = neg_color
+            ax.bar(i, v, bottom=start[i], color=color, edgecolor="black",
+                   linewidth=0.5, width=0.6)
+
+            # Value label.
+            if show_values:
+                y_pos = start[i] + v / 2
+                ax.text(i, y_pos, format(v, ".1f"), ha="center",
+                        va="center", fontsize=7, fontproperties=fp)
+
+        # Draw connecting lines.
+        for i in range(n - 1):
+            ax.plot([i + 0.3, i + 1 - 0.3], [cumsum[i], cumsum[i]],
+                    "k--", linewidth=0.5, alpha=0.5)
+
+        ax.set_xticks(range(n))
+        ax.set_xticklabels(labels, fontsize=8, fontproperties=fp)
+        ax.set_ylabel("Value")
+        return None
+
+
+class BodePlot(ChartPlugin):
+    """Bode plot for control systems (magnitude + phase vs frequency).
+
+    Two panels: magnitude (dB) and phase (degrees) on log frequency scale.
+    """
+    name = "bode"
+    zh = "博德图"
+    kind = "specialized"
+    required_keys = ("freq", "mag", "phase")
+    optional_keys = ("gain_db", "phase_deg", "freq_hz")
+    data_format = "json"
+
+    def render(self, data, ax, colors, cjk_fp, **kwargs):
+        freq = np.asarray(data["freq"], dtype=float)
+        mag = np.asarray(data["mag"], dtype=float)
+        phase = np.asarray(data["phase"], dtype=float)
+        gain_db = data.get("gain_db", True)
+        phase_deg = data.get("phase_deg", True)
+        freq_hz = data.get("freq_hz", True)
+
+        fp = _load_cjk_font(cjk_fp)
+        n = len(freq)
+        if n == 0:
+            return None
+
+        # Magnitude panel (top half).
+        mag_y = 0.55 + 0.4 * (mag - mag.min()) / (mag.max() - mag.min() + 1e-10)
+        ax.plot(freq, mag_y, color=colors[0] if colors else "#1F77B4",
+                linewidth=2)
+        ax.fill_between(freq, 0.55, mag_y, alpha=0.15,
+                        color=colors[0] if colors else "#1F77B4")
+
+        # Phase panel (bottom half).
+        phase_y = 0.45 - 0.4 * (phase - phase.min()) / (phase.max() - phase.min() + 1e-10)
+        ax.plot(freq, phase_y, color=colors[1] if len(colors) > 1 else "#D62728",
+                linewidth=2, linestyle="--")
+
+        # Separator line.
+        ax.axhline(0.5, color="grey", linewidth=0.5, linestyle="-")
+
+        # Labels.
+        ax.set_xlabel("Frequency (Hz)" if freq_hz else "Frequency (rad/s)")
+        ax.set_ylabel("Magnitude (dB)" if gain_db else "Magnitude")
+        ax.text(0.02, 0.95, "Magnitude", transform=ax.transAxes,
+                fontsize=9, fontproperties=fp)
+        ax.text(0.02, 0.05, "Phase (%s)" % ("deg" if phase_deg else "rad"),
+                transform=ax.transAxes, fontsize=9, fontproperties=fp)
+        return None
+
+
+class PeriodogramPlot(ChartPlugin):
+    """Periodogram (power spectral density) for signal analysis.
+
+    Shows frequency content of a signal. Used in signal processing,
+    seismology, and vibration analysis.
+    """
+    name = "periodogram"
+    zh = "周期图"
+    kind = "specialized"
+    required_keys = ("freq", "psd")
+    optional_keys = ("x_labels", "ylabel", "log_scale")
+    data_format = "json"
+
+    def render(self, data, ax, colors, cjk_fp, **kwargs):
+        freq = np.asarray(data["freq"], dtype=float)
+        psd = np.asarray(data["psd"], dtype=float)
+        x_labels = data.get("x_labels", "Frequency (Hz)")
+        ylabel = data.get("ylabel", "PSD")
+        log_scale = data.get("log_scale", False)
+
+        fp = _load_cjk_font(cjk_fp)
+        n = len(freq)
+        if n == 0:
+            return None
+
+        if log_scale:
+            psd_plot = np.log10(np.clip(psd, 1e-20, None))
+        else:
+            psd_plot = psd
+
+        ax.plot(freq, psd_plot, color=colors[0] if colors else "#1F77B4",
+                linewidth=1.5)
+        ax.fill_between(freq, ax.get_ylim()[0], psd_plot, alpha=0.2,
+                        color=colors[0] if colors else "#1F77B4")
+
+        ax.set_xlabel(x_labels)
+        ax.set_ylabel(ylabel + " (dB)" if log_scale else ylabel)
+        if log_scale:
+            ax.set_yscale("linear")
+        return None