Roadmap: ggtaichi after 0.3.0 — consolidated plan and the research behind it

[PursuitOfDataScience]

The research behind the releases after 0.3.0, and the plan that comes out of it.

Read this section and stop, unless you want the argument behind an item.
Ten literature passes each ended with their own prioritisation, which between
them re-ranked the same work nine times. What follows is the single
consolidated list. Section numbers (§n) refer to the full text in the comments.

---

69. What to build next

This section adds nothing. Ten passes each ended with a prioritisation delta
(§14, §24, §31, §37, §42, §47, §51, §56, §61, plus notes in the addenda), which
between them re-ranked the same items nine times and left no single place
showing what to do. This is that place. Where a later delta contradicts an
earlier one, the later one wins and the change is noted. Nothing below is new;
if an item here surprises you, the cross-reference is where it was argued.

No literature was consulted for this section. The one candidate found on
this pass — Lo et al. (2022), a taxonomy of 74 misleading-visualization
issues — turned out to restate §33.2, §34 and §54 rather than add to them, so
it is deliberately not cited above. Consolidation was the better use of the
pass.

---

Tier 0 — corrections to code that has already shipped

These are not features. Each is a defect or an unstated caveat in 0.3.0, all
are small, and they should go first because every one of them is currently
misleading somebody.

	what	where argued	size
1	rank needs a caveat. The widest gap in a 96-cell grid is frequently the largest noise, and taichi_summary() hands the extreme over in one line with no warning.	§54, §55	one sentence
2	is.ordered() for discrete fills. The automatic scale paints a sequential ramp on any factor, which asserts an ordering that an unordered factor does not have.	§53, §55	one branch
3	radius_exponent. The radius channel scales by sqrt(); cartography's answer for proportional circles is Flannery's ≈0.57, and 0.5 was a silent choice.	§30	one argument
4	Label the colour space in every number taichi_check_palette() prints. All of them are space-dependent and none says which space.	§68	one line of output
5	Trend caveat. Every bundled dataset is temporal and every example puts time on x; the grid encodes the series in colour, so slope is not encoded at all.	§58	one paragraph

Tier 1 — Wave 2, in dependency order

The ordering matters: several items are prerequisites for others, which none of
the nine deltas made visible.

1. taichi_seriate() via Suggests: seriation, with on = "difference",
   a reported merit gain, and a temporal-axis guard (§22, §35, §60). Two
   independent literatures support it — structure revelation and outlier
   findability under attention limits — and it is the most-supported item in
   the document. The guard is not optional: reordering a week axis destroys
   the data, so it ships with seriation or seriation ships broken.
2. taichi_lineup() / taichi_rorschach() via Suggests: nullabor
   (§39). Build it with seriation: reordering optimises an objective and will
   find blocks in noise, and a Rorschach over seriated null data is the only
   honest guard against that. The package-specific piece is the pairing
   null, which no existing tool provides.
3. taichi_check() as linter-and-fixer (§21), now covering five
   categories: data shape, presentation, inference (§39), things the mark
   cannot show (§50), and multiplicity (§54). Every finding carries the call
   that fixes it. Individual checks worth including, each a few lines:
   proportional bias (§49), frame count (§44), missingness pattern (§67),
   temporal axis (§58), cell-count/legibility (§17.3).
4. taichi_summary() as the abstract data model (§65) — add mean (§49),
   observed as a four-level missingness factor (§67), and a traversal
   order (§65). Document it as the model every other representation derives
   from, not as a convenience function.
5. taichi_describe() / taichi_alt() with as = for placement (§19,
   §36, §65). Four independent justifications: accessibility, colour naming,
   machine readability, on-chart annotation. Depends on 4.
6. Size-aware taichi_check_palette(cell_size =) (§18), plus the surround
   line and theme_taichi(panel_fill = "auto") (§27). No new dependency;
   the renderer already resolves physical glyph size.
7. annotate_taichi_key() (§34) — onboarding is where the evidence says
   the return is largest for an unfamiliar mark, and the README does not travel
   with the figure.
8. vignette("design") (§13), which now has a great deal to say: mirror
   symmetry (§17.1), ensemble coding (§17.3), Trumbo's four principles (§23),
   the MCDA scoring table (§20), metaphor and valence (§33.2, §45), the
   staging rule (§44), and "what this mark structurally cannot show" (§60)
   — proportional bias, field-level agreement, within-row trend.

Also in Wave 2, independent of the above: HOPs for uncertainty (§23),
palette = "scientific" via Suggests: scico (§23), labels with
contrast-aware colour (§5), na_style with "omit" as the likely default
(§10, §67), stat_taichi() (§9).

Tier 2 — Wave 3, gated

• Settle the argument question first (§15 Q1, §40). The answer the evidence
  supports: group only the genuine clusters (eyes, interactivity), keep
  palette and explicit flat, and keep the flat path working
  permanently — which the stable badge now also requires.
• taichi_agreement(), all three branches together or not at all:
  Bland–Altman for continuous (§49), kappa / weighted kappa / AC1 for
  categorical (§53), the Taylor triple for the field (§59). Shipping one
  branch makes the function misleading for the other inputs.
• geom_taichi_ba() (§49), taichi_stage() (§44),
  palette = "neutral" (§45), pattern fills, scatter placement (§6).
• split (§8) — demoted twice. Its original justification (area outranks
  colour) does not survive §26.2, and it should be scored under §20 and ideally
  wait on the proxy measurement (§17.2) before anyone writes it.

Tier 3 — outside the package

The evaluation agenda (§63). Q1, Q2 and Q3 share one apparatus and are one
study with three conditions. Q1 is the one that matters: if the yin bulb's
position biases which fish reads as heavier, every taichi ever drawn has a
systematic asymmetry no palette check can detect. Q8, the VLM benchmark, needs
no participants at all. The package can ship the stimulus generator, and the
questions should be pre-registered.

Explicitly not planned

Everything on Part I's original list — plotly, a third fill channel,
reimplementing animation, a rendering engine, more than two sources — plus,
added since: a bespoke guide framework (compose legendry, §23),
automatic per-cell p-values (§56), audio synthesis in this package
(§65), and reimplementing the Taylor diagram (§59).

---

The five things that would change the package most

If the list above is still too long: these five, in order.

1. The rank caveat and the is.ordered() branch — shipped code is
   currently misleading, and both are one-liners.
2. taichi_seriate() with its temporal guard — the most-supported feature
   in the document.
3. taichi_check() — it is the delivery mechanism for a dozen findings
   scattered across Parts II–IX, and the only place a user will ever encounter
   most of them.
4. taichi_describe() — four independent justifications, no dependency.
5. Q1 of the evaluation agenda — the only item that would let this package
   make a claim about its own mark rather than borrowing one.

---

---

The full text

In the comments, ~4,400 lines in four parts:

• Part I (§1–§16) — the original catalogue: the survey, themes A–K, the
  first prioritisation, and the open questions.
• Parts II–VI (§17–§48) — measurement of the encoding; corrections; the
  mark's meaning and its novice reader; visual inference and API usability;
  animated transitions and colour semantics.
• Parts VII–X (§49–§64) — agreement and method comparison; categorical
  agreement and multiplicity; time-series structure and field summaries; the
  evaluation agenda.
• §65–§71 — multimodal accessibility, missingness, colour space, the
  candidates evaluated and rejected, and a 2026 result on glyph set size.

Roughly 70 works are cited, each checked against the primary source; CRAN
availability was verified against the live index.

Wave 1

Wave 1 shipped in 0.3.0 and #6 recorded it. The Tier 0 audit below then turned
up six defects in 0.3.0 itself, all fixed on main (0b678f5) — including a
legend order that was not deterministic between sessions, and an animations
vignette that had never rendered a frame.

[PursuitOfDataScience]

ggtaichi — Future Features

A research-grounded feature catalogue for the releases after 0.2.0. This is a
design and literature document, not a changelog and not a commitment. §2
surveys the glyph-visualization and graphical-perception literature and locates
the taichi glyph inside it; §3–§13 turn that into concrete, API-level proposals;
§14 prioritises. CRAN availability of every suggested dependency was verified
against the live CRAN index (July 2026). No package code is changed by this
document.

A note on "the ledger". ggtaichi 0.2.0 was planned in a separate document,
next_release.md — the original brainstorm, the four confirmed 0.1.0 bugs, the
two implemented waves, and a short "deferred to 0.3+" list. That document was
retired once 0.2.0 reached CRAN: everything it shipped is recorded in NEWS.md,
everything it deferred was carried into this file, and the document itself is in
the git history if it is ever wanted. Items below marked [ledger] are the
ones it named first; for those, the content here is the evidence for why they
matter and a sharper design.

The framing that organises everything below. ggtaichi's core encoding is
two colour ramps compared within one mark. The perception literature is
unambiguous that colour/shading is the least accurate channel for reading
values (Cleveland & McGill 1984 rank it last of six), and equally clear that
glyph grids are excellent for pattern and similarity judgements and poor for
value extraction (Fuchs et al. 2017, over 64 user studies). That is not a
flaw to hide — it is a specification. The taichi is a gestalt mark. So the
highest-value features are the ones that (a) make the pattern channel as good
as it can be (palette pairing §7, seriation §5, placement §6), and (b) supply
a second, accurate route to the values when a reader needs them
(interactivity §4, explicit difference encoding §3, labels and binned scales
§5). Adding more colour channels without addressing this would make the
package worse, not better.

---

Status

Wave 1 shipped in 0.3.0. All five items of §14's first wave are built:
§4 ggiraph interactivity, §3 explicit encoding (explicit /
explicit_channel, geom_taichi_diff(), taichi_summary()), §12's ggplot2
4.x work (from_theme() geom defaults, draw_key_taichi(), S7-dispatch
tests, inst/CITATION, coverage and hygiene CI), §7's palette functions
(taichi_palette_pair(), taichi_check_palette(), taichi_palette(), the
scale_taichi_* family) and §5's binned-scale support. See NEWS.md for what
each of them actually does.

Four of §15's open questions are now decided:

• Q2, do the default palettes change? Resolved as proposed. The mismatch
  was measured (about 41 L* units; taichi_check_palette() reports it and
  prints FAIL on the defaults), it is documented in the README, the vignette
  and the help pages, palette = "balanced" ships, and the default is
  unchanged so no existing figure moves. Flipping it is a 1.0.0 decision.
• Q3, raise the ggplot2 floor to 4.0.0? No, not yet. The theme-aware
  defaults are installed in .onLoad() when the installed ggplot2 supports
  them and the literal fallbacks are used otherwise, so the floor stays at
  3.4.0 and nobody is dropped. Revisit at 1.0.0, alongside Q2.
• Q6, recommend shared_legend = TRUE more strongly? Yes. It is
  documented as the perceptually correct choice when the two sources are
  directly comparable --- one ramp makes equal values equal ink by
  construction, with no pairing left to get wrong --- with the cost stated
  plainly: the sources are then told apart only by position within the glyph.
• Q4, the eye-size legend, is partly answered by §3 rather than by a
  guide. With explicit_channel = "eye_size" the eyes carry a defined
  quantity (the gap between the sources) on a documented rescaling, and cells
  where the sources agree draw no eye at all. That is still an
  attention channel rather than a measured one, and precision-seekers are
  pointed at explicit_channel = "angle". A custom guide remains unbuilt.

Still open, and unchanged: Q1 (argument grouping --- now more pressing,
since geom_taichi() takes around thirty arguments; settle it before Wave
3's channels), Q5 (split), Q7 (the map vignette), Q8 (what earns
stable).

Waves 2 to 4 are untouched.

Two further literature passes were run after 0.3.0 shipped, appended as
Part II (§17–§25), Part III (§26–§32), Part IV (§33–§38), Part V (§39–§43), Part VI (§44–§48), Part VII (§49–§52), Part VIII (§53–§57), Part IX (§58–§62) and Part X (§63–§64), with short addenda at §65–§66, §67 and §68. §69 consolidates the nine
scattered prioritisation deltas into one list and is the section to read if you
are reading only one.
Part X remains the closing argument; §65 is a correction to §19 rather than a
new direction. Part III opens with corrections:
two claims in Parts I and II are contradicted by evidence found later, and
§26 says so rather than quietly editing them. Part II (§17–§25). It does not replace anything above; it adds five new themes
(L–P), supplies the empirical backing §2 was missing for the package's central
claim, and revises five of the existing themes where newer evidence changes the
design. §24 folds the result back into the prioritisation.

---

Contents

1. Where the package stands today
2. The survey: where the taichi glyph sits in the literature
3. Theme A — Explicit encoding: the missing third comparison mode
4. Theme B — Interactivity as the value-reading channel
5. Theme C — Making the grid readable: labels, bins, seriation
6. Theme D — Placement beyond the regular grid
7. Theme E — Palette pairing is a correctness problem
8. Theme F — More glyph channels, ranked by how well they work
9. Theme G — A statistical layer
10. Theme H — Uncertainty and missingness
11. Theme I — Animation, export and rendering
12. Theme J — ggplot2 4.x currency and extension hygiene
13. Theme K — Documentation, positioning, datasets
14. Prioritisation
15. Open questions and decisions needed
16. References

Part II — second literature pass (added after 0.3.0 shipped)

17. What the second pass changes about §2
18. Theme L — Colour difference depends on how big the mark is
19. Theme M — Describing the plot in words
20. Theme N — Deciding design questions with a method
21. Theme O — taichi_check() as a linter and fixer
22. Theme P — Seriation, properly
23. Revisions to existing themes
24. Revised prioritisation
25. Additional references

Part III — third literature pass

26. Corrections to Parts I and II
27. Theme Q — The panel is the surround
28. Theme R — Nameability
29. Theme S — Machine readability
30. Further revisions to existing themes
31. Prioritisation delta
32. Third-pass references

Part IV — the reader is a novice, and the mark means something

33. Theme T — Iconicity: a measured asset and an unnamed liability
34. Theme U — Onboarding a mark nobody has seen before
35. Theme V — Attention limits, and a second reason to seriate
36. Revisions from the fourth pass
37. Prioritisation delta
38. Fourth-pass references

Part V — is the pattern real, and is the API usable

39. Theme W — Visual inference: is the structure in this grid real?
40. Theme X — API usability, and a caution about the fix for Q1
41. Revisions from the fifth pass
42. Prioritisation delta
43. Fifth-pass references

Part VI — transitions, and what the colours say

44. Theme Y — Now that animation works, design the transitions
45. Theme Z — The palette's third asymmetry: valence
46. Revisions from the sixth pass
47. Prioritisation delta
48. Sixth-pass references

Part VII — agreement

49. Theme AA — The package computes the difference and never the mean
50. Revisions from the seventh pass
51. Prioritisation delta
52. Seventh-pass references

Part VIII — agreement when the data is categorical, and the cost of a big grid

53. Theme AB — Categorical agreement, and the statistic the mark makes salient
54. Theme AC — A grid is many comparisons
55. Revisions from the eighth pass
56. Prioritisation delta
57. Eighth-pass references

Part IX — time on the x axis, and summarising the field

58. Theme AD — What the grid does to a trend
59. Theme AE — Summarising the field, not just showing it
60. Revisions from the ninth pass
61. Prioritisation delta
62. Ninth-pass references

Part X — the evaluation agenda

63. Theme AF — Nine open questions and how to answer them
64. Tenth-pass references

Addendum to §19 — the accessibility thread is one modality short

65. Theme AG — Multimodal, not just described
66. Addendum references

Addendum to §10 — missingness has four states, and the mark can show them

67. Theme AH — Missingness is data

Addendum to §7 and §18 — the colour space the palette work runs in

68. Theme AI — CIELAB is the weakest link, and it is weakest in blue

The consolidated plan

69. What to build next — one list, superseding the nine deltas
70. Search log — candidates evaluated and rejected
71. Addendum to §17.3 and §35 — set size may not be the binding constraint

---

1. Where the package stands today

0.2.0 (built, not yet released; CRAN has 0.1.0) exports seven objects:
geom_taichi(), geom_yin_fish(), geom_yang_fish(), the GeomYinFish /
GeomYangFish ggproto objects, theme_taichi() and remove_padding(). Four
bundled datasets: pitts_tg, states_tg, pitts_emojis, cafes_tg.

The glyph currently encodes up to six dimensions — x, y, yin fill, yang
fill, yin eye, yang eye — plus angle as a seventh (constant or mapped).
0.2.0 added data-driven eyes, rotation, discrete-fill auto-detection,
yin_scale/yang_scale overrides, shared_limits/shared_legend, exported
fish geoms, remove_padding() auto mode, a print() method, a vectorised
makeContent() renderer (~15× faster on a 1200-cell grid, pixel-identical), a
testthat + vdiffr suite, and an animation vignette verified against
gganimate 1.0.11.

Verified properties worth protecting. The fish geometry is provably exact
(Monte-Carlo tiling: 100% of points in exactly one fish, ~0.50 area each, no
overlap, no gap). Rendering is stable across macOS/Windows/Linux, and works
under coord_fixed, coord_flip, coord_polar, facets, NA values and
duplicated cells. Any new channel must keep the tiling exact and the vdiffr
suite green.

Deferred by the ledger: ggiraph interactivity, coord_sf/map placement, the
eye-size legend question, and promoting the lifecycle badge off experimental.

---

2. The survey

2.1 What kind of design is a taichi grid?

Gleicher et al. (2011), Visual comparison for information visualization,
gives the vocabulary. Every comparison design is assembled from three
building blocks: juxtaposition (side by side), superposition (on top of
each other), and explicit encoding (compute the relationship and show
that). A taichi grid is a superposition design — the two sources occupy
one mark in one position, which is what makes spatial patterns co-registered and
directly comparable.

The taxonomy also names superposition's weakness precisely: it supports "are
these similar?" and "which is larger here?" but not "how much larger?" —
that requires explicit encoding. The package currently offers no explicit
encoding at all, and that is the single clearest structural gap (→ §3).

2.2 What does the glyph literature say a glyph should do?

Borgo et al. (2013), Glyph-based Visualization (Eurographics STAR) is the
canonical reference: it links glyph design to semiotics, collects design
guidelines, and surveys applications. Its central claim is directly relevant —
glyph-based designs are strong precisely because multivariate patterns become
perceptible in a spatial context, which is exactly the taichi grid's premise.

Fuchs et al. (2017), A Systematic Review of Experimental Studies on Data
Glyphs (IEEE TVCG), synthesises 64 user studies, and four of its findings
bear directly on this package:

1. The simple star glyph without contours performs best across several
   criteria — simplicity wins. This is an argument against piling on channels
   and for making the existing ones excellent.
2. Contours help shape-similarity judgements but distract from
   data-similarity judgements. ggtaichi draws an outline (colour,
   linewidth); the default colour = NA is therefore the right default for
   value comparison, and the classic black taichi border should stay opt-in and
   be documented as a stylistic, not analytic, choice.
3. Colour comparisons need no common axis; position/length comparisons require
   mental rotation across a grid. This is a genuinely favourable result for
   a colour-filled glyph grid: unlike star or polyline glyphs, the taichi's two
   fills can be compared cell to cell without realigning axes.
4. Performance drops significantly as the number of glyphs increases — every
   scalability study found this. So dense-grid guidance is not a nicety; and
   reordering the grid so structure is visible at a glance (→ §5) is a
   first-class feature, not polish.

Ward (2002), A Taxonomy of Glyph Placement Strategies splits placement
into data-driven (positions come from the data) and structure-driven
(positions come from relationships/structure), plus post-processing distortions
to resolve overlap. ggtaichi supports exactly one strategy — a regular
categorical grid. The taxonomy is a ready-made roadmap (→ §6).

