plotilla 1.0.0 → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (155) hide show
  1. package/README.md +37 -11
  2. package/data/boundaries/world_countries.geojson +1 -1
  3. package/dist/colour/colour_scale.d.ts +55 -0
  4. package/dist/colour/colour_scale.js +80 -0
  5. package/dist/colour/palette.d.ts +176 -0
  6. package/dist/colour/palette.js +220 -0
  7. package/dist/fields/axis_fields.d.ts +56 -0
  8. package/dist/fields/axis_fields.js +46 -0
  9. package/dist/fields/colour_fields.d.ts +32 -0
  10. package/dist/fields/colour_fields.js +31 -0
  11. package/dist/fields/column_fields.d.ts +52 -0
  12. package/{src/fields/column_fields.ts → dist/fields/column_fields.js} +15 -29
  13. package/dist/fields/common_fields.d.ts +9 -0
  14. package/{src/fields/common_fields.ts → dist/fields/common_fields.js} +3 -6
  15. package/dist/fields/decide_plot_axes.d.ts +56 -0
  16. package/dist/fields/decide_plot_axes.js +71 -0
  17. package/dist/fields/marker_fields.d.ts +8 -0
  18. package/dist/fields/marker_fields.js +13 -0
  19. package/dist/fields/read_date_time.d.ts +85 -0
  20. package/dist/fields/read_date_time.js +199 -0
  21. package/dist/figure/check_axis_year_formats.d.ts +36 -0
  22. package/dist/figure/check_axis_year_formats.js +116 -0
  23. package/dist/figure/check_plot_category_limits.d.ts +128 -0
  24. package/dist/figure/check_plot_category_limits.js +284 -0
  25. package/dist/figure/plot_figure.d.ts +861 -0
  26. package/dist/figure/plot_figure.js +58 -0
  27. package/dist/figure/resolve_plot_figure.d.ts +28 -0
  28. package/dist/figure/resolve_plot_figure.js +41 -0
  29. package/dist/figure/validate_plot_figure.d.ts +50 -0
  30. package/dist/figure/validate_plot_figure.js +441 -0
  31. package/dist/map/assign_map_layer_hue_slots.d.ts +89 -0
  32. package/dist/map/assign_map_layer_hue_slots.js +146 -0
  33. package/dist/map/boundary_sets.d.ts +65 -0
  34. package/dist/map/boundary_sets.js +103 -0
  35. package/dist/map/build_world_outline_across_180.d.ts +21 -0
  36. package/dist/map/build_world_outline_across_180.js +23 -0
  37. package/dist/map/check_map_layers.d.ts +16 -0
  38. package/dist/map/check_map_layers.js +31 -0
  39. package/dist/map/fetch_region_outlines.d.ts +25 -0
  40. package/dist/map/fetch_region_outlines.js +39 -0
  41. package/dist/map/geojson.d.ts +150 -0
  42. package/dist/map/geojson.js +248 -0
  43. package/dist/map/join_region_rows.d.ts +40 -0
  44. package/dist/map/join_region_rows.js +45 -0
  45. package/dist/map/map_layers.d.ts +229 -0
  46. package/dist/map/map_layers.js +87 -0
  47. package/dist/model/find_panel_colour_scale.d.ts +25 -0
  48. package/dist/model/find_panel_colour_scale.js +27 -0
  49. package/dist/model/map_model.d.ts +30 -0
  50. package/dist/model/map_model.js +234 -0
  51. package/dist/model/panel_layout.d.ts +42 -0
  52. package/dist/model/panel_layout.js +154 -0
  53. package/dist/model/panel_model.d.ts +223 -0
  54. package/dist/model/panel_model.js +7 -0
  55. package/dist/model/plot_model.d.ts +28 -0
  56. package/dist/model/plot_model.js +431 -0
  57. package/dist/model/statistics.d.ts +83 -0
  58. package/dist/model/statistics.js +107 -0
  59. package/dist/plots/bar_plot.d.ts +46 -0
  60. package/dist/plots/bar_plot.js +30 -0
  61. package/dist/plots/box_plot.d.ts +30 -0
  62. package/dist/plots/box_plot.js +21 -0
  63. package/dist/plots/density_plot.d.ts +36 -0
  64. package/dist/plots/density_plot.js +23 -0
  65. package/dist/plots/heatmap_plot.d.ts +22 -0
  66. package/dist/plots/heatmap_plot.js +18 -0
  67. package/dist/plots/histogram_plot.d.ts +32 -0
  68. package/dist/plots/histogram_plot.js +24 -0
  69. package/dist/plots/line_plot.d.ts +44 -0
  70. package/dist/plots/line_plot.js +25 -0
  71. package/dist/plots/map_plot.d.ts +92 -0
  72. package/dist/plots/map_plot.js +35 -0
  73. package/dist/plots/pie_plot.d.ts +17 -0
  74. package/dist/plots/pie_plot.js +16 -0
  75. package/dist/plots/scatter_plot.d.ts +47 -0
  76. package/dist/plots/scatter_plot.js +27 -0
  77. package/dist/renderers/date_ticks.d.ts +37 -0
  78. package/dist/renderers/date_ticks.js +148 -0
  79. package/dist/renderers/echarts_map.d.ts +47 -0
  80. package/dist/renderers/echarts_map.js +492 -0
  81. package/dist/renderers/echarts_options.d.ts +30 -0
  82. package/dist/renderers/echarts_options.js +449 -0
  83. package/dist/renderers/echarts_pie_radius.d.ts +52 -0
  84. package/dist/renderers/echarts_pie_radius.js +158 -0
  85. package/dist/renderers/escape_html.d.ts +10 -0
  86. package/dist/renderers/escape_html.js +15 -0
  87. package/dist/renderers/line_colour_segments.d.ts +39 -0
  88. package/dist/renderers/line_colour_segments.js +41 -0
  89. package/dist/renderers/plotly_map.d.ts +48 -0
  90. package/dist/renderers/plotly_map.js +159 -0
  91. package/dist/renderers/plotly_options.d.ts +19 -0
  92. package/dist/renderers/plotly_options.js +345 -0
  93. package/dist/renderers/year_ticks.d.ts +27 -0
  94. package/dist/renderers/year_ticks.js +42 -0
  95. package/dist/table/check_column.d.ts +36 -0
  96. package/dist/table/check_column.js +46 -0
  97. package/dist/table/check_values_have_spread.d.ts +30 -0
  98. package/{src/table/check_values_have_spread.ts → dist/table/check_values_have_spread.js} +16 -17
  99. package/dist/table/compute_quantile.d.ts +16 -0
  100. package/dist/table/compute_quantile.js +23 -0
  101. package/dist/table/data_table.d.ts +59 -0
  102. package/dist/table/data_table.js +87 -0
  103. package/dist/table/density_bandwidth.d.ts +64 -0
  104. package/dist/table/density_bandwidth.js +88 -0
  105. package/dist/table/find_line_fit.d.ts +30 -0
  106. package/dist/table/find_line_fit.js +36 -0
  107. package/dist/table/get_number_range.d.ts +16 -0
  108. package/{src/table/get_number_range.ts → dist/table/get_number_range.js} +8 -8
  109. package/dist/table/group_rows.d.ts +40 -0
  110. package/dist/table/group_rows.js +67 -0
  111. package/dist/table/list_categories.d.ts +14 -0
  112. package/{src/table/list_categories.ts → dist/table/list_categories.js} +2 -3
  113. package/dist/table/read_number.d.ts +12 -0
  114. package/dist/table/read_number.js +14 -0
  115. package/package.json +28 -23
  116. package/src/colour/colour_scale.ts +0 -80
  117. package/src/colour/palette.ts +0 -220
  118. package/src/examples/example_figures.ts +0 -320
  119. package/src/fields/axis_fields.ts +0 -32
  120. package/src/fields/colour_fields.ts +0 -40
  121. package/src/fields/decide_plot_axes.ts +0 -77
  122. package/src/fields/marker_fields.ts +0 -16
  123. package/src/figure/plot_figure.ts +0 -67
  124. package/src/figure/resolve_plot_figure.ts +0 -47
  125. package/src/figure/validate_plot_figure.ts +0 -412
  126. package/src/map/boundary_sets.ts +0 -116
  127. package/src/map/check_map_layers.ts +0 -32
  128. package/src/map/fetch_region_outlines.ts +0 -48
  129. package/src/map/geojson.ts +0 -174
  130. package/src/map/map_layers.ts +0 -108
  131. package/src/model/check_axis_shows_years.ts +0 -58
  132. package/src/model/map_model.ts +0 -238
  133. package/src/model/panel_layout.ts +0 -171
  134. package/src/model/panel_model.ts +0 -85
  135. package/src/model/plot_model.ts +0 -347
  136. package/src/model/statistics.ts +0 -134
  137. package/src/plots/bar_plot.ts +0 -36
  138. package/src/plots/box_plot.ts +0 -26
  139. package/src/plots/density_plot.ts +0 -29
  140. package/src/plots/heatmap_plot.ts +0 -24
  141. package/src/plots/histogram_plot.ts +0 -29
  142. package/src/plots/line_plot.ts +0 -29
  143. package/src/plots/map_plot.ts +0 -46
  144. package/src/plots/pie_plot.ts +0 -23
  145. package/src/plots/scatter_plot.ts +0 -32
  146. package/src/renderers/echarts_map.ts +0 -194
  147. package/src/renderers/echarts_options.ts +0 -317
  148. package/src/renderers/plotly_map.ts +0 -170
  149. package/src/renderers/plotly_options.ts +0 -318
  150. package/src/table/check_column.ts +0 -34
  151. package/src/table/compute_quantile.ts +0 -23
  152. package/src/table/data_table.ts +0 -83
  153. package/src/table/density_bandwidth.ts +0 -94
  154. package/src/table/find_line_fit.ts +0 -44
  155. package/src/table/group_rows.ts +0 -71
