Skip to content

aipoch/open-science / resources/skills/figure-style

figure-style

Verified

Publication-grade correctness and legibility rules for final-deliverable scientific figures, not exploratory plots. Use for a figure that will ship in a report, paper, export, or kept artifact. Covers data fidelity, label economy, color threading, chart choice, layout, and render-then-verify QA without imposing a visual house style. For multi-panel composition use `figure-composer`; for whole-paper ordering use `paper-narrative`.

FileKindSize
SKILL.mdskill md20.2 KB
kernel.pyscript17.5 KB
open-science.jsonconfig493 B
META_GREY = "#888888"


def apply_figure_style(*, frame="open", font=None, sizes=(8, 7, 6), grid=False):
    """Set matplotlib rcParams for publication-grade output. Call once before plotting.

    This sets mechanics (role-mapped font-size ladder, outward ticks, frameless
    legends, 300-dpi save, Type-42 embedded fonts) — not a house aesthetic.
    Frame, font and the size ladder are parameters.

    frame : 'open' (bottom+left spines, default) | 'boxed' (all four) | 'none'
    font  : sans-serif family name; None = system default sans-serif
    sizes : (base, secondary, tick) — titles/axis-labels, legend/annotation, ticks
    grid  : whether to draw axes.grid (default False)
    """
    import matplotlib as mpl
    if frame not in ("open", "boxed", "none"):
        raise ValueError(f"frame must be 'open'|'boxed'|'none', got {frame!r}")

    try:
        import os, sys, glob, matplotlib.font_manager as fm
        fdir = os.path.join(os.environ.get("CONDA_PREFIX") or sys.prefix, "fonts")
        if os.path.isdir(fdir):
            known = {f.fname for f in fm.fontManager.ttflist}
            for f in glob.glob(os.path.join(fdir, "*.ttf")):
                if f not in known:
                    fm.fontManager.addfont(f)
    except Exception:
        pass
    base, secondary, tick = sizes
    boxed = (frame == "boxed")
    rc = {
        "font.family": "sans-serif",
        "font.size": base,
        "axes.labelsize": base,
        "axes.titlesize": base,
        "legend.fontsize": secondary,
        "xtick.labelsize": tick,
        "ytick.labelsize": tick,
        "axes.linewidth": 0.6,
        "xtick.direction": "out", "ytick.direction": "out",
        "xtick.major.size": 3, "ytick.major.size": 3,
        "xtick.major.width": 0.6, "ytick.major.width": 0.6,
        "axes.spines.top": boxed, "axes.spines.right": boxed,
        "axes.spines.left": frame != "none", "axes.spines.bottom": frame != "none",
        "axes.grid": bool(grid),
        "legend.frameon": False,
        "figure.dpi": 200,
        "savefig.dpi": 300,
        "savefig.bbox": "tight",
        "axes.titleweight": "normal",
        "axes.titlelocation": "left",
        "axes.labelweight": "normal",
        "lines.linewidth": 1.2,
        "patch.linewidth": 0.6,
        "pdf.fonttype": 42, "ps.fonttype": 42,
    }
    if font:
        rc["font.sans-serif"] = [font, "DejaVu Sans"]
    mpl.rcParams.update(rc)


def set_frame(ax, style="open"):
    """§3: set spine visibility on an existing axes. style ∈ {'open','boxed','none'}."""
    show = {"open": (False, False, True, True),
            "boxed": (True, True, True, True),
            "none": (False, False, False, False)}[style]
    for side, vis in zip(("top", "right", "bottom", "left"), show):
        ax.spines[side].set_visible(vis)
        if vis:
            ax.spines[side].set_linewidth(0.6)
    ax.tick_params(direction="out", length=0 if style == "none" else 3, width=0.6)