Wickham, Hofmann, Wickham & Cook (2012), Glyph-maps is the closest
methodological ancestor for the map case: one glyph per spatial location, with a
transformation that embeds each glyph's own coordinate system into map space.
That paper (and the cubble package's glyph-map workflow) is the model to follow
for a coord_sf taichi map, rather than inventing placement rules.

2.3 What does perception research say about the fill channel?

Cleveland & McGill (1984) ordered elementary perceptual tasks by accuracy:

Rank	Task	ggtaichi channel
1	Position along a common scale	x, y (the grid)
2	Position along non-aligned scales	—
3	Length, direction, angle	angle (rotation)
4	Area	split ratio (§8) — not yet implemented
5	Volume, curvature	—
6	Shading, colour saturation	yin fill, yang fill — the core encoding

Two consequences, and they are the backbone of this document:

• The package's primary channel is the least accurate one. Everything that
  gives a reader a second, more accurate route to the numbers is high value:
  tooltips (§4), labels and binned scales (§5), and an explicit difference
  channel (§3).
• The deferred "shift the split to encode a ratio" idea (ledger §3d) is
  better-founded than it looked. Area ranks above colour. Encoding a
  proportion by moving the S-curve would be more accurate than encoding it
  by fill — at the cost of the iconic 50/50 silhouette. That is a real
  trade-off with evidence on both sides, not a gimmick (→ §8).

2.4 Where ggtaichi sits among CRAN packages

Closest neighbours, all live on CRAN: gggibbous 0.1.1 (moon charts —
a two-part glyph for proportions), scatterpie 0.2.6 (pie glyphs at
coordinates), ggstar 1.0.6, ggforce 0.5.0, ggpattern 1.3.1,
biscale-style bivariate approaches, GGally 2.4.0 (glyph/matrix displays),
treemapify, ggalluvial.

The honest differentiation is worth stating in the docs. Moon charts and pie
glyphs encode part-to-whole: one number, split. The taichi encodes two
independent measurements that need not sum to anything — that is a genuinely
different job, and it is why shared_limits/shared_legend exist. Nothing else
on CRAN does it. Conversely, when the two numbers are parts of a whole,
gggibbous is the better tool and the docs should say so.

Infrastructure available: ggiraph 0.9.6, gganimate 1.0.11 + gifski +
av 0.9.6 (MP4), vdiffr 1.0.9, colorspace 2.1-3 and farver 2.1.2 (for
§7's palette work), sf 1.1-2 + ggspatial (for §6), S7 0.2.2,
marquee 1.2.1. ggplot2 on CRAN is 4.0.3 — see §12.

---

3. Theme A — Explicit encoding

Problem. Superposition answers "which is bigger?" and not "by how much?"
(§2.1). A reader looking at a 12 × 8 taichi grid can see where yang dominates
but cannot quantify it, and there is currently no way to ask.

Features.

# a third, computed channel alongside the two sources
geom_taichi(yin = espresso, yang = matcha,
            explicit = c("none", "difference", "ratio", "log_ratio", "z"),
            explicit_channel = c("eye_size", "angle", "border", "radius"))

# or the standalone companion mark: one fish per cell, signed
geom_taichi_diff(yin, yang, method = "difference", palette = "diverging")

# the numbers, tidily, for the reader who needs a table
taichi_summary(data, yin, yang)
#> per cell: yin, yang, difference, ratio, dominant source, rank

Design notes.

• explicit_channel = "eye_size" is the elegant option because the eyes
  already exist as a data channel and are visually subordinate: the fills carry
  the two sources, the eye size carries the gap. A big eye means a big
  difference, which reads as "look here" — semantically apt.
• explicit_channel = "angle" is the most accurate option (direction/angle
  is rank 3 vs colour's rank 6), and rotation already exists. Encoding
  yin − yang as tilt would make the difference readable to a precision the fills
  can never reach. It costs the glyph's upright orientation, so it belongs behind
  an explicit choice — but it is the highest-accuracy option available.
• geom_taichi_diff() is the honest escape hatch: sometimes the right chart
  for "how much bigger" is a diverging heatmap, and a package that offers one
  next to its signature glyph is more trustworthy than one that insists on the
  glyph. Cheap to build (it is a geom_tile() with the package's palette
  conventions) and it makes the explicit argument's semantics concrete.
• ratio/log_ratio need zero/negative handling defined up front — return NA
  with a warning, never Inf.

Deps none. Effort M. Risk low. Value high — this is the
structural gap in the design, named by the comparison taxonomy.

---

4. Theme B — Interactivity as the value-reading channel [ledger, deferred to 0.3]

Problem. The ledger correctly identifies ggiraph as "the single
most-requested kind of feature for glyph-heavy plots". §2.3 explains why it is
more than a convenience: interactivity is how a colour-encoded chart supplies
accurate values without abandoning its encoding.

Features.

geom_taichi(..., interactive = TRUE,
            tooltip = NULL,        # default: both values + difference + cell id
            data_id = NULL,        # per-cell by default; per-fish available
            onclick = NULL)

girafe(ggobj = p, options = list(
  opts_hover(css = "stroke:black;"),
  opts_hover_key(...)              # hover one SOURCE, highlight all its fish
))

Design notes.

• The vectorised makeContent() renderer built in 0.2.0 is what makes this
  natural — as the ledger anticipated. The id-batched polygonGrob maps
  directly onto ggiraph::interactive_polygon_grob() with vectors of tooltip
  and data_id, so this is a substitution inside one function rather than a
  second rendering path.
• Per-fish data_id enables the feature that matters most: hovering the
  yin fish in any cell highlights the yin fish in every cell, turning a
  superposition display temporarily into a single-source display. That directly
  addresses superposition's weakness (§2.1) — the reader can decompose the
  comparison interactively instead of mentally.
• Default tooltip content should include the difference, not just the two
  values — the quantity §3 exists to expose.
• Testing: girafe output is an htmlwidget, so test the grob level (that
  interactive grobs are emitted with the right ids and tooltip vectors) rather
  than snapshotting HTML, which is brittle. Keep the static path byte-identical
  and guarded by the existing vdiffr snapshots.
• plotly remains not worth it (custom grobs; ggplotly() cannot translate
  them) — the ledger's judgement stands. Say so in the docs so users stop asking.

Deps Suggests: ggiraph. Effort M. Risk low.

---

5. Theme C — Making the grid readable

Problem. Every scalability study in Fuchs et al. found performance degrades
as glyph count rises (§2.2), and the package's own docs now admit dense grids
are hard. Three interventions are available, and one of them is unusually
powerful.

Features.

# 1. seriation — reorder rows/columns so structure becomes visible
taichi_seriate(data, x, y, yin, yang,
               method = c("hclust", "pca", "mean", "difference", "none"))
geom_taichi(..., seriate = "hclust")     # or reorder the factors yourself

# 2. binned fills — match to legend bins instead of interpolating luminance
geom_taichi(..., yin_scale = scale_fill_fermenter(n.breaks = 5), ...)
scale_taichi_yin_binned(...); scale_taichi_yang_binned(...)

# 3. on-glyph values, for small grids
geom_taichi(..., label = c("none", "both", "yin", "yang", "difference"),
            label_size = 2.5, label_colour = "auto")

Design notes.

• Seriation is the highest-value idea in this document after §3 and §4. A
  taichi grid on alphabetically-ordered categories hides its own structure;
  reordering rows and columns by hierarchical clustering on the two value
  vectors makes blocks of similar cells adjacent, which is precisely the
  pattern-detection task the glyph is good at (§2.3). The matrix-reordering
  literature has established this for heatmaps for decades, and it transfers
  directly. It is also cheap: stats::hclust + factor releveling, no new
  dependency. Offer it both as a standalone data verb (composable, testable) and
  as a convenience argument.
• Binned fills are the cheapest accuracy win available. Reading a continuous
  luminance ramp is a rank-6 task; matching a swatch to one of five discrete
  bins is far closer to a categorical lookup. ggplot2 already ships binned
  scales; the package needs to (a) make sure they compose with the discrete/
  continuous auto-detection added in 0.2.0, (b) provide the scale_taichi_*
  constructors the ledger listed as §4c, and (c) recommend binning for large
  grids in the docs.
• label_colour = "auto" needs real contrast logic, not a fixed colour:
  compute the fill's relative luminance and choose black or white per cell
  (farver makes this trivial). A hard-coded label colour will be invisible on
  half a diverging palette.
• Labels should be honest about space: refuse (with a warning) above a cell count
  where text cannot fit, rather than drawing overlapping mush. ggfittext is on
  CRAN if automatic shrink-to-fit is wanted.

Deps none required (Suggests: ggfittext optional). Effort M
(seriation), S (binned scale constructors), M (labels). Risk low.

---

6. Theme D — Placement beyond the regular grid [ledger §6, deferred]

Problem. Ward's taxonomy (§2.2) describes a space of placement strategies;
ggtaichi implements one point in it. The map case in particular is, as the
ledger says, "a very compelling demo".

Features.

# map placement — one taichi per region, at its centroid
geom_taichi(..., placement = "map")          # inside coord_sf()
taichi_map(sf_data, yin, yang, size = 0.6)   # convenience wrapper

# continuous (data-driven) placement with overlap resolution
geom_taichi(..., placement = "scatter", collision = c("none", "jitter",
                                                      "repel", "grid_snap"))

# structure-driven placement
taichi_layout(data, method = c("pca", "mds", "umap"), yin, yang)
#> returns x/y positions from the data's own structure, for geom_taichi()

Design notes.

• Follow the glyph-maps method rather than improvising. Wickham et al. (2012)
  solve exactly this: embed each glyph's local coordinate system into map space
  with an explicit width/height, so glyph shape stays constant while position
  comes from geography. The 0.2.0 renderer already resolves radius at draw time
  against the physical panel, which is the same idea and means the hard part is
  done.
• The map demo has an obvious cross-package partner. countryatlas produces
  ISO-reconciled country geometry and centroids; a two-source country comparison
  (e.g. two data providers' estimates of the same indicator) as a taichi map is
  a compelling joint vignette, and neither package needs to depend on the other —
  just documented recipes.
• Overlap is the real problem in continuous placement, and Ward's
  post-processing distortions are the framework: jitter, repulsion, or snapping
  to a coarse grid (the last preserves readability best and is closest to what
  the package already does well). Default to "grid_snap" with a message saying
  what happened, and never silently overplot.
• coord_sf needs system dependencies on CI, so gate it (Suggests: sf), keep
  the vignette eval-guarded, and add a tiny synthetic sf fixture for tests.

Deps Suggests: sf, optionally ggrepel. Effort M (map), M (scatter +
collision), S (taichi_layout). Risk medium — CI system deps and the
overlap semantics.

---

7. Theme E — Palette pairing is a correctness problem

Problem, and it is a real one. The default palettes are a grey ramp
(gray100 → gray0) for yin and a red ramp (#FED7D8 → #C20824) for yang.
Those two ramps do not span the same luminance range, so equal values do not
produce equal visual weight — one fish will systematically appear to dominate.
For a design whose entire purpose is comparing two sources fairly, palette
pairing is not aesthetics; it is the chart's validity. shared_limits fixed the
numeric half of this problem in 0.2.0; the perceptual half is untouched.

Features.

taichi_palette_pair(n = 5, hues = c(250, 20), luminance = c(30, 90),
                    chroma = 60)
#> two ramps, distinct in hue, matched in luminance and chroma trajectory

taichi_check_palette(yin_colors, yang_colors)
#> per-step luminance and chroma of each ramp, the max luminance mismatch,
#> CVD simulations (deutan/protan/tritan), and a pass/fail verdict

geom_taichi(..., palette = c("balanced", "viridis_pair", "brewer_pair",
                             "diverging", "print_safe"))
scale_taichi_yin_viridis_c(); scale_taichi_yang_viridis_c(); ...   # §4c

Design notes.

• colorspace is the right tool and it is on CRAN. Sequential HCL ramps with
  a shared luminance trajectory and different hues are exactly the construction
  needed, and colorspace also provides CVD simulation for the check function.
  farver handles the per-colour luminance arithmetic.
• taichi_check_palette() should be runnable on the current defaults and
  the result documented honestly. If grey-vs-red is unbalanced, say so in the
  help page, offer palette = "balanced", and consider changing the default at
  the next major version with a loud NEWS note. Do not silently change it —
  0.2.0 already made "the default look must not change" a commitment.
• shared_legend = TRUE deserves a re-read in this light. It paints both
  fish with yin_colors so identical values read as identical ink — which is the
  perceptually correct answer for directly comparable sources, and arguably
  should be recommended more strongly than it currently is. The cost is that the
  two sources are then distinguished only by position within the glyph (top bulb
  vs bottom bulb), which is worth stating explicitly.
• A print_safe pair (works in greyscale) matters for journal figures, where
  a two-hue design collapses. Pair with ggpattern texture fills (§8) as the
  belt-and-braces option.
• This theme is also the answer to the ledger's "audit the current red/grey
  defaults for accessibility" note — with a function instead of a manual check.

Deps Suggests: colorspace; farver (already a ggplot2 dependency).
Effort M. Risk low technically; the only sensitive part is whether to
change defaults.

---

8. Theme F — More glyph channels

Ordered by the perceptual evidence (§2.3), not by novelty.

# 1. split ratio -> area (rank 4: BETTER than fill)          [ledger §3d]
geom_taichi(..., split = proportion, split_range = c(0.25, 0.75))

# 2. radius -> size (rank 4-ish, familiar from bubble charts) [ledger §3c]
geom_taichi(..., radius = total, radius_range = c(0.3, 1))

# 3. eye-size legend — resolve the open question              [ledger, open]
guide_taichi_eye(...)      # or: document eyes as annotation-only

# 4. texture/pattern fill for print and CVD safety
geom_taichi(..., yin_pattern = "stripe", yang_pattern = "crosshatch")

# 5. decorative, not data: the classic border and bagua trim
geom_taichi(..., colour = "black", linewidth = 0.3)   # already possible
annotate_bagua(...)                                    # decorative only

Design notes.

• The split-ratio channel is more defensible than the ledger assumed. Area
  outranks colour in Cleveland & McGill, so moving the S-curve to encode a
  proportion gives a more accurate reading than a third fill would. Ship it
  behind an explicit split = argument, default off, with split_range
  clamped away from degenerate slivers, and document the trade-off plainly: you
  gain accuracy and lose the iconic 50/50 silhouette. Non-negotiable
  constraint: the two fish must still tile the circle exactly — extend the
  Monte-Carlo tiling test to a grid of split values before this ships.
• radius is the easy one but needs care about neighbour collision (§6's
  problem in miniature) and about the classic area-vs-diameter scaling error —
  scale by area, i.e. radius ∝ √value, and say so.
• The eye legend should probably be resolved by not building a custom
  guide. Mapped eye size is a low-precision channel by construction; the
  honest resolution is to document eyes as an annotation/attention channel
  rather than a measured one, and point users who need a legend at radius
  or split instead. A custom guide grob is real work for a channel we should
  not encourage precise reading from. (Decision, not a foregone conclusion —
  see §15.)
• Patterns are the accessibility backstop. ggpattern composes with
  polygon grobs; a striped yin and crosshatched yang survive greyscale printing
  and total colour-blindness. Cost: pattern rendering is slow and device-
  dependent, so gate it and warn on large grids.
• Resist adding a seventh and eighth colour channel. Fuchs et al.'s
  "simple star glyph without contours performs best" is the warning: past a
  point, more channels reduce the glyph's legibility rather than its
  information. The package's channel budget should be spent on accurate
  channels (area, angle, position) and on §3–§5's readability work.

Deps Suggests: ggpattern. Effort M (split, with geometry tests),
S (radius), S (patterns). Risk medium for split — it touches the one
piece of the package with a proof behind it.

---

9. Theme G — A statistical layer

Problem. geom_taichi() needs one row per cell. Real data arrives long and
unaggregated, so every user's first step is a group_by() + summarise() they
have to get right, and duplicate cells are currently handled by the geom rather
than by an explicit statistical choice.

Features.

stat_taichi(mapping, data, fun = mean, na.rm = FALSE)
#> aggregates yin and yang per (x, y) cell before drawing, like stat_summary_2d

geom_taichi(..., stat = "taichi", fun = sum)
taichi_check(data, x, y, yin, yang)
#> pre-flight diagnostics: duplicate cells, missing combinations, extreme
#> skew, cell count vs readability, NA counts per fish

Design notes.

• A stat_taichi() makes the aggregation visible in the plot spec, which is
  both more tidyverse-idiomatic and less error-prone than silent handling. It
  also gives a natural home for fun.min/fun.max if uncertainty (§10) is
  later encoded.
• taichi_check() is a small function with outsized value for a geom this
  particular about its input: it turns four separate confusing failure modes
  (duplicate cells, missing combinations, one-sided NAs, too many cells) into one
  readable report. It is also the natural place to warn "142 cells with labels
  will not be legible" (§5) and "your two ramps are luminance-mismatched" (§7).
• Continue the 0.2.0 practice of erroring at + time with the offending column
  name — that was the fix for BUG-3 and it is the right ergonomic.

Deps none. Effort M. Risk low.

---

10. Theme H — Uncertainty and missingness

Problem. 0.2.0 defined NA semantics (a mapped eye size of NA suppresses
the eye; NA fills use na.value) and documented "NA visibility" in the
vignette. What is missing is a way to say "this value is uncertain" as opposed
to "this value is missing", and the two-source design makes that pointed: a cell
where yin is well-measured and yang is a rough estimate should not look like a
cell where both are solid.

Features.

geom_taichi(..., yin_uncertainty = se_a, yang_uncertainty = se_b,
            uncertainty_channel = c("alpha", "pattern", "eye_size", "vsup"))

geom_taichi(..., na_style = c("na_value", "hatched", "hollow", "omit"))
#> "hollow"  = outline only, unmistakably "no data"
#> "omit"    = draw the other fish alone, so a half-glyph reads as half-known

Design notes.

• na_style = "omit" is the semantically perfect option for this glyph and
  no other package can do it: drawing only the fish whose source has data makes
  a half-present glyph mean "one source missing here". That is a rare case
  where the mark's structure carries the metadata for free.
• "vsup" is the ambitious option: Value-Suppressing Uncertainty Palettes
  (Correll, Moritz & Heer, CHI 2018) narrow the colour range as uncertainty
  rises, and a crowdsourced study found readers weight uncertainty more heavily
  with them than with ordinary bivariate encodings. Applying a VSUP per fish
  would be a genuinely novel visualization contribution. It is also the hardest
  item here (a 2-D palette plus a trapezoidal legend, twice), so it belongs late.
• Start with alpha and pattern, which are cheap and already plumbed, and
  document the caveat that alpha interacts with the luminance comparison §7 is
  trying to protect — an uncertain-but-high value can end up looking like a
  certain-but-low one. That interaction is a reason to prefer pattern or
  eye_size as the default uncertainty channel.

Deps Suggests: ggpattern. Effort M (na_style, alpha/pattern),
L (VSUP). Risk medium for VSUP.

---

11. Theme I — Animation, export and rendering

The ledger's gganimate spike succeeded and the animation vignette shipped, so
this theme is mostly small additions:

• MP4 export alongside GIF. av 0.9.6 is on CRAN and gives H.264 without
  gifski's palette limits — better for talks and journal supplements. Document
  the coord_fixed() + fps + frame-count recipe so glyphs stay round.
• Spin animation as a documented recipe, now that angle exists (ledger
  §1b): rotate as pure decoration for a title/hero animation, and separately as
  a data channel over frames.
• transition_reveal() / grow-in recipes (ledger §1c) — docs only.
• Frame-count guidance: the vectorised renderer makes frames cheap
  (0.24 s for 1200 cells with eyes), so animations that were impractical in
  0.1.0 now are not; the vignette should say so with numbers.
• Rendering: ragg for raster output and svglite for vector are the
  right recommendations for a glyph-dense plot; add a one-paragraph note. Also
  keep the known trap documented: vdiffr snapshots are coupled to the ggplot2
  minor version on CRAN, so regenerate them when CRAN's ggplot2 bumps.
• Keep the animations vignette's discipline: chunks attach their own packages,
  animate() calls stay commented (no gifski on CI), and
  transition_states() needs at least one positive length.

Deps Suggests: av. Effort S. Risk low.

---

12. Theme J — ggplot2 4.x currency and extension hygiene

This is the most time-sensitive section. ggplot2 4.0.0 (Sept 2025; CRAN is
now at 4.0.3) was a large extension-facing release, and the package should
be deliberate about it rather than merely passing checks.

1. S3 → S7. ggplot2 4.0.0 replaced many S3 classes with S7. ggtaichi
   defines ggplot_add.ggtaichi_plot(), ggplot_add.taichi_padding(),
   makeContent.taichi_cells() and print.ggtaichi_plot() — S3 methods on
   generics whose objects may now be S7. These currently work (the package's
   tests pass on 4.0.3), but the right move is an explicit test asserting that
   ggplot_add() dispatch and the + chain behave on the current ggplot2, so a
   future S7 tightening is caught by us rather than by CRAN. Watch the extension
   guidance for a recommended S7-native pattern.
2. theme(geom = element_geom(ink, paper, accent)). ggplot2 4.0 lets themes
   set geom defaults, with ink (foreground), paper (background) and accent
   propagating automatically — and from_theme() lets a geom's default_aes
   read them. GeomYinFish/GeomYangFish hard-code fill = "grey20",
   colour = NA. Consequence: ggtaichi does not currently follow a dark
   theme — on a dark paper, a grey20 fallback fish and NA outlines are
   close to invisible. Migrating the fallbacks to from_theme(ink) /
   from_theme(paper) is a small change that makes the package a good citizen
   of modern themes, and it interacts well with §7's palette work.
3. draw_key. Both fish geoms use draw_key_rect. A draw_key_taichi()
   that draws a tiny yin-yang in the legend would be a small, delightful,
   on-brand touch — and it is exactly the kind of thing an extension package
   should do. (Consider a half-fish key for the individual fish geoms.)
4. Guides. The guide system was rewritten in 3.5/4.0; if the eye legend
   (§8) is ever built, build it against the new guide API, not the old one.
5. linewidth. 0.2.0 completed the size → linewidth migration with a
   soft-deprecation path. Schedule the removal of the size fallback for a
   later major version and note it in NEWS now, so the deprecation actually ends.
6. Version floor. Imports: ggplot2 (>= 3.4.0) was right for linewidth.
   If from_theme() is adopted (item 2), the floor must rise to 4.0.0 — a real
   cost/benefit decision, since it drops users on older ggplot2. Alternative:
   detect at build time and degrade. Prefer raising the floor once, cleanly,
   at a major version.
7. Testing infrastructure. The suite is good; add (a) a vdiffr case per new
   channel, (b) the extended Monte-Carlo tiling test parameterised over split
   and angle (§8), (c) expect_snapshot() for print.ggtaichi_plot() and for
   error messages, (d) a covr badge, (e) spelling + urlchecker as
   scheduled CI jobs.
8. inst/CITATION — worth adding now that the design has an evidence base
   to cite alongside it.

Effort S–M. Risk low, and it retires a growing compatibility debt.

---

13. Theme K — Documentation, positioning, datasets

• A vignette("design") grounded in the literature. The ledger's
  "when (not) to use taichi" section shipped as prose; this would give it
  citations and turn it into the package's intellectual centre: what a
  superposition glyph is for (Gleicher), what glyph grids are good and bad at
  (Fuchs, Borgo), why the fill channel is imprecise and what to do about it
  (Cleveland & McGill → §3, §4, §5), and how to place glyphs (Ward, Wickham).
  Very few ggplot2 extension packages document why their mark works; doing so
  is cheap and differentiating.
• An honest comparison table — taichi vs gggibbous moon charts vs
  scatterpie vs bivariate choropleth vs small multiples vs a diverging heatmap
  — with a one-line "use this instead when…" for each. Specifically: when the
  two numbers are parts of one whole, gggibbous; when precision matters more
  than pattern, a heatmap or dot plot; when there are more than two sources,
  small multiples.
• Gallery growth: the pkgdown gallery exists; add seriated vs unseriated
  side by side (§5), the palette-pair check output (§7), a map (§6), and an
  interactive example (§4). Each new feature ships with a gallery entry.
• Datasets: cafes_tg covers the shared-units case. Two gaps worth filling:
  (a) an sf-shaped dataset for the map demo (a handful of regions with two
  measures), and (b) a larger grid (~40 × 30) so the seriation and
  performance stories have something to show. Both clearly synthetic and seeded,
  with builders in data-raw/, per the cafes_tg precedent.
• Lifecycle badge (ledger, open): the API grew again in 0.2.0. Keep
  experimental through 0.3.0; the honest gate for stable is one release
  cycle with no new arguments to geom_taichi() — which, given §3–§8, is
  not the next one. Say that in the docs rather than leaving the badge
  unexplained.
  Settled after 0.3.0, against this proposal: the badge is now stable.
  The owner's reading is that stable promises no breaking change, not no
  new arguments, and on that reading the package has earned it — three
  releases, no removals, no altered semantics, and every 0.1.0 plot still
  draws the same picture. That is also the definition the tidyverse lifecycle
  documentation uses, so the "no new arguments" gate proposed here was
  stricter than the standard it appealed to. See §15 Q8.
• Argument-count pressure. geom_taichi() already takes ~20 arguments, and
  this document proposes a dozen more. That is a real design smell. Consider a
  grouping mechanism before the next wave: taichi_eyes(...),
  taichi_scales(...), taichi_uncertainty(...) option-objects passed as single
  arguments (the pattern theme()/element_*() uses), keeping the flat
  arguments as a deprecated-but-working path. Decide this before §8, not
  after.

Effort M. Risk low.

---

14. Prioritisation

Wave 1 — close the structural gap and modernise (0.3.0).

1. §4 ggiraph interactivity — the deferred headline; the value-reading
   channel the encoding needs; the renderer is already shaped for it.
2. §3 explicit encoding (explicit = + geom_taichi_diff() +
   taichi_summary()) — the missing third comparison mode.
3. §12 ggplot2 4.x work — from_theme(ink/paper) so dark themes work,
   draw_key_taichi(), S7-dispatch tests, inst/CITATION, covr.
4. §7 taichi_check_palette() + taichi_palette_pair() + the
   scale_taichi_* constructors — palette pairing is chart validity, and the
   check function can be run on the current defaults immediately.
5. §5 binned-scale support and recommendation — the cheapest accuracy win.

Wave 2 — readability and placement (0.4.0).
taichi_seriate() and labels with contrast-aware colour (§5); stat_taichi()
and taichi_check() (§9); na_style incl. "omit" (§10); the map placement
path + countryatlas recipe (§6); the vignette("design") and the comparison
table (§13); MP4 export (§11).

Wave 3 — new channels, carefully (0.5.0).
Settle the argument-grouping question (§13) first, then split (with the
extended tiling proof) and radius (§8); pattern fills; scatter placement with
collision resolution (§6); resolve the eye-legend question (§8/§15).

Wave 4 — ambitious and optional.
Per-fish VSUP uncertainty palettes (§10); taichi_layout() structure-driven
placement (§6); the stability cycle that earns a stable badge (§13).

Explicitly not planned. plotly support (custom grobs make it impractical;
ggiraph covers the need); a third or fourth fill channel (Fuchs et al.'s
simplicity result argues against it); reimplementing animation (gganimate
composes already); a rendering engine of our own; more than two data sources in
one glyph (that is what small multiples are for, and the docs should say so).

---

15. Open questions and decisions needed

1. Argument grouping, and when. ~20 arguments now, ~32 if §3–§8 all ship
   flat. Option-objects (taichi_eyes(), taichi_scales(), …) are the
   tidyverse-idiomatic fix, but they are a breaking-ish change and should land
   before the next channel wave, not after. This is the most consequential
   API decision in the document.

2. Do the default palettes change? If taichi_check_palette() shows
   grey-vs-red is luminance-mismatched (§7), the defaults are producing subtly
   unfair comparisons. Changing them breaks every existing figure. Proposal:
   measure, document honestly, ship palette = "balanced", and flip the default
   only at 1.0.0 with a prominent NEWS entry.

3. Raise the ggplot2 floor to 4.0.0? Required for from_theme() (§12).
   Cleaner than runtime detection, but excludes older installs. Leaning: yes, at
   the same major version as the palette change.

4. Eye-size legend: build a guide, or reframe the channel? (§8.) Leaning
   towards documenting eyes as an annotation/attention channel and pointing
   precision-seekers at radius/split — but this is the ledger's open
   question and deserves a real decision.

5. Does split compromise the brand? The 50/50 silhouette is the design's
   identity; area is a more accurate channel than colour. Leaning: ship it
   off-by-default with the trade-off documented, and require the extended tiling
   proof before merge.

6. Should shared_legend = TRUE be recommended more strongly? It is the
   perceptually correct choice for comparable sources (§7) but makes the two
   sources distinguishable only by position within the glyph. Worth a decision
   and a docs sentence either way.

7. Is a taichi map its own package/vignette, or a countryatlas recipe?
   (§6.) Leaning: a vignette here plus a documented recipe, no dependency in
   either direction.

8. What earns stable? Proposal: one full release with no new arguments
   to geom_taichi(), the argument-grouping question settled, and the palette
   defaults final. Decided after 0.3.0: the badge is stable now. The
   proposal above conflated two different promises. stable is a commitment
   that the API will not break — that arguments will not be removed or change
   meaning without a deprecation cycle — and ggtaichi has honoured that across
   three releases. It is not a commitment to stop growing, and reading it that
   way would have kept the badge at experimental indefinitely, since §3–§8
   propose new arguments for every remaining wave.

   Two consequences worth holding the package to, now that the promise is
   made: the size argument's removal (§12.5) must go through a full
   deprecation cycle rather than a version bump, and the argument-grouping
   question (Q1, §40) can no longer be answered by breaking the flat
   arguments — which is the conclusion §40 had already reached on usability
   grounds. The palette-default question (Q2) is unaffected: a default palette
   is not API.

---

16. References

Comparison and glyph design

• Gleicher M, Albers D, Walker R, Jusufi I, Hansen CD, Roberts JC (2011).
  Visual comparison for information visualization. Information Visualization
  10(4): 289–309. https://doi.org/10.1177/1473871611416549 ·
  https://graphics.cs.wisc.edu/Papers/2011/GAWJHR11/paper.pdf
• Gleicher M (2018). Considerations for Visualizing Comparison.
  IEEE TVCG. https://graphics.cs.wisc.edu/Papers/2018/Gle18/viscomp.pdf
• Borgo R, Kehrer J, Chung DHS, Maguire E, Laramee RS, Hauser H, Ward M,
  Chen M (2013). Glyph-based Visualization: Foundations, Design Guidelines,
  Techniques and Applications. Eurographics State of the Art Reports: 39–63.
  https://www.cg.tuwien.ac.at/research/publications/2013/borgo-2013-gly/borgo-2013-gly-report.pdf
• Fuchs J, Isenberg P, Bezerianos A, Keim D (2017). A Systematic Review of
  Experimental Studies on Data Glyphs. IEEE TVCG 23(7): 1863–1879.
  https://doi.org/10.1109/TVCG.2016.2549018 ·
  https://inria.hal.science/hal-01378429/document
• Ward MO (2002). A taxonomy of glyph placement strategies for
  multidimensional data visualization. Information Visualization 1(3–4):
  194–210. https://davis.wpi.edu/xmdv/docs/jinfovis02_glyphpos.pdf
• Chernoff H (1973). The Use of Faces to Represent Points in k-Dimensional
  Space Graphically. JASA 68(342): 361–368.

Graphical perception

• Cleveland WS, McGill R (1984). Graphical Perception: Theory, Experimentation,
  and Application to the Development of Graphical Methods. JASA 79(387):
  531–554. http://euclid.psych.yorku.ca/www/psy6135/papers/ClevelandMcGill1984.pdf
• Correll M, Moritz D, Heer J (2018). Value-Suppressing Uncertainty Palettes.
  CHI 2018. https://doi.org/10.1145/3173574.3174216 ·
  https://idl.uw.edu/papers/uncertainty-palettes
• Harrower M, Brewer CA (2003). ColorBrewer.org: An Online Tool for Selecting
  Colour Schemes for Maps. The Cartographic Journal 40(1): 27–37.

Glyphs in space

• Wickham H, Hofmann H, Wickham C, Cook D (2012). Glyph-maps for visually
  exploring temporal patterns in climate data and models. Environmetrics
  23(5): 382–393. https://doi.org/10.1002/env.2152 ·
  https://vita.had.co.nz/papers/glyph-maps.html
• McNabb L, Laramee RS (2019). Multivariate Maps — A Glyph-Placement Algorithm
  to Support Multivariate Geospatial Visualization. Information 10(10): 302.
  https://www.mdpi.com/2078-2489/10/10/302
• Beecham R et al. (2021). On the Use of 'Glyphmaps' for Analysing the Scale
  and Temporal Spread of COVID-19 Reported Cases. IJGI 10(4): 213.
  https://www.mdpi.com/2220-9964/10/4/213
• cubble's glyph-map workflow (R implementation of the glyph-map idea):
  https://huizezhang-sherry.github.io/cubble/articles/cb4glyph.html

R ecosystem and tooling

• ggplot2 4.0.0 release notes (S7 migration; theme(geom = element_geom())
  with ink/paper/accent; from_theme()):
  https://tidyverse.org/blog/2025/09/ggplot2-4-0-0/ ·
  https://ggplot2.tidyverse.org/news/index.html
• gggibbous (moon charts — the part-to-whole neighbour):
  https://cran.r-project.org/package=gggibbous
• scatterpie: https://cran.r-project.org/package=scatterpie
• ggiraph: https://cran.r-project.org/package=ggiraph
• gganimate: https://cran.r-project.org/package=gganimate · av (MP4):
  https://cran.r-project.org/package=av
• colorspace (HCL palette construction + CVD simulation):
  https://cran.r-project.org/package=colorspace
• ggpattern: https://cran.r-project.org/package=ggpattern
• ggfittext: https://cran.r-project.org/package=ggfittext
• vdiffr: https://cran.r-project.org/package=vdiffr

---

Part II — Second literature pass

Added after 0.3.0 shipped. Part I was written before Wave 1 was built; this
part is a second sweep of the journals, run with the built package in hand. It
is organised the same way: §17 revises the survey, §18–§22 are new themes
lettered L to P, §23 lists the places where new evidence changes an existing
theme's design, §24 re-prioritises, §25 holds the new references. Everything
below was checked against the primary source; CRAN availability was verified
against the live index.

What changed in the framing. Part I asserted that a taichi grid is a
superposition comparison and reasoned from the taxonomy. It never cited
evidence that superposition actually works, because at the time the
document leaned on Gleicher's 2011 design-space paper, which is a taxonomy
rather than an experiment. That evidence exists, it is favourable, and it is
specific enough to be actionable — see §17. The second thing that changed is
that two of the package's own claims turn out to be measurable and
currently unmeasured: colour discriminability depends on how big the fish
is on the page (§18), and a plot that insists on fig.alt everywhere can
generate that text itself (§19).

---

17. What the second pass changes about §2

17.1 Superposition has been tested, and the taichi is on the right side of it

Ondov, Jardine, Elmqvist & Franconeri (2019), Face to Face: Evaluating
Visual Comparison (IEEE TVCG) ran crowdsourced low-level comparison tasks
across five arrangements: stacked small multiples on a common baseline,
adjacent small multiples without one, overlaid (superposition), mirror
symmetric small multiples, and animated transitions. Overlaid beat
standard small multiples. Mirror-symmetric arrangements also improved
performance, as did animation.

That is a direct, three-way endorsement of things this package already does:

• The taichi is superposition — the finding that overlay beats small multiples
  is the empirical claim §2.1 was missing.
• The taichi is mirror symmetric: the two fish are 180-degree rotations of
  each other about the cell centre. The mirror-symmetry result says that is not
  merely decorative — symmetric arrangement is itself a measured advantage, and
  the glyph gets it for free. This belongs in vignette("design") (§13) as a
  first-class argument, not a footnote about aesthetics.
• Animation improved comparison performance, which retro-justifies §11 as a
  comparison feature rather than a presentational one. The animations
  vignette currently sells motion as suiting a cyclical symbol; it can now also
  say motion measurably helps the reader compare.

L'Yi, Jo & Seo (2021), Comparative Layouts Revisited (IEEE TVCG 27(2):
1525–1535) is the modern successor to Gleicher 2011: 127 papers, 15 of them
with quantitative user studies, re-deriving the design space with the evidence
attached. Part I's anchor citation should become "Gleicher 2011 for the
vocabulary, L'Yi 2021 for what the experiments since have shown".

17.2 Readers do not extract the quantity — they extract a proxy

Jardine, Ondov, Elmqvist & Franconeri (2020), The Perceptual Proxies of
Visual Comparison (IEEE TVCG; InfoVis 2019 Best Paper Honourable Mention)
shows the visual system answers comparison questions with heuristic shortcuts —
a centre of mass, a shape envelope — rather than with the quantity the chart
encodes, and that which proxy gets used depends on the arrangement.

This sharpens §3's argument considerably. The reason "which is bigger?" is easy
in a taichi and "by how much?" is impossible is not just that colour is a
rank-6 channel: it is that the reader is answering a different, easier
question about ink. It also raises a concrete empirical question this package
could answer about itself:

What is the taichi's proxy? Plausibly the ink centroid of each fish, or
the perceived area of the darker one. If it is the centroid, then the two
fish are not symmetric proxies — the yin bulb sits at the top and the yang
bulb at the bottom, so vertical position may bias which one reads as
"heavier". That is testable with a small crowdsourced study, and it is the
kind of thing a package documenting its own mark should want to know.

Until it is tested, it is an argument for making the explicit channel (§3) easy
to reach rather than for asking readers to squint harder at the fills.

17.3 Dense grids read as texture — and there is a name for that

The README, the vignette and the gallery all say that past roughly a thousand
cells the reader stops reading symbols and starts reading a field. That is
ensemble coding, and Szafir, Haroz, Gleicher & Franconeri (2016), Four
types of ensemble coding in data visualizations (Journal of Vision 16(5):11)
is the reference: viewers extract summary statistics from a display
pre-attentively, and the paper enumerates which summaries.

This turns an apology into a specification. Instead of "dense grids are hard,
subset or facet", the docs can say which questions a dense grid answers well
(where the field is high on average, where it is variable, where an outlier
sits, where a regime changes) and which it does not (any per-cell lookup). That
is a better sentence and a truer one, and it is cheap: docs only.

It also suggests a small feature with an unusually good cost/benefit ratio:

geom_taichi(..., density_advice = TRUE)
#> message: 1,116 cells at this panel size means glyphs of ~2.1 mm.
#>   Below ~4 mm the grid reads as texture rather than as symbols; that is
#>   fine for spotting bands and regime changes and unreliable for reading
#>   individual cells. Consider binned fills, seriation, or a subset.

The threshold has to come from the rendered panel size, which the 0.2.0
renderer already resolves at draw time — so the package can actually know this
rather than guess at it from the row count.

---

18. Theme L — Colour difference depends on how big the mark is

This is the most consequential new finding, because it says
taichi_check_palette() is currently measuring the wrong thing.

[PursuitOfDataScience]

Problem. 0.3.0 measures a palette pair in CIE Lab and reports CIE2000
distances. Those metrics were derived from large uniform colour patches under
optimal viewing. A taichi fish is not a large uniform patch: in a 12 x 8
grid it might be 8 mm across, and in a 40 x 30 grid it is 2 mm, curved, and
tapering to a point at the tail. Stone, Szafir & Setlur (2014), An
Engineering Model for Color Difference as a Function of Size (CIC) and
Szafir (2018), Modeling Color Difference for Visualization Design (IEEE
TVCG; IEEE VIS 2017) establish that perceived colour difference varies
inversely with mark size, and that mark shape matters too — elongated marks
are significantly more discriminable than compact ones. Szafir gives
probabilistic models fitted separately for three mark types.

So the current check is optimistic for dense grids: a pair it passes at nine
large swatches may be indistinguishable at the size the fish are actually
drawn. And it is pessimistic about one thing — the fish are elongated, which
helps.

Features.

taichi_check_palette(..., cell_size = NULL)
#> cell_size = 4        # millimetres; scales the discriminability thresholds
#> cell_size = "auto"   # take it from a plot object

taichi_check_palette(p)          # accept a ggplot and read its rendered geometry
#> ... glyph size at 7 x 6 in: 4.3 mm
#> ... at this size the two ramps are distinguishable at steps 4-9 and NOT
#>     at steps 1-3

# and the constructive direction
taichi_palette_pair(n = 5, cell_size = 2)
#> widens the luminance and chroma trajectories so the pair survives a
#> 2 mm glyph, and says by how much it had to

Design notes.

• This makes the check size-aware, which no other R palette tool is.
  colorspace, colorblindr and friends all evaluate swatches. Evaluating
  the mark as drawn is a genuinely novel contribution for a glyph package,
  and the package is unusually well placed to do it because the renderer
  already resolves the physical glyph radius at draw time (§1).
• The honest first version does not need Szafir's full probabilistic model:
  scaling the pass/fail tolerance by a documented function of size, with the
  model cited and the assumption stated, is defensible and testable. Fitting
  the published model properly is the second version.
• It changes the advice, not just the report. Below some size no hue pair
  is reliably discriminable, and the correct answer is to stop trying: bin the
  scale (§5), seriate (§22), or drop to one source. The check should say that
  rather than emit a slightly worse number.
• Interacts with §8's radius channel in an unwelcome way: shrinking a glyph
  to encode magnitude also shrinks its colour discriminability. Anything that
  makes glyphs smaller has a colour cost, and the check is where that shows up.

Deps none beyond the current farver. Effort M. Risk low.
Value high — it is the difference between a palette check that is a nice
gesture and one that answers the question the user actually has.

---

19. Theme M — Describing the plot in words

Problem. The package is already disciplined about fig.alt: every figure
in the README, the vignettes and the gallery carries alt text, written by hand.
Hand-written alt text does not scale, goes stale when the data changes, and is
exactly the sort of thing a package that knows the plot spec and the data can
generate. Meanwhile a glyph grid is one of the harder chart types to describe,
so the manual burden is highest precisely where the tool would help most.

Lundgard & Satyanarayan (2022), Accessible Visualization via Natural
Language Descriptions: A Four-Level Model of Semantic Content (IEEE TVCG
28(1)) gives the structure. Their four levels are: (1) construction
properties — marks, encodings, axes, legends; (2) statistical concepts and
relations — extrema, correlations, differences; (3) perceptual and cognitive
phenomena — complex trends and patterns; (4) domain-specific insight.

Their empirical finding matters as much as the taxonomy: blind readers did
not want to be told what to think. They wanted levels 2 and 3 — the numbers
and the patterns — and they wanted to do the interpreting themselves. Level 4
was not welcome from the tool.

Features.

taichi_describe(p, level = 1:3)
#> "A 12-week by 8-neighbourhood grid of taichi glyphs. Each glyph's upper
#>  bulb (yin) is shaded by matcha orders and its lower bulb (yang) by
#>  espresso orders, both on one grey scale from 21 to 78 orders per 100
#>  customers.  Espresso leads in 71 of 96 cells.  The largest gap is
#>  Garden District, week 11 (matcha 74, espresso 29).  Matcha rises and
#>  espresso falls across the season in every neighbourhood; the crossover
#>  happens earliest in University (week 4) and latest in Riverside
#>  (week 10)."

# and the one-liner that plugs into knitr
knitr::opts_chunk$set(fig.alt = taichi_alt(p))

Design notes.

• Levels 1 and 2 are mechanical. Level 1 comes from the plot spec: the
  layer, the two source labels, the scales, the limits, the grid dimensions.
  Level 2 is taichi_summary(), which 0.3.0 already computes — extrema,
  dominance counts, the widest gaps, the rank. The function is mostly a
  formatter over machinery that exists.
• Level 3 is where the judgement is, and where a taichi has something
  specific to say: monotone trends along each axis, crossover points, blocks of
  agreement, rows or columns that behave unlike their neighbours. Keep it to
  claims the data supports arithmetically and say nothing else.
• Stop at level 3, deliberately, and document why. Not offering level 4 is
  the finding, not a limitation.
• The output should be plain text with no markup, so it works as fig.alt, as
  a girafe aria-label, and read aloud.
• Test it the way the rest of the package is tested: expect_snapshot() on the
  generated string for a handful of fixed datasets.

Deps none. Effort M. Risk low. Value high, and unusually
differentiating: very few ggplot2 extensions generate their own descriptions,
and a package whose entire encoding is visual has more reason to than most.

---

20. Theme N — Deciding design questions with a method

Problem. §15 lists eight open questions and settles them by argument.
Three of them — does split compromise the brand, is a ninth channel worth it,
should the eyes get a guide — are exactly the kind of question that gets
re-litigated every release because there is no agreed way to score an answer.

Hsieh, Zavatsky & Chen (2024), Multi-Criteria Decision Analysis for Aiding
Glyph Design (arXiv:2303.08554) supplies one. It defines twelve criteria
for a glyph design — typedness, discernability, intuitiveness, invariance to
geometry (resistance to size degradation), invariance to colorimetry,
compositional separability, compositional comparability, attention importance,
attention balance, searchability, learnability, memorability — scored 1 to 5,
at four scopes (a single variable, a pair of variables, one variable against
all others, and the glyph as a whole), then aggregated with weights.

Features. Not code — a documented scoring of ggtaichi's own glyph, kept in
the repo and updated when a channel is added:

                                 fills  eyes  angle  radius  split(?)
typedness                          5     3      4      4        4
discernability                     2     3      4      4        4
intuitiveness                      5     4      2      3        1
invariance: geometry               3     1      3      2        2
invariance: colorimetry            2     4      5      5        5
composition: separability          4     4      3      2        1
composition: comparability         5     3      4      3        3
...

Design notes.

• The value is in the disagreements it forces. Scoring the eyes on
  "invariance: geometry" immediately says what the dense-grid guidance has been
  circling: a 0.15-radius dot inside a 2 mm glyph is 0.3 mm and gone. That is
  an argument for the eye channel being large-glyph only, stated as a number
  rather than a hunch.
• "Attention: balance — preventing inattentional blindness" is the criterion
  that speaks to §8's warning against more channels. A channel that always
  grabs attention regardless of its value (a heavy border, say) starves the
  fills, which are the point.
• It is also the honest way to settle §15 Q5 (split). Split scores well on
  discernability (area beats colour) and badly on intuitiveness and
  separability (it deforms the silhouette that makes the mark recognisable, and
  it interacts with every other channel's geometry). Whether it ships should
  turn on the weighted total under a stated weighting, published in the repo,
  not on taste.
• Cheap: a table in vignette("design") plus a paragraph on the weighting.

Deps none. Effort S. Risk none. Value medium — it does not add
a feature, it stops the same three arguments recurring.

---

21. Theme O — taichi_check() as a linter and fixer

§9 proposes taichi_check() as pre-flight diagnostics. Two papers say what
shape it should take.

Hopkins, Correll & Satyanarayan (2020), VisuaLint: Sketchy In Situ
Annotations of Chart Construction Errors (Computer Graphics Forum / EuroVis)
covers six error classes that overlap this package's failure modes almost
exactly — inexpressive size encodings, perceptually ineffective colour
encodings, missing legends, truncated axes. Their crowdsourced evaluation
(N = 62) found readers identified errors more reliably after seeing the
annotations, and preferred more verbose explanations for the less obvious
flaws. The unobtrusive, in-place annotation is the interaction design;
verbosity for the subtle cases is the content design.

Chen, Ye, Wang, Zhang, Cui, Wu & Wu (2022), VizLinter: A Linter and Fixer
Framework for Data Visualization (IEEE TVCG) adds the half §9 is missing:
a linter that only reports is half a tool. VizLinter pairs detection with a
fixer that proposes the corrected specification.

Features.

taichi_check(data, x, y, yin, yang)
#> x 4 duplicate (x, y) cells -- geom_taichi() needs one row per cell
#>     fix: stat = "taichi", fun = mean
#> x the two ramps are luminance-mismatched by 41 L* (see §7)
#>     fix: palette = "balanced"
#> ! 1,116 cells at a typical 7 x 6 in panel means ~2.1 mm glyphs
#>     fix: yin_scale = scale_taichi_yin_binned(), or seriate, or subset
#> ! yin has 12 NAs and yang has 0 -- one-sided missingness
#>     fix: na_style = "omit" makes a half-glyph mean "one source missing"
#> v no missing (x, y) combinations

Design notes.

• Every finding carries the call that fixes it. That is the VizLinter
  lesson and it costs almost nothing here, because each check corresponds to
  exactly one argument the package already has.
• Verbosity should scale with obscurity, per VisuaLint: "4 duplicate cells"
  needs one line; "your two ramps are luminance-mismatched, which means equal
  values do not read as equal ink" needs three.
• The in-situ half of VisuaLint has an R analogue worth considering later:
  drawing the warning on the plot during interactive use (a corner
  annotation, suppressed on save). Interesting, and clearly a later wave.
• GeoLinter (arXiv:2310.13707) is the same idea specialised to choropleth
  maps, and is the reference to reach for if §6's map placement ever ships.

Deps none. Effort M. Risk low. Value high — it converts four
confusing failure modes into one readable report with the remedy attached.

---

22. Theme P — Seriation, properly

§5 proposes taichi_seriate() with method = c("hclust", "pca", "mean", "difference", "none") and calls it "cheap: stats::hclust + factor
releveling, no new dependency". The literature says the menu is ad hoc and the
dependency is worth taking.

Behrisch, Bach, Henry Riche, Schreck & Fekete (2016), Matrix Reordering
Methods for Table and Network Visualization (Computer Graphics Forum
35(3):693–716) is the state-of-the-art report: it collects reordering
algorithms from statistics, bioinformatics, graph theory, archaeology and
cartography, and — the useful part — classifies them by the visual pattern
they reveal (blocks, bands, off-diagonal structure, noise). That converts
method = from a list of things that happen to be implementable into a menu
organised by what the user is looking for.

Hahsler, Hornik & Buchta (2008), Getting Things in Order: An Introduction to
the R Package seriation (Journal of Statistical Software 25(3):1–34) and the
seriation package (on CRAN) supply about twenty methods behind one interface,
plus the loss and merit functions — which is the piece that makes the
feature honest, because it lets the package report how much the reordering
improved things rather than just asserting it did.

Baroni & da Silva (2022), A comparative analysis of matrix reordering
algorithms regarding canonical data patterns (Information Visualization)
compares algorithms by the pattern present in the data, which is how to pick a
defensible default.

Features.

taichi_seriate(data, x, y, yin, yang,
               method = "auto",       # or any seriation::seriate() method
               on = c("both", "yin", "yang", "difference"))
#> reorders the x and y factors; attaches the merit before/after

geom_taichi(..., seriate = "auto")

taichi_seriate_gain(data, ...)
#> how much structure the reordering exposed, on a stated merit function

Design notes.

• Suggests: seriation, not a reimplementation. Twenty methods, a
  consistent interface, and the loss/merit machinery, for one Suggests entry.
  Fall back to stats::hclust when it is absent, so the feature degrades
  rather than disappearing — the same pattern 0.3.0 uses for colorspace.
• on = is the ggtaichi-specific part and does not exist in the general
  literature: a two-source grid can be reordered to make the yin field
  legible, the yang field legible, or the difference field legible, and
  those give different orders. Seriating on the difference is the one worth
  featuring — it puts the cells where the sources disagree next to each other,
  which is the question §3 exists to answer.
• Report the gain. A reordering that improves the merit by 2% has rearranged
  the reader's mental model for nothing. Saying so is the difference between a
  feature and a gimmick.
• Seriation and §18 interact well: reordering is one of the few things that
  makes a too-small grid readable without making the glyphs bigger.

Deps Suggests: seriation. Effort M. Risk low. Value high —
Part I already called seriation the highest-value idea after §3 and §4, and
this is what makes it defensible rather than improvised.

---

23. Revisions to existing themes

Where the second pass changes a design already sketched in Part I.

§5 (readable grids) — binning has better support than assumed

Part I argued for binned fills from first principles. The bivariate-mapping
literature supports it empirically: reading a classed scheme is closer to a
categorical lookup than reading a continuous ramp, which is why classed
bivariate choropleths remain the cartographic default despite continuous
schemes being available for decades. Combined with §18 (small marks are harder
to discriminate than swatches), binning is not merely "the cheapest accuracy
win" — for any grid below a few millimetres per glyph it is close to the only
one that does not change the data shown.

§7 (palette pairing) — Trumbo is the theory the check was missing

0.3.0 measures luminance mismatch and CVD distance because those were the
measurable things. Trumbo (1981), A Theory for Coloring Bivariate
Statistical Maps (The American Statistician 35(4):220–226) is the theory
underneath, and it is older than any of the perception work Part I cites.
Trumbo's principles for a two-variable colour scheme are:

1. Order — each variable's colours must have a perceptual ordering.
2. Separation — significantly different values must get separable colours.
3. Rows and columns — the two dimensions must remain perceivable
   distinctly; the colours must not interact so as to destroy either
   univariate reading.
4. Resolution of the diagonal — the scheme must resolve the three cases
   relative to the main diagonal (A larger, B larger, roughly equal).

Strode, Morgan, Thornton, Mesev, Rau, Shortes & Johnson (2020),
Operationalizing Trumbo's Principles of Bivariate Choropleth Map Design
(Cartographic Perspectives 94:5–24) turns them into tests.

This maps onto the package almost line for line, and gives
taichi_check_palette() three checks it does not currently make:

Trumbo	ggtaichi has	ggtaichi is missing
Order	monotone-luminance check	—
Separation	CVD distance, luminance mismatch	size-aware separation (§18)
Rows and columns	—	does the yang fish's colour change how the yin fish's value reads? A simultaneous-contrast check: the two fish are adjacent, so each is the other's surround.
Resolution of the diagonal	—	can a reader tell "yin bigger", "yang bigger" and "equal" apart? That is precisely the taichi's job, and it is exactly what explicit (§3) encodes. The palette check should report whether the fills alone resolve it.

The "rows and columns" gap is the interesting one: the taichi puts its two
colours in direct contact along the S-curve, which is the worst case for
simultaneous contrast. No other bivariate design has quite this problem — a
bivariate choropleth blends two variables into one colour, and a moon chart
has one. It is a genuinely package-specific correctness question and nobody has
measured it.

§8 (more channels) — radius now has a documented cost

§18 says shrinking a glyph reduces colour discriminability. So radius as a
data channel is not free: it trades a rank-4 channel (area) for degradation of
the rank-6 channel that carries the two sources. That is probably still a good
trade when the radius encodes "total", but the docs must say it, and
taichi_check_palette(cell_size =) should be run at the smallest radius the
mapping produces, not the nominal cell size.

§10 (uncertainty) — frequency framing before VSUP

Part I put alpha/pattern first as cheap and VSUP last as ambitious.
Padilla, Kay & Hullman (2022), Uncertainty Visualization (Wiley StatsRef)
reorders that: visualizations showing distributional information with
frequency framing — quantile dotplots and hypothetical outcome plots
(HOPs) — outperform density plots, interval plots and textual descriptions
for decisions under risk, and improve memory of distributional information.

For this package that is a striking result, because HOPs are nearly free
here: gganimate already composes (§11), and a HOP is exactly "draw the grid
once per draw from the uncertainty distribution and animate". No new geometry,
no 2-D palette, no trapezoidal legend.

taichi_hops(data, x, y, yin, yang, yin_se, yang_se, n_frames = 50)
#> a long data frame of sampled draws, ready for
#> geom_taichi() + gganimate::transition_manual(.draw)

Revised §10 order: HOPs (cheap, best evidence) -> na_style including
"omit" (cheap, package-specific, no competitor can do it) -> alpha/pattern
(cheap, weak evidence, interacts badly with §7) -> VSUP (expensive,
ambitious). Part I had this close to backwards.

§11 (animation) — motion is a comparison aid, not decoration

Per §17.1, Ondov et al. found animated transitions improved comparison
performance. The animations vignette should say so, and the framing should
change from "the taichi is cyclical so motion suits it" to "animation is one of
the arrangements that measurably helps comparison, and here is how to use it
for that".

§12 (ggplot2 currency) — the eye-legend question just got cheaper

§15 Q4 leaned towards not building a guide for eye size because a custom
guide grob is real work for a low-precision channel. legendry 0.2.4 (on
CRAN, Teun van den Brand) changes the cost side: it provides composable guides,
a standard key specification, and drop-in replacements for ggplot2's guides.
A size guide for the eyes composed from legendry primitives is a fraction of
the work of a bespoke guide.

The 0.3.0 decision still stands on the other side of the argument — the eyes
are an attention channel and encouraging precise reading from them is wrong —
but the reason should now be "because we do not want one", not "because it is
too expensive". Worth restating in those terms, and worth revisiting if
explicit_channel = "eye_size" turns out to be how people actually use the
package, since that gives the eyes a defined quantity.

§13 (positioning) — two more neighbours, and a sharper table

• biscale (CRAN) is the bivariate-choropleth neighbour: two variables,
  one area, blended into one colour. The taichi keeps the two variables in
  two separate colours inside one mark. That is the sharpest one-line
  contrast in the whole comparison table, because it is the same job solved the
  opposite way — and it comes with the trade-off attached: blending is compact
  and unreadable without a 2-D legend; splitting is legible cell by cell and
  costs twice the ink.
• scico (CRAN) wraps Crameri's scientific colour maps (§23, below).
• Viau, Raveneau, Poncelet, Rodriguez, Sallaberry & Trottier (2025), A
  comparison of hybrid maps for the visualization of two geolocated
  quantitative variables (Information Visualization) is a recent empirical
  comparison of exactly the design space §6 would be entering. Read it before
  building the map path, not after.

§7 again — a scientific-colour-map preset

Crameri, Shephard & Heron (2020), The misuse of colour in science
communication (Nature Communications 11:5444) is the paper journal editors
now cite when they reject a rainbow colour map. Its colour maps are
perceptually uniform and CVD-safe by construction and ship on CRAN as
scico. A palette = "scientific" preset built from a matched pair of
scico maps, gated behind Suggests: scico, is a small addition that lets a
user answer "is this figure acceptable to the journal?" with a citation.

---

24. Revised prioritisation

Part I's §14 stands for Waves 3 and 4. Waves 2 and 2.5 are re-cut in light of
the above.

Wave 2 — readability and honesty (0.4.0). Unchanged in spirit, reordered
and with two additions.

1. §22 seriation via the seriation package, with on = "difference" and
   a reported merit gain — Part I's highest-value remaining idea, now with a
   defensible method menu.
2. §18 size-aware taichi_check_palette() — the cheapest way to make the
   0.3.0 palette work correct rather than merely present, and it needs no new
   dependency.
3. §21 taichi_check() as linter-and-fixer, plus stat_taichi() (§9).
4. §19 taichi_describe() / taichi_alt() — high value, no dependency,
   and it retires a manual chore the package already imposes on itself.
5. §5 labels with contrast-aware colour, and §10's na_style including
   "omit".
6. vignette("design") (§13), now with something to say: the mirror
   symmetry result (§17.1), ensemble coding (§17.3), Trumbo's four principles
   (§23) and the MCDA scoring table (§20).

Wave 2.5 — cheap wins that arrived with the evidence.

• HOPs for uncertainty (§23) — reuses gganimate, best-evidenced uncertainty
  display, no new geometry.
• palette = "scientific" via Suggests: scico.
• Ensemble-coding density advice (§17.3) — a message, computed from the
  real panel geometry.
• The MCDA scoring table (§20) — a docs table that settles three recurring
  arguments.

Unchanged. Wave 3 (argument grouping, then split and radius, patterns,
scatter placement) and Wave 4 (VSUP, taichi_layout(), the stability cycle)
are as Part I left them, with two notes: radius now carries the documented
colour cost from §18, and split should be scored under §20 before it is
argued about again.

Still explicitly not planned. Everything Part I ruled out stays ruled out.
Adding to that list: no bespoke guide framework — if the eye legend is ever
built it composes legendry, and if legendry cannot express it, that is
evidence the channel should not have a guide.

---

25. Additional references

Comparison, empirically

• Ondov B, Jardine N, Elmqvist N, Franconeri S (2019). Face to Face:
  Evaluating Visual Comparison. IEEE TVCG 25(1): 861–871.
  https://doi.org/10.1109/TVCG.2018.2864884 ·
  https://visualthinking.psych.northwestern.edu/publications/OndovFacetoFace2018.pdf
• Jardine N, Ondov BD, Elmqvist N, Franconeri S (2020). The Perceptual Proxies
  of Visual Comparison. IEEE TVCG 26(1): 1012–1021.
  https://doi.org/10.1109/TVCG.2019.2934786 ·
  https://www.cs.au.dk/~elm/pdf/perceptual-proxies.pdf
• L'Yi S, Jo J, Seo J (2021). Comparative Layouts Revisited: Design Space,
  Guidelines, and Future Directions. IEEE TVCG 27(2): 1525–1535.
  https://doi.org/10.1109/TVCG.2020.3030419 · https://arxiv.org/abs/2009.00192

Perception

• Szafir DA, Haroz S, Gleicher M, Franconeri S (2016). Four types of ensemble
  coding in data visualizations. Journal of Vision 16(5): 11.
  https://doi.org/10.1167/16.5.11 ·
  https://graphics.cs.wisc.edu/Papers/2016/AHGF16/main.pdf
• Stone M, Szafir DA, Setlur V (2014). An Engineering Model for Color
  Difference as a Function of Size. Color and Imaging Conference.
  https://graphics.cs.wisc.edu/Papers/2014/SAS14/2014CIC_48_Stone_v3.pdf
• Szafir DA (2018). Modeling Color Difference for Visualization Design.
  IEEE TVCG 24(1): 392–401. https://doi.org/10.1109/TVCG.2017.2744359 ·
  https://danielleszafir.com/colordiff_vis2017.pdf

Bivariate colour, from cartography

• Trumbo BE (1981). A Theory for Coloring Bivariate Statistical Maps.
  The American Statistician 35(4): 220–226.
  https://doi.org/10.1080/00031305.1981.10479360
• Strode G, Morgan JD, Thornton B, Mesev V, Rau E, Shortes S, Johnson N (2020).
  Operationalizing Trumbo's Principles of Bivariate Choropleth Map Design.
  Cartographic Perspectives 94: 5–24.
  https://cartographicperspectives.org/index.php/journal/article/view/1538
• Crameri F, Shephard GE, Heron PJ (2020). The misuse of colour in science
  communication. Nature Communications 11: 5444.
  https://doi.org/10.1038/s41467-020-19160-7
• Viau L, Raveneau V, Poncelet P, Rodriguez N, Sallaberry A, Trottier C (2025).
  A comparison of hybrid maps for the visualization of two geolocated
  quantitative variables. Information Visualization.
  https://doi.org/10.1177/14738716251325133

Accessibility

• Lundgard A, Satyanarayan A (2022). Accessible Visualization via Natural
  Language Descriptions: A Four-Level Model of Semantic Content. IEEE TVCG
  28(1): 1073–1083. https://doi.org/10.1109/TVCG.2021.3114770 ·
  https://vis.csail.mit.edu/pubs/vis-text-model/

Design method, and checking designs

• Hsieh H-P, Zavatsky A, Chen M (2024). Multi-Criteria Decision Analysis for
  Aiding Glyph Design. https://arxiv.org/abs/2303.08554
• Hopkins AK, Correll M, Satyanarayan A (2020). VisuaLint: Sketchy In Situ
  Annotations of Chart Construction Errors. Computer Graphics Forum
  (Proc. EuroVis) 39(3). https://doi.org/10.1111/cgf.13975 ·
  https://vis.csail.mit.edu/pubs/visualint/
• Chen Q, Ye F, Wang M, Zhang W, Cui W, Wu Y, Wu Y (2022). VizLinter: A Linter
  and Fixer Framework for Data Visualization. IEEE TVCG 28(1): 206–216.
  https://doi.org/10.1109/TVCG.2021.3114804 ·
  https://arxiv.org/abs/2108.10299
• Lei F, et al. (2023). GeoLinter: A Linting Framework for Choropleth Maps.
  https://arxiv.org/abs/2310.13707

Seriation

• Behrisch M, Bach B, Henry Riche N, Schreck T, Fekete J-D (2016). Matrix
  Reordering Methods for Table and Network Visualization. Computer Graphics
  Forum 35(3): 693–716. https://doi.org/10.1111/cgf.12935 ·
  https://bib.dbvis.de/uploadedFiles/MatrixReorderingSTAR.pdf
• Hahsler M, Hornik K, Buchta C (2008). Getting Things in Order: An
  Introduction to the R Package seriation. Journal of Statistical Software
  25(3): 1–34. https://doi.org/10.18637/jss.v025.i03
• Baroni MP, da Silva CG (2022). A comparative analysis of matrix reordering
  algorithms regarding canonical data patterns. Information Visualization.
  https://doi.org/10.1177/14738716221091487

Uncertainty

• Padilla L, Kay M, Hullman J (2022). Uncertainty Visualization.
  Wiley StatsRef: Statistics Reference Online.
  https://doi.org/10.1002/9781118445112.stat08296 ·
  http://space.ucmerced.edu/Downloads/publications/Uncertainty_Visualization_Padilla_Kay_Hullman_2022.pdf

R packages named above (all on CRAN, verified August 2026)

• seriation — twenty-odd reordering methods plus loss/merit functions:
  https://cran.r-project.org/package=seriation
• scico — Crameri's scientific colour maps:
  https://cran.r-project.org/package=scico
• legendry 0.2.4 — extended and composable ggplot2 guides:
  https://cran.r-project.org/package=legendry
• biscale — bivariate choropleth mapping for ggplot2:
  https://cran.r-project.org/package=biscale
• ggpattern / gridpattern — pattern fills:
  https://cran.r-project.org/package=ggpattern

---

Part III — Third literature pass

Organised like Part II, with one difference: it opens with §26,
Corrections. Two things asserted earlier turn out to be wrong or
overstated. They are corrected in place rather than silently edited, because a
design document whose errors vanish is not a record of anything. §27–§29 are
new themes Q, R and S; §30 revises; §31 is the prioritisation delta; §32 the
new references.

---

26. Corrections to Parts I and II

26.1 Animation: Part II overstated it

Part II §23 said "motion is a comparison aid, not decoration", on the
strength of Ondov et al.'s finding that animated transitions improved
comparison performance, and proposed reframing the animations vignette around
it.

That is half true and the framing was wrong. Robertson, Fernandez,
Fisher, Lee & Stasko (2008), Effectiveness of Animation in Trend
Visualization (IEEE TVCG 14(6)) evaluated animated trends against two static
alternatives — all traces overlaid, and small multiples — for both analysis
and presentation, and found animation among the least effective formats
for analysis while being effective and engaging for presentation.

The two results are not in conflict; they are about different things:

	Ondov et al. 2019	Robertson et al. 2008
what was animated	a transition between two states	a trend over many frames
task	low-level perceptual comparison	trend analysis, and presentation
result	animation helped	animation hurt analysis, helped presentation

Corrected guidance for §11. A two-state animated transition — source A to
source B, before to after — is a legitimate comparison aid with evidence behind
it. transition_states() over thirty weeks of pitts_tg is a presentation
device, and the vignette should say so plainly and point analysts at the
static faceted grid, which the same paper found superior. The current vignette
sells motion on the grounds that a taichi is a cyclical symbol; that is an
aesthetic argument, and it should stay an aesthetic argument rather than being
upgraded to an analytic one on the strength of half the literature.

26.2 The channel ranking is a partial order, not a list

Part I's framing rests on Cleveland & McGill's six ranks, and reasons
arithmetically from them — §2.3's table, and §8's central argument that
"area outranks colour, so moving the S-curve to encode a proportion gives a
more accurate reading than a third fill would".

Kay & Heer (2016), Beyond Weber's Law: A Second Look at Ranking
Visualizations of Correlation (IEEE TVCG 22(1)) re-analysed a
ranking of this kind with individual differences, a log transform, censored
regression and Bayesian estimation. Two findings bear on the argument:

1. The refined model deviates from Weber's Law while predicting better —
   so the tidy monotone story behind these rankings is an approximation.
2. Using credibility intervals they derive a partial ranking that groups
   visualizations with similar performance, rather than a strict order. And
   individual differences between readers are large.

Corrected guidance. "Area beats colour" is a tendency with overlapping
uncertainty and large between-reader variation, not a guarantee, and Cleveland
& McGill's ranks 4 and 6 are not two rungs of a ladder that can be traded
against each other arithmetically. That materially weakens §8's case for
split: the design would deform the one silhouette that makes the mark
recognisable, in exchange for an accuracy gain that is real on average and not
reliable for any given reader. It does not kill the idea — it means the
justification has to be "measured on our own mark", not "rank 4 > rank 6".

§20's MCDA scoring is the right way to settle it, and this correction is
exactly why: an argument from a rank ordering looked rigorous and was not.

---

27. Theme Q — The panel is the surround

Problem, and it is specific to this mark. Two fills that touch along a
shared boundary change each other's appearance. That is simultaneous
contrast, and the sharpened special case is the crispening effect:
discriminability between two colours of similar lightness is greatest when the
surround lightness lies between them. Neither Part I nor Part II
considers the surround at all, and the taichi has two of them: each fish is the
other's immediate surround along the S-curve, and the panel is the surround for
the whole glyph.

Three consequences, all actionable, none previously noticed.

1. The panel colour is a free parameter nobody has tuned.
theme_taichi() sets plot.background to a rice-paper #f3efe6 and never
touches panel.background, so the fish are drawn on theme_bw()'s white
panel. For a pair of mid-to-dark fills that is close to the worst available
surround; a mid-lightness panel would crispen exactly the comparison the chart
exists to support.

theme_taichi(panel_fill = "auto")
#> sets the panel lightness to the midpoint of the two ramps' luminance
#> trajectory, which is the surround that maximises discriminability
#> between them

taichi_check_palette(...)
#> ... optimal surround lightness for this pair: L* 58 (#8C8C8C)
#> ... current panel is white (L* 100), which flattens the dark half
#>     of both ramps

This is cheap — one line of luminance arithmetic the package already does —
and it is the kind of finding that only shows up if you take the mark's
geometry seriously.

2. Within-cell and across-cell readings diverge, systematically. Because
the two fish are adjacent, a given pair of values reads as more different
inside one glyph than the same two values read across two different glyphs,
where each is surrounded by panel rather than by its partner. So the taichi is
biased towards the "which is bigger here?" task and against "is this
cell's yin the same as that cell's yin?". That is a real, measurable, entirely
package-specific bias, it is consistent with what the design is for, and nobody
has quantified it. It belongs in vignette("design") as a stated limitation
even before it is measured.

3. It gives colour = NA a second, independent justification. Part I
defends the no-outline default on Fuchs et al.'s finding that contours help
shape-similarity judgements but distract from data-similarity ones. Crispening
adds a different reason: an outline between the fish would break the contact
and suppress the mutual contrast that makes the within-cell comparison easier.
Two independent lines of evidence converging on the same default is worth
saying out loud — and it also means explicit_channel = "border", which
introduces an outline, has a perceptual cost the docs do not currently
mention.

Deps none. Effort S (panel fill, check output), L (measuring the bias).
Risk low. Value high for the panel-fill work, which is nearly free.

---

28. Theme R — Nameability

Problem. People talk about these plots out loud. "The red one is Google."
A palette that is perceptually excellent and verbally indistinct — two blues,
say — cannot be discussed, captioned, or described in alt text. Part I and
Part II measure luminance, chroma and CVD distance, and never ask whether a
reader can say which fish they mean.

Heer & Stone (2012), Color Naming Models for Color Selection, Image Editing
and Palette Design (CHI) built a probabilistic model of colour naming from a
large corpus of unconstrained human colour-name judgements, and defined two
metrics from it: saliency (how reliably a colour draws the same name) and
name difference (how far apart two colours are in naming, as opposed to in
colour space).

Features.

taichi_check_palette(...)
#> ... name difference between the two ramps: 0.91 (distinct)
#> ... yin endpoints name as: "white" -> "black"
#> ... yang endpoints name as: "pink" -> "dark red"

Design notes.

• This produces an honest defence of the default palette that the package
  has not been able to offer. 0.3.0's check fails grey-vs-red on luminance
  and says so loudly. But "grey" and "red" are about as nameable and as
  name-distinct as an English-speaking pair can be, and palette = "balanced"
  (blue against brick) is less so. The real situation is a trade-off — the
  default wins on nameability, "balanced" wins on equal visual weight — and
  saying that is better than the current one-sided verdict. It also sharpens
  the 1.0.0 decision (§15 Q2): if the default changes, the package loses
  something measurable, and should pick a replacement that is nameable as well
  as matched.
• It feeds §19 directly. taichi_describe() has to name the colours to
  produce level-1 content ("the upper bulb is shaded grey, the lower red"), and
  Heer & Stone's model is precisely the machinery that turns a hex code into a
  word. The same dependency serves both features, which improves the case for
  taking it.
• Implementation: the model is a lookup table over a quantised colour space,
  distributed with the original paper. It is a data file, not an algorithm.
  Ship it in inst/extdata or take a Suggests dependency if a package wraps
  it. English-only, and the docs must say so.

Deps a bundled lookup table, or Suggests. Effort M. Risk low.
Value medium-high, and it is a dimension no R palette tool currently
reports.

---

29. Theme S — Machine readability

Problem, and it is new since Part I was written. A growing share of chart
reading is done by models rather than people: alt-text generation, "explain
this chart" features, screen-reader pipelines, and document-understanding
systems. If a vision-language model cannot read a taichi grid, then in those
pipelines the chart carries no information at all.

The 2025 evidence says this is a real risk for a bespoke glyph:

• Bendeck & Stasko (2025), Probing the Visualization Literacy of Vision
  Language Models: The Good, the Bad, and the Ugly (IEEE VIS 2025 / TVCG)
  finds VLMs fall short on visual reasoning that is hard to restate as text,
  and that correctness alone hides how badly the internal reasoning goes.
• EncQA (arXiv:2508.04650) benchmarks VLMs systematically across six
  visual encoding channels and eight analytic tasks, and finds performance
  collapsing when a task needs aggregation or judgement rather than counting —
  GPT-4o dropping below 50% on filter-values tasks against near-100% on
  counting.
• ChartMuseum (arXiv:2505.13444) finds model performance degrades sharply
  with visual complexity while human performance stays robust.

A taichi grid is a non-standard mark, outside any training distribution, whose
central task ("which of these two interlocked regions is darker, across a
grid") is exactly the aggregate visual judgement these benchmarks find models
worst at.

Features and consequences.

• This is the strongest argument yet for §19's taichi_describe(). Do not
  hope a model reads the picture; ship the description with the plot. The
  package knows the data and the encoding, and can state both exactly. Where
  Part II justified taichi_describe() on accessibility grounds, this justifies
  it on plain correctness grounds too — and the two motivations want the same
  output.
• Emit the description as machine-readable metadata, not only as prose. A
  girafe widget can carry an aria-label and a <desc>; a saved SVG can
  carry <title> and <desc>; and taichi_summary() is already the tidy
  table a model should be handed instead of a picture. A one-line helper that
  attaches the description to the SVG is a small addition with a clear payoff.
• A cheap self-evaluation the package could actually run. Render a set of
  taichi grids with known ground truth from taichi_summary(), ask a VLM the
  questions the glyph is supposed to answer ("which source is larger in row
  3?", "where is the gap widest?"), and score it. If the package's own mark
  reads badly, that is worth knowing and worth publishing; if it reads well,
  that is a differentiator. Either result is useful, and the harness is a
  scripted afternoon.

Deps none for the description; the evaluation is out-of-band tooling, not
package code. Effort S (metadata), M (evaluation). Risk low.

---

30. Further revisions to existing themes

§3 and §8 — the radius channel is scaled with the wrong exponent

0.3.0 ships explicit_channel = "radius" and scales it by the square root of
the statistic (R/explicit.R: if (channel == "radius") frac <- sqrt(frac)),
on the standard reasoning that the eye reads area, so radius should go as the
square root of the value. Cartography has been here for seventy years and has a
more specific answer.

Flannery (1956; and 1971, The relative effectiveness of some common
graduated point symbols in the presentation of quantitative data) measured
how readers judge the relative size of proportional circles and found they
systematically underestimate the area ratio between large and small ones —
one of the results that Stevens's power law later formalised. The cartographic
fix, apparent-magnitude or Flannery scaling, compensates by using an
exponent of about 0.57 rather than 0.5, making larger symbols slightly
larger than the geometry alone would dictate. It is standard enough to be a
checkbox in GIS software.

geom_taichi(..., explicit_channel = "radius", radius_exponent = 0.57)
#> 0.5   strict area scaling (0.3.0's behaviour)
#> 0.57  Flannery compensation for area underestimation (proposed default)

Two caveats worth documenting rather than glossing:

• Flannery's exponent was measured for whole circles read as magnitudes. A
  taichi at reduced radius is a whole circle, so the case transfers better than
  most — but the quantity encoded here is a gap between two sources, not a
  magnitude, and the reader is also reading two fills inside the circle.
• It interacts with §18: a smaller glyph is also a less colour-discriminable
  glyph, so any exponent that shrinks the low end further has a compounding
  cost. taichi_check_palette(cell_size =) should be evaluated at the smallest
  radius the mapping produces.

Either way, 0.5 is a choice the package made silently and should make
explicitly, with the exponent exposed and the literature cited. This is the
most concrete change in Part III: it touches shipped code.

§21 — Draco gives the linter a formalism, and learned weights

Part II grounded taichi_check() in VizLinter and VisuaLint. The layer beneath
both is Moritz, Wang, Nelson, Lin, Smith, Howe & Heer (2019), Formalizing
Visualization Design Knowledge as Constraints: Actionable and Extensible Models
in Draco (IEEE TVCG 25(1)), which represents design knowledge as hard and
soft constraints in Answer Set Programming — and, the part that matters here,
learns the soft-constraint weights from experimental data instead of
hard-coding them.

ggtaichi's checks are already soft constraints with arbitrary thresholds: 5 L*
units of luminance mismatch, 10 units of CVD distance, "too many cells". Every
one of those numbers is currently a judgement call documented as such. Draco's
contribution is the observation that such weights are estimable, and that a
tool which exposes them is extensible by its users. Even without adopting ASP,
the lesson is concrete: make the thresholds arguments with documented
defaults and a stated provenance, so a user can say "in my field 10 L* is
fine" rather than arguing with the package.

§7 — a fourth axis for the palette check

With Part II's §18 and Part III's §27 and §28, taichi_check_palette() has
four dimensions rather than one:

axis	question	status
luminance match	do equal values read as equal ink?	shipped in 0.3.0
size	at the size the fish are actually drawn?	§18, proposed
surround	on the panel they are actually drawn on?	§27, proposed
nameability	can a reader say which one they mean?	§28, proposed

That is a coherent, four-part definition of "is this pair of ramps fair", and
as far as this survey found, no existing tool in R or elsewhere reports all
four. It is the strongest candidate in the whole document for something the
package could contribute that is genuinely new rather than well-executed.

---

31. Prioritisation delta

Part II's §24 stands. Three changes:

Promoted into Wave 2, because they are nearly free and touch shipped code:

• radius_exponent (§30) — one argument, one citation, corrects a silent
  choice in 0.3.0.
• theme_taichi(panel_fill = "auto") and the surround line in the palette
  check (§27) — luminance arithmetic the package already performs.

Demoted:

• §8 split slips further. Part I ranked it Wave 3 on the strength of
  "area outranks colour"; §26.2 says that argument does not carry the weight
  put on it. It should not ship before the MCDA scoring (§20) and, ideally, not
  before someone measures the mark's own proxies (§17.2).

Unchanged but re-motivated:

• §19 taichi_describe() now has three independent justifications —
  accessibility (Part II §19), colour naming (§28), and machine readability
  (§29). Three motivations pointing at one deliverable is the clearest signal
  in this document about what to build next after seriation.

---

32. Third-pass references

Perception and scaling

• Kay M, Heer J (2016). Beyond Weber's Law: A Second Look at Ranking
  Visualizations of Correlation. IEEE TVCG 22(1): 469–478.
  https://doi.org/10.1109/TVCG.2015.2467671 ·
  https://idl.cs.washington.edu/files/2015-BeyondWebersLaw-InfoVis.pdf
• Flannery JJ (1971). The relative effectiveness of some common graduated
  point symbols in the presentation of quantitative data. Canadian
  Cartographer 8(2): 96–109. (Apparent-magnitude / Flannery scaling; the
  underlying psychophysics is Flannery's 1956 dissertation, later subsumed by
  Stevens's power law.)
• Takasaki H (1966). Lightness change of grays induced by change in reflectance
  of gray background. JOSA 56(4): 504–509. (The crispening effect.)
• Ekroll V, Faul F (2012). Basic Characteristics of Simultaneous Color Contrast
  Revisited. Psychological Science 23(10).
  https://doi.org/10.1177/0956797612443369

Animation

• Robertson G, Fernandez R, Fisher D, Lee B, Stasko J (2008). Effectiveness of
  Animation in Trend Visualization. IEEE TVCG 14(6): 1325–1332.
  https://doi.org/10.1109/TVCG.2008.125 ·
  https://www.cc.gatech.edu/~stasko/papers/infovis08-anim.pdf

Colour naming

• Heer J, Stone M (2012). Color Naming Models for Color Selection, Image
  Editing and Palette Design. CHI 2012.
  https://doi.org/10.1145/2207676.2208547 ·
  http://vis.stanford.edu/papers/color-naming-models

Design knowledge as constraints

• Moritz D, Wang C, Nelson GL, Lin H, Smith AM, Howe B, Heer J (2019).
  Formalizing Visualization Design Knowledge as Constraints: Actionable and
  Extensible Models in Draco. IEEE TVCG 25(1): 438–448.
  https://doi.org/10.1109/TVCG.2018.2865240 ·
  https://idl.cs.washington.edu/files/2019-Draco-InfoVis.pdf

Machine readability

• Bendeck A, Stasko J (2025). Probing the Visualization Literacy of Vision
  Language Models: The Good, the Bad, and the Ugly. IEEE VIS 2025 / IEEE
  TVCG. https://arxiv.org/abs/2504.05445 ·
  https://www.uw-insight-lab.com/assets/papers/TVCG-Probing_Vis_Literacy.pdf
• EncQA: Benchmarking Vision-Language Models on Visual Encodings (2025).
  https://arxiv.org/abs/2508.04650
• ChartMuseum: Testing Visual Reasoning Capabilities of Large Vision-Language
  Models (2025). https://arxiv.org/abs/2505.13444

---

Part IV — The reader is a novice, and the mark means something

Parts I to III treat the taichi as an encoding and ask how accurately it can
be decoded. This pass asks two questions none of them asked: what does the
symbol mean before any data is mapped to it, and what happens the first
time somebody sees one. Both have literatures, both are favourable in one
direction and unfavourable in another, and neither appears anywhere above.

The finding that reframes the mark. ggtaichi's own docs treat the
taichi's cultural recognisability as branding — a nice hex logo, a memorable
name. It is not only branding. Recognisability is a measured advantage
for memorability (§33), and the metaphor that comes with it is a measured
liability for interpretation (§33 again). The package currently collects
the first for free and pays the second without noticing.

---

33. Theme T — Iconicity

33.1 The asset: recognisable objects are remembered

Borkin, Vo, Bylinskii, Isola, Sunkavalli, Oliva & Pfister (2013), What
Makes a Visualization Memorable? (IEEE TVCG 19(12)) scored 2,070
single-panel visualizations for recognition memory and found that colour and
the inclusion of a human-recognisable object enhance memorability.

A taichi grid is a field of human-recognisable objects. On this axis the mark
has an advantage that no bar chart, heatmap or moon chart has, and the document
has never claimed it — Part I's §2.2 quotes Fuchs et al.'s "the simple star
glyph without contours performs best" and treats every departure from
minimalism as a cost.

The claim has to be made carefully, and the paper supports the careful version
only: Borkin et al. measured recognition memory, not comprehension. A
memorable chart is not an accurate one, and the two are separately valuable. So
the honest sentence for vignette("design") is: the taichi is likely to be
remembered better than the equivalent pair of heatmaps, which matters for a
figure meant to be recalled after a talk, and does nothing for how precisely it
can be read. That is worth saying, and it is a genuine differentiator for the
presentation use case that §11's animation work already serves.

33.2 The liability: the metaphor arrives before the data

Ziemkiewicz & Kosara (2008), The Shaping of Information by Visual
Metaphors (IEEE TVCG 14(6)) argues that a visualization's nature lies in the
visual metaphors it uses to structure information, and that comprehension is an
interaction between the external metaphor and the reader's internal one. Their
experiment varied whether the wording of the question matched the metaphor of
the chart (treemap vs node-link) and found that metaphor compatibility
affects accuracy, and that how strongly a reader is affected correlates with
how well they answer. The 2009 follow-up (Computer Graphics Forum) adds that
individual differences and stated metaphor preference modulate the effect.

This is the strongest unexamined risk in the whole document. The taichi is
not a neutral container. It carries an unusually specific and widely known
metaphor: one whole divided into two complementary opposites, in balance,
each containing a seed of the other. Every part of that is a claim about the
data, and ggtaichi maps arbitrary pairs of columns into it.

Three consequences, in increasing order of how much they should change:

1. It explains a misreading the docs already worry about. §2.4 warns that
   moon charts and pie glyphs encode part-to-whole while the taichi encodes two
   independent measurements. Ziemkiewicz & Kosara supply the mechanism for
   why readers will nonetheless assume the two fish sum to something: the
   circle is visibly whole and visibly divided. The warning is currently
   phrased as a positioning note ("here is how we differ from gggibbous"). It
   should be phrased as a reader-error prediction, because that is what it
   is.

2. It gives "when (not) to use taichi" a criterion it lacks. The existing
   caveats are all perceptual — density, luminance, palette fairness, missing
   data. A semantic criterion belongs beside them:

   Use a taichi when the two sources are genuine counterparts — the same
   quantity from two providers, two comparable populations, two arms of a
   trial. Avoid it when the two columns are merely co-measured: the mark
   will assert a relationship of opposition and balance that your data does
   not contain, and readers will act on that assertion.

3. It strengthens the case for shared_limits / shared_legend. If the
   mark asserts commensurability, then the scales had better actually be
   commensurable. Part II §23 already argued shared_legend is the
   perceptually correct default for comparable sources; the metaphor argument
   says something stronger — with unshared scales the glyph makes a claim the
   encoding does not support. That is close to an argument for warning when
   shared_limits = FALSE and the two columns share units.

Deps none. Effort S (docs), S (the optional warning). Risk low.
Value high — it is the kind of thing that, unaddressed, produces a
plausible critical review of the package rather than a bug report.

---

34. Theme U — Onboarding

Problem. Nobody has seen a taichi grid before. That is the package's
selling point and its largest usability cost, and the literature says the cost
is concentrated exactly where the package sits.

Stoiber et al., Visualization Onboarding and Comparative evaluations of
visualization onboarding methods (Visual Informatics, 2022) ran studies with
388, 145 and 63 participants across a bar chart, a horizon graph, a change
matrix and a parallel coordinates plot. The headline: performance improvement
from onboarding is observable for the most unfamiliar idiom — the parallel
coordinates plot — and participants valued easy examples, precise step-by-step
wording, and highlighting of the relevant part.

The taichi is more unfamiliar than a parallel coordinates plot. Onboarding is
therefore not a nicety here; it is where the evidence says the return is
largest, and the package currently offers none inside the plot. The README
explains the anatomy; a figure in a slide deck does not come with the README.

Feature.

annotate_taichi_key(x, y, size = 1,
                    yin_label = NULL, yang_label = NULL)
#> one oversized annotated glyph, placed in the panel or beside it:
#>   - the yin bulb labelled with the yin column's name
#>   - the yang bulb labelled with the yang column's name
#>   - a "darker = more" note tied to the actual scale direction

ggplot(cafes_tg, aes(week, neighbourhood)) +
  geom_taichi(yin = matcha, yang = espresso) +
  annotate_taichi_key(x = 13.5, y = 8)

Design notes.

• It should read the plot, not be configured by hand. The labels, the
  scale direction and the eye semantics are all already known to the layer;
  an onboarding key that has to be told them will drift out of date the first
  time somebody swaps the columns. This wants the same ggplot_add()
  machinery the package already uses.
• Stokes et al. (below) removes the main objection, which would otherwise
  be "that is clutter".
• Interacts well with §27: the key glyph should be drawn on the same panel
  fill as the data glyphs, or it will teach the wrong colour appearance.
• The natural companion is a static image in the docs, but the point is that
  it travels with the figure.

Deps none. Effort M. Risk low. Value high, and it is the single
most direct answer to "this is a strange chart and I do not know how to read
it".

---

35. Theme V — Attention limits

Haroz & Whitney (2012), How Capacity Limits of Attention Influence
Information Visualization Effectiveness (IEEE TVCG 18(12); VisWeek 2012 best
paper) tested how feature type, layout, and the number of feature
varieties (bins) affect whether a viewer can find information they were not
looking for. Two results bear directly on this package:

1. Finding a unique colour was much easier in grouped displays than in
   ungrouped ones.
2. Effectiveness is strongly modulated by the number of distinct feature
   bins — attention's capacity limits, not the display's resolution, are the
   binding constraint.

What this changes.

• Seriation (§22) gets a second, independent justification. Part I and
  Part II justify reordering as revealing structure — blocks become visible.
  Haroz & Whitney give a different and arguably more practical reason:
  grouping makes the outlier findable. On a taichi grid the cell where the
  two sources disagree most is exactly the "unexpected information" a reader is
  not explicitly searching for, and an unseriated grid hides it. Two unrelated
  literatures converging on the same feature is the strongest signal in this
  document for building it next.
• It puts a ceiling on discrete fills. scale_taichi_yin_d() will happily
  interpolate a ramp to twelve levels. The attention literature says the useful
  number of feature bins is small, and this glyph asks the reader to hold two
  such sets at once. A documented recommendation — and possibly a message above
  some level count — is cheap and well founded.
• It also supports §5's binning recommendation from a third direction: bins are
  not merely easier to read off a legend (§5), and not merely more robust at
  small mark sizes (§18); they are fewer feature varieties, which is what
  attention can actually handle.

Deps none. Effort S (docs, level-count message). Risk low.

---

36. Revisions from the fourth pass

§19 — taichi_describe() should place text, not just emit it

Part II specified taichi_describe() as an alt-text generator, structured by
Lundgard & Satyanarayan's four semantic levels. Stokes, Setlur, Cogley,
Satyanarayan & Hearst (2022), Striking a Balance: Reader Takeaways and
Preferences when Integrating Text and Charts (IEEE VIS) extends that
usefully. With 302 participants ranking charts carrying from no text to a
paragraph, they found:

• Heavily annotated charts were not penalised — participants preferred
  the most-annotated charts to sparser ones, and to text alone.
• Semantic level determines the takeaway: text describing statistical or
  relational content produces statistical and relational takeaways; text
  describing the encoding produces takeaways about the encoding.
• Placement interacts with level — some content belongs in the title,
  other content belongs next to the data.

[PursuitOfDataScience]

So the same generator that produces alt text should be able to place its output
on the plot, with the level choosing the slot:

taichi_describe(p, level = 2, as = "subtitle")   # "Espresso leads in 71 of 96 cells"
taichi_describe(p, level = 1, as = "caption")    # what the bulbs and shading mean
taichi_describe(p, level = 1:3, as = "alt")      # the accessibility string

That also resolves a tension Part II left open: the reason to stop at level 3
(readers want to interpret for themselves) applies to descriptions for
non-sighted readers; Stokes et al. show sighted readers happily take
level-2 and level-3 annotations on the chart. Same content, different slot,
both well evidenced.

§5 — the objection to on-glyph labels was weaker than assumed

Part I hedged labels heavily: refuse above some cell count, warn, worry about
overlap. The overlap concern is real and geometric. The aesthetic concern —
that annotation is clutter — is contradicted by Stokes et al. Label generously
where the geometry allows it.

§13 — the comparison table needs a semantic row

Per §33.2, the table comparing the taichi to gggibbous, scatterpie,
biscale and small multiples should carry a row that is not about accuracy at
all: what relationship does the mark assert? Moon charts assert
part-to-whole. Bivariate choropleths assert a joint value. The taichi asserts
complementary opposition. Readers act on those assertions whether or not the
data supports them.

---

37. Prioritisation delta (IV)

Promoted:

• §22 seriation moves to unambiguously first in Wave 2. It now has two
  independent justifications (structure revelation; outlier findability under
  attention limits) plus a ready implementation (seriation) plus a
  package-specific twist (on = "difference"). Nothing else in this document
  has that much converging support.
• §34 annotate_taichi_key() enters Wave 2. Cheap, no dependency, and it
  targets the package's largest practical barrier with the literature's
  strongest onboarding result.

Re-scoped:

• §19 taichi_describe() grows an as = argument for placement. Its
  motivation count is now four: accessibility, colour naming, machine
  readability, and on-chart annotation.

Docs-only, do at the next docs pass:

• The semantic criterion in "when (not) to use taichi" (§33.2) — arguably the
  highest value-per-line change in Part IV.
• The memorability claim, stated carefully (§33.1).
• A discrete-level ceiling recommendation (§35).

---

38. Fourth-pass references

Iconicity and metaphor

• Borkin MA, Vo AA, Bylinskii Z, Isola P, Sunkavalli S, Oliva A, Pfister H
  (2013). What Makes a Visualization Memorable? IEEE TVCG 19(12):
  2306–2315. https://doi.org/10.1109/TVCG.2013.234 ·
  http://olivalab.mit.edu/Papers/Borkin_etal_MemorableVisualization_TVCG2013.pdf
• Ziemkiewicz C, Kosara R (2008). The Shaping of Information by Visual
  Metaphors. IEEE TVCG 14(6): 1269–1276.
  https://doi.org/10.1109/TVCG.2008.171 ·
  https://media.eagereyes.org/papers/2008/Ziemkiewicz-InfoVis-2008.pdf
• Ziemkiewicz C, Kosara R (2009). Preconceptions and Individual Differences in
  Understanding Visual Metaphors. Computer Graphics Forum 28(3): 911–918.
  https://doi.org/10.1111/j.1467-8659.2009.01442.x

Onboarding and literacy

• Stoiber C, Grassinger F, Pohl M, Stitz H, Streit M, Aigner W (2019).
  Visualization Onboarding: Learning How to Read and Use Visualizations.
  https://doi.org/10.31219/osf.io/c38ab
• Stoiber C, et al. (2022). Comparative evaluations of visualization onboarding
  methods. Visual Informatics 6(4).
  https://doi.org/10.1016/j.visinf.2022.07.001 ·
  https://arxiv.org/pdf/2203.15418

Attention

• Haroz S, Whitney D (2012). How Capacity Limits of Attention Influence
  Information Visualization Effectiveness. IEEE TVCG 18(12): 2402–2410.
  https://doi.org/10.1109/TVCG.2012.233 ·
  http://steveharoz.com/research/attention/papers/Haroz_Whitney_2012_InfoVis.pdf

Text with charts

• Stokes C, Setlur V, Cogley B, Satyanarayan A, Hearst MA (2022). Striking a
  Balance: Reader Takeaways and Preferences when Integrating Text and Charts.
  IEEE VIS / TVCG. https://arxiv.org/abs/2208.01780 ·
  https://vis.csail.mit.edu/pubs/vis-text-balance.pdf

---

Part V — Is the pattern real, and is the API usable

Four passes have asked whether the mark can be decoded (I), measured (II),
corrected (III), and understood by a novice (IV). Two questions remain that
none of them touch. First: when a reader sees a block of dark cells, is that
block real, or is it noise the eye assembled into a shape? Second: the
document's single most consequential open question is about argument design,
and it has been argued entirely from idiom — there is an empirical literature on
API usability, and it does not say quite what §15 assumes.

---

39. Theme W — Visual inference

Problem, and this document created it. Part II §17.3 established, with
citation, that a dense taichi grid is read as texture — the viewer extracts
ensemble statistics rather than reading cells. Part I's §2.2 says the same
thing informally, and the README and vignette both say it to users. Texture is
precisely where apophenia lives: the visual system is extremely good at
assembling noise into blocks, bands and diagonals, and a grid of 1,116 glyphs
gives it a great deal to work with.

So the package tells its users, in three places, that past a certain density
they are reading a field — and then offers them no way whatever to ask whether
the field is real. That is an obligation the docs have taken on and not
discharged.

The method exists, it is well validated, and it comes from this ecosystem.

• Buja, Cook, Hofmann, Lawrence, Lee, Swayne & Wickham (2009), Statistical
  inference for exploratory data analysis and model diagnostics (Phil. Trans.
  R. Soc. A 367) sets out the framework.
• Wickham, Cook, Hofmann & Buja (2010), Graphical Inference for Infovis
  (IEEE TVCG 16(6)) gives the two protocols. The line-up hides the real
  plot among plots of null data; if an observer picks it out, the structure is
  distinguishable from the null. The Rorschach shows only null plots, to
  calibrate how much structure an analyst hallucinates in noise.
• Majumder, Hofmann & Cook (2013), Validation of Visual Statistical
  Inference, Applied to Linear Models (JASA 108(503): 942–956) validates it
  against conventional tests and formalises the visual p-value from a
  binomial model over multiple observers.
• nullabor is on CRAN, provides lineup(), rorschach(),
  null_permute(), null_dist() and null_lm(), and is designed to be
  faceted with ggplot2.

Features.

taichi_lineup(data, x, y, yin, yang, n = 20, method = "permute_pairing")
#> returns a lineup-shaped data frame; facet it and draw with geom_taichi()

taichi_rorschach(data, x, y, yin, yang, n = 20)
#> all null. Look at it before you look at your data.

decrypt("...")   # nullabor's answer key

Design notes.

• The null has to be chosen per question, and the taichi's own question needs
  a null that nullabor does not ship. This is the package-specific
  contribution and it is worth getting right:

  question	null
  is there any structure in yin at all?	permute yin across cells
  is the pattern in yin real?	permute yin within rows, or within columns
  is the yin-yang relationship real?	permute the pairing — keep both marginal fields intact and shuffle which yang goes with which yin

  The third is the one a taichi grid is actually asking, and it is not
  null_permute() on either column: it holds both fields' own structure fixed
  and destroys only their correspondence. A reader who can still pick the real
  plot out of that lineup has seen a real relationship between the two sources.
  Nothing else in the ecosystem offers that null, because nothing else
  superposes two fields in one mark.

• It composes with the rest of the roadmap rather than competing. §3's
  explicit channel makes the difference field visible; a lineup says whether
  that field is distinguishable from noise. §22's seriation makes structure
  findable; a Rorschach on seriated null data is the honest check that seriation
  is not manufacturing the blocks it claims to reveal — which is a real hazard,
  since reordering optimises an objective and will happily find blocks in noise.
  That last point is important enough to state in the seriation docs.

• Cost is low. Suggests: nullabor, one data verb, one docs section, and
  the drawing is facet_wrap() over the existing geom. The intellectual work is
  the pairing null, which is a dozen lines.

• Honest caveat for the docs: a visual p-value needs multiple independent
  observers to be a p-value. A single analyst running a lineup on their own
  screen gets a useful sanity check, not a test, and the docs should say which
  is which rather than implying inference the workflow cannot deliver.

Deps Suggests: nullabor. Effort M. Risk low. Value high —
and unusually well matched to this package, because the design's own documented
weakness is exactly the failure mode the protocol was invented to catch.

---

40. Theme X — API usability

§15 Q1 is called "the most consequential API decision in the document." It
observes that geom_taichi() takes around thirty arguments and proposes option
objects — taichi_eyes(...), taichi_scales(...), taichi_uncertainty(...) —
passed as single arguments, on the model of theme() and element_*(). The
whole argument is from idiom: this is what the tidyverse does.

There is an empirical literature on API usability, and it complicates that.

• Ellis, Stylos & Myers (2007), The Factory Pattern in API Design: A
  Usability Evaluation (ICSE) found that creating objects through factories
  takes programmers significantly longer than through direct constructors
  (p = 0.005), regardless of context or experience level. An option object
  is a factory in this sense: the user must discover, name and call a second
  function before they can express what they wanted.
• Stylos & Clarke's constructor work, summarised in the same line of
  research, found programmers were more effective with APIs that did not
  require constructor parameters, because required parameters interfere with
  common learning strategies and force premature commitment — the user must
  decide something before they know enough to decide it.
• Myers & Stylos (2016), Improving API usability (CACM 59(6)) collects the
  practical guidance.

What this changes, and what it does not.

It does not kill the option-object plan. theme()/element_text() is a
pattern ggplot2 users already know, and familiarity is itself a usability
property that a general study of Java factories does not measure. But it
converts the plan from "the idiomatic fix, therefore correct" into "a fix with
a documented cost that must be paid down deliberately":

1. Keep the flat arguments working, permanently, not as a deprecated path.
   Part I already proposes "flat arguments as a deprecated-but-working path".
   The evidence argues for something stronger: geom_taichi(eyes = TRUE, yin_eye_size = 0.2) should stay a first-class way to say a simple thing,
   because the factory route costs measurable time for exactly the casual use
   that flat arguments serve well. Grouping should buy something for the
   complex case without taxing the simple one.
2. Group only what is genuinely a cluster. Nine eye arguments are a
   cluster. interactive, tooltip, data_id, onclick, data_id_by are a
   cluster. palette and explicit are not — they are single decisions and
   should stay single arguments.
3. Resist adding required parameters. yin and yang are required and
   should be: they are the entire point of the mark, and a user who does not
   know them has nothing to plot. Nothing else should join them.
4. Discoverability beats brevity. The measured problem with factories is
   finding them. Whatever ships, ?geom_taichi must name the option
   constructors in the argument's own description, and the constructors must be
   in the pkgdown reference index under a heading a reader will scan.

One existing wart the literature names. geom_taichi()'s ... goes to the
scales, not to the layer — documented at length, and a genuine violation of
where an experienced ggplot2 user expects ... to go. The API literature's
term for this is a violated expectation, and its cost is paid on every first
use. It is probably too late to change without breaking code, but it belongs in
the Q1 discussion as evidence for the general principle: this API's problems
are about where things go, not how many things there are, and an option-object
refactor that does not fix the ... surprise fixes the less important half.

Deps none. Effort — this is a decision, not a feature. Value high,
because it is the decision Part I says gates Wave 3.

---

41. Revisions from the fifth pass

§9 — taichi_check() should be able to say "and it might be noise"

Part II §21 shaped taichi_check() as a linter-and-fixer over data-shape and
palette problems. §39 adds a check of a different kind, and the fixer line
writes itself:

! 1,116 cells: at this density the grid reads as texture, and texture is
    where the eye invents structure
    fix: taichi_rorschach() to calibrate, taichi_lineup() to test

§22 — seriation needs the Rorschach as a guard, not just a merit score

Part II proposed reporting the merit gain from reordering, so a 2% improvement
is not sold as a discovery. §39 supplies the sharper guard: reordering
optimises an objective, so it will find blocks in pure noise, and the merit
gain alone cannot distinguish the two. A Rorschach over seriated null data is
the check. This should be a paragraph in the seriation docs from the start
rather than a later correction.

§17.3 — the texture argument now has an ending

Part II reframed dense grids from "hard to read, apologise" to "read as an
ensemble, here is what that supports". The honest completion is: and here is
how to check the ensemble is real. Ensemble perception and visual inference
are two halves of one story, and the vignette should tell both.

§15 Q1 — restated

The question is no longer "should we group the arguments?" but "what does
grouping cost, and what must stay ungrouped to keep the simple case cheap?"
See §40. The proposal that survives the evidence is: group the eye cluster and
the interactivity cluster, keep everything else flat, keep flat forms working
indefinitely rather than deprecating them, and fix discoverability in the docs
at the same time.

---

42. Prioritisation delta (V)

New, and it slots into Wave 2 rather than later:

• §39 taichi_lineup() / taichi_rorschach(). One Suggests, one verb, and
  it discharges an obligation the docs already took on. It also pairs with
  seriation, which is already Wave 2's first item — build them together and the
  seriation docs get their guard for free.

Changed, not added:

• §15 Q1 is now answerable rather than open. It still gates Wave 3, but the
  shape of the answer is settled: partial grouping, no deprecation of the flat
  path, discoverability fixed in docs. That is a smaller and safer change than
  Part I envisaged, which is a good outcome for a question labelled "most
  consequential".

Unchanged: everything else.

---

43. Fifth-pass references

Visual inference

• Buja A, Cook D, Hofmann H, Lawrence M, Lee E-K, Swayne DF, Wickham H (2009).
  Statistical inference for exploratory data analysis and model diagnostics.
  Philosophical Transactions of the Royal Society A 367(1906): 4361–4383.
  https://doi.org/10.1098/rsta.2009.0120
• Wickham H, Cook D, Hofmann H, Buja A (2010). Graphical Inference for Infovis.
  IEEE TVCG 16(6): 973–979. https://doi.org/10.1109/TVCG.2010.161 ·
  https://vita.had.co.nz/papers/inference-infovis.html
• Majumder M, Hofmann H, Cook D (2013). Validation of Visual Statistical
  Inference, Applied to Linear Models. JASA 108(503): 942–956.
  https://doi.org/10.1080/01621459.2013.808157
• nullabor — lineup and Rorschach protocols for R, with several null
  generators: https://cran.r-project.org/package=nullabor

API usability

• Ellis B, Stylos J, Myers B (2007). The Factory Pattern in API Design: A
  Usability Evaluation. ICSE 2007: 302–312.
  https://doi.org/10.1109/ICSE.2007.85 ·
  https://www.cs.cmu.edu/~marmalade/papers/Ellis2007FactoryUsability.pdf
• Myers BA, Stylos J (2016). Improving API usability. Communications of the
  ACM 59(6): 62–69. https://doi.org/10.1145/2896587
• Stylos J, Myers B. Mapping the Space of API Design Decisions. VL/HCC.
  http://www.cs.cmu.edu/~NatProg/apiusability.html

---

Part VI — Transitions, and what the colours say

Two things prompted this pass, and only one of them was a search. While
building animated examples for the README it emerged that the package's
animations had never worked — gganimate's frame encoding lives in the group
column and the geom was overwriting it, so every transition since the first
release rendered a single frame. Fixing that turned a theoretical section (§11)
into a live one, and made a literature that Parts I–V never consulted suddenly
relevant: how do you design an animated transition that actually helps? §44
answers that. §45 is a straight gap — the document has measured the two
palettes four ways and never once asked what the colours mean.

---

44. Theme Y — Designing the transitions

Context. §11 has always been the thinnest theme in the document: "the
gganimate spike succeeded and the animation vignette shipped, so this theme is
mostly small additions." It now turns out the spike did not succeed. The
vignette built gganim objects and left every animate() call commented out
for CI, so no frame was ever rendered, and the geom silently collapsed every
transition. That is fixed, and §11 needs rewriting from "export formats and
recipes" to "what makes an animated transition good".

Heer & Robertson (2007), Animated Transitions in Statistical Data Graphics
(IEEE TVCG 13(6)) is the reference the document should have had all along.
It extends the model of statistical graphics to cover transitions, gives a
taxonomy of transition types, proposes design principles, and — the part
that matters — runs two controlled experiments finding that animated
transitions significantly improve graphical perception. Its central design
principles are:

• Staging. Decompose a complex transition into stages and do one kind of
  change at a time. Their worked example moves points to their new
  x-coordinates and updates the x-axis in one stage, then morphs points into
  bars in a second.
• Congruence. The animation's structure should mirror the semantic
  structure of the change, so the motion means what the data change means.
• Avoid simultaneous unrelated changes, which is where tracking breaks down.

Why this is pointed for a taichi. A taichi glyph has more simultaneously
tweenable channels than almost any mark in the ecosystem: two fills, an angle,
two eye sizes, a radius and a border. transition_states() tweens all of
them at once. That is precisely the design Heer & Robertson advise against,
and the more channels a package offers the worse it gets — so the channel work
of §3 and §8 quietly makes the animation problem harder.

Features.

taichi_stage(p, order = c("fill", "eye_size", "angle"))
#> splits one transition into consecutive staged transitions, so the fills
#> settle before the glyphs turn

# and the diagnostic, because the failure is silent
taichi_check_animation(p)
#> ! this transition changes fill, angle and eye_size simultaneously
#>     Heer & Robertson (2007): stage them. See taichi_stage().
#> ! 1 frame will be rendered -- transition variable has 1 level

Design notes.

• The frame-count check is not hypothetical. The bug that motivated this
  section produced exactly one frame and reported nothing. A check that says
  "this will render 1 frame" would have caught it in 2024. Cheap, and it
  belongs in taichi_check() (§21) rather than as its own function.

• The package's own examples should follow the principles. Of the three
  animations now in the README, the two that change only fills (and eye size,
  which is derived from the fills) are congruent and single-staged by accident.
  A "spin while the data changes" demo would violate staging, and the docs
  should say why it is not offered rather than leaving it as an obvious gap.

• Staging composes with explicit. The natural two-stage taichi transition
  is: first let the two fills move to their new values, then let the explicit
  channel (eye, tilt) resolve. That is congruent — the relationship updates
  after the things it is a relationship between — and it is a genuinely
  novel, mark-specific application of the principle.

• Revisit the Robertson 2008 correction (§26.1) in this light. Three
  results now resolve cleanly rather than tensely:

  	animation helps?
  Heer & Robertson 2007 — transition between two states, staged	yes, measurably
  Ondov et al. 2019 — transition between two states, comparison task	yes
  Robertson et al. 2008 — long trend, many frames, analysis	no; use small multiples

  The rule that falls out: animate a change, not a history. Two states,
  staged, for comparison — good. Twelve weeks scrolling past for analysis —
  present it, don't analyse it. That is a sentence the animations vignette can
  actually lead with.

Deps none. Effort S (frame-count check), M (taichi_stage()).
Risk low. Value high, and overdue: this theme was assumed done for two
releases while being entirely broken.

---

45. Theme Z — Valence

The gap. By the end of Part V the palette check has four axes — luminance
match, mark size, surround, nameability. All four ask can the reader
discriminate the two ramps. None asks what the two colours say. For a mark
this culturally loaded, that is a conspicuous omission.

The default palette is asymmetric in affect, not just in luminance.
Adams & Osgood (1973), A Cross-Cultural Study of the Affective Meanings of
Color (Journal of Cross-Cultural Psychology 4(2)) measured colour affect
across 23 cultures with semantic differentials and found substantial
cross-cultural agreement: red is affectively salient and strong; black and
grey are evaluated negatively; white, blue and green positively; yellow, white
and grey are weak.

Map that onto yin_colors = grey100 → grey0 and yang_colors = pale pink → seal red and the default pair says, before any data is mapped:

• yin — grey to black — reads bad and weak
• yang — red — reads strong and salient

That is a second, independent editorial thumb on the scale, on top of the
41 L* luminance mismatch the package already measures and reports. A reader
comparing two candidates, two treatments or two vendors gets told which one is
the strong one by the palette.

And it is culture-dependent in a way this mark cannot ignore. The taichi is
Chinese, and in Chinese usage red is auspicious — luck and prosperity — while
white is the colour of mourning. So the default's affective asymmetry does not
merely exist; it points in different directions for different readers. A
package that borrows a Chinese cosmological symbol and then paints it with
Western colour affect should at least know it is doing so.

The other edge: semantics measurably help. Lin, Fortuna, Kulkarni, Stone
& Heer (2013), Selecting Semantically-Resonant Colors for Data Visualization
(Computer Graphics Forum / EuroVis; Best Paper) shows that colours which
resonate with what they represent improve speed on chart-reading tasks
against a standard palette, and gives an algorithm that recovers most of the
expert-chosen gain automatically.

This gives the default palette its third independent defence, after
nameability (§28): ink-black and cinnabar seal-red are exactly the colours of
the object the mark depicts. Grey-and-red is semantically resonant with the
taichi itself. The luminance check penalises it, the nameability axis rewards
it, and the resonance argument rewards it again. That is a genuinely interesting
result for the 1.0.0 default-palette decision (§15 Q2) and it was invisible
until this pass.

Features.

• Document valence; do not pretend to measure it. There is no defensible
  automatic valence score, and a package that emitted one would be overclaiming.
  What belongs in the docs is a short, sourced paragraph in
  vignette("design") and a line in "when (not) to use taichi": if your two
  sources are contested — candidates, treatments, providers — a palette that is
  asymmetric in affect editorialises. Prefer shared_legend = TRUE.
• This is the fourth independent argument for shared_legend. One ramp
  cannot be affectively asymmetric between the two sources, because there is
  only one. Perceptual correctness (§7), metaphor congruence (§33.2), the
  no-pairing-to-get-wrong argument (Part II §23), and now valence neutrality all
  point at the same default.
• A palette = "neutral" preset is worth considering: two hues chosen to be
  close in affect as well as matched in luminance — two blues of different hue
  angle, say, or blue against teal. Lower discriminability, no editorial lean.
  For contested comparisons that is the right trade, and no other package
  offers it.
• Any future preset work should note that semantic resonance is
  domain-specific: espresso-brown against matcha-green would beat both the
  default and "balanced" for the bundled cafes_tg example, per Lin et al.
  A taichi_palette_semantic(terms = c("espresso", "matcha")) is a real
  possibility, though it needs an image corpus and is Wave 4 at best.

Deps none for the documentation. Effort S (docs), S ("neutral").
Risk low. Value medium-high — mostly for what it says about the 1.0.0
palette decision, which now has arguments on both sides rather than one.

---

46. Revisions from the sixth pass

§11 — rewrite the theme, and the vignette's opening claim

§11 currently reads as a list of export formats. It should lead with §44's
rule — animate a change, not a history — and the staging principle, and the
export recipes should follow as detail. The animations vignette's framing
("the taichi is a cyclical symbol, so motion suits it") is an aesthetic
argument standing where an evidence-based one now exists.

§12.7 — a testing lesson, from an incident rather than a paper

I looked for an empirical study of documentation code that never executes and
did not find one worth citing, so this is recorded as what it is: an incident,
not a literature finding.

The animation bug survived three releases because the only thing exercising
the feature was a vignette whose animate() calls were commented out. The
vignette built the gganim object, which succeeds whether or not the
transition works, and the comment was added for a good reason — no gifski on
CI. The general shape is worth stating as a rule:

If a feature is only demonstrated in documentation, and the demonstration
is eval = FALSE or commented out, the feature is untested. A guard that
makes a vignette CI-safe also makes it evidence-free. Anything guarded that
way needs a test that reaches the same code by a path with no system
dependencies.

For this package that meant gganimate::file_renderer(), which writes PNG
frames and needs no gifski, no ffmpeg and no ImageMagick — so the frame count
is now asserted wherever gganimate is installed. The same reasoning applies to
the other Suggests-gated demonstrations: the ggiraph path is tested at the grob
level rather than through girafe(), which is right, and any future sf map
work (§6) should be tested against a synthetic fixture rather than only shown
in an eval-guarded vignette.

§7 — a fifth consideration, and it is not a metric

The palette check has four measurable axes (§30). Valence is a fifth
consideration that should be documented and deliberately not scored. Worth
being explicit about the distinction in the help page, so the absence reads as
a decision rather than an oversight.

§15 Q2 — the default-palette decision is now genuinely balanced

Part I framed Q2 as "the defaults are unfair, change them at 1.0.0". Three
passes later the picture is:

against the default	for the default
41 L* luminance mismatch (§7)	maximally nameable (§28)
protanopia halves its separation (§7)	semantically resonant with the mark (§45)
affectively asymmetric (§45)	every existing figure depends on it

That is not a one-sided case any more, and the honest resolution may well be to
keep the default and make "balanced" prominent, rather than to flip at
1.0.0. Worth restating the question that way rather than treating the flip as
scheduled.

---

47. Prioritisation delta (VI)

Into Wave 2, both small and both prompted by a real failure:

• A frame-count check in taichi_check() (§44). Would have caught a
  three-release bug. Hours of work.
• The valence and staging paragraphs in vignette("design") and the
  animations vignette (§45, §44). Docs only.

Into Wave 3:

• taichi_stage() (§44) — genuinely useful, but it wants the argument
  question (§40) settled first, since it adds another cross-cutting option.
• palette = "neutral" (§45).

Reframed:

• §11 is no longer "mostly small additions". It was assumed complete while
  being broken, and now needs both the design principles and the tests.
• §15 Q2 is a live question with evidence on both sides, not a scheduled
  change.

---

48. Sixth-pass references

Animated transitions

• Heer J, Robertson GG (2007). Animated Transitions in Statistical Data
  Graphics. IEEE TVCG 13(6): 1240–1247.
  https://doi.org/10.1109/TVCG.2007.70539 ·
  https://idl.cs.washington.edu/files/2007-AnimatedTransitions-InfoVis.pdf

Colour meaning

• Adams FM, Osgood CE (1973). A Cross-Cultural Study of the Affective Meanings
  of Color. Journal of Cross-Cultural Psychology 4(2): 135–156.
  https://doi.org/10.1177/002202217300400201
• Lin S, Fortuna J, Kulkarni C, Stone M, Heer J (2013). Selecting
  Semantically-Resonant Colors for Data Visualization. Computer Graphics
  Forum (Proc. EuroVis) 32(3): 401–410.
  https://doi.org/10.1111/cgf.12127 ·
  https://idl.cs.washington.edu/files/2013-SemanticColor-EuroVis.pdf
• Setlur V, Stone MC (2016). A Linguistic Approach to Categorical Color
  Assignment for Data Visualization. IEEE TVCG 22(1): 698–707.
  https://doi.org/10.1109/TVCG.2015.2467471

---

Part VII — Agreement

One theme, because only one thing in this pass was worth the space. It is not
an addition: it is a critique of §3, the theme this document calls its
structural centrepiece, from a literature that has been the standard answer to
ggtaichi's exact question since 1986 and that Parts I–VI never opened.

---

49. Theme AA — Agreement

The setting is literally the package's own. ggtaichi exists to compare two
sources measuring the same thing. shared_legend is documented as the option
for "directly comparable sources"; cafes_tg was built specifically because
its two columns share units; §3 computes the difference between them. In
statistics that is method comparison, and it has a canonical answer.

Bland & Altman (1986), Statistical methods for assessing agreement between
two methods of clinical measurement (The Lancet 327: 307–310) — among the
most-cited papers ever written — makes one central point: when you compare two
measurements of the same quantity, plot the difference against the mean of
the two, because the discrepancy between methods is very often proportional
to the magnitude being measured, and that proportional bias is invisible in
any display that does not put the difference against the mean. Correlation and
scatter against the line of equality both hide it: two methods can correlate at
r = 1.0 and still disagree by an amount that grows with the value.

Now look at what this package computes. taichi_summary() returns yin,
yang, difference, ratio, log_ratio, z, dominant and rank. It does
not return the mean of the two sources — the single covariate Bland &
Altman say the difference must be examined against. And the glyph has the same
blind spot structurally:

A taichi grid plots the difference between two sources against position in
the grid. It never plots it against magnitude. geom_taichi_diff()
inherits the blind spot exactly — it is a diverging heatmap of the difference
over x and y. So if the two sources disagree more where the values are
large, which is the normal case in real measurement, a taichi grid will show
you where without ever showing you that.

That is a genuine limitation of the design, it is not currently documented
anywhere, and it sits directly under the theme Part I calls "the single
clearest structural gap" the package had closed.

The package already has half the answer, by accident. Bland & Altman's own
remedy when the difference scales with the mean is to log-transform and work
with the ratio. explicit = "log_ratio" does exactly that, and §3 justifies
it only as "symmetric around zero, and the right choice when the two sources
span orders of magnitude". The deeper reason — that a multiplicative difference
is the signature of proportional bias, and logging is how you make it additive
and readable — is the better sentence, and it is free.

Features.

taichi_summary(data, yin, yang, x, y)
#> ... gains `mean` -- the Bland-Altman covariate, (yin + yang) / 2

taichi_agreement(data, yin, yang)
#> bias (mean difference)                 -8.4
#> limits of agreement (95%)      -19.2 to  2.4
#> proportional bias (diff ~ mean)   r = 0.71  ** the difference grows
#>                                              with the magnitude
#> concordance correlation (Lin)          0.42

geom_taichi_ba(yin, yang)
#> the Bland-Altman companion: difference against mean, with bias and
#> limits of agreement drawn in -- the same "sometimes the glyph is not
#> the right chart" escape hatch as geom_taichi_diff()

Design notes.

• geom_taichi_ba() is the right shape for this package. §3 already
  established the pattern: when the question is one the glyph cannot answer,
  ship the chart that can rather than insisting on the mark. geom_taichi_diff()
  did that for "how much bigger?"; this does it for "do these two agree, and
  does the disagreement depend on the level?". The two together turn the taichi
  into the overview of a method comparison with the proper analysis one call
  away.

• The proportional-bias check is the highest-value part and the cheapest.
  A correlation between the difference and the mean is three lines of
  arithmetic, and a warning when it is substantial would tell the user
  something the glyph physically cannot:

  ! the difference between matcha and espresso grows with their mean
      (r = 0.71). A taichi grid shows the difference against position,
      not against magnitude, so this will not be visible in the glyphs.
      fix: explicit = "log_ratio", or geom_taichi_ba()
  

  That belongs in taichi_check() (§21) and it follows the linter-and-fixer
  shape Part II established.

• Lin (1989)'s concordance correlation coefficient is the one-number
  summary of agreement, combining precision and accuracy as distance from the
  45-degree line, and is the standard companion to the limits of agreement. It
  is arithmetic; DescTools::CCC() and epiR::epi.ccc() exist if a reference
  implementation is wanted, and blandr, BlandAltmanLeh and SimplyAgree are
  on CRAN for the plots. No dependency is needed — bias, limits of
  agreement and the CCC are all closed-form — and taking one would be worse
  than computing them, because the point is to have the numbers next to
  taichi_summary(), not in a different package's idiom.

• Scope it honestly. All of this applies only when the two sources measure
  the same quantity in the same units. When they do not — Google searches
  against tweets, say — the mean of the two is meaningless and so is the bias.
  So the feature should be offered rather than assumed, and the natural
  gate already exists: it is exactly the case shared_limits /
  shared_legend is for. taichi_check() could reasonably suggest an
  agreement analysis when shared_legend = TRUE and stay quiet otherwise.

• It sharpens §39's null, too. Part V proposed permuting the pairing
  between yin and yang to test whether their relationship is real. Agreement
  analysis asks a neighbouring question with a closed form: not "is the
  correspondence distinguishable from noise" but "how far apart are they, and
  does the gap depend on the level". Offering both, and saying which answers
  which, would be unusually complete for a plotting package.

Deps none. Effort S (mean, the check), M (taichi_agreement(),
geom_taichi_ba()). Risk low. Value high — it closes a documented
blind spot in the package's central feature, and it connects ggtaichi to the
standard vocabulary of the field its users are most likely to come from.

---

50. Revisions from the seventh pass

§3 — the statistic menu is missing its covariate

explicit offers four statistics of the relationship and the summary returns
five columns, and none of them is the mean. Add it. The change is one column in
taichi_summary() and it is what makes every downstream agreement statistic
possible.

§9 / §21 — a third class of check

taichi_check() currently has data-shape checks (duplicate cells, missing
combinations), presentation checks (palette fairness, cell count) and, after
Part V, an inference check. Proportional bias is a fourth kind: a property of
the data that the mark cannot show. That framing is worth stating in the
function's docs, because "things this chart structurally cannot tell you" is a
genuinely useful category and most packages never offer it.

§13 — one more row for the comparison table

Alongside "what relationship does the mark assert?" (§36), the table wants
"what question is this for?". For a taichi the answer is where do two sources
differ across a grid; for a Bland-Altman plot it is do two sources agree, and
does the disagreement depend on the level. They are complements, not rivals,
and a user doing method comparison should be told to make both.

§11 — no change, but a note

Part VI's rule was "animate a change, not a history". Agreement analysis is the
clearest example of a question that animation cannot help with at all: bias and
limits of agreement are properties of the whole dataset, not of any frame.

---

51. Prioritisation delta (VII)

Into Wave 2, both cheap:

• mean in taichi_summary() — one column.
• The proportional-bias check in taichi_check() — three lines of
  arithmetic and a message, and it reports something the glyph cannot.

Into Wave 3:

• taichi_agreement() and geom_taichi_ba() — the full companion.
  They belong after taichi_check() exists, since the check is what will make
  people want them.

Documentation, next docs pass:

• The blind-spot paragraph: a taichi grid shows the difference against
  position, never against magnitude.
• The better justification for explicit = "log_ratio".

---

52. Seventh-pass references

• Bland JM, Altman DG (1986). Statistical methods for assessing agreement
  between two methods of clinical measurement. The Lancet 327(8476):
  307–310. https://doi.org/10.1016/S0140-6736(86)90837-8 ·
  https://www-users.york.ac.uk/~mb55/meas/ba.pdf
• Bland JM, Altman DG (1999). Measuring agreement in method comparison
  studies. Statistical Methods in Medical Research 8(2): 135–160.
  https://doi.org/10.1177/096228029900800204
• Lin LI-K (1989). A concordance correlation coefficient to evaluate
  reproducibility. Biometrics 45(1): 255–268.
  https://doi.org/10.2307/2532051
• Ranganathan P, Pramesh CS, Aggarwal R (2017). Common pitfalls in statistical
  analysis: Measures of agreement. Perspectives in Clinical Research 8(4).
  https://doi.org/10.4103/picr.PICR_123_17

R packages (all on CRAN, verified August 2026)

• blandr — Bland-Altman method comparison:
  https://cran.r-project.org/package=blandr
• BlandAltmanLeh — extended Bland-Altman plots:
  https://cran.r-project.org/package=BlandAltmanLeh
• SimplyAgree — agreement studies with repeated observations:
  https://cran.r-project.org/package=SimplyAgree
• DescTools::CCC(), epiR::epi.ccc() — Lin's concordance correlation
  coefficient.

---

Part VIII — Categorical agreement, and the cost of a big grid

Both themes here close holes that earlier parts of this document opened. §53
finishes the job Part VII started: it gave the package agreement machinery for
continuous sources and ignored the categorical ones the geom has supported
since 0.2.0. §54 finishes the job Part V started: the lineup protocol asks
whether one plot shows real structure, and says nothing about the fact that a
grid of 96 glyphs is 96 invitations to find one.

---

53. Theme AB — Categorical agreement

The hole Part VII left. §49 gave the package bias, limits of agreement and
Lin's concordance coefficient — all of which require continuous sources.
geom_taichi() has auto-detected factor, character and logical fills since
0.2.0, where it was a headline feature and a bug fix (BUG-4). For those
sources, "do the two agree?" has an entirely different standard answer, and
Part VII's taichi_agreement() as sketched would simply not apply.

Cohen's kappa is that answer, and it comes with a warning. Kappa corrects
observed agreement for the agreement expected by chance. Feinstein &
Cicchetti (1990) made its two paradoxes famous:

1. High observed agreement can produce a low kappa. When one category
   dominates, chance agreement is large, so even 96% raw agreement can leave
   kappa near 0.6 or below.
2. Unbalanced marginals inflate kappa relative to balanced ones at the same
   observed agreement.

And here is why this matters more for this mark than for a table. A
discrete taichi grid renders agreement as visual matching: a cell whose two
halves are the same colour is a cell where the two sources agree. The reader
counts matching cells. That count is raw percent agreement — precisely the
statistic the kappa literature exists to warn people off. The glyph does not
merely fail to show kappa; it makes the misleading alternative maximally
salient and effortless to read.

There is a sharper version of this. 0.2.0 fixed a bug (#2) where
shared_legend = TRUE painted the two fish from differently-interpolated
palettes, so identical categories did not read as identical ink. The fix was
correct. But its effect is to make matching cells perfectly matched and
therefore trivially countable — so a legitimate bug fix inadvertently optimised
the display for the statistic that misleads. That is worth knowing about one's
own package.

Features.

taichi_agreement(data, yin, yang)
#> dispatches on the type of the two sources

#> continuous (Part VII):
#>   bias, limits of agreement, proportional bias, CCC

#> categorical:
#>   observed agreement                    0.83   <- what the grid shows you
#>   Cohen's kappa                         0.41   <- what it means
#>   Gwet's AC1                            0.79
#>   ! kappa is far below observed agreement: one category covers 71% of
#>     cells, so most of the matching you can see in the grid is chance.
#>   ! marginals are unbalanced (yin 71/29, yang 44/56), which inflates
#>     kappa relative to a balanced table -- read it with that in mind

Design notes.

• Report observed agreement and kappa together, always. Reporting kappa
  alone is unhelpful when the grid is showing the reader the other number;
  reporting the gap between them with the reason is the useful output, and it
  is the one thing a package that draws the grid is uniquely well placed to
  say.
• Gwet's AC1 is the prevalence-robust alternative and is worth including
  precisely because the paradox is not rare in this package's use cases — a
  grid of weeks × categories where one outcome dominates is the normal case,
  not a corner case.
• Ordinal categories need weighted kappa, and the package cannot currently
  tell. The discrete fill scale interpolates a sequential ramp across
  levels, which visually asserts that the categories are ordered — an ordered
  factor and an unordered one get the same visual treatment. If the levels
  really are ordinal, weighted kappa is the right statistic and near-miss
  disagreements should count partially. If they are not, the ramp is
  misleading and a qualitative palette would be better. Detecting
  is.ordered() and behaving differently is a small change with two payoffs:
  the right agreement statistic, and a warning when an unordered factor is
  about to be painted on a sequential ramp. That second one is arguably a bug
  in the current discrete-fill behaviour and nobody has raised it.
• Deps: none. Kappa, weighted kappa and AC1 are all closed-form on a
  contingency table. DescTools and irr have reference implementations to
  check against.

Effort M. Risk low. Value high — it is the categorical half of the
package's central question, and the observation about which statistic the mark
makes salient is not something the general literature will tell a user.

---

54. Theme AC — A grid is many comparisons

Part V's gap. §39 brought in the lineup protocol to ask whether the
structure in a plot is real. It never addressed the complementary problem:
a taichi grid presents 96, or 270, or 1,116 cells, and the reader scans them
for the interesting one. Every cell is an implicit comparison, and the
probability that the most striking one is noise rises with the count.

This has been measured, in visualization specifically. Zgraggen, Zhao,
Zeleznik & Kraska (2018), Investigating the Effect of the Multiple Comparisons
Problem in Visual Analysis (CHI) had participants report insights from
visualizations of synthetic data with known ground truth. Over 60% of
reported insights were false. The paper also shows that a confirmatory
analysis accounting for all the visual comparisons made — insights and
non-insights alike — recovers most of what a held-out validation set would
give. The related framing is the garden of forking paths in visualization
(Pu & Kay, 2018), which treats every unrecorded analytic choice as an implicit
test.

Where this bites ggtaichi specifically. taichi_summary() returns a
rank column — the cell's rank by the size of the gap, 1 being the widest —
and Part I's own example is head(summ[order(summ$rank), ], 5), "the five
cells where the two sources disagree most". That is the multiple comparisons
problem written as a convenience function. Taking the extreme of 96 cells and
reporting it is exactly the move Zgraggen et al. measured people getting wrong
60% of the time, and the package hands it over in one line with no caveat
attached.

Features.

taichi_check(...)
#> ! 96 cells means 96 implicit comparisons. The most extreme cell in a
#>     grid this size is often the most extreme *noise*.
#>     fix: taichi_lineup() to test the field as a whole, or supply
#>          replicate data and use taichi_summary(adjust = "BH")

taichi_summary(data, yin, yang, x, y, replicates = rep, adjust = "BH")
#> ... gains `p` and `q` columns when the data can support a per-cell test,
#>     and `rank` then ranks by adjusted significance rather than raw gap

Design notes.

• Do not overclaim. A per-cell p-value needs a model, and geom_taichi()
  requires only one row per cell — there is usually no replicate structure and
  therefore no legitimate test. So the FDR machinery must be opt-in and
  gated on the user supplying something to test with, and the default
  behaviour should be a warning about multiplicity, not a fabricated
  q-value. A package that invented p-values from single observations would be
  doing more harm than the problem it was fixing.
• The cheap, always-correct intervention is the caveat on rank. One
  sentence in ?taichi_summary and one line in taichi_check(). It costs
  nothing and it addresses the specific way this package makes the error easy.
• It composes with §39 rather than duplicating it. The lineup asks "is
  there structure in this field at all?" — one question, one answer, no
  multiplicity. Per-cell testing asks "which cells?" — many questions, needing
  correction. Offering the lineup as the first recourse is the better default
  advice, because it is the one that works without replicate data.
• Zgraggen et al.'s constructive result — that accounting for all comparisons,
  including the ones that produced no insight, recovers the validation-set
  answer — is interesting but needs an interactive session to count against.
  Not applicable to a static plotting package; worth citing and not chasing.

Deps none (stats::p.adjust). Effort S (the caveat and the check),
M (the opt-in testing path). Risk low, provided the opt-in gate holds.

---

55. Revisions from the eighth pass

§3 — rank needs a caveat in its own help page

The column is useful and the caveat is one sentence: the widest gap in a large
grid is frequently the largest noise; treat rank as a place to look, not as a
finding. This is the cheapest correction in Part VIII and it applies to
shipped 0.3.0 code.

§49 — taichi_agreement() dispatches on type

Part VII's sketch assumed continuous sources. It should branch: limits of
agreement and CCC for numeric, kappa / weighted kappa / AC1 for categorical,
and an error rather than a guess for mixed types — the same rule
shared_limits already applies when the two sources are of different kinds.

§5 / BUG-4 — ordered factors deserve different treatment

Raised in §53 and worth pulling out, because it is about the drawing, not the
statistics: the automatic discrete scale interpolates a sequential ramp for any
factor, ordered or not. A sequential ramp asserts an ordering. For an unordered
factor that assertion is false, and a qualitative palette would be right. This
looks like a genuine defect in behaviour that has shipped since 0.2.0, and
is.ordered() is the one-line test that distinguishes the cases.

§21 — the check now has five categories

Data shape, presentation, inference (§39), things the mark cannot show (§50),
and now multiplicity. Worth keeping that list explicit in the function's
documentation, because the fifth is the one users will least expect from a
plotting package.

---

56. Prioritisation delta (VIII)

Into Wave 2 — all three are sentences or near-sentences:

• The rank caveat (§55) — applies to shipped code, costs one line.
• The multiplicity line in taichi_check() (§54).
• is.ordered() handling for discrete fills (§55) — small, and it fixes a
  false visual assertion rather than adding a feature.

Into Wave 3:

• Categorical branch of taichi_agreement() (§53), alongside the
  continuous branch from Part VII. They should ship together or the function
  will be misleading for half its inputs.

Not planned:

• Automatic per-cell p-values. Gated behind user-supplied replicate data or
  not at all.

---

57. Eighth-pass references

Categorical agreement

• Cohen J (1960). A coefficient of agreement for nominal scales. Educational
  and Psychological Measurement 20(1): 37–46.
  https://doi.org/10.1177/001316446002000104
• Feinstein AR, Cicchetti DV (1990). High agreement but low kappa: I. The
  problems of two paradoxes. Journal of Clinical Epidemiology 43(6):
  543–549. https://doi.org/10.1016/0895-4356(90)90158-L
• Cicchetti DV, Feinstein AR (1990). High agreement but low kappa: II.
  Resolving the paradoxes. Journal of Clinical Epidemiology 43(6): 551–558.
  https://doi.org/10.1016/0895-4356(90)90159-M
• Warrens MJ (2010). A formal proof of a paradox associated with Cohen's kappa.
  Journal of Classification 27: 322–332.
  https://doi.org/10.1007/s00357-010-9060-x
• Gwet KL (2008). Computing inter-rater reliability and its variance in the
  presence of high agreement. British Journal of Mathematical and Statistical
  Psychology 61(1): 29–48. https://doi.org/10.1348/000711006X126600

Multiplicity in visual analysis

• Zgraggen E, Zhao Z, Zeleznik R, Kraska T (2018). Investigating the Effect of
  the Multiple Comparisons Problem in Visual Analysis. CHI 2018.
  https://doi.org/10.1145/3173574.3174053
• Pu X, Kay M (2018). The Garden of Forking Paths in Visualization: A Design
  Space for Reliable Exploratory Visual Analytics. IEEE VIS BELIV.
  https://doi.org/10.1109/BELIV.2018.8634103
• Benjamini Y, Hochberg Y (1995). Controlling the false discovery rate: a
  practical and powerful approach to multiple testing. JRSS B 57(1):
  289–300. https://doi.org/10.1111/j.2517-6161.1995.tb02031.x

---

Part IX — Time on the x axis, and summarising the field

§58 is about something the package does in every single one of its own
examples and has never examined. §59 is the other half of Part VII: the grid
shows a field, most of the questions users bring are about the field as a
whole, and there is a canonical diagram for exactly that which this document
has never named.

---

58. Theme AD — What the grid does to a trend

Start with an observation about this package's own materials. Every
bundled dataset is temporal, and every flagship example puts time on the
x axis:

dataset	grid
pitts_tg	30 weeks × 9 categories
states_tg	31 weeks × 9 categories × 4 states
cafes_tg	12 weeks × 8 neighbourhoods

So in practice a taichi grid is almost always a stack of time series, one per
row, with each series drawn as a row of discrete coloured glyphs. The
document has nine parts on how the mark encodes two values in a cell and has
never asked what it does to the series those cells belong to.

Javed, McDonnel & Elmqvist (2010), Graphical Perception of Multiple Time
Series (IEEE TVCG 16(6): 927–934) is the reference. They divide
multiple-series designs into shared-space (all series in one set of axes)
and split-space (a separate chart per series — small multiples, horizon
graphs), and test comparison, slope and discrimination tasks. Their result:
split-space techniques are generally more efficient than shared-space for
comparisons across series with a large visual span.

That cuts both ways for a taichi grid, and the split is the interesting
part.

• The good news. A taichi grid is a split-space design: one row per
  series, no overplotting, and it scales to more series than a shared-space
  line chart can carry. Javed et al.'s finding says that is the right family
  for the cross-series question — "which categories behave differently from
  each other?" — which is exactly what the package is for.
• The bad news, and it is not small. Within a row, the series is encoded in
  fill, not position. Slope — the thing a line chart makes effortless, and
  which Cleveland & McGill rank third — is not merely harder to read, it is
  not encoded at all. A reader perceives a trend by comparing the shade of
  adjacent glyphs, which is a sequence of rank-6 judgements standing in for one
  rank-3 judgement. Horizon graphs, the other split-space technique Javed et
  al. tested, keep position and win on exactly the tasks a taichi grid loses.

So the honest characterisation is: a taichi grid is a good split-space design
for cross-series pattern and a poor one for trend, and the package has been
demonstrating it almost exclusively on temporal data without saying so.

Features.

• A line in "when (not) to use taichi", which is the whole fix for most
  users:

  If one of your axes is time and the question is what is the trend, a
  taichi grid is the wrong chart: it encodes the series in colour, so the
  reader has to infer slope by comparing adjacent shades. Use it when the
  question is which series differ from each other, and where — and put a
  line chart or a horizon plot beside it for the trend.

• A documented companion recipe, not a new geom. Two sources over time per
  row is geom_line() faceted by row, or a horizon plot via ggHoriPlot
  (on CRAN). Neither needs to live in this package; both belong in the
  vignette next to the grid they complement.

• taichi_check() can detect the case cheaply: if the x mapping is a
  Date, POSIXct, or an evenly spaced integer sequence with many levels,
  say so once.

Design notes.

• This interacts with the animation conclusion from Part VI. The obvious
  rescue — animate over time and free the x axis — does not work, because
  Robertson et al. found animation the least effective format for trend
  analysis. Animation moves time out of the grid; it does not restore position
  encoding. The two findings agree: for trend, use small multiples of a
  position-encoded chart.
• It also reframes the seriation work (§22). Reordering rows is the right
  move for a categorical axis and is wrong for a temporal one — the x axis of
  these datasets must not be seriated, and taichi_seriate() should refuse, or
  at least warn, when an axis looks like time. That is a real safety issue for
  a feature already at the top of Wave 2, and it is cheap to guard.

Deps none (Suggests: ggHoriPlot only if a recipe is shipped).
Effort S (docs and the check), S (the seriation guard). Risk low.
Value high — it corrects the impression every example in the package
currently gives.

---

59. Theme AE — Summarising the field

Part VII's unfinished half. §49 established that a taichi grid shows the
difference against position and never against magnitude, and brought in
Bland–Altman for the latter. But there is a more basic gap: the grid shows a
field of comparisons and never a summary of the field. "How well do
these two sources agree overall?" has no answer anywhere in the package.

Taylor (2001), Summarizing multiple aspects of model performance in a
single diagram (JGR 106(D7): 7183–7192) — over seven thousand citations —
is the canonical answer in every field that compares a model against an
observation. It puts correlation, centred RMS difference, and the ratio of
standard deviations into one plane using the law of cosines: correlation is
the azimuthal angle, standard deviation the radial distance, and the centred
RMS difference falls out as the distance from the reference point.

Why it matters here, in two ways.

1. As a neighbour, for §2.4's positioning. The Taylor diagram solves
   exactly the problem this package's tagline claims: summarising multiple
   aspects of a two-source comparison in a single mark. It does it with
   geometry over a whole field; ggtaichi does it with a glyph per cell.
   That is the sharpest available contrast after biscale, and it is
   flattering rather than not — the two are complements, because a Taylor

[PursuitOfDataScience]

diagram cannot tell you where the sources diverge and a taichi grid cannot
tell you how much they agree overall.

2. As a decomposition Part VII was missing. Bland–Altman decomposes
   agreement into bias and limits of agreement, and asks whether the bias is
   proportional. Taylor decomposes it into correlation, variance ratio and
   centred RMS difference, which answers a different question: are the two
   sources shaped the same (correlation), does one vary more than the
   other (variance ratio), and how large is what is left over. Two sources can
   have zero bias and still disagree badly if one is systematically flatter
   than the other — and neither the grid nor a Bland–Altman plot shows that,
   while the variance ratio does immediately.

Features.

taichi_agreement(data, yin, yang)
#> ... gains the Taylor triple alongside the Bland-Altman one:
#>   correlation                            0.84
#>   sd ratio (yang / yin)                  0.61   ** espresso varies far
#>                                                    less than matcha
#>   centred RMS difference                 6.9

Design notes.

• Report the triple; do not draw the diagram. plotrix::taylor.diagram()
  is on CRAN and openair has one too. Reimplementing a well-understood polar
  diagram would be scope creep of the kind Part I's "explicitly not planned"
  list exists to prevent. The three numbers next to the Bland–Altman numbers
  in taichi_agreement() is the right amount, plus a documented recipe
  pointing at the existing implementations.
• The variance ratio is the most useful of the three for this package, and
  the least likely to be known by its users. A grid where one source is
  consistently mid-range and the other swings between extremes looks, glyph by
  glyph, like a lot of disagreement scattered around — the summary that says
  "one of these varies 1.6× as much as the other" explains the whole field in
  one number.
• Same scope gate as Part VII: this is only meaningful when the two sources
  measure the same quantity in the same units, which is the
  shared_limits / shared_legend case.
• It belongs in the "things the mark cannot show" category established in
  §50, which now has three members: proportional bias (§49), field-level
  agreement (§59), and trend within a row (§58). That category is turning out
  to be the most useful organising idea in the later parts of this document —
  a plotting package that documents what its chart structurally cannot tell
  you is doing something rare.

Deps none. Effort S. Risk low.

---

60. Revisions from the ninth pass

§22 — seriation must not reorder a temporal axis

Raised in §58 and worth stating on its own, because seriation is Wave 2's first
item and this is a correctness bug waiting to be written: reordering rows or
columns is right for categorical axes and destroys the data for a temporal
one. taichi_seriate() needs an axis-type guard, and on = "difference"
seriation of a week axis should be refused rather than warned about.

§2.4 — two more entries for the comparison table

• Taylor diagram — multiple aspects of a two-source comparison in one
  mark, by geometry over a whole field. Answers how well overall; cannot
  answer where.
• Horizon plot (ggHoriPlot) — split-space, position-encoded, for the
  trend question a taichi grid cannot serve.

§50 — the category has a name now

"Things the mark structurally cannot show" now covers proportional bias, field
-level agreement, and within-row trend. It deserves its own short section in
vignette("design") rather than three scattered caveats — and it is a genuine
differentiator, since almost no plotting package documents the shape of its own
blind spots.

---

61. Prioritisation delta (IX)

Into Wave 2:

• The temporal-axis guard on taichi_seriate() (§60) — ships with
  seriation or it ships a bug.
• The trend caveat in "when (not) to use" (§58) — one paragraph, and it
  corrects what every current example implies.

Into Wave 3:

• The Taylor triple in taichi_agreement() (§59) — alongside the
  Bland–Altman and kappa branches from Parts VII and VIII. All three are the
  same function.

Docs, next pass:

• The "what this mark cannot show" section in vignette("design") (§60).
• Taylor and horizon plots in the comparison table.

---

62. Ninth-pass references

• Javed W, McDonnel B, Elmqvist N (2010). Graphical Perception of Multiple
  Time Series. IEEE TVCG 16(6): 927–934.
  https://doi.org/10.1109/TVCG.2010.162 ·
  http://users.umiacs.umd.edu/~elm/projects/multilinevis/multilinevis.pdf
• Heer J, Kong N, Agrawala M (2009). Sizing the Horizon: The Effects of Chart
  Size and Layering on the Graphical Perception of Time Series
  Visualizations. CHI 2009. https://doi.org/10.1145/1518701.1518897
• Taylor KE (2001). Summarizing multiple aspects of model performance in a
  single diagram. Journal of Geophysical Research: Atmospheres 106(D7):
  7183–7192. https://doi.org/10.1029/2000JD900719 ·
  https://pcmdi.llnl.gov/staff/taylor/CV/Taylor_diagram_primer.pdf

R packages (all on CRAN, verified August 2026)

• ggHoriPlot — horizon plots for ggplot2:
  https://cran.r-project.org/package=ggHoriPlot
• plotrix — includes taylor.diagram():
  https://cran.r-project.org/package=plotrix
• openair — air-quality tools, includes a Taylor diagram:
  https://cran.r-project.org/package=openair

---

Part X — The evaluation agenda

This part adds no features. Across nine parts this document has repeatedly
written some version of "and nobody has measured it" — about the mark's
perceptual proxy, about contrast between adjacent fish, about what panel
lightness is best, about whether machines can read the glyph at all. Each time
the observation was left there. This part collects those claims into one list,
assigns each a method, and ranks them by which answer would actually change
the package. It is the closing section of the document rather than another
theme, and if only one thing from Parts II–IX is ever acted on, the argument
here is that it should be this.

---

63. Theme AF — The evaluation agenda

63.1 The two references that make this cheap

Lam, Bertini, Isenberg, Plaisant & Carpendale (2012), Empirical Studies in
Information Visualization: Seven Scenarios (IEEE TVCG 18(9): 1520–1536)
reviewed over 800 visualization publications and derived seven evaluation
scenarios — among them evaluating user performance (UP), evaluating
communication through visualization (CTV), evaluating user experience
(UE) and evaluating visualization algorithms (VA). Its practical use is
as a decision aid: given the question you have, it tells you which kind of
study answers it, so you do not run a usability study to answer a perception
question.

Heer & Bostock (2010), Crowdsourcing Graphical Perception: Using Mechanical
Turk to Assess Visualization Design (CHI 2010: 203–212) is what makes the UP
questions affordable. They replicated the Cleveland & McGill spatial-encoding
study and a luminance-contrast study on Mechanical Turk, matched the
laboratory results, and went on to produce new findings on rectangular area
perception and chart size. Two things follow for this document:

1. Crowdsourced graphical perception is validated, including for exactly
   the kind of proportion-judgement task the taichi's fills demand.
2. The rankings Part I builds its entire framing on were themselves
   replicated this way — so appealing to Cleveland & McGill while treating
   "run a study" as out of reach is inconsistent.

And a third instrument is already in the document: the lineup protocol
(§39) is itself a crowdsourced human-evaluation method with a defined visual
p-value (Majumder, Hofmann & Cook 2013). Some of the questions below are
lineups, not bespoke experiments.

63.2 The nine open questions, with methods

#	Question	From	Scenario	Method	Would change
1	What is the taichi's perceptual proxy — ink centroid, area of the darker fish, something else? And is there a vertical bias, since yin's bulb sits at the top and yang's at the bottom?	§17.2	UP	Crowdsourced 2AFC: which fish is larger, across matched value pairs at varying positions	Whether split ships at all; whether the glyph needs a vertical correction
2	Do two values read as more different inside one glyph than across two glyphs (simultaneous contrast)?	§27.2	UP	Same pair shown within-cell vs across-cell; measure JND	Documented guidance on which comparisons the grid supports
3	What panel lightness maximises discriminability of the two fills (crispening)?	§27.1	UP	Discrimination task across panel L* levels	theme_taichi()'s default panel fill
4	How do Szafir's size-dependent colour-difference models transfer to a curved, tapering, interlocking mark?	§18	UP	Discrimination at a ladder of rendered glyph sizes	The thresholds taichi_check_palette(cell_size =) reports
5	Do readers of a discrete grid actually count raw agreement rather than perceive chance-corrected agreement?	§53	UP	Estimate-the-agreement task against known kappa/percent pairs	How hard the docs push kappa over the visible number
6	Does split (area) beat fill for value comparison on this mark?	§8, §26.2	UP	Direct comparison, split vs fill, same values	Whether Wave 3's headline channel ships
7	Is a taichi grid more memorable than paired heatmaps?	§33.1	CTV	Recognition-memory protocol after Borkin et al.	A claim in the docs, and nothing else
8	Can a VLM read a taichi grid?	§29	VA	Benchmark against taichi_summary() ground truth	Whether taichi_describe() is a nicety or a necessity
9	Does the onboarding key (§34) improve first-time reading?	§34	UP / UE	Between-subjects, with and without the key	Whether annotate_taichi_key() is worth building

63.3 Which four are worth doing

Nine studies is not a plan; it is a wish. Ranked by decision value per unit of
effort, four stand out and five can wait indefinitely.

Do these:

• Q3, panel lightness. The cheapest by a distance — a discrimination task
  over a handful of background greys — and it settles a concrete default in
  theme_taichi(). It is also the only one whose answer the package can act on
  without any other work.
• Q1, the proxy and the vertical bias. The highest-stakes. If the yin bulb's
  position biases which fish reads as heavier, then every taichi ever drawn
  has a systematic asymmetry that no palette check can detect, and the fix is
  geometric rather than chromatic. This is the question that most deserves an
  answer and it has been sitting in §17.2 since Part II.
• Q2, within versus across cell. Determines what the grid can honestly
  claim to support, and it is the same experimental apparatus as Q1 — run them
  together.
• Q8, the VLM benchmark. Not a human study at all: render grids, ask a model
  the questions taichi_summary() already knows the answers to, score it. A
  scripted afternoon, no participants, no ethics approval, and the result is
  publishable either way.

Defer these: Q4 (needs Q1's apparatus first), Q5 and Q6 (both wait on
features that are not built), Q7 (changes only a marketing sentence), Q9 (wait
until the key exists).

63.4 What this means for the package

• Q1, Q2 and Q3 share one apparatus — a two-alternative forced-choice task
  over rendered taichi glyphs — so they are one study with three conditions
  rather than three studies. That is the single most useful thing in this
  section.
• The package can ship the stimulus generator. geom_taichi() already
  renders the marks; a data-raw/ script that emits the stimulus set with its
  ground truth is a small amount of code and it makes the study reproducible
  by anyone. That is a more valuable contribution than any of the remaining
  Wave 3 channels.
• Register the questions before answering them. Part V (§54) established
  that this document's own author is subject to the multiple-comparisons
  problem; running nine analyses and reporting the interesting ones is exactly
  that failure. Pre-registering Q1–Q3 costs nothing and makes the answers
  worth something.
• A negative result is still worth having. If the proxy turns out to be
  unbiased, that is a sentence the design vignette can state with evidence
  instead of hedging — and hedging is what the document currently does in four
  places.

Deps none for the package. Effort — outside the package entirely.
Value high, and of a different kind from everything else here: it is the
only item in the document that would let ggtaichi make claims about its own
mark rather than borrowing them from studies of other marks.

---

64. Tenth-pass references

• Lam H, Bertini E, Isenberg P, Plaisant C, Carpendale S (2012). Empirical
  Studies in Information Visualization: Seven Scenarios. IEEE TVCG 18(9):
  1520–1536. https://doi.org/10.1109/TVCG.2011.279 ·
  https://petra.isenberg.cc/publications/papers/Lam_2012_ESI.pdf
• Heer J, Bostock M (2010). Crowdsourcing Graphical Perception: Using
  Mechanical Turk to Assess Visualization Design. CHI 2010: 203–212.
  https://doi.org/10.1145/1753326.1753357 ·
  http://vis.stanford.edu/files/2010-MTurk-CHI.pdf

(The lineup protocol as an evaluation instrument — Majumder, Hofmann & Cook
2013 — is cited in §43.)

---

Addendum to §19 — Multimodal, not just described

Part X is the closing argument of this document and still is. This is a
correction to a single earlier section: §19 proposed taichi_describe() on the
strength of a 2022 paper, and the accessibility field moved after it. The
correction is small, the architectural observation that falls out of it is not.

---

65. Theme AG — Multimodal, not just described

What §19 got right and what it missed. Part II proposed
taichi_describe() structured by Lundgard & Satyanarayan's four-level model of
semantic content, and Parts III and V added two more reasons to build it
(colour naming, machine readability). All of that stands. What §19 assumed,
without noticing it was an assumption, is that the accessible version of a
chart is text. That was the state of the art when the four-level model was
published. It is not now.

• Zong, Pedraza Pineros, Chen, Hajas & Satyanarayan (2024), Umwelt:
  Accessible Structured Editing of Multimodal Data Representations (CHI
  2024) is the clearest statement of the current position. Umwelt treats
  visualization, sonification and textual description as coequal
  representations derived from a shared abstract data model, explicitly so
  that no modality is prioritised over the others. It was evaluated with expert
  screen-reader users.
• Thompson, Martinez, Sarikaya, Cutrell & Lee (2023), Chart Reader:
  Accessible Visualization Experiences Designed with Screen Reader Users
  (CHI 2023) combines textual description, sonification and flexible
  navigation, co-designed with ten blind and low-vision screen-reader users.
  The navigation is the part text alone cannot provide: the reader chooses what
  to examine rather than receiving a fixed summary.
• Controlled work on infosonics with 18 BLV adults found sonification
  complementary to text description rather than a substitute — which is the
  finding that matters most here, because it means §19 is not wrong, only
  incomplete.

The architectural observation, which is the useful part. Umwelt's framing —
coequal modalities derived from one shared abstract data model — describes a
structure this package has already built without meaning to. taichi_summary()
is that model: one row per cell, both values, their relationship, the cell's
identity. The glyph is a rendering of it; taichi_describe() (§19) would be a
second rendering of it; a sonification would be a third. All three are
traversals of the same table.

That reframes §19 in a way that is worth acting on even if no audio is ever
emitted:

taichi_summary() should be documented and designed as the package's
abstract data model, not as a convenience function that happens to return a
data frame. Every other representation should be derived from it, and
anything the glyph can express that the table cannot is a gap in the model.

Checked against the current table, one thing is already missing: the table has
no notion of the traversal order a non-visual reader needs — row-major,
column-major, or by rank. That is a small addition and it is the thing both
Chart Reader and Umwelt build their navigation on.

And a cross-modal insight that runs back the other way. The sonification
literature's standing warning about multiple series is that simultaneous
streams of only moderate similarity confuse the listener, that timbre
separation helps keep them apart, and that a good tool lets the user switch
between simultaneous and sequential presentation.

That is the taichi's own design restated in audio. Superposing two fields in
one mark is the visual equivalent of two simultaneous voices: good for
detecting crossings, bad for following either stream on its own. Hue separation
plays the role of timbre separation. And the recommended remedy — a
simultaneous/sequential toggle — is exactly what
data_id_by = "source" already does (§4): hovering one source suppresses the
other and turns the superposition into a single-stream display. Two fields
arrived at the same remedy independently, which is a reasonable sign it is the
right one, and it is worth saying so in vignette("design").

Features.

taichi_summary(data, yin, yang, x, y, order = c("row", "column", "rank"))
#> the traversal order a non-visual reader navigates in

taichi_describe(p, level = 1:3, as = "alt")     # §19, unchanged

taichi_sonify(p)      # far later, if at all -- see below
#> a note specification per cell: pitch = yin, second voice = yang,
#> traversal per `order`; rendering delegated

Design notes.

• Do not implement audio in this package. sonify, tuneR, audio and
  seewave are all on CRAN and any of them can render a note specification.
  What ggtaichi should own is the mapping — which channel becomes pitch,
  which becomes the second voice, how a missing cell sounds — and that is a
  documented recipe plus, at most, a specification-emitting function. Building
  a synthesiser here would be the scope creep Part I's "explicitly not
  planned" list exists to prevent.
• Sequential before simultaneous. Given the confusion finding, a first
  sonification should traverse one source and then the other, not both at
  once, with simultaneous playback as the option rather than the default. That
  inverts the glyph's own design choice, deliberately.
• This is Wave 4 at the earliest, and honestly it may never be right for
  this package to ship. But the reframing of taichi_summary() as the
  abstract model costs nothing, improves §19, and should happen in Wave 2
  alongside the mean column (§49) and the traversal order.
• Both papers were built with blind and low-vision users, not for them.
  Anything in this direction that is not co-designed should be labelled as a
  guess, and the docs should say who has and has not been consulted.

Deps none. Effort S (the model reframing and order), L (anything
audio). Risk low for the former, high for the latter.

---

66. Addendum references

• Zong J, Pedraza Pineros I, Chen M, Hajas D, Satyanarayan A (2024). Umwelt:
  Accessible Structured Editing of Multimodal Data Representations. CHI
  2024. https://doi.org/10.1145/3613904.3641996 ·
  https://vis.csail.mit.edu/pubs/umwelt/
• Thompson JR, Martinez JJ, Sarikaya A, Cutrell E, Lee B (2023). Chart Reader:
  Accessible Visualization Experiences Designed with Screen Reader Users.
  CHI 2023. https://doi.org/10.1145/3544548.3581186

R packages (all on CRAN, verified August 2026)

• sonify — data sonification: https://cran.r-project.org/package=sonify
• tuneR, audio, seewave — audio synthesis and I/O.

---

Addendum to §10 — Missingness is data

67. Theme AH — Missingness is data

What §10 proposed. Four rendering options — na_style = c("na_value", "hatched", "hollow", "omit") — with "omit" singled out as "semantically
perfect for this glyph": draw only the fish whose source has data, so a
half-present glyph means one source is missing. That remains the best idea in
§10. But every option in the list is a way of drawing missingness, and the
theme never treats missingness as something to reason about.

Tierney & Cook (2023), Expanding Tidy Data Principles to Facilitate Missing
Data Exploration, Visualization and Assessment of Imputations (JSS 105(7))
is the R-ecosystem statement of the alternative: missingness is a variable, it
belongs in the data as a first-class column, and once it is there you can
group, facet and model by it. Their naniar package implements it via the
"nabular" form — the data augmented with a shadow matrix of _NA indicators.
Rubin (1976), Inference and missing data (Biometrika 63(3): 581–592) is
why it matters: whether missingness is ignorable depends on its mechanism,
and MNAR — missing because of the value — cannot be diagnosed without
looking at the pattern.

The observation this yields is specific to a two-source mark, and the
document has not made it. A one-value heatmap cell is present or absent: two
states. A taichi cell has four:

state	what the glyph shows under na_style = "omit"
both present	a whole taichi
yin only	the yin fish alone
yang only	the yang fish alone
neither	nothing

That is a categorical variable with four levels that the package never names,
never counts and never reports — and which "omit" already renders
distinguishably. A taichi grid drawn with na_style = "omit" is
simultaneously a data display and a missingness display, which is a genuinely
unusual property and follows directly from the mark having two halves.

It also makes a Rubin-style question visible. If the yin fish is absent
precisely where the yang fish is dark, missingness is associated with the
observed value — the signature of a non-ignorable mechanism, and a finding
rather than a nuisance. Half-glyphs clustering in one region of the grid is
exactly what that looks like, and no other two-source display shows it without
a second chart.

Features.

taichi_summary(...)
#> gains `observed`: a four-level factor
#>   "both" / "<yin label> only" / "<yang label> only" / "neither"

taichi_check(...)
#> ! 12 cells have yin but not yang, 0 the reverse -- missingness is
#>     one-sided
#> ! the cells missing matcha have systematically higher espresso
#>     (r = 0.63). Missingness may depend on the value; do not read the
#>     visible fish as a fair sample.
#>     fix: na_style = "omit" makes the pattern visible in the grid

Design notes.

• observed is the cheap half and it composes with everything. As a
  column in taichi_summary() it can be counted, tabulated or faceted on; as
  a factor it is exactly what a reader needs to answer "how much of this grid
  is actually complete?". It also gives taichi_check() a precise thing to
  report instead of the current per-fish NA counts.
• The informative-missingness check is the valuable half. Correlating the
  present source against the missingness of the other is a few lines, and it
  catches a class of error the glyph would otherwise present as clean data.
  Same category as §49's proportional-bias check and §58's trend caveat:
  something true about the data that the mark cannot show by itself — except
  here, uniquely, the mark can show it once na_style = "omit" is on, so
  the check's fix is a package argument rather than a different chart.
• Do not depend on naniar. The four-state factor is one ifelse. What is
  worth borrowing is the principle — missingness in the data, not only in the
  rendering — and a docs pointer for users who want the full missing-data
  workflow.
• Ordering within na_style should follow from this. Of the four proposed
  options, "omit" is the only one that distinguishes all four states;
  "hollow" distinguishes three; na_value and "hatched" collapse yin-only
  and yang-only into "something is missing here". That is an argument for
  "omit" as the eventual default rather than merely an option, and it is
  stronger than the aesthetic argument §10 currently makes for it.

Deps none. Effort S (observed), S (the check). Risk low.
Value medium-high, and it promotes §10 from a rendering menu to something
that reasons about the data.

References

• Tierney N, Cook D (2023). Expanding Tidy Data Principles to Facilitate
  Missing Data Exploration, Visualization and Assessment of Imputations.
  Journal of Statistical Software 105(7): 1–31.
  https://doi.org/10.18637/jss.v105.i07
• Rubin DB (1976). Inference and missing data. Biometrika 63(3): 581–592.
  https://doi.org/10.1093/biomet/63.3.581
• naniar — structures and tools for missing data:
  https://cran.r-project.org/package=naniar

---

Addendum to §7 and §18 — The colour space the palette work runs in

68. Theme AI — The colour space

A narrow, concrete point about shipped code. The palette machinery this
document has spent four sections on runs in three different colour spaces,
and nothing above has asked whether they are the right ones:

what	space	where
taichi_palette_pair() builds ramps	polarLUV	grDevices::hcl()
taichi_check_palette() measures L* and chroma	CIELAB	farver::convert_colour(to = "lab")
interpolate_ramp() resamples a ramp	CIELAB	colorRampPalette(space = "Lab")
ggplot2 renders the gradient	CIELAB	scales::colour_ramp()

So measurement and interpolation are both CIELAB, and CIELAB is the oldest and
least uniform of the modern options.

The specific problem is blue, which is the specific problem for this
package. CIELAB has a well-documented hue shift toward purple through the
blue range, bad enough that later spaces are routinely justified by fixing it.
Luo, Cui & Li (2006), Uniform colour spaces based on CIECAM02 colour
appearance model (Color Research & Application 31(4): 320–330) introduced
CAM02-UCS for exactly this class of non-uniformity, and the more recent
engineering consensus — Oklab, now the default gradient interpolation space
in Photoshop and part of CSS Color 4 — is adopted on the same grounds.

And palette = "balanced", the pair this document recommends over the
defaults, is built at hue 250: blue. The recommended preset is constructed
and resampled in the two spaces that handle its own hue worst.

How much this actually matters, stated honestly.

• The luminance verdict is unaffected. L* is the axis CIELAB gets right,
  and the headline finding — a 41 L* mismatch in the defaults — does not
  depend on hue uniformity at all. taichi_check_palette()'s pass/fail stands.
• The chroma numbers and the interpolation do move. Chroma in CIELAB is
  sqrt(a² + b²) in a space that is not uniform in hue, so the per-step chroma
  column and the resampled intermediate colours are the affected parts.
• The CIE2000 distances are already a patch for this. CIE2000 exists
  precisely because plain Euclidean CIELAB distance is not perceptually
  uniform, which is a point in favour of the current CVD code and an argument
  that the fix here is smaller than it first looks.

So this is a refinement, not a correction, and it should be labelled that
way rather than filed as a bug.

Features.

taichi_palette_pair(..., space = c("hcl", "oklab"))
taichi_check_palette(..., space = c("lab", "oklab"))
#> report which space the numbers are in, because they are not comparable
#> across spaces and a silent switch would invalidate every recorded value

Design notes.

• Whatever else changes, report the space. The single cheapest improvement
  is one line of output naming the space the measurements were taken in. Every
  number this package prints about colour is space-dependent and currently
  unlabelled, which makes them impossible to check against another tool.
• Do not switch the default silently. The 41 L* figure now appears in the
  README, the vignette, the help pages and this document. If the measurement
  space changes, every one of those numbers must be regenerated in the same
  commit, and the space must be named next to them.
• farver already supports Oklab, so this costs a to = argument rather
  than a dependency. Construction in Oklab would be more work, since
  grDevices::hcl() is polarLUV and there is no base equivalent.
• A caveat on sourcing, since the framing of this document is literature.
  CAM02-UCS is peer-reviewed (Luo et al. 2006). Oklab is not — it is a 2020
  technical note by Björn Ottosson, adopted widely on engineering merit rather
  than through review. That is a perfectly good reason to offer it and a poor
  reason to make it the default, and the docs should say which is which.
• Lowest priority of anything in Parts VII–XII. It is here because it is
  concrete, it touches code that shipped in 0.3.0, and the blue coincidence is
  too on-the-nose to leave unrecorded.

Deps none. Effort S (label the space), M (offer Oklab). Risk low.
Value low-medium — but the labelling half is nearly free and makes every
other palette number in the package auditable.

References

• Luo MR, Cui G, Li C (2006). Uniform colour spaces based on CIECAM02 colour
  appearance model. Color Research & Application 31(4): 320–330.
  https://doi.org/10.1002/col.20227
• Luo MR, et al. (2023). A comprehensive test of colour-difference formulae and
  uniform colour spaces using available visual datasets. Color Research &
  Application. https://doi.org/10.1002/col.22844
• Ottosson B (2020). A perceptual color space for image processing (Oklab).
  Technical note, not peer reviewed.
  https://bottosson.github.io/posts/oklab/

---

The consolidated plan

69. What to build next

This section adds nothing. Ten passes each ended with a prioritisation delta
(§14, §24, §31, §37, §42, §47, §51, §56, §61, plus notes in the addenda), which
between them re-ranked the same items nine times and left no single place
showing what to do. This is that place. Where a later delta contradicts an
earlier one, the later one wins and the change is noted. Nothing below is new;
if an item here surprises you, the cross-reference is where it was argued.

No literature was consulted for this section. The one candidate found on
this pass — Lo et al. (2022), a taxonomy of 74 misleading-visualization
issues — turned out to restate §33.2, §34 and §54 rather than add to them, so
it is deliberately not cited above. Consolidation was the better use of the
pass.

---

Tier 0 — corrections to code that has already shipped

These are not features. Each is a defect or an unstated caveat in 0.3.0, all
are small, and they should go first because every one of them is currently
misleading somebody.

	what	where argued	size
1	rank needs a caveat. The widest gap in a 96-cell grid is frequently the largest noise, and taichi_summary() hands the extreme over in one line with no warning.	§54, §55	one sentence
2	is.ordered() for discrete fills. The automatic scale paints a sequential ramp on any factor, which asserts an ordering that an unordered factor does not have.	§53, §55	one branch
3	radius_exponent. The radius channel scales by sqrt(); cartography's answer for proportional circles is Flannery's ≈0.57, and 0.5 was a silent choice.	§30	one argument
4	Label the colour space in every number taichi_check_palette() prints. All of them are space-dependent and none says which space.	§68	one line of output
5	Trend caveat. Every bundled dataset is temporal and every example puts time on x; the grid encodes the series in colour, so slope is not encoded at all.	§58	one paragraph

Tier 1 — Wave 2, in dependency order

The ordering matters: several items are prerequisites for others, which none of
the nine deltas made visible.

1. taichi_seriate() via Suggests: seriation, with on = "difference",
   a reported merit gain, and a temporal-axis guard (§22, §35, §60). Two
   independent literatures support it — structure revelation and outlier
   findability under attention limits — and it is the most-supported item in
   the document. The guard is not optional: reordering a week axis destroys
   the data, so it ships with seriation or seriation ships broken.
2. taichi_lineup() / taichi_rorschach() via Suggests: nullabor
   (§39). Build it with seriation: reordering optimises an objective and will
   find blocks in noise, and a Rorschach over seriated null data is the only
   honest guard against that. The package-specific piece is the pairing
   null, which no existing tool provides.
3. taichi_check() as linter-and-fixer (§21), now covering five
   categories: data shape, presentation, inference (§39), things the mark
   cannot show (§50), and multiplicity (§54). Every finding carries the call
   that fixes it. Individual checks worth including, each a few lines:
   proportional bias (§49), frame count (§44), missingness pattern (§67),
   temporal axis (§58), cell-count/legibility (§17.3).
4. taichi_summary() as the abstract data model (§65) — add mean (§49),
   observed as a four-level missingness factor (§67), and a traversal
   order (§65). Document it as the model every other representation derives
   from, not as a convenience function.
5. taichi_describe() / taichi_alt() with as = for placement (§19,
   §36, §65). Four independent justifications: accessibility, colour naming,
   machine readability, on-chart annotation. Depends on 4.
6. Size-aware taichi_check_palette(cell_size =) (§18), plus the surround
   line and theme_taichi(panel_fill = "auto") (§27). No new dependency;
   the renderer already resolves physical glyph size.
7. annotate_taichi_key() (§34) — onboarding is where the evidence says
   the return is largest for an unfamiliar mark, and the README does not travel
   with the figure.
8. vignette("design") (§13), which now has a great deal to say: mirror
   symmetry (§17.1), ensemble coding (§17.3), Trumbo's four principles (§23),
   the MCDA scoring table (§20), metaphor and valence (§33.2, §45), the
   staging rule (§44), and "what this mark structurally cannot show" (§60)
   — proportional bias, field-level agreement, within-row trend.

Also in Wave 2, independent of the above: HOPs for uncertainty (§23),
palette = "scientific" via Suggests: scico (§23), labels with
contrast-aware colour (§5), na_style with "omit" as the likely default
(§10, §67), stat_taichi() (§9).

Tier 2 — Wave 3, gated

• Settle the argument question first (§15 Q1, §40). The answer the evidence
  supports: group only the genuine clusters (eyes, interactivity), keep
  palette and explicit flat, and keep the flat path working
  permanently — which the stable badge now also requires.
• taichi_agreement(), all three branches together or not at all:
  Bland–Altman for continuous (§49), kappa / weighted kappa / AC1 for
  categorical (§53), the Taylor triple for the field (§59). Shipping one
  branch makes the function misleading for the other inputs.
• geom_taichi_ba() (§49), taichi_stage() (§44),
  palette = "neutral" (§45), pattern fills, scatter placement (§6).
• split (§8) — demoted twice. Its original justification (area outranks
  colour) does not survive §26.2, and it should be scored under §20 and ideally
  wait on the proxy measurement (§17.2) before anyone writes it.

Tier 3 — outside the package

The evaluation agenda (§63). Q1, Q2 and Q3 share one apparatus and are one
study with three conditions. Q1 is the one that matters: if the yin bulb's
position biases which fish reads as heavier, every taichi ever drawn has a
systematic asymmetry no palette check can detect. Q8, the VLM benchmark, needs
no participants at all. The package can ship the stimulus generator, and the
questions should be pre-registered.

Explicitly not planned

Everything on Part I's original list — plotly, a third fill channel,
reimplementing animation, a rendering engine, more than two sources — plus,
added since: a bespoke guide framework (compose legendry, §23),
automatic per-cell p-values (§56), audio synthesis in this package
(§65), and reimplementing the Taylor diagram (§59).

---

The five things that would change the package most

If the list above is still too long: these five, in order.

1. The rank caveat and the is.ordered() branch — shipped code is
   currently misleading, and both are one-liners.
2. taichi_seriate() with its temporal guard — the most-supported feature
   in the document.
3. taichi_check() — it is the delivery mechanism for a dozen findings
   scattered across Parts II–IX, and the only place a user will ever encounter
   most of them.
4. taichi_describe() — four independent justifications, no dependency.
5. Q1 of the evaluation agenda — the only item that would let this package
   make a claim about its own mark rather than borrowing one.

---

70. Search log

Kept so that the survey's completeness is legible and so that later passes —
or a later maintainer — do not spend effort re-finding things that were found
and set aside. Each entry says what was looked at and why it is not above.

Pursued, and became sections. Sonification and multimodal accessibility
(→ §65), colour-space choice (→ §68), missing-data mechanisms (→ §67),
agreement and method comparison (→ §49, §53, §59), visual inference and
multiplicity (→ §39, §54), animated-transition design (→ §44), colour valence
and semantic resonance (→ §45), evaluation methodology (→ §63).

Evaluated and rejected.

candidate	why not
Lo et al. (2022), taxonomy of 74 misleading-visualization issues (CGF 41)	Real and well cited, but its four directions restate work already here: informal fallacies → §54 multiplicity and the rank caveat; exploiting conventions and data literacy → §34 onboarding; deceptive tricks in uncommon charts → §33.2 metaphor. Would have been a fourth statement of "the taichi is unfamiliar and asserts things".
sRGB → CMYK gamut mapping for print figures	A real practical concern, but the available sourcing is journal author-guidelines and vendor pages rather than research, which is a step below the rest of this document. One genuine finding is recorded below rather than inflated into a section.
Compositional data / Aitchison log-ratio analysis	Considered three times. The package explicitly does not encode part-to-whole (§2.4), and the one real connection — that log-ratio is the right transform for compositional pairs — is already made in §49 for a better reason (proportional bias).
Eye-tracking and scanpath studies of matrix reading	Plausible, but what it would say about reading order is already covered by attention capacity (§35) and seriation (§22), and nothing found would change a build decision.
Expert versus novice chart reading	§34 covers the novice case with a directly applicable result. The expert-reader literature would not change anything the package does.
Data physicalization and tactile charts	Genuinely interesting for accessibility and far outside what an R plotting package can act on. §65 already reaches the edge of what is actionable here.
Cognitive load theory applied to visualization	Overlaps attention capacity limits (§35) without adding a distinct prediction about this mark.
Grammar-of-graphics theory	§12 covers ggplot2 extension hygiene, which is the actionable part.

The one finding from the rejected set that is worth keeping.

palette = "print_safe" is named for greyscale survival — the two ramps
share a luminance trajectory, so they collapse to the same ink when colour is
removed (§7). That is not the same property as surviving CMYK conversion,
which is what most people mean by "print safe". A grey ramp is trivially inside
the CMYK gamut; a saturated hue ramp is not, and the dark ends of both the
default yang ramp and "balanced" sit where sRGB and CMYK diverge most. The
name over-promises. Either document precisely what it guarantees, or rename it
to something like "greyscale_safe" — the second is cleaner and the preset is
new enough in 0.3.0 that renaming costs almost nothing.

A note on where the survey stands. Fifteen passes in, the last two produced
no new theme: one candidate was redundant with existing sections and one failed
on sourcing quality. Earlier passes each found something because each asked a
genuinely different question — what does the mark mean, what field do its
users come from, what can it structurally not show. That supply is not
infinite, and the shift from "found a theme" to "rejected two candidates" is
the signal that it has run out. The useful work left is in §69, not in more
searching.

---

71. Addendum to §17.3 and §35 — Set size may not be the binding constraint

A 2026 result that complicates the document's dense-grid advice.

Two places above treat glyph count as the thing that degrades a grid.
§2.2 quotes Fuchs et al.: "performance drops significantly as the number of
glyphs increases", found by every scalability study they reviewed. §35 adds
Haroz & Whitney on attention's capacity limits. Between them they motivate the
density advice sketched in §17.3, whose suggested remedies are binned fills,
seriation, or a subset.

Li, Shao, Baudains, Meso, Holliman, Abdul-Rahman & Borgo (2026), Set Size
Matters: Capacity-Limited Perception of Grouped Spatial-Frequency Glyphs
(IEEE TVCG 32(1)) tested this directly for grouped glyphs. Participants
discriminated between pairs of maps of spatial-frequency glyphs — four discrete
levels each — judging an aggregate "risk strength" per map, with set sizes from
3 to 7. The findings:

• Judgements were no harder when each set contained more points.
• Redundant and conflicting encodings, and additional sets, did not strongly
  affect performance.
• Judgements were harder when the encoding was less salient.

Why this matters here. It is direct empirical support for the reframing
Part II made on theoretical grounds. §17.3 argued that a dense taichi grid
should be understood through ensemble coding — the reader extracting a
summary rather than reading cells — and that this is a specification rather
than a failure. Li et al. tested exactly an aggregate judgement over a set of
glyphs and found set size did not degrade it. Aggregate reading is the regime
where count stops being the constraint.

And it changes what the density advice should recommend:

If the binding constraint on an aggregate judgement is encoding salience
rather than glyph count, then of §17.3's three suggested remedies, two
are right for the wrong reason and one may be wrong. Binning raises
salience — fewer, more distinct steps — so it helps, and §18's size argument
and §5's accuracy argument now have a third, independent reason behind them.
Seriation does not change salience but makes structure findable, which
§35 already established. Subsetting reduces the count, which is the thing
the study says was not hurting you — and it throws away data to do it. It
should drop to last resort in the advice rather than sitting alongside the
other two.

Stated with its limits, because they are large. Set sizes were 3 to 7; a
taichi grid is 96 to 1,116 cells, so this is an extrapolation of two orders of
magnitude. The encoded channel was spatial frequency, not colour. And the task
was aggregate strength, not per-cell lookup — so the result says nothing about
the reading a legend invites, and Fuchs et al.'s finding may still hold exactly
where the taichi is weakest. The honest summary is: for the ensemble question,
count is probably not the problem and salience is; for the per-cell question,
nothing here rescues a 2 mm glyph. That distinction is worth making in the
docs either way, because the package currently gives one piece of density
advice for two very different tasks.

Action. No new feature. Reword the §17.3 density message to lead with
salience, demote subsetting, and split the advice by task. Add the citation to
§2.2's scalability paragraph as the counterweight to Fuchs et al.

Reference

• Li Y, Shao S, Baudains P, Meso A, Holliman N, Abdul-Rahman A, Borgo R
  (2026). Set Size Matters: Capacity-Limited Perception of Grouped
  Spatial-Frequency Glyphs. IEEE TVCG 32(1).
  https://doi.org/10.1109/TVCG.2025.3627102 ·
  https://kclpure.kcl.ac.uk/portal/files/344818398/Set_Size_Matters_1557.pdf