API¶
Signatures and docstrings are read out of skill/scripts/ when this page
builds, so what is shown is what the code has.
Installed and vendored copies have the same signatures. Only the import line differs, and Choose your import line gives it.
Not on this page: the thresholds. They are module-level constants, one
table per module on the gates, with the measurement behind each on
the style guide. Read them as cf.TYPE_FLOOR_PT.
Everything else is here, including the 21 gate functions, at the bottom.
audit is what most callers want: it runs all 21 and computes the renderer,
canvas and scale arguments they take. Call one directly and that is yours to
reproduce, which the how-to covers.
Three ways to take the same verdict out: audit returns the rows, report
prints them for a person, and audit_json serialises them for a build.
check_palette.check and check_palette.check_json are the same pair on the
colour side, and both JSON documents carry the same schema string, so a CI step
collecting figure and palette verdicts reads ok and rows out of either.
check_figure¶
Composition. Takes a built figure, measures what it renders at print size.
check_figure.audit
¶
audit(fig: Figure, scale: float | None = None, placed_frac: float = 1.0, *, context_axes: Sequence[Axes] | None = None, venue: str | None = None) -> tuple[bool, list[tuple[str, bool | str, str]]]
Run every gate over a figure. Returns (ok, rows).
check_palette.check returns the same shape.
rows are (label, status, detail), one per gate, in the order the report
prints them. status is True, False, or the string "warn"; only a hard
False sets ok to False, so an advisory row reports without gating a
build.
placed_frac is the fraction of the content width the figure is placed at,
and venue names a row of VENUE_WIDTH_PT instead of setting
CONTENT_WIDTH_PT by hand; between them they decide the page scale every
type and stroke measurement runs through. scale overrides that
calculation outright. context_axes names axes whose fill is a context
surface rather than data ink, which is what stops a filled contourf panel
reading as saturated.
context_axes and venue are keyword-only. context_axes is iterated and
a string is iterable, so a venue in that slot would be read as axes rather
than raise, and the figure measured at the wrong width.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
fig
|
Figure
|
The built figure. Measured through an Agg canvas at |
required |
scale
|
float | None
|
Placed size over authored size, overriding |
None
|
placed_frac
|
float
|
Fraction of the content width the figure is placed at. |
1.0
|
venue
|
str | None
|
A key of |
None
|
context_axes
|
Sequence[Axes] | None
|
Axes whose fill is a context surface, not data ink. |
None
|
Returns:
| Type | Description |
|---|---|
bool
|
|
list[tuple[str, bool | str, str]]
|
report order; |
Source code in skill/scripts/check_figure.py
check_figure.report
¶
report(fig: Figure, name: str = '', scale: float | None = None, placed_frac: float = 1.0, *, context_axes: Sequence[Axes] | None = None, venue: str | None = None, suggest: bool = False) -> bool
audit(), printed. Returns the same ok bool and nothing else.
The arguments are audit's, plus name for the heading. Advisory rows
print as WARN and do not change the verdict, so a figure can be COMPOSED
with advisories; only a hard FAIL makes this return False.
suggest=True prints what suggest_fixes.py has to offer for the marked
rows, under the table. Off by default and kept in that file rather than
this one: a gate measures, and what to do about it is a separate claim that
can be wrong on its own. Several rows get more than one suggestion, because
the choice between them is the author's.
This is what the examples and the CLI call. Use audit() when the rows
themselves are wanted rather than a printed table.
context_axes, venue and suggest are keyword-only, for the reason
audit gives.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
fig
|
Figure
|
The built figure. |
required |
name
|
str
|
A heading for the table. |
''
|
scale
|
float | None
|
Placed size over authored size, overriding |
None
|
placed_frac
|
float
|
Fraction of the content width the figure is placed at. |
1.0
|
venue
|
str | None
|
A key of |
None
|
context_axes
|
Sequence[Axes] | None
|
Axes whose fill is a context surface, not data ink. |
None
|
suggest
|
bool
|
Print |
False
|
Returns:
| Type | Description |
|---|---|
bool
|
|
Source code in skill/scripts/check_figure.py
check_figure.audit_json
¶
audit_json(fig: Figure, scale: float | None = None, placed_frac: float = 1.0, *, name: str = '', context_axes: Sequence[Axes] | None = None, venue: str | None = None) -> str
audit(), as a JSON document. Returns the text, and prints nothing.
report is for a person reading a terminal; this is for a build that has to
decide something. The arguments are audit's, plus name, and the verdict
is the same object audit computed: this function serialises, it does not
re-measure.
The document carries the measurement context as well as the rows, because a
verdict without the width it was measured against cannot be read later. A
figure that passes at venue="neurips" and fails at icml-column is one
figure and two true answers, and a stored artifact that records only the
answer is the one that gets quoted at the wrong width. scale is the one the
gates actually ran at, resolved from placed_frac and venue rather than
echoed from the argument, so it is filled in even when the caller passed
neither.
scale is page_scale's number, which is a ratio and not a length: placed
size over authored size, 1.0 for a figure measured as authored. The field
is named for the argument rather than for a unit, because there is no unit to
name.
status is "pass", "fail" or "warn", not the tuple API's
True/False/"warn". A JSON consumer should not have to know that one
field holds a bool for two of the three cases, and ok is already the bool
worth branching on.
schema is AUDIT_SCHEMA, and check_palette.check_json emits the same
one. The two documents differ only in tool and inputs, so a CI step that
collects both can read ok and rows out of either without asking which
checker produced it.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
fig
|
Figure
|
The built figure, measured exactly as |
required |
scale
|
float | None
|
Placed size over authored size, overriding |
None
|
placed_frac
|
float
|
Fraction of the content width the figure is placed at. |
1.0
|
name
|
str
|
Recorded as |
''
|
venue
|
str | None
|
A key of |
None
|
context_axes
|
Sequence[Axes] | None
|
Axes whose fill is a context surface, not data ink. |
None
|
Returns:
| Type | Description |
|---|---|
str
|
A JSON object as text, with |
Source code in skill/scripts/check_figure.py
6687 6688 6689 6690 6691 6692 6693 6694 6695 6696 6697 6698 6699 6700 6701 6702 6703 6704 6705 6706 6707 6708 6709 6710 6711 6712 6713 6714 6715 6716 6717 6718 6719 6720 6721 6722 6723 6724 6725 6726 6727 6728 6729 6730 6731 6732 6733 6734 6735 6736 6737 6738 6739 6740 6741 6742 6743 6744 6745 6746 6747 6748 6749 6750 6751 6752 6753 6754 6755 | |
check_figure.describe
¶
Attach a text description to a figure, for readers who cannot see it.
Across 100,000 public Jupyter notebooks, 99.81% of programmatically
generated images shipped with no alt text at all, and the overwhelming
majority of them were matplotlib. Matplotlib has no field for this, so the
description is stashed on the figure and handed to savefig:
describe(fig, "Validation loss against training epoch for three "
"optimisers. All three fall; the Bayesian run reaches "
"0.05 by epoch 6, the baseline is still at 0.25 at 12.")
fig.savefig(path, metadata=alt_metadata(fig, path))
Say what the reader would have taken from looking, not what the figure is made of. "A line chart with three lines" describes the file; the numbers and the direction describe the finding.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
fig
|
Figure
|
The figure to attach the description to. |
required |
text
|
str
|
The description. |
required |
Returns:
| Type | Description |
|---|---|
Figure
|
|
Source code in skill/scripts/check_figure.py
check_figure.alt_metadata
¶
The metadata= dict for savefig, carrying whatever describe set.
Pass the same path you are about to save to, so the description lands in
a field the target format actually has:
fig.savefig(path, metadata=alt_metadata(fig, path))
PNG, PDF and SVG all keep a description and none of them agrees with the others about what to call it, so the key is chosen from the suffix.
For a format that carries no description -- ps, or any of the rasters --
this returns None rather than an empty dict, and the difference is not
cosmetic. matplotlib's guard is elif metadata is not None: raise, so an
empty dict is rejected exactly as hard as a full one; savefig(path,
metadata={}) on a jpeg is a traceback. None is savefig's own default
for the argument and the only value those formats accept.
Called without a path, or with a buffer whose format cannot be read, it
returns Description. That is right for PNG and SVG and is what every
earlier version returned unconditionally.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
fig
|
Figure
|
The figure |
required |
path
|
Any
|
The path about to be saved to. The suffix picks the key. |
None
|
Returns:
| Type | Description |
|---|---|
dict[str, str] | None
|
A dict for |
dict[str, str] | None
|
no description. Empty when |
Source code in skill/scripts/check_figure.py
check_figure.page_scale
¶
Scale from the authored figure to the one placed on the page.
placed_frac is the fraction of the content width the figure is placed at,
so it reads like the call site: \includegraphics[width=0.48\textwidth]
is placed_frac=0.48. Without it every figure is measured as if it were
full width, and a half-width figure is certified at twice the type size it
actually ships at - which is the wrong direction for a legibility gate to
be wrong in.
venue names a row of VENUE_WIDTH_PT and overrides CONTENT_WIDTH_PT for
this call, which is the usual way in: the width is a property of the
document, not of the checkout.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
fig
|
Figure
|
The figure, read for its authored width in inches. |
required |
placed_frac
|
float
|
Fraction of the content width the figure is placed at. |
1.0
|
venue
|
str | None
|
A key of |
None
|
Returns:
| Type | Description |
|---|---|
float
|
Placed size over authored size: a ratio, not a length. |
float
|
content width is set, which measures the figure at the size it was |
float
|
authored. |
Raises:
| Type | Description |
|---|---|
ValueError
|
|
Source code in skill/scripts/check_figure.py
check_figure.content_width_pt
¶
The usable page width to measure against, in points.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
venue
|
str | None
|
A key of |
None
|
Returns:
| Type | Description |
|---|---|
float | None
|
The width in points, or |
Raises:
| Type | Description |
|---|---|
KeyError
|
The venue is not in |
Source code in skill/scripts/check_figure.py
check_figure.type_ceiling_pt
¶
The largest text size, in points on the page, in force for venue.
The stricter of TYPE_CEILING_PT and the venue's published maximum. A
venue passed here replaces the one a configuration file named, the way
it replaces CONTENT_WIDTH_PT; TYPE_CEILING_PT holds for both.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
venue
|
str | None
|
A key of |
None
|
panel_label
|
bool
|
Use the venue's |
False
|
Returns:
| Type | Description |
|---|---|
float
|
The ceiling in points, |
Source code in skill/scripts/check_figure.py
check_figure.x_height_fraction
cached
¶
The height of a font's x over its em, read from the font file.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
path
|
str
|
A font file, as |
required |
Returns:
| Type | Description |
|---|---|
float | None
|
The fraction, or None when the font has no |
Source code in skill/scripts/check_figure.py
check_figure.load_config
¶
Apply a configuration file to the threshold constants.
Assigns the module-level constants the file names, in check_palette as well
as here. That is what cf.TYPE_FLOOR_PT = 9.0 does by hand: the gates read
the global when they run. Call it once, before audit.
Every key is checked before any is assigned, so a file with one bad key
changes nothing. A key that names no constant raises rather than being
skipped, unless a released version accepted it: a RETIRED_KEYS key
warns and is skipped. A venue naming no row of VENUE_WIDTH_PT comes back as the
KeyError content_width_pt raises, which lists the rows it knows.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
path
|
Any
|
The file to read. |
None
|
start
|
Any
|
Directory to search from when |
None
|
Returns:
| Type | Description |
|---|---|
dict[str, Any]
|
|
dict[str, Any]
|
included when the file set it through |
dict[str, Any]
|
file to read. |
Warns:
| Type | Description |
|---|---|
FutureWarning
|
A key is in |
Raises:
| Type | Description |
|---|---|
ValueError
|
A key names no settable constant, a value has the wrong
type, a value for an integer constant is not a whole number, or
the file sets both |
Source code in skill/scripts/check_figure.py
886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 | |
check_figure.find_config
¶
The nearest configuration file at or above start, or None.
Walks up from start (the current directory when it is None) to the
filesystem root, and at each level takes figure-gate.toml before
pyproject.toml. A pyproject.toml with no [tool.figure-gate] table is
not a configuration file and the walk continues past it: a project that
keeps its figures in a subdirectory with its own file is the ordinary case,
and stopping at the first pyproject.toml would find the wrong one.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
start
|
Any
|
Directory to search from. |
None
|
Returns:
| Type | Description |
|---|---|
Any
|
A |
Source code in skill/scripts/check_figure.py
check_figure.config_keys
¶
Every key a configuration file may set, sorted.
venue is in the list and is not a constant: it sets CONTENT_WIDTH_PT
from VENUE_WIDTH_PT, and type_ceiling_pt reads the venue's maxima.
A palette key is only here when check_palette.py is importable. Naming one
without it raises rather than being ignored.
Source code in skill/scripts/check_figure.py
check_figure.scatter_diameter_pt
¶
The diameter in points that scatter(s=size) actually draws.
matplotlib documents s as "the marker size in points**2", which reads as
an area and is not one. The unit marker path for 'o' is a circle of radius
0.5, and scatter scales it by sqrt(s): the drawn diameter is sqrt(s)
points and the drawn area is pi * s / 4, a factor 4/pi below the nominal
number.
Measured rather than inferred. At 200 dpi, scatter(s=100) and
plot(markersize=10) each lay down 741 pixels of ink, which is what makes
markersize and sqrt(s) the same quantity and s an area only up to
that constant. test_scatter_size_is_a_squared_diameter pins it against
matplotlib rather than against this docstring.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
size
|
float | ndarray
|
The value passed to |
required |
Returns:
| Type | Description |
|---|---|
float | ndarray
|
The drawn diameter in points, |
float | ndarray
|
|
Public because both check_mark_ratio and check_overplotting decide on
it.
Source code in skill/scripts/check_figure.py
check_figure.marker_extent_pt
¶
The width and height in points that a plot marker actually draws.
markersize is a diameter in points, which is the honest half of the
story and the half that made scatter_diameter_pt necessary on the other
side. The rest is that matplotlib does not draw every marker at that
diameter:
","ignoresmarkersizeoutright.lines.pyspecial-cases it and skips the scale, so the mark is one device pixel however large the number is: measured here at ms 1, 3, 6, 12 and 24, every one laid down exactly 1 pixel of ink."."carries ascale(0.5)in its own transform, so it draws at half the diameter asked for;ms=6and"o"atms=3each put down 101 pixels."|"and"_"are one segment. Their path has zero extent across the stroke, so what they draw across it ismarkeredgewidthand nothing else - 2px wide against 10px tall at ms 5, mew 1.
So the extent is the marker's own unit path, transformed the way the
marker will transform it, scaled by markersize. Checked against the
render for o . s ^ D * | _ , across two sizes; every prediction landed
within a pixel of the drawn bounding box.
The edge stroke is counted, and where it lands is measured rather than
assumed. A stroke is centred on the path, so it puts half its width
outside the outline on each side and widens the bounding box by one full
markeredgewidth; but marker strokes are butt-capped, so it does not
reach past the ends of an open path. Rendered at 600 dpi, ink minus path:
"o" mew 1 +1.12 across +1.12 down "|" mew 1 +1.20 across +0.04 down
"o" mew 2 +2.08 across +2.08 down "|" mew 2 +2.04 across +0.16 down
One rule covers both: the stroke widens an axis exactly when the path has extent in the other one. A disc has extent in both, so both grow. A bar marker is a segment with extent in one, so it grows across the stroke and not along it. That subsumes the older special case, which returned the stroke as a fallback for an axis of zero extent and arrived at the same number by a narrower argument.
Counting it is what makes this agree with the render rather than with
scatter_diameter_pt. The two were once left to under-report together on
the theory that a row reading the two spellings differently is a defect,
but that symmetry is a property of two rcParams and not of the two APIs:
under bare matplotlib defaults lines.markeredgewidth and
patch.linewidth are both 1.0 and one 4pt mark draws 5.16pt either way,
while under this project's own figure.mplstyle they are 0.0 and 0.7 and
the same mark draws 4.20pt from plot against 4.92pt from scatter.
Leaving the stroke out bought agreement in the case that already agreed
and manufactured it in the case that does not. check_overplotting states
what the corpus paid for the change, which was nothing.
An edge that is not drawn adds nothing: a zero width, or an edge colour
that is transparent or "none", is the artist declining to stroke rather
than a stroke of no consequence.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
line
|
Any
|
A |
required |
dpi
|
float
|
The resolution the figure will be measured at, needed only for
|
required |
stroked
|
bool
|
Count the edge stroke. |
True
|
Returns:
| Type | Description |
|---|---|
tuple[float, float]
|
|
Source code in skill/scripts/check_figure.py
2239 2240 2241 2242 2243 2244 2245 2246 2247 2248 2249 2250 2251 2252 2253 2254 2255 2256 2257 2258 2259 2260 2261 2262 2263 2264 2265 2266 2267 2268 2269 2270 2271 2272 2273 2274 2275 2276 2277 2278 2279 2280 2281 2282 2283 2284 2285 2286 2287 2288 2289 2290 2291 2292 2293 2294 2295 2296 2297 2298 2299 2300 2301 2302 2303 2304 2305 2306 2307 2308 2309 2310 2311 2312 2313 2314 2315 2316 2317 2318 2319 2320 | |
check_figure.marker_stroke_pt
¶
The stroke line actually lays down around each marker, in points.
Zero when the edge is not drawn at all, which figure.mplstyle is the
reason to care about: it ships lines.markeredgewidth: 0.0, so every
plot marker in this project's own gallery is unstroked and any widening
read off the width alone would be measuring ink that is not on the page.
get_markeredgecolor resolves "auto" to a real colour itself, so the
only strings that reach to_rgba here are ones it understands, "none"
among them at alpha 0.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
line
|
Any
|
A |
required |
Returns:
| Type | Description |
|---|---|
float
|
|
Source code in skill/scripts/check_figure.py
check_figure.collection_stroke_pt
¶
The stroke a scatter actually lays down around each mark, in points.
The scatter half of marker_stroke_pt, and the reason it is a separate
function is that a Collection says "nothing is stroked" a third way that
a Line2D has no equivalent of. edgecolors="none" leaves
get_edgecolors() an empty (0, 4) array while get_linewidths() keeps
reporting the patch.linewidth default, so a width read on its own is a
width for a stroke that never happens.
That case is not hypothetical. gallery-parity is spelled exactly this
way, and taking its reported 0.70pt as drawn moves it from 48.8% contact
to 58.3% and past OVERPLOT_THRESHOLD - a hard false positive, on the one
corpus figure the question reaches at all, off ink the render does not
contain.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
coll
|
Any
|
A |
required |
Returns:
| Type | Description |
|---|---|
float
|
The drawn stroke width in points, or 0.0 if nothing is stroked. |
Source code in skill/scripts/check_figure.py
check_figure.bars_rest_on_a_shared_edge
¶
Whether these bars stand on one edge or each carries its own offset.
What separates a bar chart from a Gantt chart or a waterfall, and the only
thing check_form needs to know once a BarContainer has already said
these are bars.
A bar chart's lengths are all measured from one edge, so cutting that edge misstates every one of them. A Gantt bar's length is a duration and its position is a start date; a waterfall segment's length is a delta and its base is the running total. Neither is measured from the axis edge, so neither has a baseline to truncate, and the row's own advice - "the fix is the form, not the axis" - is not actionable against them.
The shared edge is the modal one rather than a unanimous one, so a stacked chart is read by its bottom row rather than not at all. On its own that is too loose: a four-step waterfall had two segments land on the same edge by arithmetic. So every rectangle off the modal edge has to stand on the top of another one in its own column, which is what stacking is and what floating is not.
This is deliberately narrower than the detection path that reads a heap of
loose rectangles, which has to decide whether they are a bar chart at all
and carries two guards for that: at least FORM_BAR_MIN_PATCHES of them,
and more than one distinct length. Both are right for detection and wrong
once a container has already answered the question. A single truncated bar
and a row of equal truncated bars are bar charts on the container's own
word, and they still misstate their values; measured, both pass
check_form if the detection guards are reused for this question.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ax
|
Axes
|
The panel. |
required |
vertical
|
bool
|
The bar direction, from the container. |
required |
Returns:
| Type | Description |
|---|---|
bool
|
True when the bars share a baseline, including by stacking on it, and |
bool
|
when there is nothing here to judge. |
Source code in skill/scripts/check_figure.py
check_palette¶
Colour. Standard library only, so these are also the functions to port when the checks are reimplemented elsewhere.
check_palette.check
¶
check(colors: Sequence[str], surface: str = '#ffffff', all_pairs: bool = False, ordinal: bool = False, ink: Collection[str] = frozenset()) -> tuple[bool, list[tuple[str, bool | str, str]]]
Gate a palette. Returns (ok, rows).
check_figure.audit returns the same shape.
rows are (name, status, detail), one per gate. status is True,
False, or the string "warn" for the advisory contrast row, and only a
hard False sets ok to False.
colors are hex strings. surface is the page they are drawn on and sets
what the contrast row measures against. all_pairs gates every pair rather
than adjacent ones, which is what a scatter needs and a line chart does
not. ordinal swaps the categorical separation rows for the ramp rows:
monotone lightness, even steps, a light end that still holds contrast.
ink names colours to treat as furniture rather than data.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
colors
|
Sequence[str]
|
Hex strings, the palette to gate. |
required |
surface
|
str
|
The page colour they are drawn on. |
'#ffffff'
|
all_pairs
|
bool
|
Gate every pair rather than adjacent ones. |
False
|
ordinal
|
bool
|
Swap the categorical rows for the ramp rows. |
False
|
ink
|
Collection[str]
|
Colours to treat as furniture rather than data. |
frozenset()
|
Returns:
| Type | Description |
|---|---|
bool
|
|
list[tuple[str, bool | str, str]]
|
|
tuple[bool, list[tuple[str, bool | str, str]]]
|
row is a hard False. |
Source code in skill/scripts/check_palette.py
853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 | |
check_palette.check_json
¶
check_json(colors: Sequence[str], surface: str = '#ffffff', all_pairs: bool = False, ordinal: bool = False, ink: Collection[str] = frozenset()) -> str
check(), as a JSON document. Returns the text, and prints nothing.
What --json prints, and what to call from a build that has to decide
something rather than show someone a table. The arguments are check's, and
the verdict is the object check computed: this function serialises, it does
not re-gate.
The document carries the inputs as well as the rows. A palette verdict is a
verdict about a palette on a surface, gated as categorical or as a ramp,
and one that records only ok cannot be read a month later: the same eight
hexes pass on white and fail on a tinted page, and both answers are true.
status is "pass", "fail" or "warn", not the tuple API's
True/False/"warn", and schema is the one
check_figure.audit_json emits, so a CI step collecting both reads ok and
rows out of either without asking which checker wrote it.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
colors
|
Sequence[str]
|
Hex strings, the palette to gate. |
required |
surface
|
str
|
The page colour they are drawn on. |
'#ffffff'
|
all_pairs
|
bool
|
Gate every pair rather than adjacent ones. |
False
|
ordinal
|
bool
|
Swap the categorical rows for the ramp rows. |
False
|
ink
|
Collection[str]
|
Colours to treat as furniture rather than data. |
frozenset()
|
Returns:
| Type | Description |
|---|---|
str
|
A JSON object as text, with |
Source code in skill/scripts/check_palette.py
check_palette.pair_separation
¶
The numbers behind check's two separation rows, for one pair.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
color_a
|
str
|
A hex string. |
required |
color_b
|
str
|
A hex string. |
required |
Returns:
| Type | Description |
|---|---|
dict[str, float | str]
|
|
dict[str, float | str]
|
the CAM02-UCS dE the CVD row gates against |
dict[str, float | str]
|
deficiency and severity named; |
dict[str, float | str]
|
row gates against |
Source code in skill/scripts/check_palette.py
check_palette.cmap_kind
¶
Classify hex samples as qualitative, sequential, diverging,
cyclic or misc.
misc is the failure: the lightness reverses, or its span is flat, or its
halves are monotone and its ends match neither cyclic nor diverging. A
colormap in that state encodes nothing the reader can order.
Fewer than CMAP_QUALITATIVE_N = 40 samples is read as a set of category
colours rather than a ramp, and gated on separation instead.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
samples
|
Sequence[str]
|
Hex strings sampled along the colormap, in order. |
required |
Returns:
| Type | Description |
|---|---|
str
|
One of |
str
|
|
Source code in skill/scripts/check_palette.py
check_palette.cmap_kind_rgb
¶
cmap_kind on float sRGB. See cmap_back_travel_rgb for why.
Source code in skill/scripts/check_palette.py
check_palette.cmap_back_travel
¶
How much of a ramp's lightness runs backwards, as a fraction of its span.
0.0 is monotone. CMAP_BACKTRAVEL_MAX = 0.02 is where a ramp stops
counting as ordered, because lightness that reverses makes two different
values render at the same lightness.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
samples
|
Sequence[str]
|
Hex strings sampled along the ramp, in ramp order. |
required |
Returns:
| Type | Description |
|---|---|
float
|
Backward lightness travel as a fraction of the ramp's span. 0.0 is |
float
|
monotone. |
Source code in skill/scripts/check_palette.py
check_palette.cmap_back_travel_rgb
¶
cmap_back_travel on float sRGB, without the 8-bit round trip.
The hex API rounds every channel to 1/255 before lightness is computed. On
a smooth ramp those roundings are oscillations of about 0.001 OKLab that
accumulate into the measure: winter reads 0.0343 through hex against
0.0139 in float, which straddles the 0.02 floor and made a sequential map
classify misc. Maps that genuinely reverse are unaffected, because their
reversals are orders of magnitude larger than the rounding.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
samples
|
Sequence[tuple[float, float, float]]
|
|
required |
Returns:
| Type | Description |
|---|---|
float
|
Backward lightness travel as a fraction of the ramp's span. |
Source code in skill/scripts/check_palette.py
check_palette.contrast
¶
WCAG contrast ratio between two hex colours, from 1.0 to 21.0.
The floors it is compared against: 4.5 for text, 3.0 for a hue against the surface it sits on.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
hex_a
|
str
|
A |
required |
hex_b
|
str
|
The colour to measure it against. |
required |
Returns:
| Type | Description |
|---|---|
float
|
The ratio, 1.0 (identical) to 21.0 (black on white). |
Source code in skill/scripts/check_palette.py
check_palette.delta_e
¶
CAM02-UCS colour difference between two linear-light colours.
Euclidean distance in CAM02-UCS, which is the space's intended use: Luo,
Cui & Li (2006) fitted it so that this distance predicts perceived
difference, so the number carries a unit somebody measured. CVD_TARGET
and NORMAL_FLOOR are quoted in it.
Not a CIELAB dEab and not a CIEDE2000. Over the gamut this file gates as series slots, one CAM02-UCS unit is a median 1.99 CIELAB dEab, but the ratio runs 1.72-2.24 across the interquartile range, so the two are not interconvertible at a fixed rate and a threshold quoted in one does not transfer to the other.
Before 0.8.0 this returned OKLab distance x100. See the CIECAM02 section above for why that number could not support a threshold.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
rgb_a
|
Sequence[float]
|
Linear-light |
required |
rgb_b
|
Sequence[float]
|
The colour to measure it against. |
required |
Returns:
| Type | Description |
|---|---|
float
|
CAM02-UCS euclidean distance. |
Source code in skill/scripts/check_palette.py
check_palette.simulate
¶
Linear-light RGB as a "protan", "deutan" or "tritan" viewer sees it.
Protan and deutan use Vienot, Brettel & Mollon (1999); tritan uses Brettel, Vienot & Mollon (1997). Both run on linear light. Protan and deutan are what the gates decide on; tritan distances are printed and never gated.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
rgb
|
Sequence[float]
|
Linear-light |
required |
kind
|
str
|
|
required |
Returns:
| Type | Description |
|---|---|
tuple[float, float, float]
|
Linear-light |
Source code in skill/scripts/check_palette.py
check_palette.simulate_anomalous
¶
Linear-light RGB as an anomalous trichromat of this severity sees it.
kind is "protan" or "deutan". severity runs 0.0 (normal vision) to
1.0 (dichromacy) and is read at the nearest tenth, which is where Machado,
Oliveira & Fernandes publish the table. No interpolation between two
published matrices, because that is a modelling claim the paper does not
make and this file would then be asserting.
simulate is the dichromacy model check reports as severity 1.0; this
function at 1.0 is the second one, reported as "1.0, Machado". Below 1.0
is anomalous trichromacy.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
rgb
|
Sequence[float]
|
Linear-light |
required |
kind
|
str
|
|
required |
severity
|
float
|
0.0 (normal vision) to 1.0 (dichromacy), read at the nearest tenth. |
required |
Returns:
| Type | Description |
|---|---|
tuple[float, float, float]
|
Linear-light |
Source code in skill/scripts/check_palette.py
check_palette.hex_to_linear
¶
A #rrggbb string as linear-light RGB, each channel in 0..1.
Linear light, not the 0..255 the hex digits carry: every distance and luminance below is defined on it, and averaging or mixing gamma-encoded values is the usual source of a wrong answer that looks plausible.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
h
|
str
|
A |
required |
Returns:
| Type | Description |
|---|---|
tuple[float, float, float]
|
|
Source code in skill/scripts/check_palette.py
check_palette.oklab_distance
¶
OKLab distance between two linear-light colours, x100.
What delta_e measured before 0.8.0, kept because the lightness rows still
reason in OKLab and because a caller comparing against a number this project
published earlier needs the old scale to do it.
It is not a colour difference in any calibrated sense: OKLab was fitted for
hue uniformity, not for discrimination, so distances in it have no published
referent. Gate on delta_e.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
rgb_a
|
Sequence[float]
|
Linear-light |
required |
rgb_b
|
Sequence[float]
|
The colour to measure it against. |
required |
Returns:
| Type | Description |
|---|---|
float
|
OKLab euclidean distance, x100. |
Source code in skill/scripts/check_palette.py
check_palette.linear_to_oklab
¶
Linear-light RGB as OKLab (L, a, b).
OKLab rather than CIELAB because its lightness tracks perceived lightness
across hues, which is what every gate here asks about. l, m, s below are
the cone responses the published matrix names, not a lint slip.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
rgb
|
Sequence[float]
|
Linear-light |
required |
Returns:
| Type | Description |
|---|---|
tuple[float, float, float]
|
|
Source code in skill/scripts/check_palette.py
check_palette.linear_to_cam02ucs
¶
Linear-light RGB as CAM02-UCS (J', a', b').
The space delta_e measures in. Euclidean distance here is a perceived
colour difference in the units Luo, Cui & Li (2006) fitted, which is what
lets the floors in this file cite a measurement instead of a preference.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
rgb
|
Sequence[float]
|
Linear-light |
required |
Returns:
| Type | Description |
|---|---|
tuple[float, float, float]
|
|
Source code in skill/scripts/check_palette.py
check_palette.relative_luminance
¶
WCAG relative luminance of linear-light RGB.
The WCAG coefficients, and deliberately not OKLab's L: the contrast
ratios this project cites are defined against this number, so computing
them from a perceptual lightness would report figures no standard backs.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
rgb
|
Sequence[float]
|
Linear-light |
required |
Returns:
| Type | Description |
|---|---|
float
|
Relative luminance in 0..1, by the WCAG coefficients. |
Source code in skill/scripts/check_palette.py
suggest_fixes¶
Remedies. Both take the rows audit returned, not the figure.
suggest_fixes.suggest
¶
Remedies for the rows of an audit that are not passing.
Takes rows rather than the figure: what is on offer depends on which
gates fired, and nothing here needs to look at the figure again. Returns
[(gate_name, [Remedy, ...]), ...] in the order the gates reported, and
skips gates with nothing to offer rather than padding them with a
restatement of the failure.
A row whose detail opens with DID_NOT_RUN is skipped as well. The remedies
here answer the question a gate asks when it runs, and three rows can report
that they did not: no style sheet to compare against, and no check_palette
to classify a colour with. "Apply the sheet inside the same rc_context" is
the wrong answer to "there is no sheet", and each of those rows already
carries the right one in its own [FIX] clause. A row opening with
GATE_RAISED is skipped for the same reason: the gate crashed and measured
nothing about the figure.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
rows
|
Sequence[tuple[str, bool | str, str]]
|
|
required |
Returns:
| Type | Description |
|---|---|
list[tuple[str, list[Remedy]]]
|
|
list[tuple[str, list[Remedy]]]
|
Empty when nothing fired that this file has an answer for. |
Source code in skill/scripts/suggest_fixes.py
suggest_fixes.format_suggestions
¶
suggest, as lines ready to print under a report.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
rows
|
Sequence[tuple[str, bool | str, str]]
|
|
required |
indent
|
str
|
Leading whitespace for each line. |
' '
|
Returns:
| Type | Description |
|---|---|
list[str]
|
A list of lines. Empty when nothing fired that this file has an |
list[str]
|
answer for. |
Source code in skill/scripts/suggest_fixes.py
The gate functions¶
One row each, in the order audit runs them, which is the order
the gates tables them in and the order a report prints. Every one
returns (status, detail), where status is True, False or "warn".
The signature says what the gate needs beyond the figure. A r parameter is a
renderer, canvas an already-drawn canvas, and scale/placed_frac/venue
the page arithmetic. audit supplies all of them.
check_figure.check_clipping
¶
Text that runs off the canvas.
Reads the axis-aligned box and is correct to: an AABB is the bounding box
of the oriented box's own corners, so its extremes are attained by real
corners of the label and a min/max test against the canvas gives the same
answer either way. Rotation costs this gate nothing. check_collisions
cannot take the same shortcut, because two AABBs can overlap where the
boxes inside them do not.
Source code in skill/scripts/check_figure.py
check_figure.check_collisions
¶
Text-on-text overlap. Tick labels on a shared axis are exempt: matplotlib lays those out itself and a 1px touch there is not a defect.
Compared as oriented boxes, because the axis-aligned one is 5x the ink at 45 degrees and the extra area is two empty triangles. Two parallel oblique labels with clear page between them collided on that box, which is the shape of false positive that teaches people to skim the row.
Source code in skill/scripts/check_figure.py
check_figure.check_text_readability
¶
check_text_readability(fig: Figure, r: Any, canvas: Any = None, scale: float | None = None, placed_frac: float = 1.0, venue: str | None = None) -> tuple[bool | str, str]
Whether each string can be read where it sits.
check_label_attribution asks which curve a label belongs to. This asks the
prior question — whether the label is legible at all — and the two come
apart hard: a label printed on its own curve is attributed perfectly, and
is read through the line crossing its letterforms.
Both clauses are measured off rendered pixels, because both depend on what happened to land behind the glyphs and no artist knows that about itself. The figure is drawn a second time with every string hidden; that render is the backdrop each label was placed onto.
Clutter. Inside a label's box the backdrop should be one surface. Pixels that no blend of {that surface, the grid, the axis rule} explains are data ink passing through the text — a curve, a marker, a spike between the strokes. Measuring the backdrop rather than the finished render is the whole trick: casing hides the evidence, because a white halo over an orange curve renders as clean white while punching a visible gap through the data. Both halves of that are defects and this sees them as one number.
Uniform data ink is not clutter. A label on a heatmap cell has the cell as its surface, so it is the contrast clause that governs there, which is the correct division: a flat fill is a background, a curve is not.
Contrast. The text against the backdrop it actually got, at the WCAG text threshold (4.5:1, or 3:1 for large text) rather than the 3:1 mark threshold, because a glyph stem is thinner than a mark. Casing counts: a black label with a white halo on a dark field is read against the halo.
Both clauses are measured over the pixels the label covers, not over the box
that contains it. A 45-degree string reports an axis-aligned extent five
times its own ink, and the extra area is two triangles nothing is drawn in;
strokes laid in one of them read as ink on the label, and a dark field in one
of them sets the contrast verdict for a string sitting on light ground. See
_oriented_mask.
Tick labels are included. They sit outside the axes on most figures and cost nothing to check there, and on the figures where they do not — an inset, a twinned frame, a label moved inside — that is exactly where they get crossed.
Source code in skill/scripts/check_figure.py
1783 1784 1785 1786 1787 1788 1789 1790 1791 1792 1793 1794 1795 1796 1797 1798 1799 1800 1801 1802 1803 1804 1805 1806 1807 1808 1809 1810 1811 1812 1813 1814 1815 1816 1817 1818 1819 1820 1821 1822 1823 1824 1825 1826 1827 1828 1829 1830 1831 1832 1833 1834 1835 1836 1837 1838 1839 1840 1841 1842 1843 1844 1845 1846 1847 1848 1849 1850 1851 1852 1853 1854 1855 1856 1857 1858 1859 1860 1861 1862 1863 1864 1865 1866 1867 1868 1869 1870 1871 1872 1873 1874 1875 1876 1877 1878 1879 1880 1881 1882 1883 1884 1885 1886 1887 1888 1889 1890 1891 1892 1893 1894 1895 1896 1897 1898 1899 1900 1901 1902 1903 1904 1905 1906 1907 1908 1909 1910 1911 1912 1913 1914 1915 1916 1917 1918 1919 1920 1921 1922 1923 1924 1925 1926 1927 1928 1929 1930 1931 1932 1933 1934 1935 1936 1937 1938 1939 1940 1941 1942 1943 1944 1945 1946 1947 1948 1949 1950 1951 1952 1953 1954 1955 1956 | |
check_figure.check_contrast_stack
¶
A figure where nothing is at full opacity has no focal point, and a long tail of alpha values reads as haze rather than hierarchy.
Neither half fires on the two forms where alpha is doing real work rather than decorating.
A graded run of one colour is one decision, not one per band. An alpha
array on a single artist counts once, because "a continuous encoding is a
single decision", and a fan chart is that same encoding spelled across
separate artists. So non-opaque alphas on artists sharing a colour collapse
to one level once there are ALPHA_RAMP_MIN_STEPS of them. Counted per
band, ALPHA_LEVELS_MAX of 3, less the opaque median line the row itself
demands, would allow a fan chart two bands.
Artists of different colours never collapse, so five series at five alphas
still reads as five decisions, which is the case this half is for.
A single alpha is not a stack. "Nothing is opaque, so the figure has no
focal point" presupposes something to focus on among alternatives. A
density scatter drawn wholly at alpha=0.3 asserts no hierarchy and has no
ranking to top out, and raising the artist that carries the point to
alpha 1 destroys the encoding it is aimed at. The opacity test
applies only where there is more than one level, which is where an author
has built a hierarchy and left it headless. Two levels with nothing opaque
still fail.
Whether a pale figure is visible at all is check_ink's question, not
this one, and it is measured off pixels rather than guessed from alpha.
Measured: a 3000-point scatter at alpha=0.01 still lays 12% ink across
the panel and is perfectly readable as a density field, while three lines
at alpha=0.02 reach 1% and Ink coverage warns. Alpha alone cannot tell
those apart and the render can.
A contrast floor is the wrong tool. Compositing
each artist over its panel and requiring WCAG 2.1's 3:1 non-text ratio
sounds principled and condemns the project's own palette: Okabe-Ito orange
#E69F00 measures 2.25:1 on white at full opacity and can never clear
the floor at any alpha, and the green needs 0.9. That floor is also one
this project deliberately keeps advisory, in check_palette, where a
sub-3:1 hue is legal and merely obligates a second channel. Borrowing it as
a hard gate here would be the same category error as judging a
mathtext script against the body type floor.
Source code in skill/scripts/check_figure.py
2061 2062 2063 2064 2065 2066 2067 2068 2069 2070 2071 2072 2073 2074 2075 2076 2077 2078 2079 2080 2081 2082 2083 2084 2085 2086 2087 2088 2089 2090 2091 2092 2093 2094 2095 2096 2097 2098 2099 2100 2101 2102 2103 2104 2105 2106 2107 2108 2109 2110 2111 2112 2113 2114 2115 2116 2117 2118 2119 2120 2121 2122 2123 2124 2125 2126 2127 2128 2129 2130 2131 2132 2133 2134 2135 2136 2137 2138 2139 2140 2141 2142 2143 2144 2145 2146 2147 2148 2149 2150 2151 2152 2153 2154 2155 2156 2157 2158 2159 2160 2161 2162 2163 2164 2165 2166 2167 2168 2169 2170 2171 2172 2173 2174 2175 2176 2177 2178 2179 2180 2181 2182 2183 2184 2185 2186 2187 2188 2189 2190 2191 2192 2193 2194 2195 2196 2197 2198 2199 2200 2201 2202 2203 2204 2205 2206 2207 2208 | |
check_figure.check_mark_ratio
¶
One mark far larger than the rest stops reading as a mark and starts reading as an ornament stuck on top of the plot.
Reads scatter sizes and line markers, both converted to the area of the disc actually drawn. Bars and other patches are deliberately NOT counted: a bar thirty times another bar is the encoding working, not a defect.
The bar exemption is about the channel, not about whether size carries a
value. A size-encoded scatter is not exempt. Cleveland and McGill ranked the elementary
perceptual tasks and put position and length near the top and area near the
bottom; references/choosing-a-form.md states it and cites them. A bar
thirty times another bar is read as thirty because length is judged well. A
mark thirty times another mark is not read as thirty by anybody, whether or
not the author meant it as the encoding. A bubble chart is precisely the
case where the reader is asked to decode a number off the weak channel, so
it is the last figure that should be exempt.
What the size distribution does change is the advice. When the largest
mark exceeds the next largest by MARK_ORNAMENT_GAP it is one ornament
stuck on top of a plot, and capping the size range is the fix. When the
sizes are graded the figure is encoding something, and clipping the array
silently flattens the values it encodes: measured on a 60-mark bubble
chart, capping the size range collapsed 52 of the 60 onto one size, drew every value from 5.8 to 39.9 identically, and
turned the row green. There the fix is the form, not the numbers.
Both operands go through one conversion because the two APIs take different
quantities and neither is an area. markersize is a diameter in points.
scatter(s=...) is a squared diameter, not the area its own
documentation calls it - see scatter_diameter_pt. Converting one side and
not the other leaves a standing 4/pi = 1.27x error on any figure mixing
scatter with plot(marker=...), which is enough against a 5.0 threshold
to fail a legal figure at a true 3.9x and pass a bad one at 6.4x.
Source code in skill/scripts/check_figure.py
2426 2427 2428 2429 2430 2431 2432 2433 2434 2435 2436 2437 2438 2439 2440 2441 2442 2443 2444 2445 2446 2447 2448 2449 2450 2451 2452 2453 2454 2455 2456 2457 2458 2459 2460 2461 2462 2463 2464 2465 2466 2467 2468 2469 2470 2471 2472 2473 2474 2475 2476 2477 2478 2479 2480 2481 2482 2483 2484 2485 2486 2487 2488 2489 2490 2491 2492 2493 2494 2495 2496 2497 2498 2499 2500 2501 2502 2503 | |
check_figure.check_overplotting
¶
Warn when scatter points overlap into an unreadable mass.
For each PathCollection with offsets (a scatter), the fraction of points whose nearest neighbour in display pixels sits closer than the two marks' radii summed - which is exactly when the two discs intersect on the page. Above the threshold the marks merge into a blob: thin the count or switch to hexbin. Fill and partial alpha are not read, so transparency and hollow markers leave the number where it was.
ax.plot(x, y, "o") draws the same cloud through a different API, and for
seven releases this row could not see it: a marker-only Line2D has no
offsets, so a figure spelled that way was answered "no scatter
overplotting" without a tree ever being built. Lines whose marker is drawn
with no connecting segment are now measured too, and the two spellings
agree exactly: plot(x, y, "o", ms=4) and scatter(x, y, s=16) are the
same 4pt disc and report the same number on the same points. A marked line
("o-") is left alone: its marks are stops on a path the eye is already
following along, and the path carries the ordering that touching marks
would otherwise lose.
The mark's size comes from marker_extent_pt, not from markersize,
because the two are not the same number for every marker and the
difference is not small. Taking markersize as the diameter put
gallery-orbit - 168000 points at marker=",", which matplotlib draws
one pixel wide whatever size is asked for - at a radius 17x its own, and
reported 100% contact off it. The narrower of the two extents is the
radius, so a bar marker is not read as a disc of its long axis: "|" at
ms=5, mew=1 is a tick two pixels across, and nineteen censoring ticks
spread along a survival curve are not nineteen five-point discs.
Every one of the three corpus figures this newly reaches was checked
against the render before it was allowed to fire, by counting the
connected components of each artist's own ink: gallery-forms draws 14
marks as 7 blobs and 12 as 8, gallery-survival 19 ticks as 12, and
gallery-orbit is the case its own comment in examples/gallery.py
predicted and accepted, where the density IS the finding. The row warns
rather than fails for that reason.
Both sides count the edge stroked around the mark, because that stroke is
ink and two marks whose strokes meet have met. marker_stroke_pt and
collection_stroke_pt are the two halves, and each answers "is an edge
drawn at all" before it answers "how wide", which is the whole difficulty:
a Line2D under figure.mplstyle reports markeredgewidth 0.0, and a
scatter spelled edgecolors="none" keeps reporting a patch.linewidth
of 0.70 for a stroke it never lays down.
What the corpus holds, every mark-drawing artist on all 21 figures:
mark-cloud artists 10
with a stroke actually drawn 2 both gallery-survival's "|" and "_"
verdict changes 0
Both of the two are bar markers, where the stroke was already the whole measured width, so nothing on the corpus moves. The change is a correctness one and its exposure is honestly near zero; the figure that would have moved is the one that proves the naive version wrong.
Two marks touch when their centres are closer than the sum of their two
radii. One radius would test whether a mark's centre is swallowed. Each
radius comes from scatter_diameter_pt, because s is not an area.
Nearest is the wrong neighbour to ask about once radii vary. Contact is
d < r_i + r_j, and the j that minimises d need not be the j that
maximises r_j, so a mark can clear its nearest neighbour and be swallowed
whole by a larger one further off. Measured on a fixture of 60 marks - 40
small ones in pairs 8px apart, each pair under a 120px disc centred 20px
away - every mark is in contact and 40 of them are not visible in the render
at all, while the 1-NN test reported 33% and the gate returned "no scatter
overplotting".
Where every mark is the same size, nearest is the right neighbour: r_i +
r_j is then a constant, so some mark is within it exactly when the nearest
one is, and the 1-NN query answers the question outright. That is the common
case and it keeps the cheap path. Where radii differ the marks are grouped
into radius octaves and each group is asked separately; see
_contact_fraction for why the bound has to be the group's largest radius
rather than the scatter's, and what enumerating candidate pairs at
2 * r_max cost on a figure with one oversized mark in it.
Source code in skill/scripts/check_figure.py
2728 2729 2730 2731 2732 2733 2734 2735 2736 2737 2738 2739 2740 2741 2742 2743 2744 2745 2746 2747 2748 2749 2750 2751 2752 2753 2754 2755 2756 2757 2758 2759 2760 2761 2762 2763 2764 2765 2766 2767 2768 2769 2770 2771 2772 2773 2774 2775 2776 2777 2778 2779 2780 2781 2782 2783 2784 2785 2786 2787 2788 2789 2790 2791 2792 2793 2794 2795 2796 2797 2798 2799 2800 2801 2802 2803 2804 2805 2806 2807 2808 2809 2810 2811 2812 2813 2814 2815 2816 2817 2818 2819 2820 2821 2822 2823 2824 2825 2826 2827 2828 2829 2830 2831 2832 2833 2834 2835 2836 2837 2838 2839 2840 2841 2842 2843 2844 2845 2846 2847 2848 2849 2850 2851 2852 2853 2854 2855 2856 2857 2858 2859 2860 2861 2862 2863 2864 2865 2866 2867 2868 2869 2870 2871 2872 2873 2874 2875 2876 2877 2878 2879 2880 2881 2882 2883 2884 2885 2886 2887 2888 2889 2890 | |
check_figure.check_redundancy
¶
Panels on the same scale should share their axis furniture.
Same-row panels are compared on their y axis and same-column panels on their x axis. A repeated axis label, or a repeated run of tick labels on the same limits, scale and label, is duplicated ink.
Source code in skill/scripts/check_figure.py
2925 2926 2927 2928 2929 2930 2931 2932 2933 2934 2935 2936 2937 2938 2939 2940 2941 2942 2943 2944 2945 2946 2947 2948 2949 2950 2951 2952 2953 2954 2955 2956 2957 2958 2959 2960 2961 2962 2963 2964 2965 2966 2967 2968 2969 2970 2971 2972 2973 2974 2975 2976 2977 2978 2979 2980 2981 2982 2983 2984 2985 2986 2987 2988 2989 2990 2991 2992 2993 2994 2995 2996 2997 2998 2999 3000 3001 3002 3003 3004 3005 3006 3007 3008 3009 3010 3011 | |
check_figure.check_type_size
¶
check_type_size(fig: Figure, r: Any, scale: float | None = None, placed_frac: float = 1.0, venue: str | None = None) -> tuple[bool | str, str]
Every rendered string clears the legibility floor once the figure is scaled into the document.
Reads get_fontsize() off the artists that actually rendered, so a size
set through rcParams, computed, or set by a helper is measured like one
written as fontsize=.
Mathtext is measured rather than read, against its own floor. A script is
drawn at 0.7 of the level above it, so the property is not the size on the
page, and the sizes a script legitimately reaches are below what body text
may. Both halves matter: reading the property let a 3.77pt glyph pass, and
judging a script against the body floor failed matplotlib's own log tick
labels. See MATH_SCRIPT_FLOOR_PT.
Source code in skill/scripts/check_figure.py
3133 3134 3135 3136 3137 3138 3139 3140 3141 3142 3143 3144 3145 3146 3147 3148 3149 3150 3151 3152 3153 3154 3155 3156 3157 3158 3159 3160 3161 3162 3163 3164 3165 3166 3167 3168 3169 3170 3171 3172 3173 3174 3175 3176 3177 3178 3179 3180 3181 3182 3183 3184 3185 3186 3187 3188 3189 3190 3191 3192 3193 3194 3195 3196 3197 3198 3199 3200 3201 3202 3203 3204 3205 3206 3207 3208 3209 3210 3211 3212 3213 3214 3215 3216 3217 3218 3219 3220 3221 3222 3223 3224 3225 3226 3227 3228 3229 3230 3231 3232 3233 3234 3235 3236 3237 3238 3239 3240 3241 3242 3243 3244 3245 3246 3247 3248 3249 3250 3251 3252 3253 3254 3255 3256 3257 3258 3259 3260 3261 3262 3263 3264 3265 | |
check_figure.check_line_weight
¶
check_line_weight(fig: Figure, scale: float | None = None, placed_frac: float = 1.0, venue: str | None = None) -> tuple[bool | str, str]
Every drawn stroke against the printer's floor, measured ON THE PAGE.
SIAM's instructions for authors ask for lines one point or thicker, because thinner lines break up or disappear. A stroke shrinks with the figure as type does -- 0.8pt authored in a 9-inch figure placed at 5.5 inches prints at 0.49pt -- so every width is multiplied by the page scale before it is judged.
Data strokes are held to LINE_FLOOR_PT: lines, line collections, unfilled
contour sets, stroked patch edges and annotation arrows. Furniture is held
to the lower FURNITURE_FLOOR_PT: spines, the major and minor gridlines
and the major and minor tick marks. So are marker outlines that carry the
mark (see _marker_outline_pt): an outline is not a line, and Science's
0.5pt minimum covers every line width. A gridline that drops out costs the
reader a reference; a data curve that drops out costs them the finding.
Not measured: colorbar axes, whose dividers are matplotlib's and not the author's; filled contour sets, whose linewidth is the seam between two fills; and any artist that is invisible or draws no stroke.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
fig
|
Figure
|
The figure to read strokes from. |
required |
scale
|
float | None
|
Placed size over authored size, overriding |
None
|
placed_frac
|
float
|
Fraction of the content width the figure is placed at. |
1.0
|
venue
|
str | None
|
A key of |
None
|
Returns:
| Type | Description |
|---|---|
bool | str
|
|
str
|
first, then marker outlines, then furniture. Otherwise |
tuple[bool | str, str]
|
kind measured. |
Source code in skill/scripts/check_figure.py
5506 5507 5508 5509 5510 5511 5512 5513 5514 5515 5516 5517 5518 5519 5520 5521 5522 5523 5524 5525 5526 5527 5528 5529 5530 5531 5532 5533 5534 5535 5536 5537 5538 5539 5540 5541 5542 5543 5544 5545 5546 5547 5548 5549 5550 5551 5552 5553 5554 5555 5556 5557 5558 5559 5560 5561 5562 5563 5564 5565 5566 5567 5568 5569 5570 5571 5572 5573 5574 5575 5576 5577 5578 5579 5580 5581 5582 5583 5584 5585 5586 5587 5588 5589 5590 5591 5592 5593 5594 5595 5596 5597 5598 5599 5600 5601 5602 5603 5604 5605 5606 5607 5608 5609 5610 5611 5612 5613 5614 5615 5616 5617 5618 5619 5620 5621 5622 5623 5624 5625 5626 5627 5628 5629 5630 5631 5632 5633 5634 5635 5636 5637 5638 5639 5640 5641 5642 5643 5644 5645 5646 5647 5648 5649 5650 5651 5652 5653 5654 5655 5656 5657 5658 5659 5660 5661 5662 5663 5664 5665 5666 5667 5668 5669 5670 5671 5672 5673 5674 5675 5676 5677 5678 5679 5680 5681 5682 5683 5684 5685 5686 5687 5688 5689 5690 5691 5692 5693 5694 5695 5696 5697 5698 5699 5700 5701 5702 5703 5704 5705 5706 5707 5708 5709 5710 5711 5712 5713 5714 5715 5716 5717 5718 5719 5720 5721 5722 5723 5724 5725 5726 5727 5728 5729 5730 | |
check_figure.check_banking
¶
Whether a panel's aspect ratio lets the reader compare rates of change.
Banking to 45 degrees is Cleveland's: slope discrimination is most accurate
near 45 and falls away either side of it, so the aspect should put the
strokes there. The aspect that does it is Talbot, Gerth & Hanrahan's, the
one minimising the strokes' arc length at constant area; _banking_factor
says why that and not the median slope. A cycle that is plain in one aspect
ratio is invisible in another, and the wrong one is usually the one the
default produced.
The failure is a resolution failure, and it is measurable. On a saw wave whose decay limbs alternate between two rates, one exactly twice the other: at 2.4 x 5.2 inches the two limbs land 1.6 degrees apart on the page and the alternation cannot be seen at all; at 6.4 x 1.9 they land 10.6 degrees apart and it is the first thing you see. Same data, same axes, same limits.
Advisory, and loose, because the right aspect is a judgement about what the
reader's job is and this cannot know that. BANKING_SLOPE_MAX is a factor
of ten either side of banked, which for one straight line is a stroke
steeper than 84 degrees or flatter than 6. See _banking_segments for what
is excluded and why; a scatter, a map at fixed aspect and a parametric curve
are all cases where banking means nothing.
Source code in skill/scripts/check_figure.py
check_figure.check_ink
¶
check_ink(fig: Figure, context_axes: Sequence[Axes] | None = None, canvas: Any = None) -> tuple[bool | str, str]
Ink as a fraction of each plotting area, measured off the rendered pixels rather than estimated from artist properties.
Near zero means a panel that did not need to be a panel. Very high means a panel with no ground left in it. Reported per-axes, and advisory only: the right density genuinely depends on the form, so this flags panels worth a second look rather than declaring them wrong.
Pass context_axes — a list of Axes whose fill is a context surface (e.g. a
contourf landscape) rather than data-ink. For those axes, the ink fraction
measures only marks ON TOP of the surface by separating the pixel values
into two clusters (k-means with k=2) and removing the larger cluster (the
surface). A figure with a filled terrain plus a few sparse marks will PASS
rather than WARN.
Pass canvas — an already-drawn Agg canvas — to avoid a second render.
Source code in skill/scripts/check_figure.py
3495 3496 3497 3498 3499 3500 3501 3502 3503 3504 3505 3506 3507 3508 3509 3510 3511 3512 3513 3514 3515 3516 3517 3518 3519 3520 3521 3522 3523 3524 3525 3526 3527 3528 3529 3530 3531 3532 3533 3534 3535 3536 3537 3538 3539 3540 3541 3542 3543 3544 3545 3546 3547 3548 3549 3550 3551 3552 3553 3554 3555 3556 3557 3558 3559 3560 3561 3562 3563 3564 3565 3566 3567 3568 3569 3570 3571 3572 3573 3574 3575 3576 3577 3578 3579 3580 3581 3582 3583 3584 3585 3586 3587 3588 3589 3590 3591 3592 | |
check_figure.check_series_color
¶
The hues actually drawn, put through the palette gates.
The hole this closes: check_palette.py judges a list of hexes someone
remembered to paste into a terminal, and this file never looked at color at
all. A figure on matplotlib's default tab10 cycle - whose orange and green
measure CAM02-UCS dE 1.6 under protanopia, against a floor of 10.5 - passed
every composition check
clean. Two scripts in one project that never spoke.
Only what is never legitimate is gated: separation under color blindness, and separation in normal vision. The lightness-band and chroma-floor rows are deliberately not applied to harvested colors. A black or gray series is legal - a reference curve, a control group - and failing it is precisely the noise that teaches people to skim past the row.
Scoped per panel. The comparison, the hue count and the all-pairs mode are all asked of one axes at a time, because the panel is the unit a reader separates hues within - a figure-wide bag gated hues that never share a frame against each other.
A single-hue ordinal ramp is judged categorically here on purpose, and
the standing complaint about it does not survive measurement. The
complaint is that this rejects every 4-step single-hue ramp, leaving
ordered stacks unconditionally red. It does not. Measured on an ordered
stacked bar chart, #0c0c0c #595959 #a5a5a5 #f2f2f2 passes both separation
rows, and so does a 3-step blue. What fails is a scheme whose steps are too
close: ColorBrewer Blues 4 fails because #eff3ff and #bdd7e7 are dE 9.5
apart under protanopia, and check_palette's ordinal rows fail the same
end independently, for contrast against the surface. The row is asking for
wider steps, which is what its own advice says, and that is achievable.
There is a real ceiling underneath, worth stating rather than leaving to be rediscovered: one hue has a finite lightness range and the adjacent floors want about 21 dE, so a single-hue ordinal encoding runs out of room at five steps even in grey.
The exemption was built and thrown away, which is the part to keep.
Detecting "these hues are a ramp" and swapping in the ordinal rows sounds
obvious, and at these lengths a colour-only detector is a coin flip:
reaching past cmap_kind's CMAP_QUALITATIVE_N guard to the underlying
monotone-lightness test calls random draws from an
Okabe-Ito/tab10/Set2/Dark2 pool a ramp about 2/k! of the time, which is
just the chance that k arbitrary colours come out sorted - 35% at three
steps and 10% at four. Each false positive silently disables the CVD
separation gate, which is the only reason this row exists. That guard is a
decision, not an oversight. check_series_color's four
single_hue/ramp_detector tests pin both halves.
The escape hatch _data_colors_by_axes documents - draw an ordinal ramp as
c=values, cmap=... and it is read as the value it is - is genuinely
unavailable to a stacked bar chart, which has no colormap route. That is
the grain of truth in the complaint, and the answer to it is to step the
ramp wider rather than to guess at intent from four hexes.
Source code in skill/scripts/check_figure.py
4338 4339 4340 4341 4342 4343 4344 4345 4346 4347 4348 4349 4350 4351 4352 4353 4354 4355 4356 4357 4358 4359 4360 4361 4362 4363 4364 4365 4366 4367 4368 4369 4370 4371 4372 4373 4374 4375 4376 4377 4378 4379 4380 4381 4382 4383 4384 4385 4386 4387 4388 4389 4390 4391 4392 4393 4394 4395 4396 4397 4398 4399 4400 4401 4402 4403 4404 4405 4406 4407 4408 4409 4410 4411 4412 4413 4414 4415 4416 4417 4418 4419 4420 4421 4422 4423 4424 4425 4426 4427 4428 4429 4430 4431 4432 4433 4434 4435 4436 4437 4438 4439 4440 4441 4442 4443 4444 4445 4446 4447 4448 4449 4450 4451 4452 4453 4454 4455 4456 4457 | |
check_figure.check_dual_axis
¶
Two data scales in one frame: axes at the same position, both drawing
data. twinx and twiny both land here.
Both scales are set by the author, so the crossing point of the two curves is an artifact of the limits chosen rather than anything in the data. Move the limits and the story changes; a reader cannot tell that from the figure.
The escape hatch is the one legitimate case: a pure unit relabel - degrees
C against degrees F, eV against nm - where the twin is furniture and carries
no data of its own. So the discriminator is data on both, not a shared
frame, which keeps the gate off secondary_yaxis and off correct work.
Source code in skill/scripts/check_figure.py
check_figure.check_form
¶
The mechanical subset of form choice - the three cases where the form is
wrong no matter what the data is: a pie or donut (any Wedge), a 3D axes,
and bars standing on a shared baseline along a linear axis that starts above
zero. references/choosing-a-form.md carries the judgement calls this
cannot make.
Returns False naming each case found, else True.
Source code in skill/scripts/check_figure.py
check_figure.check_identity_channel
¶
Identity carried by color and nothing else.
A warning rather than a gate, and the reason is honesty about what the script can see: it can count the hues, but it cannot tell a direct label from any other piece of text in the axes. Failing on that guess would fire on correct work, and a gate people learn to skip is worse than no gate.
Source code in skill/scripts/check_figure.py
check_figure.check_label_attribution
¶
A direct label sitting nearer some other series than the one it names.
check_collisions compares text against text, so a label that clears every
other label and still floats in the corridor between two curves passes it
clean. That is not hypothetical: examples/demo.py shipped with "Tuned"
closer to a neighbouring curve than to its own and the whole suite was
green. Text against text and text against data are different questions.
Harvested narrowly on purpose - only text whose string matches exactly one series label is judged, because only there is the intent known. A callout, a panel letter, an "n = 300" attributes nothing to a curve, and failing those is the noise that teaches people to skim the row.
The threshold is a ratio rather than a distance because the judgement the reader makes is comparative: a label is unambiguous when its own curve is plainly the closest thing to it, not when it is some absolute number of points away.
Scatters count as series alongside lines, and so do the path-drawn ones:
step's staircase, a stackplot band, a contour set. Reading ax.lines
and offsets alone left a label sitting on top of a dense point cloud or
inside a stacked band invisible to the gate twice over: the series could not
own a label, and it could not be the neighbour that made one ambiguous. The
premise here is that a reader resolves a direct label by proximity, and a
reader does not know what artist class drew the ink.
A filled region that encloses the named series is not a rival for its label,
and neither is a series enclosed by a named region. A confidence band lies
on top of the curve it belongs to, so on distance alone it is always tied
with that curve at zero and every direct label under a band failed. The test
is _encloses, and it is geometric: an unlabelled band and one labelled for
the legend get the same answer, which the label-based test this replaced did
not - it passed _child3 and failed 95% CI.
Source code in skill/scripts/check_figure.py
5102 5103 5104 5105 5106 5107 5108 5109 5110 5111 5112 5113 5114 5115 5116 5117 5118 5119 5120 5121 5122 5123 5124 5125 5126 5127 5128 5129 5130 5131 5132 5133 5134 5135 5136 5137 5138 5139 5140 5141 5142 5143 5144 5145 5146 5147 5148 5149 5150 5151 5152 5153 5154 5155 5156 5157 5158 5159 5160 5161 5162 5163 5164 5165 5166 5167 5168 5169 5170 5171 5172 5173 5174 5175 5176 5177 5178 5179 5180 5181 5182 5183 5184 5185 5186 5187 5188 5189 5190 5191 5192 5193 5194 5195 5196 5197 5198 | |
check_figure.check_style_sheet
¶
Every key in the sheet against the rcParams that are actually in effect.
Three separate silent failures land here at once: a color written with a
leading #, a forgotten plt.style.use, and an rcParams override applied
later. All three ship stock matplotlib while every other check passes.
The first cannot be seen by comparing values. # starts a comment in this
format, so grid.color: #e1e0d9 parses to no value and matplotlib drops
the key: the sheet and the live rcParams agree on its absence. So the keys
the file names are read off its text as well, and any that matplotlib
knows but did not parse are reported as dropped.
A warning, not a gate, for one honest reason: a figure built on a different
project's sheet is correct work, and this compares against the global
rcParams rather than what the figure was drawn under, so a figure built
inside an rc_context that has since exited reads as drift when it is not.
Both make a hard failure the wrong instrument. The row names the keys.
Finding no sheet at all warns too, as a STYLE_SHEET pointing at a
missing file does: either way the figure may be stock matplotlib, the case
this gate was written for. Installed, the sheet is inside the package and
is always found; only a vendored copy that took the script without it
reaches this.
Source code in skill/scripts/check_figure.py
6368 6369 6370 6371 6372 6373 6374 6375 6376 6377 6378 6379 6380 6381 6382 6383 6384 6385 6386 6387 6388 6389 6390 6391 6392 6393 6394 6395 6396 6397 6398 6399 6400 6401 6402 6403 6404 6405 6406 6407 6408 6409 6410 6411 6412 6413 6414 6415 6416 6417 6418 6419 6420 6421 6422 6423 6424 6425 6426 6427 6428 6429 6430 6431 6432 6433 6434 6435 6436 6437 | |
check_figure.check_contour_dash
¶
Warns when a monochrome contour set draws its negative levels dashed.
In a monochrome contour, rcParams["contour.negative_linestyle"] is
"dashed" by default, so negative-Z contours ship dashed isolines nobody
chose. The skill's own convention is dashing = unobserved / projected /
threshold, making this a silent semantic error every existing gate misses.
Non-monochrome (colored) contours are always solid and unaffected.
The rule is "any negative level", asked of the drawn strokes, not "every
level non-positive": contour over data spanning zero draws levels either
side of it and matplotlib dashes the negative half, and that signed field
is the case this gate is for.
Source code in skill/scripts/check_figure.py
check_figure.check_colormap
¶
Whether each colormap in the figure encodes what its data is.
Samples every named colormap an artist actually draws with, hands the
samples to check_palette.cmap_kind, and fails the two kinds that are not
an encoding. misc is a ramp whose lightness reverses, or is flat, or ends
somewhere neither cyclic nor diverging would: a reader cannot put two of its
values in order. A qualitative map is judged by the same all-pairs
separation floor a hand-built palette is, because an image puts every
category beside every other one.
A ramp the author evaluated themselves is caught too, by reverse lookup
rather than by classification: six jet steps handed to ax.plot as plain
colours carry no array, so the sampling above finds nothing to judge and
every row on the figure passes. See _sampled_ramp for how a sampled ramp
is told from a categorical palette, which is the whole difficulty.
One way this row passes without having judged anything, and it is
deliberate: a colormap matplotlib built from colours the author set on an
artist is skipped, since contour(colors=[...]) is three levels of one hue
rather than three categories, and classifying it qualitative would fail it.
The other way was not. The row needs check_palette.py importable beside
this file, and without it there is nothing to classify with, so the row
warns rather than passing a gate that never ran. The warn cannot fail a
build -- ok turns on
hard False only -- so a vendored copy that deliberately left the palette
module out still audits, and says which rows went unjudged.
Source code in skill/scripts/check_figure.py
6006 6007 6008 6009 6010 6011 6012 6013 6014 6015 6016 6017 6018 6019 6020 6021 6022 6023 6024 6025 6026 6027 6028 6029 6030 6031 6032 6033 6034 6035 6036 6037 6038 6039 6040 6041 6042 6043 6044 6045 6046 6047 6048 6049 6050 6051 6052 6053 6054 6055 6056 6057 6058 6059 6060 6061 6062 6063 6064 6065 6066 6067 6068 6069 6070 6071 6072 6073 6074 6075 6076 6077 6078 6079 6080 6081 6082 6083 6084 6085 6086 6087 6088 6089 6090 6091 6092 6093 6094 6095 6096 6097 6098 6099 6100 6101 6102 6103 6104 6105 6106 6107 6108 6109 6110 6111 6112 6113 6114 6115 6116 6117 6118 6119 6120 6121 6122 6123 6124 6125 6126 6127 6128 6129 6130 6131 6132 6133 6134 6135 6136 6137 6138 6139 | |
check_figure.check_fonts
¶
Two silent failures between the figure on screen and the file you submit.
Type 3. Matplotlib defaults pdf.fonttype and ps.fonttype to 3. IEEE
PDF eXpress requires embedded Type 1 or TrueType and does not accept Type 3,
so the upload is refused before a reviewer sees it. ACM and Elsevier check
embedding in production instead, which is the same problem surfacing after
acceptance rather than a milder one. Neither publishes a rule rejecting a
submission for it, and this docstring said they did until the prose audit
read the sources. Nothing warns you either way: the figure renders
identically, and the paper bounces at the latest and most expensive possible
moment. Type 42 embeds TrueType outlines instead. figure.mplstyle sets it;
this catches the project that did not copy the sheet, and the notebook that
called rcParams.update afterwards.
Silent substitution. When none of the faces named in font.<family> is
installed, matplotlib falls back to its own default and logs nothing at
default verbosity. The guide calls the typeface the single largest visual
lever in the whole method, so a figure set in DejaVu because someone named
"Times New Roman" on a machine that does not have it is the lever quietly
disengaged. Falling back within the named list is not flagged — that is
what a fallback list is for, and the sheet ships one on purpose.
A warning rather than a gate, for the same reason check_style_sheet is:
both read the global rcParams rather than anything the figure carries, so
neither can tell a figure built under someone else's settings from a figure
built under none. A figure that will only ever be a PNG in a README is also
genuinely unaffected by the PDF font type. What is gated instead is the
thing this repo controls — the shipped figure.mplstyle declares 42, and
the suite fails if that line ever goes missing.
Source code in skill/scripts/check_figure.py
6142 6143 6144 6145 6146 6147 6148 6149 6150 6151 6152 6153 6154 6155 6156 6157 6158 6159 6160 6161 6162 6163 6164 6165 6166 6167 6168 6169 6170 6171 6172 6173 6174 6175 6176 6177 6178 6179 6180 6181 6182 6183 6184 6185 6186 6187 6188 6189 6190 6191 6192 6193 6194 6195 6196 6197 6198 6199 6200 6201 6202 6203 6204 6205 6206 6207 6208 6209 6210 | |
check_figure.check_alt_text
¶
Whether the figure carries a description for a reader who cannot see it.
A warning rather than a gate, and deliberately: on a paper the description frequently is the caption, and the caption lives in the .tex file where this cannot see it. Hard-failing every figure in that entirely reasonable setup is how a row becomes something everyone learns to skip, which is worse than not having it. Where there is no caption — a notebook, a README, a slide, a web page — nothing else is carrying this and the row is the only thing that will say so.