Skip to content

How-to guides

Each guide here solves one task. They assume you have the checkers installed and have run an audit before. If you have not, start with Gate your first figure.

Every snippet uses the vendored import, import check_figure. If you installed the package, the line is from figure_gate import check_figure. Nothing else changes.

For what a row measures, see The gates. For why a threshold sits where it does, see the figure style guide.

Pass suggest=True to report. It prints the table, then what to do about the rows that did not pass:

import matplotlib
matplotlib.use("agg")                            # (1)!

from check_figure import report, self_test_figure

report(self_test_figure(), "self-test", suggest=True)  # (2)!
  1. Set the backend before pyplot imports. A figure built for measurement has no reason to open a window.
  2. suggest=True turns a failed row into a remedy. Without the optional suggest_fixes.py beside the checker, it prints the table alone.
The transcript, and what each marked row is telling you
Composition audit: self-test
  [FAIL] Clipping           clipped: ['a very long axis label that will', ...]  [FIX] add constrained_layout or widen the figure
  [FAIL] Mark ratio         largest/smallest mark area 33.3x  (drawn area 9 to 314 pt^2)  [FIX] cap at 5.0x
  ...
  -> FIX THE MARKED CHECKS

  What to do about the marked rows:
  Clipping:
    - let a layout engine place the artists, or widen the figure
        fig.set_layout_engine("constrained")
  Mark ratio:
    - when one mark is an ornament among marks that are otherwise alike, cap the size range so the largest still reads as a mark. Read the sizes first: this clips, and clipping a size encoding destroys it
        for ax in fig.axes:
            for c in ax.collections:
                s = c.get_sizes()
                if len(s):
                    c.set_sizes(s.clip(None, s.min() * 5.0))
    - when the sizes are graded they are encoding a quantity, and the fix is the form rather than the numbers: carry it by position, on a second axis or as a dot plot
  ...

Where a row prints two remedies, pick by what the detail names. A mark that dwarfs the next largest is an ornament, and the clip is right; graded sizes are an encoding that the clip would flatten.

To work with the remedies as data rather than as printed text:

from check_figure import audit
from suggest_fixes import suggest

ok, rows = audit(fig)
for gate, remedies in suggest(rows):
    print(gate, [r.suggestion for r in remedies])

Each snippet is a template against a bound fig, not a drop-in.

Gate every figure in your test suite

Use your figure-building function as the fixture. audit returns (ok, rows), and advisory rows never return False, so ok is the whole assertion:

import pytest

from check_figure import audit

from mypaper.figures import FIGURES, build


@pytest.mark.parametrize("name", sorted(FIGURES))
def test_figure_is_composed(name):
    ok, rows = audit(build(name), venue="neurips")  # (1)!
    assert ok, "\n".join(f"{k}: {d}" for k, s, d in rows if s is False)  # (2)!
  1. venue="neurips" tells the type gate how far the figure scales onto the page, so text is measured where it renders rather than where it was authored.
  2. Only hard failures print. Advisory rows are "warn", a truthy string, so s is False leaves them out of the message.

To see the advisory rows too, select the rows that are not True:

for name, status, detail in rows:
    if status is not True:
        print(name, status, detail)

Gate a palette from a toolchain that is not Python

check_palette.py imports nothing outside the standard library and exits 1 on a failing row. A non-Python build can gate on that exit code:

python check_palette.py "#E69F00,#56B4E9,#009E73" --pairs all
echo $?    # 0 all rows pass, 1 something failed

A [WARN] row still exits 0. Advisory rows report; they do not gate.

