fix(plot): fall back to Noto Sans Math for symbols Noto Sans lacks, prepare 0.16.1

[frankbuckley]

Note

Drafted by a LLM-based AI tool (Claude Code/Opus 5.5).

Closes #112.

Under the 0.16.0 default style, a literal symbol that Noto Sans lacks draws as a missing-glyph box in titles, axis labels, legend entries and tick labels. This covers →, ≈, ≤, ≥, ✓ and every other code point from U+2190 to U+27FF except U+2212 and U+25CC. It was found while adopting 0.16.0 in dseinternational/vocabulary-growth#370. This PR fixes the style, documents the gap and the mathtext workaround in the 0.16.0 upgrade notes, and prepares 0.16.1 without publishing it.

Style change

• set_matplotlib_default_style() now sets font.family from a new default_font_families(): ["sans-serif", "Noto Sans Math", "DejaVu Sans"], or ["sans-serif", "DejaVu Sans"] where Noto Sans Math is not installed.
• DEFAULT_STYLE_DICT["font.family"] is ["sans-serif", "DejaVu Sans"], which is safe on any machine because DejaVu Sans ships with matplotlib. The new constant FONT_FAMILY_FALLBACK names it.

Figures without such symbols are unchanged. A two-panel figure with a suptitle, mathtext titles, legends and a 9 pt annotation gives a pixel-identical PNG under both styles.

Why this list differs from the one proposed in #112

#112 proposed [FONT_FAMILY_DEFAULT, FONT_FAMILY_MATH, "DejaVu Sans"]. When a named family is missing, FontManager._find_fonts_by_props logs findfont: Font family %r not found. on every call, without caching, and matplotlib calls it for every text layout. Two simple figures produced 1,780 such lines. With Noto Sans named explicitly, a machine without it logs that for every text element. This includes CI runners, which install no fonts. Keeping the generic sans-serif first avoids this and keeps font.sans-serif meaningful. The "keep the previous look" recipe in the 0.16.0 notes depends on that. For the same reason, Noto Sans Math is listed only when it is installed.

Why the two-family attempt in vocabulary-growth did not work

That PR reported that font.family = ["sans-serif", "Noto Sans Math"] still drew boxes. Under matplotlib 3.11.2 that list does work on the Agg, SVG, PDF and PS backends, and the PNG output was checked visually. It fails reproducibly in two cases:

• it is set after the text is created, because each Text keeps the font.family in effect when it was created;
• set_matplotlib_default_style() runs again afterwards and resets it.

vocabulary-growth applies the style inside package code (for example comparison.py), so the second case is the likely cause. The 0.16.0 notes now state both conditions.

Known side effect

Noto Sans Math has a single regular face and DejaVu Sans has no medium weight, while the style uses medium and bold. matplotlib therefore logs findfont: Failed to find font weight …, now using 400. once per weight and size, which is three lines per process for a typical figure. This is documented in the 0.16.1 notes. It affects only the weight of fallback symbols.

Verification

• A new test draws the symbols on the Agg, SVG and PDF backends. It fails on any missing-glyph warning, or on any findfont "not found" log line. It adapts the guards in vocabulary-growth and feat(reports): upgrade research utils to 0.16.0 and use Noto Sans and Noto Sans Math throughout language-reading-predictors#694.
• The test fails against the 0.16.0 behaviour. It passes on simulated machines without the Noto fonts, both through the Windows fallback in font.sans-serif and with only DejaVu Sans.
• The full suite passes on Windows: 1,166 passed and 13 skipped. ruff check, ruff format --check, npm run format:check and npm run spellcheck are clean.

Release

__version__ is 0.16.1 and the install instructions point at v0.16.1. Nothing is tagged. Merge this PR, check CI on the merged commit, then tag that commit as v0.16.1.

Downstream follow-up after v0.16.1

• language-reading-predictors: figure_io.HOUSE_FONT_FAMILIES names Noto Sans explicitly. On a machine without Noto Sans it therefore logs Font family 'Noto Sans' not found. for every text element. The layer can be dropped, and use_house_fonts() can take font.family from default_font_families().
• vocabulary-growth: labels already rewritten as mathtext keep rendering. tests/test_figure_text_glyphs.py is no longer needed to prevent boxes.

🤖 Generated with Claude Code