Skip to content

figure-gate

CI PyPI conda-forge Docs DOI

figure-gate reads a matplotlib figure you have already built and tells you which publication requirements it fails. It checks colorblind-safe color, composition, and whether your type is still legible at the size the figure prints.

report(fig) prints one line per check:

Composition audit
  [FAIL] Clipping           clipped: ['x', 'y']  [FIX] add constrained_layout or widen the figure
  [PASS] Type size          smallest 10.0pt on page (floor 6.0)
  [WARN] Alt text           no description attached  [FIX] describe(fig, "...") ...
  ...
  -> FIX THE MARKED CHECKS

Thirteen rows can fail a build. The other eight are advisory: they report WARN and never FAIL. For a program rather than a person, audit(fig) returns (ok, rows), 21 rows, one per check, each a (name, status, detail) triple, and audit_json(fig) serialises the same verdict.

figure-gate verifies figures. It does not draw them, restyle them, or judge whether a figure is good. Each check forbids one named defect, so a figure that passes every row has avoided 21 named defects and nothing more.

Every threshold is a module-level constant you can read, change, or set from a figure-gate.toml.

Try it

pip install figure-gate                  # or: uv add figure-gate
check-palette "#E69F00,#56B4E9,#009E73" --pairs all
check-figure                             # self-test on a deliberately broken figure

check-figure prints a failing report and exits 0: its self-test passes only when the checker rejects the broken figure.

Copying the scripts in works too, and is the route if you want the thresholds beside the figures they gate. The install page covers all three routes.

Validation loss against training epoch for three optimisers over 12 epochs.
All three fall; the Bayesian run reaches 0.12 by epoch 6 and 0.02 by epoch 12,
while the baseline is still at 0.25 at epoch 12.

python examples/demo.py builds that figure and audits it. python examples/gallery.py builds the harder forms. Writing those twenty-four exposed defects in the checks themselves, listed on the gallery page.

Documentation

The documentation site is organised by what you came to do.

Learning

Start here if you have not run the checkers before:

Doing a task

Step-by-step directions for a goal you already have:

  • Install figure-gate: copy the scripts, install the package, or install from conda-forge
  • How-to guides: fix a failing row, gate a test suite, place at half width, attach alt text

Looking something up

What each check measures and what each function takes:

  • The gates: every row, its threshold, and whether it can fail a build
  • Commands: both command-line tools, their flags, and their exit codes
  • Compatibility: Python and matplotlib floors, optional dependencies, import lines by version
  • API reference: signatures and defaults, generated from the scripts when the site builds

Understanding why

Background, evidence, and the decisions behind the thresholds:

  • How the checkers decide: the measurement model, the evidence, and what a passing run does not mean
  • Figure style guide: the measurement behind each threshold, and the rules tried and reverted
  • Choosing a form: the decision no styling rule rescues, built on Cleveland and McGill's ordering
  • Gallery: twenty-four audited figures covering the forms that are hard to check

Use it with Claude Code

This repository is also a plugin marketplace, so Claude Code applies the same checks when it builds a figure for you. See Install it as a Claude Code skill.

Where this sits

Style sheets set a figure's defaults before it is drawn: SciencePlots and LovelyPlots for journal looks, tueplots and mpl_sizes for conference page sizes. Accessibility tools work from the finished chart: matplotalt generates alt text, and Chart4Blind converts a chart image into an accessible one. None of them reports which requirements a built figure fails.

vislint_mpl did, in 2018 (McNutt & Kindlmann). It took the figure and axes objects and listed the rules they failed, each with a reason. It was a research prototype; its repository is archived.

Set the defaults with a style sheet, then check the result with figure-gate.

Stability

Below version 1.0, a minor release may break the public API, and every break is named in the changelog. The version policy says what the public API covers.

Contributing

New gates are welcome at the bar the project holds itself to:

  • A test proving the gate fails on a figure with that defect.
  • A test proving it does not over-fire on the nearest legitimate case.
  • A note naming the real failure that motivated it.

See CONTRIBUTING.md and SECURITY.md.

Citing

@software{prakash_figure_gate,
  author = {Prakash, Naren},
  title  = {figure-gate},
  doi    = {10.5281/zenodo.21784217},
  url    = {https://github.com/narenp12/figure-gate}
}

License

MIT. See LICENSE.