def panel_letter(ax, letter, dx=-0.18, dy=1.02, case="lower", fontsize=None):
    """§5.7: bold panel letter outside top-left of axes. case ∈ {'lower','upper'}."""
    import matplotlib.pyplot as plt
    if fontsize is None:
        fontsize = plt.rcParams.get("font.size", 8) + 1
    s = letter.lower() if case == "lower" else letter.upper()
    artist = ax.text(dx, dy, s, transform=ax.transAxes,
                     fontweight="bold", fontsize=fontsize, va="bottom", ha="left")
    artist.set_gid("figure-style-panel-letter")


def focal_palette(labels, focal, focal_color, other="muted", base_colors=None):
    """§4.2: map labels → colors with the focal series visually dominant.

    other='muted'   — desaturate base_colors (or a default cycle) toward gray
    other='grey'    — uniform light gray for all non-focal
    other='ordinal' — non-focal on a single light→dark gray ramp (input order)
    """
    import matplotlib.colors as mcolors
    import matplotlib.pyplot as plt
    focal_set = {focal} if isinstance(focal, str) else set(focal)
    n = len(labels)
    if not focal_set & set(labels):
        raise ValueError(f"focal {focal!r} not found in labels")
    base_colors = [] if base_colors is None else list(base_colors)
    if not base_colors:
        base_colors = plt.rcParams["axes.prop_cycle"].by_key().get("color", ["#444444"])
    if not base_colors:
        base_colors = ["#444444"]
    base_colors = [base_colors[i % len(base_colors)] for i in range(n)]
    if other == "grey":
        rest = ["#BCBCBC"] * n
    elif other == "ordinal":
        nf = max(1, n - len(focal_set))
        ramp = [mcolors.to_hex((v, v, v)) for v in
                ([0.55] if nf == 1 else [0.80 - 0.35 * i / (nf - 1) for i in range(nf)])]
        rest, k = [], 0
        for l in labels:
            rest.append(ramp[min(k, nf - 1)]); k += (l not in focal_set)
    elif other == "muted":
        def mute(c):
            r, g, b = mcolors.to_rgb(c)
            m = (r + g + b) / 3
            return mcolors.to_hex((0.3 * r + 0.7 * m, 0.3 * g + 0.7 * m, 0.3 * b + 0.7 * m))
        rest = [mute(c) for c in base_colors]
    else:
        raise ValueError("other must be 'muted', 'grey', or 'ordinal'")
    return [focal_color if l in focal_set else rest[i] for i, l in enumerate(labels)]


