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.
Print the remedy for a row that failed¶
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)!
- Set the backend before pyplot imports. A figure built for measurement has no reason to open a window.
suggest=Trueturns a failed row into a remedy. Without the optionalsuggest_fixes.pybeside 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)!
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.- Only hard failures print. Advisory rows are
"warn", a truthy string, sos is Falseleaves them out of the message.
To see the advisory rows too, select the rows that are not True:
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:
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 atMEASURE_DPIfirst, asauditdoes. The others, such ascheck_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:
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:
It prints the file, the values it sets, and every key this version accepts.