The palette transcript
Palette (categorical, surface #ffffff): 3 slots
  [PASS] Lightness band               all 3 inside L 0.43-0.77
  [PASS] Chroma floor                 all 3 >= 0.1
  [PASS] CVD separation (all-pairs)   worst #E69F00 vs #009E73 dE 20.7 (protan at severity 1.0) - tritan 12.2
  [PASS] Normal-vision floor (all-pairs) worst #56B4E9 vs #009E73 dE 31.5
  [WARN] Contrast vs surface          under 3.0:1, each needs a visible direct label: [('#E69F00', 2.25), ('#56B4E9', 2.31)]

  -> ALL CHECKS PASS (with advisories - act on the WARN rows)

For every flag, see the command reference.

Place a figure at a venue's width

The type and line-weight gates measure what renders on the page, so they need to know how far the figure is scaled on the way there. Three arguments carry that:

audit(fig, venue="neurips")                       # full content width
audit(fig, venue="neurips", placed_frac=0.48)     # \includegraphics[width=0.48\textwidth]
audit(fig, scale=0.74)                            # placed over authored size, set outright

To see what a placement does to the scale, call page_scale on a 4-inch-wide figure with 10pt labels:

>>> float(page_scale(fig, venue="neurips"))
1.380138888888889
>>> float(page_scale(fig, venue="neurips", placed_frac=0.48))
0.6624666666666666

At full width the labels arrive at 13.8pt and pass. At placed_frac=0.48 they arrive at 6.6pt, over the 6pt floor, but their DejaVu Sans x-height is 3.6pt, under 4pt, and the row warns.

float() appears here because the scale comes back as a numpy.float64, which a REPL prints as np.float64(1.38...) on numpy 2. It compares and computes like a float everywhere it matters.

For all eighteen venue widths, see Venue widths. Verify one against \the\textwidth in your own document before you trust it.

Attach alt text

Call describe to attach the text, then alt_metadata to turn it into the keyword your output format wants:

from check_figure import alt_metadata, describe

describe(fig, "Validation loss against epoch for three optimisers. All three "
              "fall; the Bayesian run reaches 0.02 by epoch 12, while the "
              "baseline is still at 0.25.")
fig.savefig("figure-1.png", metadata=alt_metadata(fig, "figure-1.png"))

Pass the path to both calls. alt_metadata reads the suffix to pick the key: PNG takes Description, PDF takes Subject. Called without a path, it assumes PNG, which warns on a PDF save and is rejected outright by SVG.

The row passes at 60 characters or more. If your document's caption already carries the description, you can leave the row: it is advisory and never fails a build.

Read one row, or call one gate

Audit the figure and take the row you want. audit normalises the canvas, so a row read out of it is the row your CI will see:

rows = {name: (status, detail) for name, status, detail in audit(fig)[1]}
status, detail = rows["Type size"]

The gate functions are importable and callable on their own, and the API reference has their signatures:

>>> check_form(fig)
(True, 'no pie, no 3D, no truncated bar baseline')

Two things differ when you call a gate directly:

  • Several gates take a renderer argument, which means drawing the figure yourself. They measure on it at the dpi you drew it at, except the text-readability gate, which draws again at MEASURE_DPI.
  • A gate with no renderer argument that reads display geometry, such as check_form, draws the figure at MEASURE_DPI first, as audit does. The others, such as check_dual_axis, read no display geometry.

Change a threshold

If you vendored the checkers, edit the constant at the top of the file. If you installed the package, assign to the constant. The gates read the module global when they run:

import check_figure as cf

cf.TYPE_FLOOR_PT = 9.0        # a house minimum, in body points
ok, rows = cf.audit(fig)

Assign before you call audit, not inside a gate, and put the assignment somewhere your reader will find it. A threshold moved in one test file is a figure that passes locally and fails in CI. To move it for every author at once, see Agree on thresholds across a project.

The gates names each threshold, and the figure style guide records what was measured to land on it.

Agree on thresholds across a project

Write them in a file, so the build and every author read one set. A figure-gate.toml at the project root, or a [tool.figure-gate] table in pyproject.toml:

venue = "amsart"          # sets CONTENT_WIDTH_PT from VENUE_WIDTH_PT
TYPE_FLOOR_PT = 9.0
CVD_TARGET = 12.0         # a check_palette threshold, same file

Read it once, where your project starts:

import check_figure as cf

cf.load_config()          # searches upward from the current directory

Nothing reads the file on import. load_config returns what it assigned, so a build can log it. A key that names no threshold raises rather than being skipped.

Not every number in capitals is a threshold. MEASURE_DPI is the resolution the pixel thresholds were calibrated at, and NOT_CONFIGURABLE in each module names it and the others like it. A file setting one raises and says why. They are still module globals, so assigning one by hand does what it always did: what a file cannot do is make that choice everyone's.

To see which file a build picks up:

python check_figure.py --config

It prints the file, the values it sets, and every key this version accepts.