def bar_with_points(ax, x, ymat, labels, colors, jitter=0.08, show_points=True,
                    errorbar=None, point_alpha=0.5, point_size=8):
    """§6.1: bar = mean; optionally overlay raw points or draw an interval.

    colors   : per-label color list (e.g. from focal_palette)
    x, ymat and labels must have equal lengths; mismatches raise before drawing.
    Each group must be a nonempty, finite, one-dimensional real numeric array.
    Requested SD/CI intervals require at least two observations per group.
    errorbar : None | 'sd' | 'ci95' — drawn only when show_points is False.
               'ci95' is the t-distribution 95% CI of the mean
               (half-width t_{0.975,n-1} · s/√n); correct at small n where the
               z-approximation (1.96·s/√n) is markedly too narrow.
    """
    import numpy as np
    x = np.asarray(x)
    if x.ndim != 1 or not np.issubdtype(x.dtype, np.number):
        raise TypeError(
            "bar_with_points x must be one-dimensional numeric positions; "
            "pass category names through labels"
        )
    ymat = list(ymat)
    labels = list(labels)
    if len(x) != len(ymat) or len(x) != len(labels):
        raise ValueError("bar_with_points x, ymat and labels must have equal lengths")
    if colors is not None and not isinstance(colors, str):
        colors = list(colors)
        if not colors:
            colors = None
    if x.dtype.kind not in "iuf" or not np.isfinite(x).all():
        raise ValueError("bar_with_points x must contain finite real positions")
    for i, y in enumerate(ymat):
        if np.ma.isMaskedArray(y) and np.ma.getmaskarray(y).any():
            raise ValueError(f"bar_with_points group {i} contains masked observations; resolve exclusions explicitly before plotting")
    ymat = [np.asarray(y) for y in ymat]
    for i, y in enumerate(ymat):
        if y.ndim != 1 or y.size == 0 or y.dtype.kind not in "iuf" or not np.isfinite(y).all():
            raise ValueError(f"bar_with_points group {i} must be nonempty, one-dimensional and finite real numeric data")
    if errorbar and not show_points:
        if errorbar not in ("sd", "ci95"):
            raise ValueError("errorbar must be None, 'sd', or 'ci95'")
        if any(y.size < 2 for y in ymat):
            raise ValueError("SD/CI cannot be estimated from one observation; use raw points without an interval")
    means = np.array([np.mean(y) for y in ymat], float)
    err = None
    if errorbar and not show_points:
        if errorbar == "sd":
            err = np.array([np.std(y, ddof=1) for y in ymat])
        elif errorbar == "ci95":
            from scipy.stats import t
            def _hw(y):
                n = np.asarray(y).size
                return t.ppf(0.975, n - 1) * np.std(y, ddof=1) / np.sqrt(n)
            err = np.array([_hw(y) for y in ymat])
    ax.bar(x, means, color=colors, width=0.7, edgecolor="none",
           yerr=err, error_kw={"elinewidth": 0.8, "capsize": 0})
    if show_points:
        for xi, ys in zip(x, ymat):
            ys = np.asarray(ys)
            if ys.ndim == 1 and ys.size > 0:
                jit = (np.random.rand(ys.size) - 0.5) * 2 * jitter
                ax.scatter(np.full(ys.size, xi) + jit, ys, s=point_size, color="black",
                           alpha=point_alpha, zorder=3, linewidths=0)
    ax.set_xticks(x); ax.set_xticklabels(labels)
    return ax


def strip_with_median(ax, groups, values, colors=None, jitter=0.12):
    """§6.1: jittered points + bold horizontal median tick per group.

    groups and values must have equal lengths. Mismatches raise before drawing.
    colors=None or an empty color sequence supplies default gray; a nonempty
    color sequence cycles across groups.
    Each group must be nonempty, one-dimensional and finite real numeric data;
    resolve missing observations explicitly before plotting.
    """
    import numpy as np
    labs = list(groups)
    values = list(values)
    if len(labs) != len(values):
        raise ValueError("strip_with_median groups and values must have equal lengths")
    for i, y in enumerate(values):
        if np.ma.isMaskedArray(y) and np.ma.getmaskarray(y).any():
            raise ValueError(f"strip_with_median group {i} contains masked observations; resolve exclusions explicitly before plotting")
    values = [np.asarray(y) for y in values]
    for i, y in enumerate(values):
        if y.ndim != 1 or y.size == 0 or y.dtype.kind not in "iuf" or not np.isfinite(y).all():
            raise ValueError(f"strip_with_median group {i} must be nonempty, one-dimensional and finite real numeric data")
    colors = [] if colors is None else list(colors)
    if not colors:
        colors = ["#444444"]
    for i, ys in enumerate(values):
        c = colors[i % len(colors)]
        ys = np.asarray(ys)
        jit = (np.random.rand(ys.size) - 0.5) * 2 * jitter
        ax.scatter(np.full(ys.size, i) + jit, ys, s=10, color=c, alpha=0.6, linewidths=0, zorder=2)
        m = np.median(ys)
        ax.plot([i - 0.22, i + 0.22], [m, m], color="black", lw=1.6, zorder=3)
    ax.set_xticks(range(len(labs))); ax.set_xticklabels(labs)
    return ax


