Skip to content

The gates

This page lists every row the two checkers return, the threshold each one measures against, and what makes it fail.

audit(fig) returns (ok, rows) with one row per figure gate. check(colors) returns the same shape for a palette. Each row is a (name, status, detail) triple, and status is True, False, or "warn".

For what to type when a row fails, see the how-to guides. For why a threshold sits where it does, see the figure style guide.

Figure gates

check_figure.py renders the figure through an Agg canvas at MEASURE_DPI = 150, measures the result, and hands the figure back on the dpi and canvas it arrived on, as savefig does. audit() returns these 21 rows in this order.

Where a row below says panel, it means every axes on the figure, an ax.inset_axes or a secondary_xaxis included. Those are added through add_child_axes and never reach fig.axes. The panel numbering in a detail string counts the top-level panels first and the child axes after them.

Gate Threshold Fails when
Clipping canvas bounds a text artist's bbox extends past the canvas
Text collision oriented box overlap two text boxes overlap, rotation included, tick labels on a shared axis exempted
Text readability TEXT_CONTRAST_MIN = 4.5 text misses WCAG AA against the backdrop it got, or data ink crosses its glyphs. Furniture, and the ground the label sits on, do not count as ink; a rule lying under the text still counts against contrast
Contrast stack ALPHA_LEVELS_MAX = 3 nothing in the figure is opaque, or transparency uses more than 3 distinct levels. Overlapping fills of one colour count as a single level. A single flat alpha is not judged for a focal point
Mark ratio MARK_RATIO_MAX = 5.0 largest data mark exceeds 5x the smallest by area
Overplotting OVERPLOT_THRESHOLD = 0.5 over half a cloud's marks sit close enough to some other mark for the two to touch on the page, whether the cloud was drawn by scatter or by plot with markers and no connecting line (advisory)
Axis redundancy SHARE_SPAN_RATIO_MAX = 2.0 panels on one scale type naming one quantity repeat their axis title, and sharing the axis would cost no panel more than 2x its span; or panels sharing limits, scale type and axis title repeat tick labels
Type size TYPE_FLOOR_PT = 6.0, XHEIGHT_FLOOR_PT = 4.0, TYPE_CEILING_PT = inf, MATH_SCRIPT_FLOOR_PT = 5.0 a string renders under 6pt on the printed page, or a mathtext sub- or superscript renders under 5pt there. A string with a lowercase letter whose x-height lands under 4pt warns: 7.4pt in DejaVu Sans, 8.5pt in STIX Two Text, 8.9pt in STIXGeneral. Scripts are measured rather than read off the property. A venue in VENUE_TYPE_CEILING_PT (Nature: 7pt) sets the ceiling, and TYPE_CEILING_PT caps it; a floor above the ceiling drops to it, and a string over the ceiling fails. A bold, upright, one-letter lowercase panel label is held to VENUE_PANEL_LABEL_PT (Nature: 8pt)
Line weight LINE_FLOOR_PT = 1.0, FURNITURE_FLOOR_PT = 0.5 a data stroke renders under 1pt on the printed page: a line, a line collection, an unfilled contour, a patch edge or an annotation arrow. Spines, gridlines and tick marks are furniture and are held to the lower floor, as are marker outlines unless they repeat the fill or the background
Banking BANKING_SLOPE_MAX = 10.0 the aspect that minimises a line panel's arc length at constant area is more than 10x taller or wider than the panel's own (advisory)
Ink coverage INK_MIN, INK_MAX = 0.02, 0.55 a panel's ink fraction falls outside the band (advisory)
Series color palette gates, MAX_SERIES_HUES = 6, SERIES_CONTACT_PX = 2.0 a gated pair of hues drawn fails normal-vision separation, or fails CVD separation with no second channel (mark type, dash, marker or hatch) between the two series, or one panel carries more than 6. A panel with a legend or marks without a line gates every pair; otherwise areas that are neighbours in draw order, lines whose strokes meet, each line and its nearest of another hue, and a line and each area it crosses
Dual axis none a twinx second scale carries data of its own
Form none pie, 3D, or bars on a truncated baseline, whether drawn by the bar helper or built by hand from plain rectangles. Bars that each carry their own offset have no shared baseline and are not judged here
Identity channel none two or more series, no legend and no text in the axes (advisory)
Label attribution LABEL_MARGIN = 2.0 a label's nearest rival series, line or scatter or filled region, is closer than 2x its distance to the one it names
Style sheet 40 keys the rcParams in effect differ from figure.mplstyle, or no sheet was found to compare against (advisory)
Contour dash none a signed contour set dashes its negative levels (advisory)
Colormap kind CMAP_BACKTRAVEL_MAX = 0.02 a colormap classifies misc: its lightness reverses, or its span is flat, or its halves are monotone and its ends match neither cyclic nor diverging. Also when a qualitative map's levels fail all-pairs separation, and when a panel's series colours are RAMP_MIN_STEPS = 3 or more evenly spaced samples of such a map, sampled in code rather than handed to an artist
Fonts Type 42 PDF or PS export would embed Type 3, or no named typeface resolves (advisory)
Alt text ALT_TEXT_MIN_CHARS = 60 no description is attached, or the attached one is under 60 characters (advisory)

Advisory rows

Eight of the 21 rows are advisory. An advisory row can return "warn" but never False, so it never fails a build. ADVISORY_GATES in check_figure.py is the list:

  • Overplotting
  • Banking
  • Ink coverage
  • Identity channel
  • Style sheet
  • Contour dash
  • Fonts
  • Alt text