@@ -0,0 +1,431 @@
1
+ /**
2
+ * The renderer-neutral chart model: a validated spec turned into panels of
3
+ * ready-to-draw series, with every grouping, colour and statistic decided.
4
+ * The ECharts and Plotly mappers only translate this; they decide nothing,
5
+ * so the renderer switch never changes what the chart says.
6
+ */
7
+ import { ALL_PAIRS_COLOUR_LIMIT, pickCategoricalColour, pickLineDash, pickMarkerShape, DEFAULT_PLOT_THEME, MARKER_SHAPES, MARKER_SIZE, PLOT_THEMES, scaleToPixels, SIZE_RANGE_PIXELS, } from "../colour/palette.js";
8
+ import { applyColourScale, decideColourIsContinuous } from "../colour/colour_scale.js";
9
+ import { DEFAULT_COLOUR_SCALE } from "../fields/colour_fields.js";
10
+ import { DEFAULT_SHOW_MARKERS } from "../fields/marker_fields.js";
11
+ import { findPanelColourScale } from "./find_panel_colour_scale.js";
12
+ import { buildMapPanel } from "./map_model.js";
13
+ import { decidePlotAxes } from "../fields/decide_plot_axes.js";
14
+ import { convertDateTimeToMilliseconds, readDateColumn } from "../fields/read_date_time.js";
15
+ import { checkColumnHasNoValues } from "../table/check_column.js";
16
+ import { checkRowBecomesMark, findColumn, findOptionalColumn } from "../table/data_table.js";
17
+ import { groupRows } from "../table/group_rows.js";
18
+ import { listCategories } from "../table/list_categories.js";
19
+ import { listMarkColumns } from "../fields/column_fields.js";
20
+ import { binValues, chooseBinCount, estimateDensity, fitLine, summariseBox } from "./statistics.js";
21
+ import { getNumberRange } from "../table/get_number_range.js";
22
+ import { readNumber } from "../table/read_number.js";
23
+ import { computeDensityRange, computeSilvermanBandwidth } from "../table/density_bandwidth.js";
24
+ /** A date tick label's characters, by its form: 2025.01, 2025.01.15, 2025.01.15 08:30, or 2025.01.15 08:30:20. */
25
+ const DATE_LABEL_CHARACTERS = {
26
+ month: "2025.01".length, day: "2025.01.15".length, minute: "2025.01.15 08:30".length, second: "2025.01.15 08:30:20".length,
27
+ };
28
+ /** A two-digit year's label: 90. */
29
+ const TWO_DIGIT_YEAR_LABEL_CHARACTERS = "90".length;
30
+ /** When nothing is known about an axis's values, assume labels this long. */
31
+ const DEFAULT_LABEL_CHARACTERS = 4;
32
+ /**
33
+ * Estimate the widest tick label for numbers on an axis: ticks are round
34
+ * numbers written with thousands separators (2,600,000), or a few decimals
35
+ * below 1 (0.025). One extra character covers ticks just past the data.
36
+ *
37
+ * @param numbers - The values the axis must show.
38
+ * @returns An estimated character count.
39
+ */
40
+ export function estimateNumberLabelCharacters(numbers) {
41
+ if (numbers.length === 0)
42
+ return DEFAULT_LABEL_CHARACTERS;
43
+ const range = getNumberRange(numbers);
44
+ const largest = Math.max(Math.abs(range.minimum), Math.abs(range.maximum));
45
+ const sign = numbers.some((value) => value < 0) ? 1 : 0;
46
+ if (largest === 0)
47
+ return 1 + sign;
48
+ const digits = largest >= 1
49
+ ? Math.round(largest).toLocaleString("en-US").length
50
+ : "0.".length + Math.ceil(-Math.log10(largest)) + 1;
51
+ return digits + sign + 1;
52
+ }
53
+ /**
54
+ * Measure what an axis of numbers must show: its widest label, printed in the
55
+ * axis's declared form, and the range of its numbers (from zero when it must show zero).
56
+ *
57
+ * @param numbers - The values the axis must show.
58
+ * @param options - The declared year format (null for plain numbers), and whether the axis must show zero.
59
+ * @returns The widest label's estimated characters, and the numbers' range (null when there are none).
60
+ */
61
+ function measureNumberAxis(numbers, options) {
62
+ const shown = options.includesZero ? [...numbers, 0] : numbers;
63
+ const numberRange = numbers.length === 0 ? null : getNumberRange(shown);
64
+ if (options.yearFormat === null || numberRange === null)
65
+ return { longestLabelCharacters: estimateNumberLabelCharacters(numbers), numberRange };
66
+ if (options.yearFormat === "YY")
67
+ return { longestLabelCharacters: TWO_DIGIT_YEAR_LABEL_CHARACTERS, numberRange };
68
+ // Years print whole, with no commas: the widest is the one with the most digits.
69
+ const widest = Math.max(String(Math.trunc(numberRange.minimum)).length, String(Math.trunc(numberRange.maximum)).length);
70
+ return { longestLabelCharacters: widest, numberRange };
71
+ }
72
+ /**
73
+ * Decide how a time axis prints its dates, by the finest part any value
74
+ * holds: seconds when any has non-zero seconds; hours and minutes when any
75
+ * has a time other than midnight; months when every date is the first of
76
+ * its month; days otherwise.
77
+ *
78
+ * @param dates - The axis's dates, read into their parts.
79
+ * @returns The label form.
80
+ */
81
+ function decideDateLabelForm(dates) {
82
+ if (dates.some((date) => date.second !== 0))
83
+ return "second";
84
+ if (dates.some((date) => date.hour !== 0 || date.minute !== 0))
85
+ return "minute";
86
+ return dates.every((date) => date.day === 1) ? "month" : "day";
87
+ }
88
+ /**
89
+ * Build one axis of a plot from the values drawn on it.
90
+ *
91
+ * @param options - The values; the year format declared; the column they come from (null for counts or densities, which have none), named when a time axis refuses it; the title; the axis's kind and scale; and whether it must show zero.
92
+ * @returns The axis.
93
+ * @throws Error naming a value that is not a real date-time, or the column and two offsets when its dates mix UTC offsets.
94
+ */
95
+ function buildAxis(options) {
96
+ const { kind, scale } = options.axis;
97
+ const includesZero = options.includesZero ?? false;
98
+ const base = { kind, label: options.label, scale, includesZero };
99
+ if (kind === "category") {
100
+ const categories = listCategories(options.values);
101
+ return {
102
+ ...base, categories, labelForm: "category", numberRange: null,
103
+ longestLabelCharacters: Math.max(0, getNumberRange(categories.map((category) => category.length)).maximum),
104
+ };
105
+ }
106
+ if (kind === "time") {
107
+ if (options.column === null)
108
+ throw new Error(`Expected a column for the time axis "${options.label}"; got none.`);
109
+ const dates = readDateColumn(options.values.filter((value) => typeof value === "string"), { column: options.column });
110
+ const labelForm = decideDateLabelForm(dates);
111
+ const numberRange = dates.length === 0 ? null : getNumberRange(dates.map((date) => convertDateTimeToMilliseconds(date)));
112
+ return { ...base, categories: [], labelForm, numberRange, longestLabelCharacters: DATE_LABEL_CHARACTERS[labelForm] };
113
+ }
114
+ const numbers = options.values.filter((value) => typeof value === "number" && Number.isFinite(value));
115
+ const labelForm = options.yearFormat ?? "number";
116
+ return { ...base, categories: [], labelForm, ...measureNumberAxis(numbers, { yearFormat: options.yearFormat, includesZero }) };
117
+ }
118
+ /**
119
+ * Read a column at the given rows only, in their order.
120
+ *
121
+ * @param values - The column.
122
+ * @param options - The rows to read (groupRows' drawnRows, so an axis sees only rows drawn).
123
+ * @returns The values at those rows.
124
+ */
125
+ function pickRows(values, options) {
126
+ return options.rows.map((row) => values[row] ?? null);
127
+ }
128
+ /**
129
+ * Turn a column's numbers into what colour follows, per colour_scale, and the
130
+ * legend that goes with it: real values at its ends and ticks.
131
+ *
132
+ * @param values - The numbers (null where missing).
133
+ * @param options - The plot's colour_scale, the column's name, and where to put notes for the agent.
134
+ * @returns The value each mark is coloured by, and the panel's colour scale: null when no mark has a colour value.
135
+ */
136
+ function buildColourScale(values, options) {
137
+ const transformed = applyColourScale(values, { scale: options.scale, label: options.label, notes: options.notes });
138
+ const present = transformed.values.filter((value) => value !== null);
139
+ return {
140
+ colourValues: transformed.values,
141
+ colourScale: findPanelColourScale(present, { label: options.label, ticks: transformed.ticks }),
142
+ };
143
+ }
144
+ function buildPanel(plot, options) {
145
+ const { table, theme } = options;
146
+ if (plot.type === "map")
147
+ return buildMapPanel(plot, { table, theme });
148
+ const firstColumn = Object.values(table)[0] ?? [];
149
+ const rowCount = firstColumn.length;
150
+ const colour = "colour" in plot ? plot.colour : undefined;
151
+ const colourValues = findOptionalColumn(table, { column: colour });
152
+ const colourType = "colour_type" in plot ? plot.colour_type : undefined;
153
+ const isContinuous = colourValues !== null && decideColourIsContinuous(colourValues, { colourType });
154
+ // One rule for which rows become marks, shared with validation: only they set a range or make a series.
155
+ const markColumns = listMarkColumns(plot, { isColourCategorical: colourValues !== null && !isContinuous });
156
+ const isDrawn = (row) => checkRowBecomesMark(table, { row, ...markColumns });
157
+ const scaled = isContinuous && colourValues !== null && (plot.type === "line" || plot.type === "scatter" || plot.type === "bar")
158
+ ? buildColourScale(colourValues.map((value, row) => (isDrawn(row) ? readNumber(value) : null)), {
159
+ scale: plot.colour_scale ?? DEFAULT_COLOUR_SCALE, label: colour ?? "", notes: options.notes,
160
+ })
161
+ : null;
162
+ const continuousColours = scaled === null ? null : scaled.colourValues;
163
+ const colourScale = scaled === null ? null : scaled.colourScale;
164
+ const title = plot.title ?? null;
165
+ // One rule for each axis's kind and scale, shared with validation, which judges shared axes by it.
166
+ const axes = decidePlotAxes(plot, { table });
167
+ const requireAxis = (axis) => {
168
+ if (axis === null)
169
+ throw new Error(`Expected a ${plot.type} plot to have both axes.`);
170
+ return axis;
171
+ };
172
+ switch (plot.type) {
173
+ case "line":
174
+ case "scatter": {
175
+ const xValues = findColumn(table, { column: plot.x });
176
+ const yValues = findColumn(table, { column: plot.y });
177
+ const style = plot.type === "line" ? plot.line_type : plot.marker_shape;
178
+ const { grouping, groups, drawnRows } = groupRows(table, { rowCount, colour: isContinuous ? undefined : plot.colour, style, isDrawn });
179
+ const xAxis = buildAxis({ values: pickRows(xValues, { rows: drawnRows }), yearFormat: plot.x_year_format ?? null, column: plot.x, label: plot.x_label ?? plot.x, axis: requireAxis(axes.x) });
180
+ const yAxis = buildAxis({ values: pickRows(yValues, { rows: drawnRows }), yearFormat: plot.y_year_format ?? null, column: plot.y, label: plot.y_label ?? plot.y, axis: requireAxis(axes.y) });
181
+ // Sizes scale once over every drawn row, across groups, so one value is one size in the whole plot.
182
+ const sizeValues = plot.type === "scatter" ? findOptionalColumn(table, { column: plot.size }) : null;
183
+ const sizePixels = sizeValues === null ? null : scaleToPixels(sizeValues.map((value, row) => (isDrawn(row) ? readNumber(value) : null)), { range: SIZE_RANGE_PIXELS, fallback: MARKER_SIZE });
184
+ const series = [];
185
+ for (const group of groups) {
186
+ const colour = isContinuous ? null : pickCategoricalColour(group.colourIndex, { theme });
187
+ const { rows } = group;
188
+ if (plot.type === "line") {
189
+ series.push({
190
+ mark: "line", name: group.name, colour, dash: pickLineDash(style === undefined ? 0 : group.styleIndex),
191
+ // Coloured by a number, the points show the colour where a renderer cannot shade the line itself.
192
+ showMarkers: plot.show_markers ?? isContinuous, isFilled: false,
193
+ points: rows.map((row) => ({
194
+ x: xValues[row], y: yValues[row],
195
+ colourValue: continuousColours === null ? null : (continuousColours[row] ?? null),
196
+ })),
197
+ });
198
+ continue;
199
+ }
200
+ // Past the all-pairs limit, shape carries identity alongside colour. The automatic shapes cycle past the
201
+ // last one: colour already tells every series apart, and a repeated shape on another hue still leaves
202
+ // each colour-and-shape pair unique, where dropping shapes would lose the second cue just as series multiply.
203
+ const shapeIndex = style !== undefined ? group.styleIndex
204
+ : grouping.colourCategories.length > ALL_PAIRS_COLOUR_LIMIT ? group.colourIndex % MARKER_SHAPES.length : 0;
205
+ series.push({
206
+ mark: "scatter", name: group.name, colour, shape: pickMarkerShape(shapeIndex),
207
+ points: rows.map((row) => ({
208
+ x: xValues[row], y: yValues[row],
209
+ sizePixels: sizePixels === null ? MARKER_SIZE : (sizePixels[row] ?? MARKER_SIZE),
210
+ colourValue: continuousColours === null ? null : (continuousColours[row] ?? null),
211
+ })),
212
+ });
213
+ if (plot.show_trend_line) {
214
+ // A fit needs numbers on x; skipping the line silently would hide a figure that bypassed validation.
215
+ if (xAxis.kind !== "value")
216
+ throw new Error("A trend line needs a number x drawn on a value axis; validation should have refused this plot.");
217
+ const points = rows.map((row) => ({ x: xValues[row], y: yValues[row] }));
218
+ const { start, end } = fitLine(points);
219
+ series.push({
220
+ mark: "line", name: `${group.name || plot.y} trend`, colour: colour ?? PLOT_THEMES[theme].textSecondary, dash: "dashed",
221
+ showMarkers: false, isFilled: false, points: [{ ...start, colourValue: null }, { ...end, colourValue: null }],
222
+ });
223
+ }
224
+ }
225
+ return { title, xAxis, yAxis, series, colourScale };
226
+ }
227
+ case "bar": {
228
+ const xValues = findColumn(table, { column: plot.x });
229
+ const yValues = findColumn(table, { column: plot.y });
230
+ const { groups, drawnRows } = groupRows(table, { rowCount, colour: isContinuous ? undefined : plot.colour, style: undefined, isDrawn });
231
+ const isHorizontal = plot.orientation === "horizontal";
232
+ // The x column holds the categories and y the values, whichever way the bars lie.
233
+ const categoryAxis = buildAxis({ values: pickRows(xValues, { rows: drawnRows }), yearFormat: null, column: plot.x, label: plot.x_label ?? plot.x, axis: requireAxis(isHorizontal ? axes.y : axes.x) });
234
+ const valueAxis = buildAxis({ values: pickRows(yValues, { rows: drawnRows }), yearFormat: null, column: plot.y, label: plot.y_label ?? plot.y, axis: requireAxis(isHorizontal ? axes.x : axes.y), includesZero: true });
235
+ const series = groups.map((group) => ({
236
+ mark: "bar", name: group.name, colour: isContinuous ? null : pickCategoricalColour(group.colourIndex, { theme }),
237
+ isStacked: plot.mode === "stacked", isHorizontal,
238
+ points: group.rows.map((row) => ({
239
+ x: String(xValues[row]), y: yValues[row],
240
+ colourValue: continuousColours === null ? null : (continuousColours[row] ?? null),
241
+ })),
242
+ }));
243
+ if (plot.mode === "stacked") {
244
+ // Stacked bars reach the sum of each category, not its largest part.
245
+ const totals = new Map();
246
+ for (const entry of series)
247
+ if (entry.mark === "bar")
248
+ for (const point of entry.points)
249
+ totals.set(point.x, (totals.get(point.x) ?? 0) + point.y);
250
+ Object.assign(valueAxis, measureNumberAxis([...totals.values()], { yearFormat: null, includesZero: true }));
251
+ }
252
+ return { title, xAxis: isHorizontal ? valueAxis : categoryAxis, yAxis: isHorizontal ? categoryAxis : valueAxis, series, colourScale };
253
+ }
254
+ case "box": {
255
+ const yValues = findColumn(table, { column: plot.y });
256
+ const xValues = findOptionalColumn(table, { column: plot.x });
257
+ const { groups, drawnRows } = groupRows(table, { rowCount, colour: plot.colour, style: undefined, isDrawn });
258
+ const categories = xValues === null ? [plot.y] : listCategories(pickRows(xValues, { rows: drawnRows }));
259
+ // Each group's rows are split by category in one pass, so the work is linear in rows, not rows times categories.
260
+ const rowsByCategory = new Map(groups.map((group) => {
261
+ const rowsOfCategory = new Map();
262
+ for (const row of group.rows) {
263
+ const category = xValues === null ? plot.y : xValues[row] === null ? null : String(xValues[row]);
264
+ if (category === null)
265
+ continue;
266
+ const rows = rowsOfCategory.get(category);
267
+ if (rows === undefined)
268
+ rowsOfCategory.set(category, [row]);
269
+ else
270
+ rows.push(row);
271
+ }
272
+ return [group, rowsOfCategory];
273
+ }));
274
+ const series = groups.map((group) => ({
275
+ mark: "box", name: group.name, colour: pickCategoricalColour(group.colourIndex, { theme }), showMarkers: plot.show_markers ?? DEFAULT_SHOW_MARKERS,
276
+ boxes: categories.flatMap((category) => {
277
+ const values = (rowsByCategory.get(group)?.get(category) ?? []).map((row) => readNumber(yValues[row])).filter((value) => value !== null);
278
+ return values.length === 0 ? [] : [{ category, summary: summariseBox(values), values }];
279
+ }),
280
+ }));
281
+ const xAxis = {
282
+ ...requireAxis(axes.x), label: plot.x_label ?? plot.x ?? "", categories, includesZero: false, labelForm: "category", numberRange: null,
283
+ longestLabelCharacters: Math.max(0, getNumberRange(categories.map((category) => category.length)).maximum),
284
+ };
285
+ const yAxis = buildAxis({ values: pickRows(yValues, { rows: drawnRows }), yearFormat: plot.y_year_format ?? null, column: plot.y, label: plot.y_label ?? plot.y, axis: requireAxis(axes.y) });
286
+ return { title, xAxis, yAxis, series, colourScale: null };
287
+ }
288
+ case "histogram":
289
+ case "density": {
290
+ const xValues = findColumn(table, { column: plot.x });
291
+ const { groups, drawnRows } = groupRows(table, { rowCount, colour: plot.colour, style: undefined, isDrawn });
292
+ const drawnValues = pickRows(xValues, { rows: drawnRows });
293
+ const drawnNumbers = drawnValues.map(readNumber).filter((value) => value !== null);
294
+ if (drawnNumbers.length === 0)
295
+ throw new Error(`Expected a drawn row with a number in "${plot.x}"; validation refuses a figure without one.`);
296
+ const xAxis = buildAxis({ values: drawnValues, yearFormat: plot.x_year_format ?? null, column: plot.x, label: plot.x_label ?? plot.x, axis: requireAxis(axes.x) });
297
+ const yLabel = plot.type === "density" || (plot.type === "histogram" && plot.is_normalised) ? "density" : "count";
298
+ const yAxis = buildAxis({ values: [], yearFormat: null, column: null, label: plot.y_label ?? yLabel, axis: requireAxis(axes.y), includesZero: true });
299
+ const { minimum, maximum } = getNumberRange(drawnNumbers);
300
+ const series = groups.map((group) => {
301
+ const values = group.rows.map((row) => readNumber(xValues[row])).filter((value) => value !== null);
302
+ const colour = pickCategoricalColour(group.colourIndex, { theme });
303
+ if (plot.type === "histogram") {
304
+ const binCount = plot.bins ?? chooseBinCount(drawnNumbers.length);
305
+ return { mark: "histogram", name: group.name, colour, bins: binValues(values, { binCount, minimum, maximum, isNormalised: plot.is_normalised }) };
306
+ }
307
+ const bandwidth = plot.bandwidth ?? computeSilvermanBandwidth(values);
308
+ const range = computeDensityRange({ minimum, maximum, bandwidth });
309
+ const points = estimateDensity(values, { bandwidth, minimum: range.minimum, maximum: range.maximum }).map((point) => ({ ...point, colourValue: null }));
310
+ return { mark: "line", name: group.name, colour, dash: "solid", showMarkers: false, isFilled: plot.show_area, points };
311
+ });
312
+ // The y values (counts, densities) exist only now.
313
+ Object.assign(yAxis, measureNumberAxis(series.flatMap((entry) => entry.mark === "histogram" ? entry.bins.map((bin) => bin.height) : entry.mark === "line" ? entry.points.map((point) => point.y) : []), { yearFormat: null, includesZero: true }));
314
+ return { title, xAxis, yAxis, series, colourScale: null };
315
+ }
316
+ case "heatmap": {
317
+ const xValues = findColumn(table, { column: plot.x });
318
+ const yValues = findColumn(table, { column: plot.y });
319
+ const cellValues = findColumn(table, { column: plot.value });
320
+ const placed = xValues.flatMap((x, row) => {
321
+ const value = readNumber(cellValues[row]);
322
+ return x === null || yValues[row] === null || yValues[row] === undefined || value === null ? [] : [{ x: String(x), y: String(yValues[row]), value }];
323
+ });
324
+ const { colourValues: cellColours, colourScale: heatmapScale } = buildColourScale(placed.map((cell) => cell.value), { scale: plot.colour_scale ?? DEFAULT_COLOUR_SCALE, label: plot.value, notes: options.notes });
325
+ const cells = placed.map((cell, index) => ({ ...cell, colourValue: cellColours[index] ?? null }));
326
+ return {
327
+ title,
328
+ xAxis: buildAxis({ values: xValues, yearFormat: null, column: plot.x, label: plot.x_label ?? plot.x, axis: requireAxis(axes.x) }),
329
+ yAxis: buildAxis({ values: yValues, yearFormat: null, column: plot.y, label: plot.y_label ?? plot.y, axis: requireAxis(axes.y) }),
330
+ series: [{ mark: "heatmap", name: plot.value, cells }],
331
+ colourScale: heatmapScale,
332
+ };
333
+ }
334
+ case "pie": {
335
+ const labels = findColumn(table, { column: plot.label });
336
+ const values = findColumn(table, { column: plot.value });
337
+ const slices = labels.flatMap((label, row) => {
338
+ const value = readNumber(values[row]);
339
+ return label === null || value === null ? [] : [{ label: String(label), value }];
340
+ });
341
+ return {
342
+ title, xAxis: null, yAxis: null, colourScale: null,
343
+ series: [{ mark: "pie", name: plot.value, hole: plot.hole, slices: slices.map((slice, index) => ({ ...slice, colour: pickCategoricalColour(index, { theme }) })) }],
344
+ };
345
+ }
346
+ }
347
+ }
348
+ /**
349
+ * Find the column whose values a plot draws as its marks' positions or
350
+ * amounts, the one with no marks when it is empty: y for line, scatter,
351
+ * bar, box and heatmap; value for pie. A map's columns are checked by its
352
+ * layers, and a histogram's or density's x with no numbers is refused by
353
+ * validation instead, so neither has one here.
354
+ *
355
+ * @param plot - The plot.
356
+ * @returns The column, or null when the plot has none of that kind.
357
+ */
358
+ function findDrawnValueColumn(plot) {
359
+ if (plot.type === "pie")
360
+ return plot.value;
361
+ if ("y" in plot && plot.y !== undefined)
362
+ return plot.y;
363
+ return null;
364
+ }
365
+ /**
366
+ * Find the note for a plot whose drawn values column (y, or a pie's value)
367
+ * holds no values, every cell missing. It is a note, not a refusal: an
368
+ * empty chart can be legitimate (the data is not in yet), but it must not
369
+ * be silent, or the agent sees an empty chart with no word of why. Line,
370
+ * scatter, bar, box and heatmap draw nothing with an empty y, and a pie
371
+ * nothing with an empty value; a histogram's or density's x with no
372
+ * numbers is refused by validation instead, and a map has no such column.
373
+ *
374
+ * @param plot - The plot.
375
+ * @param options - Its table, and where it is in the figure, which names it when it has no title.
376
+ * @returns The note, or null when the plot has no such column or the column has a value.
377
+ */
378
+ function findEmptyDrawnValueColumnNote(plot, options) {
379
+ const column = findDrawnValueColumn(plot);
380
+ if (column === null)
381
+ return null;
382
+ if (!checkColumnHasNoValues(options.table, { column }))
383
+ return null;
384
+ const name = plot.title === undefined ? options.where : `"${plot.title}"`;
385
+ return `${name}: "${column}" has no values, so nothing can be drawn.`;
386
+ }
387
+ /**
388
+ * Build the chart model for a validated figure.
389
+ *
390
+ * @param figure - A figure that passed validatePlotFigure.
391
+ * @param options - The theme it is drawn in (default: dark).
392
+ * @returns Panels in grid order (row by row), ready for a renderer.
393
+ */
394
+ export function buildFigureModel(figure, options = {}) {
395
+ const theme = options.theme ?? DEFAULT_PLOT_THEME;
396
+ const rows = figure.grid?.rows ?? figure.plots.length;
397
+ const columns = figure.grid?.columns ?? 1;
398
+ const chartNotes = [];
399
+ const panels = figure.plots.map((plot, index) => {
400
+ const table = plot.data ?? figure.data;
401
+ const emptyColumnNote = findEmptyDrawnValueColumnNote(plot, { table, where: `plots[${index}]` });
402
+ if (emptyColumnNote !== null)
403
+ chartNotes.push(emptyColumnNote);
404
+ return buildPanel(plot, { table, theme, notes: chartNotes });
405
+ });
406
+ const legendNames = [...new Set(panels.flatMap((panel) => [
407
+ ...panel.series.map((series) => series.name),
408
+ // Map layers join the legend when they are colour categories.
409
+ ...(panel.map?.layers ?? []).flatMap((layer) => ((layer.kind === "points" || layer.kind === "lines") && layer.isCategory ? [layer.name] : [])),
410
+ ]).filter((name) => name !== ""))];
411
+ const notes = [...chartNotes, ...panels.flatMap((panel) => panel.map?.notes ?? [])];
412
+ // One plot needs one title: keep the figure's, or move the plot's up to
413
+ // the top. Plot titles only tell plots apart in a grid.
414
+ let title = figure.title ?? null;
415
+ const onlyPanel = panels.length === 1 ? panels[0] : undefined;
416
+ if (onlyPanel !== undefined) {
417
+ title = title ?? onlyPanel.title;
418
+ onlyPanel.title = null;
419
+ }
420
+ return {
421
+ title,
422
+ rows,
423
+ columns,
424
+ isXAxisShared: figure.is_x_axis_shared,
425
+ isYAxisShared: figure.is_y_axis_shared,
426
+ theme,
427
+ legendNames,
428
+ notes,
429
+ panels,
430
+ };
431
+ }
@@ -0,0 +1,83 @@
1
+ /**
2
+ * The statistics plots need, computed here so both renderers draw
3
+ * identical numbers: box-plot summaries, histogram bins, and kernel density.
4
+ *
5
+ * Density is computed here rather than by a renderer: Plotly has trouble
6
+ * with several densities in one plot and ECharts has none
7
+ * (scribble.tube's .documents/concepts/plot_spec.md).
8
+ */
9
+ import { type FitPoint, type LineFit } from "../table/find_line_fit.ts";
10
+ /** Tukey's whisker reach, in interquartile ranges. */
11
+ export declare const WHISKER_IQR_MULTIPLE = 1.5;
12
+ /** Points at which a density curve is evaluated. */
13
+ export declare const DENSITY_POINTS = 200;
14
+ /** A box plot's five numbers and its outliers. */
15
+ export type BoxSummary = {
16
+ lowerWhisker: number;
17
+ firstQuartile: number;
18
+ median: number;
19
+ thirdQuartile: number;
20
+ upperWhisker: number;
21
+ outliers: number[];
22
+ };
23
+ /** One histogram bar: [start, end) and its height. */
24
+ export type HistogramBin = {
25
+ start: number;
26
+ end: number;
27
+ height: number;
28
+ };
29
+ /**
30
+ * Summarise values for a box plot (Tukey: whiskers reach the furthest value
31
+ * within 1.5 IQR of the box; beyond that are outliers).
32
+ *
33
+ * @param values - The values; at least one.
34
+ * @returns The summary.
35
+ */
36
+ export declare function summariseBox(values: number[]): BoxSummary;
37
+ /**
38
+ * Choose a bin count by Sturges' rule, ceil(log2 n) + 1.
39
+ *
40
+ * @param count - How many values.
41
+ * @returns The number of bins.
42
+ */
43
+ export declare function chooseBinCount(count: number): number;
44
+ /**
45
+ * Bin values for a histogram.
46
+ *
47
+ * @param values - The values; at least one.
48
+ * @param options - The bin count, the shared range (so several groups line
49
+ * up), and whether heights are densities (area 1) rather than counts.
50
+ * @returns The bins, in order.
51
+ */
52
+ export declare function binValues(values: number[], options: {
53
+ binCount: number;
54
+ minimum: number;
55
+ maximum: number;
56
+ isNormalised: boolean;
57
+ }): HistogramBin[];
58
+ /**
59
+ * Estimate a density curve with a Gaussian kernel.
60
+ *
61
+ * @param values - The values; at least two.
62
+ * @param options - The bandwidth, and the x range to evaluate over (shared
63
+ * across groups so their curves line up).
64
+ * @returns Points along the curve, in x order.
65
+ */
66
+ export declare function estimateDensity(values: number[], options: {
67
+ bandwidth: number;
68
+ minimum: number;
69
+ maximum: number;
70
+ pointCount?: number;
71
+ }): {
72
+ x: number;
73
+ y: number;
74
+ }[];
75
+ /**
76
+ * Fit a least-squares line, for a series validation has already judged
77
+ * fittable by the same rule; failing here means validation missed a case.
78
+ *
79
+ * @param points - Points whose fit is finite (see findLineFit).
80
+ * @returns The slope, intercept and the line's ends.
81
+ * @throws Error when the points have no finite fit.
82
+ */
83
+ export declare function fitLine(points: readonly FitPoint[]): LineFit;
@@ -0,0 +1,107 @@
1
+ /**
2
+ * The statistics plots need, computed here so both renderers draw
3
+ * identical numbers: box-plot summaries, histogram bins, and kernel density.
4
+ *
5
+ * Density is computed here rather than by a renderer: Plotly has trouble
6
+ * with several densities in one plot and ECharts has none
7
+ * (scribble.tube's .documents/concepts/plot_spec.md).
8
+ */
9
+ import { computeQuantile } from "../table/compute_quantile.js";
10
+ import { computeDensityNormaliser } from "../table/density_bandwidth.js";
11
+ import { findLineFit } from "../table/find_line_fit.js";
12
+ /** Tukey's whisker reach, in interquartile ranges. */
13
+ export const WHISKER_IQR_MULTIPLE = 1.5;
14
+ /** Points at which a density curve is evaluated. */
15
+ export const DENSITY_POINTS = 200;
16
+ /**
17
+ * Summarise values for a box plot (Tukey: whiskers reach the furthest value
18
+ * within 1.5 IQR of the box; beyond that are outliers).
19
+ *
20
+ * @param values - The values; at least one.
21
+ * @returns The summary.
22
+ */
23
+ export function summariseBox(values) {
24
+ const sorted = [...values].sort((first, second) => first - second);
25
+ const firstQuartile = computeQuantile(sorted, { quantile: 0.25 });
26
+ const median = computeQuantile(sorted, { quantile: 0.5 });
27
+ const thirdQuartile = computeQuantile(sorted, { quantile: 0.75 });
28
+ const reach = WHISKER_IQR_MULTIPLE * (thirdQuartile - firstQuartile);
29
+ const inside = sorted.filter((value) => value >= firstQuartile - reach && value <= thirdQuartile + reach);
30
+ return {
31
+ lowerWhisker: inside[0],
32
+ firstQuartile,
33
+ median,
34
+ thirdQuartile,
35
+ upperWhisker: inside[inside.length - 1],
36
+ outliers: sorted.filter((value) => value < firstQuartile - reach || value > thirdQuartile + reach),
37
+ };
38
+ }
39
+ /**
40
+ * Choose a bin count by Sturges' rule, ceil(log2 n) + 1.
41
+ *
42
+ * @param count - How many values.
43
+ * @returns The number of bins.
44
+ */
45
+ export function chooseBinCount(count) {
46
+ return count <= 1 ? 1 : Math.ceil(Math.log2(count)) + 1;
47
+ }
48
+ /**
49
+ * Bin values for a histogram.
50
+ *
51
+ * @param values - The values; at least one.
52
+ * @param options - The bin count, the shared range (so several groups line
53
+ * up), and whether heights are densities (area 1) rather than counts.
54
+ * @returns The bins, in order.
55
+ */
56
+ export function binValues(values, options) {
57
+ const width = options.maximum > options.minimum ? (options.maximum - options.minimum) / options.binCount : 1;
58
+ const counts = new Array(options.binCount).fill(0);
59
+ for (const value of values) {
60
+ // The top edge belongs to the last bin.
61
+ const index = Math.min(Math.floor((value - options.minimum) / width), options.binCount - 1);
62
+ counts[index] = counts[index] + 1;
63
+ }
64
+ return counts.map((count, index) => ({
65
+ start: options.minimum + index * width,
66
+ end: options.minimum + (index + 1) * width,
67
+ height: options.isNormalised ? count / (values.length * width) : count,
68
+ }));
69
+ }
70
+ /**
71
+ * Estimate a density curve with a Gaussian kernel.
72
+ *
73
+ * @param values - The values; at least two.
74
+ * @param options - The bandwidth, and the x range to evaluate over (shared
75
+ * across groups so their curves line up).
76
+ * @returns Points along the curve, in x order.
77
+ */
78
+ export function estimateDensity(values, options) {
79
+ const pointCount = options.pointCount ?? DENSITY_POINTS;
80
+ const normaliser = computeDensityNormaliser({ count: values.length, bandwidth: options.bandwidth });
81
+ const step = (options.maximum - options.minimum) / (pointCount - 1);
82
+ const points = [];
83
+ for (let index = 0; index < pointCount; index += 1) {
84
+ const x = options.minimum + index * step;
85
+ let sum = 0;
86
+ for (const value of values) {
87
+ const distance = (x - value) / options.bandwidth;
88
+ sum += Math.exp(-0.5 * distance * distance);
89
+ }
90
+ points.push({ x, y: sum * normaliser });
91
+ }
92
+ return points;
93
+ }
94
+ /**
95
+ * Fit a least-squares line, for a series validation has already judged
96
+ * fittable by the same rule; failing here means validation missed a case.
97
+ *
98
+ * @param points - Points whose fit is finite (see findLineFit).
99
+ * @returns The slope, intercept and the line's ends.
100
+ * @throws Error when the points have no finite fit.
101
+ */
102
+ export function fitLine(points) {
103
+ const fit = findLineFit(points);
104
+ if (fit === null)
105
+ throw new Error("A trend line needs x values that vary measurably, with a finite fit; validation should have refused this series.");
106
+ return fit;
107
+ }
@@ -0,0 +1,46 @@
1
+ /** The bar plot: a bar per category, grouped or stacked by colour. */
2
+ import { z } from "zod";
3
+ /** How bars of different colours share a category. */
4
+ export declare const BAR_MODES: readonly ["grouped", "stacked"];
5
+ /** The mode bars get when the agent names none. */
6
+ export declare const DEFAULT_BAR_MODE: (typeof BAR_MODES)[number];
7
+ /** Whether bars stand up or lie down. */
8
+ export declare const BAR_ORIENTATIONS: readonly ["vertical", "horizontal"];
9
+ /** The orientation bars get when the agent names none. */
10
+ export declare const DEFAULT_BAR_ORIENTATION: (typeof BAR_ORIENTATIONS)[number];
11
+ /** A bar plot as an agent sends it. */
12
+ export declare const BAR_PLOT_SCHEMA: z.ZodObject<{
13
+ colour: z.ZodOptional<z.ZodString>;
14
+ colour_type: z.ZodOptional<z.ZodEnum<{
15
+ categorical: "categorical";
16
+ continuous: "continuous";
17
+ }>>;
18
+ colour_scale: z.ZodOptional<z.ZodEnum<{
19
+ linear: "linear";
20
+ log: "log";
21
+ quantile: "quantile";
22
+ }>>;
23
+ x_label: z.ZodOptional<z.ZodString>;
24
+ y_label: z.ZodOptional<z.ZodString>;
25
+ y_scale: z.ZodDefault<z.ZodEnum<{
26
+ linear: "linear";
27
+ log: "log";
28
+ }>>;
29
+ title: z.ZodOptional<z.ZodString>;
30
+ data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodUnion<readonly [z.ZodNumber, z.ZodPipe<z.ZodString, z.ZodTransform<string | null, string>>, z.ZodNull]>>>>;
31
+ type: z.ZodLiteral<"bar">;
32
+ x: z.ZodString;
33
+ y: z.ZodString;
34
+ mode: z.ZodDefault<z.ZodEnum<{
35
+ grouped: "grouped";
36
+ stacked: "stacked";
37
+ }>>;
38
+ orientation: z.ZodDefault<z.ZodEnum<{
39
+ horizontal: "horizontal";
40
+ vertical: "vertical";
41
+ }>>;
42
+ }, z.core.$strict>;
43
+ /** A bar plot, through the schema. */
44
+ export type BarPlot = z.infer<typeof BAR_PLOT_SCHEMA>;
45
+ /** The column fields that must hold numbers. */
46
+ export declare const BAR_NUMERIC_COLUMNS: readonly (keyof BarPlot)[];