def goodness_arrow(ax, text="higher = better", loc="upper left", axis="y", fontsize=None):
    """§3.6: small upright direction-of-goodness cue in the margin."""
    import matplotlib.pyplot as plt
    if fontsize is None:
        fontsize = plt.rcParams["legend.fontsize"]
    pos = {"upper left": (0.02, 0.98), "upper right": (0.98, 0.98),
           "lower left": (0.02, 0.02), "lower right": (0.98, 0.02)}[loc]
    ha = "left" if "left" in loc else "right"
    va = "top" if "upper" in loc else "bottom"
    arrow = "↑ " if axis == "y" else "→ "
    ax.text(pos[0], pos[1], arrow + text, transform=ax.transAxes,
            fontsize=fontsize, color=META_GREY, ha=ha, va=va)


def two_tier_label(name, meta):
    """§5: two-line label string (name / metadata). Meta line styled separately by caller."""
    return f"{name}\n{meta}"


def end_of_line_labels(ax, xs, ys, labels, colors=None, dx=0.01, fontsize=None):
    """§6.3 / §7.3: label each line series at its right end instead of a legend box.

    Each label requires a nonempty, matched x/y series. Validate all series
    before drawing. Nonempty colors cycle; None or empty uses default text color.
    Inner sequences must support len() and indexing; they are not copied.
    Nonfinite endpoints are rejected rather than producing an invisible label.
    """
    import matplotlib.pyplot as plt
    import math
    xs, ys, labels = list(xs), list(ys), list(labels)
    if len(xs) != len(ys) or len(xs) != len(labels):
        raise ValueError("end_of_line_labels xs, ys and labels must have equal lengths")
    if any(len(x) == 0 or len(x) != len(y) for x, y in zip(xs, ys)):
        raise ValueError("end_of_line_labels each x/y series must be nonempty and have equal lengths")
    if any(not math.isfinite(x[-1]) or not math.isfinite(y[-1]) for x, y in zip(xs, ys)):
        raise ValueError("end_of_line_labels endpoints must be finite; choose valid endpoints explicitly")
    if fontsize is None:
        fontsize = plt.rcParams["font.size"]
    colors = [] if colors is None else list(colors)
    if not colors:
        colors = [None]
    span = ax.get_xlim()[1] - ax.get_xlim()[0]
    for i, (x, y, lab) in enumerate(zip(xs, ys, labels)):
        c = colors[i % len(colors)]
        ax.text(x[-1] + dx * span, y[-1], lab, color=c, va="center", ha="left", fontsize=fontsize)