Three rows do both. Type size fails under the floor and warns on a figure placed under PLACED_FRAC_WARN = 0.35 of the content width. Series color and Colormap kind fail on what they measure and warn when check_palette.py is not importable beside check_figure.py.

Detail strings

A row's detail carries up to two marks:

[FIX]
introduces an action. Nothing else uses this mark.
[WHY]
introduces the reason the row fired: the published floor, the perceptual fact, or what a reader loses.

A detail may carry both, in that order:

under 1.0pt on page at scale 0.50: ['a stroke at 0.40pt']
  [FIX] set linewidth to at least 2.00 at this scale
  [WHY] SIAM: lines thinner than one point break up or disappear in print

Every gate except check_collisions names a fix. That gate names the two colliding strings and stops, because which of the pair is free to move is a fact about the layout it cannot see.

Three details open with did not run: instead: the style-sheet row with no sheet to compare against, and the two colour rows with no check_palette.py to classify with.

That prefix is DID_NOT_RUN. A row carrying it gets no remedy from suggest, because a remedy answers the question a gate asks when it runs.

Palette gates

check_palette.py takes hex strings on the command line or through check(), and imports nothing outside the standard library. Distances are CAM02-UCS dE. The lightness and chroma rows stay in OKLab.

check(colors) returns these five rows:

Gate Threshold Fails when
Lightness band L_MIN, L_MAX = 0.43, 0.77 OKLab lightness outside the band
Chroma floor CHROMA_MIN = 0.10 OKLab chroma below it, so the color reads as gray
CVD separation CVD_TARGET = 10.5 two hues under 10.5 dE in protan or deutan simulation, at dichromacy under either ViƩnot's or Machado's model, or at any severity in ANOMALOUS_SEVERITIES
Normal-vision floor NORMAL_FLOOR = 21.0 two hues under 21 dE in full color
Contrast vs surface CONTRAST_MIN = 3.0 a hue under 3:1 on the page (advisory)

Ink tokens passed through ink= are exempt from the lightness and chroma rows.

The separation rows are named CVD separation (adjacent) or CVD separation (all-pairs) after the comparison they ran. all_pairs=False is the default and compares neighbours. all_pairs=True compares every pair, which is what a legend or a scatter needs: the reader matches each mark against every other hue.

Protanopia and deuteranopia are gated. Tritan separation is measured and printed in the detail string, but not gated.

Ordinal rows

ordinal=True swaps the five categorical rows for four that apply to an ordered ramp:

Gate Threshold Fails when
Lightness monotone direction lightness does not run one way along the ramp
Adjacent dL ORDINAL_DL_MIN = 0.06 two neighbouring steps are closer in lightness than the floor
Light-end contrast ORDINAL_LIGHT_END_CONTRAST_MIN = 2.0 the lightest step is under 2:1 against the surface
Step uniformity ORDINAL_STEP_RATIO_MAX = 2.0 the largest lightness step is over twice the smallest

What each row tells you to do

Eleven rows carry a remedy in suggest_fixes.py, and eight of those come with a runnable snippet. Nine of the other ten name their fix in the detail string and stop, mostly because the answer is to draw something else. Text collision names the two strings and no fix.

Row First move suggest()
Clipping Turn on constrained_layout, or widen the figure yes
Text collision Move one of the two named strings. Which one is free is yours to know
Text readability Move the label to clear ground, or case it against the ink under it
Contrast stack Take one artist to alpha 1, and keep to three alpha levels. A fan chart's bands are one level, so it needs its median line rather than fewer intervals yes
Mark ratio Clip the size array when one mark is an ornament among marks otherwise alike. When the sizes are graded, carry the quantity by position instead yes
Overplotting Thin the counts, or switch to hexbin. Alpha does not move this row yes
Axis redundancy sharex/sharey at creation, or ax.label_outer() after yes
Type size Cut words. Do not shrink type
Line weight Raise linewidth to clear 1pt at the placed scale, or 0.5pt for the axis rule and the grid
Banking Set the panel aspect or the figure size to the ratio the row names
Ink coverage Look at the named panel: empty and saturated both read as a defect
Series color Fold the tail into "Other", or facet. Both need a redraw. For a single-hue ordinal ramp, step it wider, or hand it to a colormap rather than a list of hexes yes
Dual axis Split the two scales into two panels
Form Redraw: bars from zero, no pie, no 3D
Identity channel Direct labels, not a legend
Label attribution Move the label nearer the series it names, or rely on a leader line
Style sheet Apply the sheet in the same rc_context the figure is drawn in yes
Contour dash linestyles="solid" on signed contour data yes
Colormap kind viridis for sequential, RdBu for diverging, twilight for cyclic yes
Fonts Set pdf.fonttype and ps.fonttype to 42 yes
Alt text describe(fig, "..."), then pass alt_metadata(fig, path) to savefig yes

Thresholds

Every threshold is a module-level constant. To change one, see Change a threshold.

Thresholds cite a published floor where one exists: SIAM's one point for data strokes, Science's half point for furniture, WCAG's 4.5:1, and the Nature and PNAS type minima. The rest were measured or set by judgement. ALT_TEXT_MIN_CHARS = 60 is judgement: the length below which a description names the figure rather than describing it. The figure style guide records the measurement and the figure that motivated each one.