build(release): prepare dse-research-utils 0.18.0

[frankbuckley]

Note

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

Summary

#121 and #122 moved the plot colours to the DSE design tokens, but consumers pin v0.17.0 and can't take them until a tag exists. This prepares dse-research-utils 0.18.0. It is a minor release because the change breaks figure code.

• __version__ is 0.18.0.
• The readme and the Python readme install v0.18.0, and link the new upgrade notes. The Python readme's package map links its plot colours section.
• docs/migrating-to-0.18.md covers:
  • the colours that change without code changes;
  • the two categorical_palette changes;
  • the deprecated COLOUR_* names;
  • reference lines and signed heatmaps;
  • the new names;
  • the upgrade steps, including running tests with the deprecation warning raised as an error.
• docs/README.md names v0.18.0 as the current release. It keeps the 0.17.0 notes for projects upgrading from 0.16.2 or earlier, and lists feat(plot)!: take plot colours from the DSE design tokens #121.

The release contains these changes since v0.17.0:

• feat(plot)!: take plot colours from the DSE design tokens #121, breaking: the plot colours from the design tokens, the ordered palettes and colour maps, MUTED_TEXT_COLOUR and BACKGROUND_COLOUR, and plot_heatmap(..., centre=). categorical_palette raises above six series and returns hex strings. The COLOUR_* names are deprecated.
• build(plot): pin the design tokens to tokens/2026.3.0 #122: the design tokens are pinned to their released file. The colours are unchanged.
• build(deps): refresh Python and npm dependencies #119: the notebook extra, and so all, requires jupytext 1.19.6 or later; the lock is refreshed.
• docs: clarify documentation and remove superseded notes #120: documentation changes only. Comparing the syntax trees of the 15 Python modules it touched, with docstrings removed, shows no code change.

Python 3.14, the base requirements and the other extras are unchanged.

Downstream upgrades

• build(deps): upgrade dse-research-utils to 0.18.0 vocabulary-growth#390
• build(deps): upgrade dse-research-utils to 0.18.0 and draw figures in the design-token colours language-reading-predictors#710
• build(deps): upgrade dse-research-utils to 0.18.0 dspopulations/us-birth-certificates#133

Each pins research main (a1c2656) by rev until the tag exists.

After merging

1. Tag v0.18.0 on the merged commit once its checks pass.
2. Publish the GitHub release. Its text is drafted below.
3. In each downstream draft, replace the rev pin with tag = "v0.18.0" and re-lock.

Release text

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

Takes the plot colours from the DSE design tokens (#121, #122), so a group has the same colour in a research figure as on DSE's websites. This is a breaking release for figure code.

• The default colour cycle is CHART_COLOURS: blue, green, orange, purple, teal and pink, in place of tab10. "C1" is now green and "C3" purple.
• image.cmap and plot_heatmap default to the sequential scale dse_sequential, in place of tab10 and viridis. plot_heatmap(..., centre=0.0) uses the diverging scale dse_diverging, for correlations and other signed values.
• sequential_palette(n) and diverging_palette(n) return three to five ordered steps. Every categorical colour and ordered step reaches 3:1 against the white background.
• TEXT_COLOUR is #202020 and LINE_COLOUR is the lighter #d2d8df, for grid lines only. The new MUTED_TEXT_COLOUR is for secondary text and reference lines that carry meaning.
• Breaking: categorical_palette(n) raises ValueError for more than six series, and returns hex strings rather than RGBA tuples. categorical_palette(n, palette="tab20") keeps the old behaviour.
• Deprecated: the COLOUR_* names raise DeprecationWarning. Blue, green, orange and purple return CHART_COLOURS[0] to [3]. Red, yellow and the dark hues keep their old values until callers choose a chart colour or an ordered step.
• The notebook extra, and so all, requires jupytext 1.19.6 or later (build(deps): refresh Python and npm dependencies #119). Python 3.14, the base requirements and the other extras are unchanged. The documentation was condensed, and the upgrade notes for 0.16.2 and earlier were removed from the tree (docs: clarify documentation and remove superseded notes #120).

No statistical, reporting or storage behaviour changes. See the 0.18.0 upgrade notes. Projects on 0.16.2 or earlier also need the 0.17.0 upgrade notes.

uv add "dse-research-utils @ git+https://github.com/dseinternational/research.git@v0.18.0#subdirectory=src/python"

Downstream upgrades: dseinternational/vocabulary-growth#390, dseinternational/language-reading-predictors#710 and dspopulations/us-birth-certificates#133.

Validation

• uv lock --check --offline passes and uv.lock is unchanged. uv sync --locked, then uv run pytest: 1,210 passed, 15 skipped (Windows symlink and POSIX permission skips).
• uv run ruff check src/python and uv run ruff format --check src/python pass.
• npm run format:check and npm run spellcheck pass, with the new guide included; git diff --check is clean.
• uv build --package dse-research-utils builds dse_research_utils-0.18.0 as a source distribution and a wheel. The wheel's metadata and __version__ both report 0.18.0, and it includes plot/design_tokens/colors.json. Its requirements match a wheel built from v0.17.0, except jupytext >=1.19.6 in notebook and all.

🤖 Generated with Claude Code