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,55 @@
1
+ /**
2
+ * Colour scales: how numbers map to colour, shared by charts and maps so
3
+ * `colour_scale` means the same on every plot.
4
+ */
5
+ import { type ColourScale, type ColourType } from "../fields/colour_fields.ts";
6
+ /**
7
+ * Write a real value the way legends and hovers show it.
8
+ *
9
+ * @param value - The number.
10
+ * @returns It with thousands separators, or to three significant figures when not whole.
11
+ */
12
+ export declare function formatValue(value: number): string;
13
+ /**
14
+ * Turn values into the numbers colour follows, per the layer's colour scale.
15
+ *
16
+ * @param values - The layer's numbers (null where missing).
17
+ * @param options - The scale, the column's name, and where to put notes.
18
+ * @returns The transformed values, and legend ticks in real values when the scale transforms them.
19
+ */
20
+ export declare function applyColourScale(values: (number | null)[], options: {
21
+ scale: ColourScale | undefined;
22
+ label: string;
23
+ notes: string[];
24
+ }): {
25
+ values: (number | null)[];
26
+ ticks: {
27
+ value: number;
28
+ text: string;
29
+ }[] | undefined;
30
+ };
31
+ /**
32
+ * The text at a colour legend's two ends, top first: the real values when
33
+ * the scale transforms them, else the column's name.
34
+ *
35
+ * @param scale - The panel's colour scale.
36
+ * @returns The top and bottom text.
37
+ */
38
+ export declare function buildColourLegendText(scale: {
39
+ label: string;
40
+ ticks?: {
41
+ value: number;
42
+ text: string;
43
+ }[];
44
+ }): [string, string];
45
+ /**
46
+ * Decide whether a column colours by a scale (numbers) or by category: what
47
+ * its values imply, unless colour_type says otherwise.
48
+ *
49
+ * @param values - The colour column's values.
50
+ * @param options - The colour_type the agent sent, if any.
51
+ * @returns True for a colour scale.
52
+ */
53
+ export declare function decideColourIsContinuous(values: (number | string | null)[], options: {
54
+ colourType: ColourType | undefined;
55
+ }): boolean;
@@ -0,0 +1,80 @@
1
+ /**
2
+ * Colour scales: how numbers map to colour, shared by charts and maps so
3
+ * `colour_scale` means the same on every plot.
4
+ */
5
+ import { DEFAULT_COLOUR_SCALE } from "../fields/colour_fields.js";
6
+ import { getNumberRange } from "../table/get_number_range.js";
7
+ import { describeCount } from "./palette.js";
8
+ /** Where quantile legends put their labels (0 = lowest, 1 = highest). */
9
+ const QUANTILE_TICKS = [0, 0.25, 0.5, 0.75, 1];
10
+ /**
11
+ * Write a real value the way legends and hovers show it.
12
+ *
13
+ * @param value - The number.
14
+ * @returns It with thousands separators, or to three significant figures when not whole.
15
+ */
16
+ export function formatValue(value) {
17
+ return Number.isInteger(value) ? value.toLocaleString("en-US") : value.toPrecision(3);
18
+ }
19
+ /**
20
+ * Turn values into the numbers colour follows, per the layer's colour scale.
21
+ *
22
+ * @param values - The layer's numbers (null where missing).
23
+ * @param options - The scale, the column's name, and where to put notes.
24
+ * @returns The transformed values, and legend ticks in real values when the scale transforms them.
25
+ */
26
+ export function applyColourScale(values, options) {
27
+ const scale = options.scale ?? DEFAULT_COLOUR_SCALE;
28
+ if (scale === "linear")
29
+ return { values, ticks: undefined };
30
+ if (scale === "log") {
31
+ const dropped = values.filter((value) => value !== null && value <= 0).length;
32
+ if (dropped > 0) {
33
+ const droppedValues = describeCount(dropped, { singular: `value of "${options.label}" is`, plural: `values of "${options.label}" are` });
34
+ options.notes.push(`${droppedValues} zero or negative, which a log scale cannot show; ${dropped === 1 ? "it is" : "they are"} left grey.`);
35
+ }
36
+ const logs = values.map((value) => (value === null || value <= 0 ? null : Math.log10(value)));
37
+ const present = logs.filter((value) => value !== null);
38
+ const ticks = [];
39
+ const logRange = getNumberRange(present);
40
+ for (let power = Math.ceil(logRange.minimum); power <= Math.floor(logRange.maximum); power += 1)
41
+ ticks.push({ value: power, text: formatValue(10 ** power) });
42
+ return { values: logs, ticks };
43
+ }
44
+ // Quantile: each value becomes its rank from 0 to 1, so colour steps hold equal numbers of places.
45
+ const sorted = values.filter((value) => value !== null).sort((first, second) => first - second);
46
+ // First sorted position of each value, built once; NaN is left out so it ranks -1 like indexOf, which never matches NaN.
47
+ const firstPositions = new Map();
48
+ sorted.forEach((value, position) => {
49
+ if (!Number.isNaN(value) && !firstPositions.has(value))
50
+ firstPositions.set(value, position);
51
+ });
52
+ const rank = (value) => (sorted.length <= 1 ? 0 : (firstPositions.get(value) ?? -1) / (sorted.length - 1));
53
+ const ticks = QUANTILE_TICKS.map((fraction) => ({ value: fraction, text: formatValue(sorted[Math.round(fraction * (sorted.length - 1))] ?? 0) }));
54
+ return { values: values.map((value) => (value === null ? null : rank(value))), ticks };
55
+ }
56
+ /**
57
+ * The text at a colour legend's two ends, top first: the real values when
58
+ * the scale transforms them, else the column's name.
59
+ *
60
+ * @param scale - The panel's colour scale.
61
+ * @returns The top and bottom text.
62
+ */
63
+ export function buildColourLegendText(scale) {
64
+ if (scale.ticks === undefined)
65
+ return [scale.label, ""];
66
+ return [scale.ticks.at(-1)?.text ?? "", scale.ticks[0]?.text ?? ""];
67
+ }
68
+ /**
69
+ * Decide whether a column colours by a scale (numbers) or by category: what
70
+ * its values imply, unless colour_type says otherwise.
71
+ *
72
+ * @param values - The colour column's values.
73
+ * @param options - The colour_type the agent sent, if any.
74
+ * @returns True for a colour scale.
75
+ */
76
+ export function decideColourIsContinuous(values, options) {
77
+ if (options.colourType !== undefined)
78
+ return options.colourType === "continuous";
79
+ return values.every((value) => value === null || typeof value === "number");
80
+ }
@@ -0,0 +1,176 @@
1
+ /**
2
+ * Colours and marks for plots, from the dataviz skill's validated reference
3
+ * palette: its dark column for the dark theme, its light column for light.
4
+ *
5
+ * Rules carried over from that skill:
6
+ * - categorical hues are assigned in this fixed order, never cycled or generated;
7
+ * - more than MAXIMUM_COLOUR_CATEGORIES categories is refused (facet or fold to "Other" instead);
8
+ * - where every pair of categories can sit side by side (scatter), only the
9
+ * first 3 hues stay distinguishable, so past 3 the marker shape varies too;
10
+ * - sequential colour is one hue, light to dark; text never wears series colour.
11
+ */
12
+ /** The viewer's two themes; each device picks one. */
13
+ export type PlotTheme = "dark" | "light";
14
+ /** The theme when none is asked for: the viewer is a dark "TV" by default. */
15
+ export declare const DEFAULT_PLOT_THEME: PlotTheme;
16
+ /** Surface, inks and categorical slots per theme (dataviz reference palette; its light and dark columns). */
17
+ export type ThemeInks = {
18
+ surface: string;
19
+ textPrimary: string;
20
+ textSecondary: string;
21
+ gridLine: string;
22
+ /** Categorical slots 1–8, in the validated order. */
23
+ categorical: readonly string[];
24
+ };
25
+ /** Each theme's inks: surface, text, grid lines and the categorical colours. */
26
+ export declare const PLOT_THEMES: Readonly<Record<PlotTheme, ThemeInks>>;
27
+ /** How many categories colour can tell apart (the palette's slot count). */
28
+ export declare const MAXIMUM_COLOUR_CATEGORIES: number;
29
+ /** How many categories can share a scatter by colour alone (all-pairs validated). */
30
+ export declare const ALL_PAIRS_COLOUR_LIMIT = 3;
31
+ /** The single-hue sequential ramp (blue), light to dark, for continuous colour. */
32
+ export declare const SEQUENTIAL_COLOURS: readonly string[];
33
+ /** Line dash styles, in order, for `line_type` categories. */
34
+ export declare const LINE_DASHES: readonly ["solid", "dashed", "dotted", "dash_dot"];
35
+ /** A line's dash pattern, one of LINE_DASHES. */
36
+ export type LineDash = (typeof LINE_DASHES)[number];
37
+ /** Marker shapes, in order, for `marker_shape` categories. */
38
+ export declare const MARKER_SHAPES: readonly ["circle", "square", "triangle", "diamond", "cross", "star"];
39
+ /** A point's marker shape, one of MARKER_SHAPES. */
40
+ export type MarkerShape = (typeof MARKER_SHAPES)[number];
41
+ /** Mark sizes from the dataviz skill: 2px lines, markers of at least 8px. */
42
+ export declare const LINE_WIDTH = 2;
43
+ /** A marker's size in pixels: at least 8 px, so it reads at a glance (dataviz skill). */
44
+ export declare const MARKER_SIZE = 8;
45
+ /** Marker sizes for a `size` column, in pixels, smallest to largest. */
46
+ export declare const SIZE_RANGE_PIXELS: {
47
+ minimum: number;
48
+ maximum: number;
49
+ };
50
+ /** The thinnest and thickest a map line drawn by a width column is, in pixels. */
51
+ export declare const LINE_WIDTH_RANGE_PIXELS: {
52
+ minimum: number;
53
+ maximum: number;
54
+ };
55
+ /** A map line's width in pixels when the layer has no width column. */
56
+ export declare const DEFAULT_LINE_WIDTH_PIXELS = 2.5;
57
+ /**
58
+ * Scale a column's numbers linearly onto a pixel range, smallest to the
59
+ * range's minimum and largest to its maximum. A missing value, or a column
60
+ * whose numbers are all equal, gets the fallback.
61
+ *
62
+ * @param values - The numbers, null where missing.
63
+ * @param options - The pixel range, and the size for a value that cannot be placed on it.
64
+ * @returns A pixel size per value.
65
+ */
66
+ export declare function scaleToPixels(values: readonly (number | null)[], options: {
67
+ range: {
68
+ minimum: number;
69
+ maximum: number;
70
+ };
71
+ fallback: number;
72
+ }): number[];
73
+ /**
74
+ * Describe a count in words, singular for one: `1 category`, `3 categories`.
75
+ * It lives in colour because every group that words a count reads it: refusals (figure), notes (model), unmatched-row
76
+ * messages (map) and colour scale notes (colour), and colour is the lowest group all of them read.
77
+ *
78
+ * @param count - How many.
79
+ * @param options - The noun, singular and plural.
80
+ * @returns The count and the noun in the number the count needs.
81
+ */
82
+ export declare function describeCount(count: number, options: {
83
+ singular: string;
84
+ plural: string;
85
+ }): string;
86
+ /**
87
+ * Count the categories that keep their own hue, shape or dash when the rest are grouped in one "Other" category:
88
+ * "Other" takes one of the field's slots too, so one fewer than the field tells apart.
89
+ *
90
+ * @param options - How many categories the field tells apart.
91
+ * @returns How many categories keep their own slot beside "Other".
92
+ */
93
+ export declare function countCategoriesKeptBesideOther(options: {
94
+ limit: number;
95
+ }): number;
96
+ /**
97
+ * Advise grouping a field's categories so they fit its limit: the clause names how many to keep, so following it fits.
98
+ *
99
+ * @param options - How many categories the field tells apart, and what the categories can be split across instead
100
+ * ("plots in a grid", "layers").
101
+ * @returns The clause, starting lower case, for the caller to lead with "Put".
102
+ */
103
+ export declare function adviseGroupingIntoOther(options: {
104
+ limit: number;
105
+ splitAcross: string;
106
+ }): string;
107
+ /**
108
+ * Advise a plot whose drawn categories in one field are too many, naming how many keep their own slot beside "Other".
109
+ *
110
+ * @param options - How many categories the field tells apart.
111
+ * @returns The advice, one sentence.
112
+ */
113
+ export declare function advisePlotGrouping(options: {
114
+ limit: number;
115
+ }): string;
116
+ /**
117
+ * Pick the colour for the n-th category.
118
+ *
119
+ * @param index - The category's position in first-seen order (0-based).
120
+ * @param options - The theme it is drawn in.
121
+ * @returns Its hex colour.
122
+ */
123
+ export declare function pickCategoricalColour(index: number, options: {
124
+ theme: PlotTheme;
125
+ }): string;
126
+ /**
127
+ * Pick the dash for the n-th line_type category.
128
+ *
129
+ * @param index - The category's position (0-based).
130
+ * @returns The dash style.
131
+ */
132
+ export declare function pickLineDash(index: number): LineDash;
133
+ /**
134
+ * Pick the marker shape for the n-th category.
135
+ *
136
+ * @param index - The category's position (0-based).
137
+ * @returns The shape.
138
+ */
139
+ export declare function pickMarkerShape(index: number): MarkerShape;
140
+ /**
141
+ * Pick a colour along the sequential ramp.
142
+ *
143
+ * @param fraction - 0 (lightest) to 1 (darkest); clamped.
144
+ * @returns The nearest ramp step.
145
+ */
146
+ export declare function pickSequentialColour(fraction: number): string;
147
+ /** The radix of hexadecimal digits, for colour channels and hashed names. */
148
+ export declare const HEXADECIMAL = 16;
149
+ /** The number of hexadecimal digits in one colour channel of a `#rrggbb` colour. */
150
+ export declare const CHANNEL_DIGITS = 2;
151
+ /**
152
+ * Blend a value's colour along a ramp exactly as ECharts' continuous
153
+ * visualMap does (zrender's fastLerp over the ramp's evenly spaced stops,
154
+ * after echarts' clamped linearMap): each channel interpolated between the
155
+ * two nearest stops and rounded. A renderer that paints a colour itself,
156
+ * where a visualMap cannot reach, then matches the colour bar to the byte.
157
+ *
158
+ * @param value - The value to colour.
159
+ * @param options - The scale's range, and the ramp's colours as `#rrggbb`.
160
+ * @returns The colour as `#rrggbb`.
161
+ */
162
+ export declare function interpolateRampColour(value: number, options: {
163
+ minimum: number;
164
+ maximum: number;
165
+ colours: readonly string[];
166
+ }): string;
167
+ /** Land, water and borders for maps drawn without street tiles (globe, ECharts), per theme. */
168
+ export declare const MAP_INKS: Readonly<Record<PlotTheme, {
169
+ land: string;
170
+ water: string;
171
+ border: string;
172
+ }>>;
173
+ /** The font OpenFreeMap serves for map labels; any other font's glyphs 404 on its server. */
174
+ export declare const MAP_LABEL_FONT = "Noto Sans Regular";
175
+ /** The street-map style (OpenFreeMap: free, no key; attribution is added by the map library) per theme. */
176
+ export declare const MAP_STYLE_URLS: Readonly<Record<PlotTheme, string>>;
@@ -0,0 +1,220 @@
1
+ /**
2
+ * Colours and marks for plots, from the dataviz skill's validated reference
3
+ * palette: its dark column for the dark theme, its light column for light.
4
+ *
5
+ * Rules carried over from that skill:
6
+ * - categorical hues are assigned in this fixed order, never cycled or generated;
7
+ * - more than MAXIMUM_COLOUR_CATEGORIES categories is refused (facet or fold to "Other" instead);
8
+ * - where every pair of categories can sit side by side (scatter), only the
9
+ * first 3 hues stay distinguishable, so past 3 the marker shape varies too;
10
+ * - sequential colour is one hue, light to dark; text never wears series colour.
11
+ */
12
+ import { getNumberRange } from "../table/get_number_range.js";
13
+ /** The theme when none is asked for: the viewer is a dark "TV" by default. */
14
+ export const DEFAULT_PLOT_THEME = "dark";
15
+ /** Each theme's inks: surface, text, grid lines and the categorical colours. */
16
+ export const PLOT_THEMES = {
17
+ dark: {
18
+ surface: "#1a1a19",
19
+ textPrimary: "#ffffff",
20
+ textSecondary: "#c3c2b7",
21
+ gridLine: "#383835",
22
+ categorical: ["#3987e5", "#d95926", "#199e70", "#c98500", "#d55181", "#008300", "#9085e9", "#e66767"],
23
+ },
24
+ light: {
25
+ surface: "#fcfcfb",
26
+ textPrimary: "#0b0b0b",
27
+ textSecondary: "#52514e",
28
+ // Recessive grid: the palette's neutral midpoint, a step below the surface.
29
+ gridLine: "#e4e3df",
30
+ categorical: ["#2a78d6", "#eb6834", "#1baf7a", "#eda100", "#e87ba4", "#008300", "#4a3aa7", "#e34948"],
31
+ },
32
+ };
33
+ /** How many categories colour can tell apart (the palette's slot count). */
34
+ export const MAXIMUM_COLOUR_CATEGORIES = PLOT_THEMES.dark.categorical.length;
35
+ /** How many categories can share a scatter by colour alone (all-pairs validated). */
36
+ export const ALL_PAIRS_COLOUR_LIMIT = 3;
37
+ /** The single-hue sequential ramp (blue), light to dark, for continuous colour. */
38
+ export const SEQUENTIAL_COLOURS = [
39
+ "#cde2fb", "#b7d3f6", "#9ec5f4", "#86b6ef", "#6da7ec", "#5598e7", "#3987e5",
40
+ "#2a78d6", "#256abf", "#1c5cab", "#184f95", "#104281", "#0d366b",
41
+ ];
42
+ /** Line dash styles, in order, for `line_type` categories. */
43
+ export const LINE_DASHES = ["solid", "dashed", "dotted", "dash_dot"];
44
+ /** Marker shapes, in order, for `marker_shape` categories. */
45
+ export const MARKER_SHAPES = ["circle", "square", "triangle", "diamond", "cross", "star"];
46
+ /** Mark sizes from the dataviz skill: 2px lines, markers of at least 8px. */
47
+ export const LINE_WIDTH = 2;
48
+ /** A marker's size in pixels: at least 8 px, so it reads at a glance (dataviz skill). */
49
+ export const MARKER_SIZE = 8;
50
+ /** Marker sizes for a `size` column, in pixels, smallest to largest. */
51
+ export const SIZE_RANGE_PIXELS = { minimum: MARKER_SIZE, maximum: 28 };
52
+ /** The thinnest and thickest a map line drawn by a width column is, in pixels. */
53
+ export const LINE_WIDTH_RANGE_PIXELS = { minimum: 1.5, maximum: 8 };
54
+ /** A map line's width in pixels when the layer has no width column. */
55
+ export const DEFAULT_LINE_WIDTH_PIXELS = 2.5;
56
+ /**
57
+ * Scale a column's numbers linearly onto a pixel range, smallest to the
58
+ * range's minimum and largest to its maximum. A missing value, or a column
59
+ * whose numbers are all equal, gets the fallback.
60
+ *
61
+ * @param values - The numbers, null where missing.
62
+ * @param options - The pixel range, and the size for a value that cannot be placed on it.
63
+ * @returns A pixel size per value.
64
+ */
65
+ export function scaleToPixels(values, options) {
66
+ const present = values.filter((value) => value !== null);
67
+ const { minimum: low, maximum: high } = getNumberRange(present);
68
+ const span = options.range.maximum - options.range.minimum;
69
+ return values.map((value) => (value === null || high === low ? options.fallback : options.range.minimum + ((value - low) / (high - low)) * span));
70
+ }
71
+ /**
72
+ * Describe a count in words, singular for one: `1 category`, `3 categories`.
73
+ * It lives in colour because every group that words a count reads it: refusals (figure), notes (model), unmatched-row
74
+ * messages (map) and colour scale notes (colour), and colour is the lowest group all of them read.
75
+ *
76
+ * @param count - How many.
77
+ * @param options - The noun, singular and plural.
78
+ * @returns The count and the noun in the number the count needs.
79
+ */
80
+ export function describeCount(count, options) {
81
+ return `${count} ${count === 1 ? options.singular : options.plural}`;
82
+ }
83
+ /**
84
+ * Count the categories that keep their own hue, shape or dash when the rest are grouped in one "Other" category:
85
+ * "Other" takes one of the field's slots too, so one fewer than the field tells apart.
86
+ *
87
+ * @param options - How many categories the field tells apart.
88
+ * @returns How many categories keep their own slot beside "Other".
89
+ */
90
+ export function countCategoriesKeptBesideOther(options) {
91
+ return options.limit - 1;
92
+ }
93
+ /**
94
+ * Advise grouping a field's categories so they fit its limit: the clause names how many to keep, so following it fits.
95
+ *
96
+ * @param options - How many categories the field tells apart, and what the categories can be split across instead
97
+ * ("plots in a grid", "layers").
98
+ * @returns The clause, starting lower case, for the caller to lead with "Put".
99
+ */
100
+ export function adviseGroupingIntoOther(options) {
101
+ const keptCount = countCategoriesKeptBesideOther({ limit: options.limit });
102
+ return `the categories past the first ${keptCount} in an "Other" category, or split them across ${options.splitAcross}.`;
103
+ }
104
+ /** What a plot's categories can be split across instead of grouping them. */
105
+ const PLOT_SPLIT_ACROSS = "plots in a grid";
106
+ /**
107
+ * Advise a plot whose drawn categories in one field are too many, naming how many keep their own slot beside "Other".
108
+ *
109
+ * @param options - How many categories the field tells apart.
110
+ * @returns The advice, one sentence.
111
+ */
112
+ export function advisePlotGrouping(options) {
113
+ return `Put ${adviseGroupingIntoOther({ limit: options.limit, splitAcross: PLOT_SPLIT_ACROSS })}`;
114
+ }
115
+ /**
116
+ * Pick the colour for the n-th category.
117
+ *
118
+ * @param index - The category's position in first-seen order (0-based).
119
+ * @param options - The theme it is drawn in.
120
+ * @returns Its hex colour.
121
+ */
122
+ export function pickCategoricalColour(index, options) {
123
+ const colour = PLOT_THEMES[options.theme].categorical[index];
124
+ if (colour === undefined) {
125
+ throw new Error(`Colour can tell apart at most ${MAXIMUM_COLOUR_CATEGORIES} categories; got more. ` +
126
+ advisePlotGrouping({ limit: MAXIMUM_COLOUR_CATEGORIES }));
127
+ }
128
+ return colour;
129
+ }
130
+ /**
131
+ * Pick the dash for the n-th line_type category.
132
+ *
133
+ * @param index - The category's position (0-based).
134
+ * @returns The dash style.
135
+ */
136
+ export function pickLineDash(index) {
137
+ const dash = LINE_DASHES[index];
138
+ if (dash === undefined) {
139
+ throw new Error(`line_type can tell apart at most ${LINE_DASHES.length} categories; got more. ` + advisePlotGrouping({ limit: LINE_DASHES.length }));
140
+ }
141
+ return dash;
142
+ }
143
+ /**
144
+ * Pick the marker shape for the n-th category.
145
+ *
146
+ * @param index - The category's position (0-based).
147
+ * @returns The shape.
148
+ */
149
+ export function pickMarkerShape(index) {
150
+ const shape = MARKER_SHAPES[index];
151
+ if (shape === undefined) {
152
+ throw new Error(`marker_shape can tell apart at most ${MARKER_SHAPES.length} categories; got more. ` + advisePlotGrouping({ limit: MARKER_SHAPES.length }));
153
+ }
154
+ return shape;
155
+ }
156
+ /**
157
+ * Pick a colour along the sequential ramp.
158
+ *
159
+ * @param fraction - 0 (lightest) to 1 (darkest); clamped.
160
+ * @returns The nearest ramp step.
161
+ */
162
+ export function pickSequentialColour(fraction) {
163
+ const clamped = Math.min(1, Math.max(0, Number.isFinite(fraction) ? fraction : 0));
164
+ return SEQUENTIAL_COLOURS[Math.round(clamped * (SEQUENTIAL_COLOURS.length - 1))];
165
+ }
166
+ /** The radix of hexadecimal digits, for colour channels and hashed names. */
167
+ export const HEXADECIMAL = 16;
168
+ const HEXADECIMAL_COLOUR_PATTERN = /^#([0-9a-f]{2})([0-9a-f]{2})([0-9a-f]{2})$/i;
169
+ const CHANNEL_MAXIMUM = 255;
170
+ /** The number of hexadecimal digits in one colour channel of a `#rrggbb` colour. */
171
+ export const CHANNEL_DIGITS = 2;
172
+ /**
173
+ * Blend a value's colour along a ramp exactly as ECharts' continuous
174
+ * visualMap does (zrender's fastLerp over the ramp's evenly spaced stops,
175
+ * after echarts' clamped linearMap): each channel interpolated between the
176
+ * two nearest stops and rounded. A renderer that paints a colour itself,
177
+ * where a visualMap cannot reach, then matches the colour bar to the byte.
178
+ *
179
+ * @param value - The value to colour.
180
+ * @param options - The scale's range, and the ramp's colours as `#rrggbb`.
181
+ * @returns The colour as `#rrggbb`.
182
+ */
183
+ export function interpolateRampColour(value, options) {
184
+ const span = options.maximum - options.minimum;
185
+ // As echarts' linearMap: a range of no width maps to the middle.
186
+ const fraction = span === 0 ? 1 / 2 : Math.min(1, Math.max(0, (value - options.minimum) / span));
187
+ const position = fraction * (options.colours.length - 1);
188
+ const left = parseHexadecimalColour(options.colours[Math.floor(position)]);
189
+ const right = parseHexadecimalColour(options.colours[Math.ceil(position)]);
190
+ const step = position - Math.floor(position);
191
+ return `#${left.map((from, channel) => {
192
+ const to = right[channel] ?? from;
193
+ const mixed = Math.min(CHANNEL_MAXIMUM, Math.max(0, Math.round(from + (to - from) * step)));
194
+ return mixed.toString(HEXADECIMAL).padStart(CHANNEL_DIGITS, "0");
195
+ }).join("")}`;
196
+ }
197
+ /**
198
+ * Read a `#rrggbb` colour's channels.
199
+ *
200
+ * @param colour - The colour.
201
+ * @returns Its red, green and blue, 0 to 255.
202
+ */
203
+ function parseHexadecimalColour(colour) {
204
+ const match = HEXADECIMAL_COLOUR_PATTERN.exec(colour ?? "");
205
+ if (match === null)
206
+ throw new Error(`Expected a ramp colour written #rrggbb; got ${String(colour)}.`);
207
+ return match.slice(1).map((digits) => Number.parseInt(digits, HEXADECIMAL));
208
+ }
209
+ /** Land, water and borders for maps drawn without street tiles (globe, ECharts), per theme. */
210
+ export const MAP_INKS = {
211
+ dark: { land: "#2a2b2f", water: "#141518", border: "#4a4b51" },
212
+ light: { land: "#fcfcfb", water: "#e9edf1", border: "#c9c8c2" },
213
+ };
214
+ /** The font OpenFreeMap serves for map labels; any other font's glyphs 404 on its server. */
215
+ export const MAP_LABEL_FONT = "Noto Sans Regular";
216
+ /** The street-map style (OpenFreeMap: free, no key; attribution is added by the map library) per theme. */
217
+ export const MAP_STYLE_URLS = {
218
+ dark: "https://tiles.openfreemap.org/styles/dark",
219
+ light: "https://tiles.openfreemap.org/styles/positron",
220
+ };
@@ -0,0 +1,56 @@
1
+ /**
2
+ * The fields of every plot drawn on x and y axes. Each describes its column,
3
+ * whatever the orientation: on horizontal bars, x_label titles the vertical
4
+ * axis, because that is where x is drawn.
5
+ */
6
+ import { z } from "zod";
7
+ /** How an axis may space numbers. */
8
+ export declare const AXIS_SCALES: readonly ["linear", "log"];
9
+ /** One of AXIS_SCALES. */
10
+ export type AxisScale = (typeof AXIS_SCALES)[number];
11
+ /** The scale an axis gets when the agent names none. */
12
+ export declare const DEFAULT_AXIS_SCALE: AxisScale;
13
+ /** The axis titles, on every plot drawn on axes. */
14
+ export declare const AXIS_LABEL_FIELDS: {
15
+ x_label: z.ZodOptional<z.ZodString>;
16
+ y_label: z.ZodOptional<z.ZodString>;
17
+ };
18
+ /** The x column's scale: only on plots whose x axis can space numbers (a bar's or a box's x is categories, a histogram's x is equal bins). */
19
+ export declare const X_SCALE_FIELDS: {
20
+ x_scale: z.ZodDefault<z.ZodEnum<{
21
+ linear: "linear";
22
+ log: "log";
23
+ }>>;
24
+ };
25
+ /** The y column's scale: only on plots whose y is numbers (a heatmap's y is categories, so it refuses it). */
26
+ export declare const Y_SCALE_FIELDS: {
27
+ y_scale: z.ZodDefault<z.ZodEnum<{
28
+ linear: "linear";
29
+ log: "log";
30
+ }>>;
31
+ };
32
+ /**
33
+ * How an axis of whole numbers may be declared to print them as years. Left
34
+ * unset, an axis prints plain numbers with thousands commas (2,020): nothing
35
+ * is guessed from a column's name or values, so a count is never taken for a year.
36
+ */
37
+ export declare const AXIS_YEAR_FORMATS: readonly ["YYYY", "YY"];
38
+ /** One of AXIS_YEAR_FORMATS. */
39
+ export type AxisYearFormat = (typeof AXIS_YEAR_FORMATS)[number];
40
+ /** The x column's year format: only on plots whose x axis can hold numbers (a bar's or a box's x is categories). */
41
+ export declare const X_YEAR_FORMAT_FIELDS: {
42
+ x_year_format: z.ZodOptional<z.ZodEnum<{
43
+ YY: "YY";
44
+ YYYY: "YYYY";
45
+ }>>;
46
+ };
47
+ /**
48
+ * The y column's year format: only on a scatter's, line's or box's y. A heatmap's y is categories, a density's y is
49
+ * fractions, and a bar's length or a histogram's count is an amount from zero, never a year.
50
+ */
51
+ export declare const Y_YEAR_FORMAT_FIELDS: {
52
+ y_year_format: z.ZodOptional<z.ZodEnum<{
53
+ YY: "YY";
54
+ YYYY: "YYYY";
55
+ }>>;
56
+ };
@@ -0,0 +1,46 @@
1
+ /**
2
+ * The fields of every plot drawn on x and y axes. Each describes its column,
3
+ * whatever the orientation: on horizontal bars, x_label titles the vertical
4
+ * axis, because that is where x is drawn.
5
+ */
6
+ import { z } from "zod";
7
+ /** How an axis may space numbers. */
8
+ export const AXIS_SCALES = ["linear", "log"];
9
+ /** The scale an axis gets when the agent names none. */
10
+ export const DEFAULT_AXIS_SCALE = "linear";
11
+ const AXIS_SCALE_SCHEMA = z.enum(AXIS_SCALES).default(DEFAULT_AXIS_SCALE);
12
+ /** The axis titles, on every plot drawn on axes. */
13
+ export const AXIS_LABEL_FIELDS = {
14
+ x_label: z.string().min(1).optional().describe("The title of the axis the x column is drawn on. Default: the x column's name."),
15
+ y_label: z.string().min(1).optional().describe("The title of the axis the y column is drawn on. Default: the y column's name."),
16
+ };
17
+ /** The x column's scale: only on plots whose x axis can space numbers (a bar's or a box's x is categories, a histogram's x is equal bins). */
18
+ export const X_SCALE_FIELDS = {
19
+ x_scale: AXIS_SCALE_SCHEMA.describe("How the x column's axis spaces numbers: evenly, or by order of magnitude."),
20
+ };
21
+ /** The y column's scale: only on plots whose y is numbers (a heatmap's y is categories, so it refuses it). */
22
+ export const Y_SCALE_FIELDS = {
23
+ y_scale: AXIS_SCALE_SCHEMA.describe("How the y column's axis spaces numbers: evenly, or by order of magnitude."),
24
+ };
25
+ /**
26
+ * How an axis of whole numbers may be declared to print them as years. Left
27
+ * unset, an axis prints plain numbers with thousands commas (2,020): nothing
28
+ * is guessed from a column's name or values, so a count is never taken for a year.
29
+ */
30
+ export const AXIS_YEAR_FORMATS = ["YYYY", "YY"];
31
+ const AXIS_YEAR_FORMAT_SCHEMA = z.enum(AXIS_YEAR_FORMATS).optional();
32
+ /** The x column's year format: only on plots whose x axis can hold numbers (a bar's or a box's x is categories). */
33
+ export const X_YEAR_FORMAT_FIELDS = {
34
+ x_year_format: AXIS_YEAR_FORMAT_SCHEMA.describe('Print the x column\'s whole numbers as years: "YYYY" prints 1990, "YY" prints 90. ' +
35
+ "Default: plain numbers with thousands commas (1,990). Needs whole numbers; dates and text print as they are. " +
36
+ "The x axis's scale (x_scale) must not be \"log\": years are a calendar, not a magnitude."),
37
+ };
38
+ /**
39
+ * The y column's year format: only on a scatter's, line's or box's y. A heatmap's y is categories, a density's y is
40
+ * fractions, and a bar's length or a histogram's count is an amount from zero, never a year.
41
+ */
42
+ export const Y_YEAR_FORMAT_FIELDS = {
43
+ y_year_format: AXIS_YEAR_FORMAT_SCHEMA.describe('Print the y column\'s whole numbers as years: "YYYY" prints 1990, "YY" prints 90. ' +
44
+ "Default: plain numbers with thousands commas (1,990). Needs whole numbers. " +
45
+ "The y axis's scale (y_scale) must not be \"log\": years are a calendar, not a magnitude."),
46
+ };
@@ -0,0 +1,32 @@
1
+ /**
2
+ * The fields of plots coloured by a column. A plot that can colour by a
3
+ * number also takes COLOUR_SCALE_FIELDS; one without them colours by
4
+ * category only, and validation refuses a numeric colour there.
5
+ */
6
+ import { z } from "zod";
7
+ /** Whether a colouring column's values are categories or a scale. */
8
+ export declare const COLOUR_TYPES: readonly ["categorical", "continuous"];
9
+ /** One of COLOUR_TYPES. */
10
+ export type ColourType = (typeof COLOUR_TYPES)[number];
11
+ /** How numbers may map to colour, on charts and maps alike. */
12
+ export declare const COLOUR_SCALES: readonly ["linear", "log", "quantile"];
13
+ /** One of COLOUR_SCALES. */
14
+ export type ColourScale = (typeof COLOUR_SCALES)[number];
15
+ /** The colour scale a plot gets when the agent names none. */
16
+ export declare const DEFAULT_COLOUR_SCALE: ColourScale;
17
+ /** The fields of a plot or layer coloured by a column. */
18
+ export declare const COLOUR_FIELDS: {
19
+ colour: z.ZodOptional<z.ZodString>;
20
+ colour_type: z.ZodOptional<z.ZodEnum<{
21
+ categorical: "categorical";
22
+ continuous: "continuous";
23
+ }>>;
24
+ };
25
+ /** The field of a plot or layer that can colour by a number. */
26
+ export declare const COLOUR_SCALE_FIELDS: {
27
+ colour_scale: z.ZodOptional<z.ZodEnum<{
28
+ linear: "linear";
29
+ log: "log";
30
+ quantile: "quantile";
31
+ }>>;
32
+ };