def panel_crops(fig, dpi=None, pad_px=6, bbox_inches=None, pad_inches=None):
    """§9.2: pixel-space crop boxes for each lettered panel in the SAVED PNG.

    Returns ``{letter: (x0, y0, x1, y1)}`` in image-space pixels (origin
    top-left, matching PIL's ``Image.crop``). Panels are detected as bold
    single-character ``Text``
    objects placed by :func:`panel_letter`; each panel's crop is its axes'
    tightbbox mapped into the saved file's pixel space, padded by ``pad_px``.
    For §3.4 composites (abutting subplots sharing an axis, letter on the
    leftmost only) the crop unions in letterless ``sharex``/``sharey`` siblings
    on the same grid row/col so the whole composite is covered. When no axes
    carries a panel letter (standalone plot, or a figure-composer sub-agent),
    falls back to one crop per axes keyed by index.

    ``bbox_inches`` mirrors ``Figure.savefig`` semantics: ``None`` means
    *consult rcParams* (so under :func:`apply_figure_style` it resolves to
    ``'tight'``); pass an explicit ``Bbox`` only if you saved with one. The
    boxes are clamped to the saved image extent; panels with no intersection
    are omitted.

        >>> from PIL import Image
        >>> fig.savefig("fig.png")  # bbox_inches='tight' via rcParams
        >>> with Image.open("fig.png") as saved:
        ...     for letter, box in panel_crops(fig).items():
        ...         saved.crop(box).save(f"panel_{letter}.png")

    Match savefig's DPI, bbox_inches and pad_inches when overriding defaults.
    Returned boxes are pixels, never savefig bbox_inches (inches). Passing them
    back to savefig as inches can allocate an enormous raster.
    """
    import matplotlib as mpl
    import matplotlib.text
    from matplotlib.backends.backend_agg import FigureCanvasAgg
    if isinstance(pad_px, bool) or not isinstance(pad_px, int) or pad_px < 0:
        raise TypeError("panel_crops pad_px must be a non-negative integer")
    if dpi is None:
        dpi = mpl.rcParams.get("savefig.dpi", fig.dpi)
        if dpi == "figure":
            dpi = fig.dpi
    dpi = float(dpi)
    if bbox_inches is None:
        bbox_inches = mpl.rcParams.get("savefig.bbox")
    # The Open-Science notebook captures and closes pyplot figures after every
    # cell. Matplotlib 3.11 decouples a closed Figure from its backend by
    # replacing FigureCanvasAgg with FigureCanvasBase, while the persistent
    # notebook namespace can still retain the Figure itself. Reattach the
    # headless canvas before asking for saved-image geometry so this helper is
    # safe in a later QA cell as well as the producer cell.
    if not hasattr(fig.canvas, "get_renderer"):
        FigureCanvasAgg(fig)
    fig.canvas.draw()
    r = fig.canvas.get_renderer()

    if bbox_inches == "tight":
        if pad_inches is None:
            pad_inches = mpl.rcParams.get("savefig.pad_inches", 0.1)
        tb = fig.get_tightbbox(r).padded(pad_inches)
        ox_in, oy_in = tb.x0, tb.y0
        W_in, H_in = tb.width, tb.height
    elif isinstance(bbox_inches, mpl.transforms.BboxBase):
        ox_in, oy_in = bbox_inches.x0, bbox_inches.y0
        W_in, H_in = bbox_inches.width, bbox_inches.height
    elif bbox_inches is None:
        ox_in, oy_in = 0.0, 0.0
        W_in, H_in = fig.get_size_inches()
    else:
        raise TypeError("panel_crops bbox_inches must be None, 'tight', or a matplotlib Bbox")
    W_px, H_px = int(round(W_in * dpi)), int(round(H_in * dpi))
    lettered = {}
    seen_letters = set()
    for ax in fig.axes:
        for t in ax.findobj(matplotlib.text.Text):
            s = (t.get_text() or "").strip()
            if t.get_gid() == "figure-style-panel-letter":
                if s in seen_letters:
                    raise ValueError(f"Duplicate panel letter: {s!r}")
                seen_letters.add(s)
                lettered[ax] = s
                break



    if not lettered:
        lettered = {ax: str(i) for i, ax in enumerate(fig.axes)}
    out = {}
    for ax, letter in lettered.items():
        bbs = [ax.get_tightbbox(r)]




        ss = ax.get_subplotspec()
        for sib in fig.axes:
            if sib is ax or sib in lettered:
                continue
            ssib = sib.get_subplotspec()
            same_row = ss is None or ssib is None or ss.rowspan == ssib.rowspan
            same_col = ss is None or ssib is None or ss.colspan == ssib.colspan
            if ((ax.get_shared_y_axes().joined(ax, sib) and same_row)
                    or (ax.get_shared_x_axes().joined(ax, sib) and same_col)):
                bbs.append(sib.get_tightbbox(r))
        bb = mpl.transforms.Bbox.union(bbs)

        bx0 = (bb.x0 / fig.dpi - ox_in) * dpi
        bx1 = (bb.x1 / fig.dpi - ox_in) * dpi
        by0 = H_px - (bb.y1 / fig.dpi - oy_in) * dpi
        by1 = H_px - (bb.y0 / fig.dpi - oy_in) * dpi
        box = (
            min(max(int(bx0) - pad_px, 0), W_px),
            min(max(int(by0) - pad_px, 0), H_px),
            max(min(int(bx1) + pad_px, W_px), 0),
            max(min(int(by1) + pad_px, H_px), 0),
        )
        if box[0] < box[2] and box[1] < box[3]:
            out[letter] = box
    return out
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 322kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 322kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 322kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 198kUpdated Claude CodeCodexVerifiedInstall