plotilla 0.0.0-stage → 0.2.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.
- package/LICENSE +21 -0
- package/README.md +82 -2
- package/data/boundaries/canada_provinces.geojson +1 -0
- package/data/boundaries/eu_countries.geojson +1 -0
- package/data/boundaries/us_states.geojson +1 -0
- package/data/boundaries/world_countries.geojson +1 -0
- package/package.json +62 -4
- package/src/colour/colour_scale.ts +80 -0
- package/src/colour/palette.ts +220 -0
- package/src/examples/example_figures.ts +320 -0
- package/src/fields/axis_fields.ts +32 -0
- package/src/fields/colour_fields.ts +40 -0
- package/src/fields/column_fields.ts +64 -0
- package/src/fields/common_fields.ts +13 -0
- package/src/fields/decide_plot_axes.ts +77 -0
- package/src/fields/marker_fields.ts +16 -0
- package/src/figure/plot_figure.ts +67 -0
- package/src/figure/resolve_plot_figure.ts +47 -0
- package/src/figure/validate_plot_figure.ts +412 -0
- package/src/map/boundary_sets.ts +116 -0
- package/src/map/check_map_layers.ts +32 -0
- package/src/map/fetch_region_outlines.ts +48 -0
- package/src/map/geojson.ts +174 -0
- package/src/map/map_layers.ts +108 -0
- package/src/model/check_axis_shows_years.ts +58 -0
- package/src/model/map_model.ts +238 -0
- package/src/model/panel_layout.ts +171 -0
- package/src/model/panel_model.ts +85 -0
- package/src/model/plot_model.ts +347 -0
- package/src/model/statistics.ts +134 -0
- package/src/plots/bar_plot.ts +36 -0
- package/src/plots/box_plot.ts +26 -0
- package/src/plots/density_plot.ts +29 -0
- package/src/plots/heatmap_plot.ts +24 -0
- package/src/plots/histogram_plot.ts +29 -0
- package/src/plots/line_plot.ts +29 -0
- package/src/plots/map_plot.ts +46 -0
- package/src/plots/pie_plot.ts +23 -0
- package/src/plots/scatter_plot.ts +32 -0
- package/src/renderers/echarts_map.ts +194 -0
- package/src/renderers/echarts_options.ts +317 -0
- package/src/renderers/plotly_map.ts +170 -0
- package/src/renderers/plotly_options.ts +318 -0
- package/src/table/check_column.ts +34 -0
- package/src/table/check_values_have_spread.ts +47 -0
- package/src/table/compute_quantile.ts +23 -0
- package/src/table/data_table.ts +83 -0
- package/src/table/density_bandwidth.ts +94 -0
- package/src/table/find_line_fit.ts +44 -0
- package/src/table/get_number_range.ts +21 -0
- package/src/table/group_rows.ts +71 -0
- package/src/table/list_categories.ts +17 -0
|
@@ -0,0 +1,412 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Check a figure before anything is drawn. The schema checks each field on
|
|
3
|
+
* its own; this adds what needs the table or the caller's limits. Every
|
|
4
|
+
* error names the field at fault, so a caller can fix the spec in one go.
|
|
5
|
+
*/
|
|
6
|
+
|
|
7
|
+
import { z } from "zod";
|
|
8
|
+
import { COLUMN_FIELD_SCHEMAS, listMarkColumns } from "../fields/column_fields";
|
|
9
|
+
import { checkMapLayers } from "../map/check_map_layers";
|
|
10
|
+
import { LAYER_NUMERIC_COLUMNS, MAP_LAYER_SCHEMAS, type MapLayer } from "../map/map_layers";
|
|
11
|
+
import { checkColumn, checkColumnIsNumeric } from "../table/check_column";
|
|
12
|
+
import { checkRowBecomesMark, countTableRows, findColumn, type DataTable } from "../table/data_table";
|
|
13
|
+
import { checkValuesHaveSpread } from "../table/check_values_have_spread";
|
|
14
|
+
import { computeSilvermanBandwidth, findBandwidthFault } from "../table/density_bandwidth";
|
|
15
|
+
import { getNumberRange } from "../table/get_number_range";
|
|
16
|
+
import { findLineFit } from "../table/find_line_fit";
|
|
17
|
+
import { groupRows } from "../table/group_rows";
|
|
18
|
+
import { decideColourIsContinuous } from "../colour/colour_scale";
|
|
19
|
+
import { decidePlotAxes, type PlotAxis } from "../fields/decide_plot_axes";
|
|
20
|
+
import { NUMERIC_COLUMNS, PLOT_FIGURE_SCHEMA, PLOT_SCHEMAS, type Plot, type PlotFigure } from "./plot_figure";
|
|
21
|
+
|
|
22
|
+
/** What the caller allows, from its own configuration. */
|
|
23
|
+
export type PlotFigureLimits = { maximumPlots: number; maximumRows: number; maximumHistogramBins: number };
|
|
24
|
+
|
|
25
|
+
/**
|
|
26
|
+
* Validate a figure, filling in every default.
|
|
27
|
+
*
|
|
28
|
+
* @param input - The figure as the caller sent it.
|
|
29
|
+
* @param options - The caller's limits.
|
|
30
|
+
* @returns The figure, valid, with defaults filled in.
|
|
31
|
+
*/
|
|
32
|
+
export function validatePlotFigure(input: unknown, options: { limits: PlotFigureLimits }): PlotFigure {
|
|
33
|
+
const figure = parsePlotFigure(input);
|
|
34
|
+
checkPlotFigure(figure, { limits: options.limits, areOutlinesLoaded: true });
|
|
35
|
+
return figure;
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
/**
|
|
39
|
+
* Validate a figure as far as it can be before its outlines are loaded:
|
|
40
|
+
* everything but the outlines themselves, so a figure that will be refused
|
|
41
|
+
* makes the host fetch nothing.
|
|
42
|
+
*
|
|
43
|
+
* @param input - The figure as the caller sent it.
|
|
44
|
+
* @param options - The caller's limits.
|
|
45
|
+
* @returns The figure with defaults filled in, its outlines still to load.
|
|
46
|
+
*/
|
|
47
|
+
export function validatePlotFigureBeforeOutlines(input: unknown, options: { limits: PlotFigureLimits }): PlotFigure {
|
|
48
|
+
const figure = parsePlotFigure(input);
|
|
49
|
+
checkPlotFigure(figure, { limits: options.limits, areOutlinesLoaded: false });
|
|
50
|
+
return figure;
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
/**
|
|
54
|
+
* Run every check that needs the table or the caller's limits.
|
|
55
|
+
*
|
|
56
|
+
* @param figure - The figure, through the schema.
|
|
57
|
+
* @param options - The caller's limits, and whether map outlines are loaded yet.
|
|
58
|
+
*/
|
|
59
|
+
function checkPlotFigure(figure: PlotFigure, options: { limits: PlotFigureLimits; areOutlinesLoaded: boolean }): void {
|
|
60
|
+
const { limits } = options;
|
|
61
|
+
countTableRows(figure.data, { where: "data", maximumRows: limits.maximumRows });
|
|
62
|
+
if (figure.plots.length > limits.maximumPlots) throw new Error(`plots: at most ${limits.maximumPlots}; got ${figure.plots.length}.`);
|
|
63
|
+
if (figure.grid !== undefined) {
|
|
64
|
+
const room = figure.grid.rows * figure.grid.columns;
|
|
65
|
+
if (room < figure.plots.length) {
|
|
66
|
+
throw new Error(`grid: ${figure.grid.rows} x ${figure.grid.columns} has room for ${room} plot${room === 1 ? "" : "s"}; got ${figure.plots.length}.`);
|
|
67
|
+
}
|
|
68
|
+
}
|
|
69
|
+
figure.plots.forEach((plot, index) => {
|
|
70
|
+
const where = `plots[${index}]`;
|
|
71
|
+
if (plot.data !== undefined) countTableRows(plot.data, { where: `${where}.data`, maximumRows: limits.maximumRows });
|
|
72
|
+
checkPlot(plot, { table: plot.data ?? figure.data, where, limits, areOutlinesLoaded: options.areOutlinesLoaded });
|
|
73
|
+
});
|
|
74
|
+
if (figure.is_x_axis_shared) checkSharedAxes(figure, { direction: "x" });
|
|
75
|
+
if (figure.is_y_axis_shared) checkSharedAxes(figure, { direction: "y" });
|
|
76
|
+
}
|
|
77
|
+
|
|
78
|
+
/** How each axis kind is named to a caller. */
|
|
79
|
+
const AXIS_KIND_NAMES: Readonly<Record<PlotAxis["kind"], string>> = { value: "numbers", category: "categories", time: "dates" };
|
|
80
|
+
|
|
81
|
+
/**
|
|
82
|
+
* Check that a shared axis can be linked: at least two plots have it, and
|
|
83
|
+
* all of one kind and scale, since Plotly links only axes of one type and a
|
|
84
|
+
* link to an axis no plot has means nothing. Judged by the rule the model
|
|
85
|
+
* builds its axes with, after every plot's columns are checked.
|
|
86
|
+
*
|
|
87
|
+
* @param figure - The figure, its plots checked.
|
|
88
|
+
* @param options - Which axis is shared.
|
|
89
|
+
*/
|
|
90
|
+
function checkSharedAxes(figure: PlotFigure, options: { direction: "x" | "y" }): void {
|
|
91
|
+
const field = `is_${options.direction}_axis_shared`;
|
|
92
|
+
const plotsWithAxis = figure.plots.flatMap((plot, index) => {
|
|
93
|
+
const axis = decidePlotAxes(plot, { table: plot.data ?? figure.data })[options.direction];
|
|
94
|
+
return axis === null ? [] : [{ axis, where: `plots[${index}]` }];
|
|
95
|
+
});
|
|
96
|
+
const [first, ...others] = plotsWithAxis;
|
|
97
|
+
if (first === undefined || others.length === 0) {
|
|
98
|
+
throw new Error(
|
|
99
|
+
`${field}: links the ${options.direction} axes of two or more plots, and ${first === undefined ? "no plot" : `only ${first.where}`} here has one ` +
|
|
100
|
+
"(pies and maps have none); leave it out.",
|
|
101
|
+
);
|
|
102
|
+
}
|
|
103
|
+
for (const other of others) {
|
|
104
|
+
if (other.axis.kind !== first.axis.kind) {
|
|
105
|
+
throw new Error(
|
|
106
|
+
`${field}: shared ${options.direction} axes must hold one kind of value; ${first.where} has ${AXIS_KIND_NAMES[first.axis.kind]} ` +
|
|
107
|
+
`and ${other.where} ${AXIS_KIND_NAMES[other.axis.kind]}. Share only plots whose ${options.direction} axes match, or leave it out.`,
|
|
108
|
+
);
|
|
109
|
+
}
|
|
110
|
+
if (other.axis.scale !== first.axis.scale) {
|
|
111
|
+
throw new Error(
|
|
112
|
+
`${field}: shared ${options.direction} axes must have one scale; ${first.where} is "${first.axis.scale}" ` +
|
|
113
|
+
`and ${other.where} "${other.axis.scale}". Give them the same scale, or leave it out.`,
|
|
114
|
+
);
|
|
115
|
+
}
|
|
116
|
+
}
|
|
117
|
+
}
|
|
118
|
+
|
|
119
|
+
/**
|
|
120
|
+
* Check a figure's shape alone, filling in every default: what can be known
|
|
121
|
+
* before outlines are loaded and without the table's contents.
|
|
122
|
+
*
|
|
123
|
+
* @param input - The figure as the caller sent it.
|
|
124
|
+
* @returns A copy of the figure, with defaults filled in.
|
|
125
|
+
*/
|
|
126
|
+
export function parsePlotFigure(input: unknown): PlotFigure {
|
|
127
|
+
const parsed = PLOT_FIGURE_SCHEMA.safeParse(input);
|
|
128
|
+
if (!parsed.success) throw new Error(formatIssues(parsed.error.issues));
|
|
129
|
+
return parsed.data;
|
|
130
|
+
}
|
|
131
|
+
|
|
132
|
+
/**
|
|
133
|
+
* Check one plot's columns, colour and limits against its table, and a map's layers against theirs.
|
|
134
|
+
*
|
|
135
|
+
* @param plot - The plot, already through the schema.
|
|
136
|
+
* @param options - Its table, where it is in the figure, the caller's limits, and whether map outlines are loaded yet.
|
|
137
|
+
*/
|
|
138
|
+
function checkPlot(plot: Plot, options: { table: DataTable; where: string; limits: PlotFigureLimits; areOutlinesLoaded: boolean }): void {
|
|
139
|
+
const shape: Record<string, z.ZodType> = findPlotSchema(plot.type).shape;
|
|
140
|
+
checkColumnFields(plot, { shape, numericColumns: NUMERIC_COLUMNS[plot.type], table: options.table, where: options.where });
|
|
141
|
+
if (plot.type === "map") {
|
|
142
|
+
let scaledLayerWhere: string | null = null;
|
|
143
|
+
plot.layers.forEach((layer, index) => {
|
|
144
|
+
const where = `${options.where}.layers[${index}]`;
|
|
145
|
+
if (layer.data !== undefined) countTableRows(layer.data, { where: `${where}.data`, maximumRows: options.limits.maximumRows });
|
|
146
|
+
const layerShape: Record<string, z.ZodType> = findLayerSchema(layer.type).shape;
|
|
147
|
+
const layerTable = layer.data ?? options.table;
|
|
148
|
+
checkColumnFields(layer, { shape: layerShape, numericColumns: LAYER_NUMERIC_COLUMNS[layer.type], table: layerTable, where });
|
|
149
|
+
// Points and lines are drawn where every coordinate is a number; which regions match an outline is known only once outlines load.
|
|
150
|
+
const coordinates = layer.type === "points" ? [layer.longitude, layer.latitude]
|
|
151
|
+
: layer.type === "lines" ? [layer.from_longitude, layer.from_latitude, layer.to_longitude, layer.to_latitude] : [];
|
|
152
|
+
const isDrawn = (row: number): boolean => checkRowBecomesMark(layerTable, { row, present: [], numeric: coordinates });
|
|
153
|
+
const colourField = layer.type === "regions" ? "value" : "colour";
|
|
154
|
+
const isScaled = layer.type === "regions" || layer.type === "points" || layer.type === "lines"
|
|
155
|
+
? checkColourValues(layer, { colourField, isAlwaysScaled: false, isDrawn, table: layerTable, where })
|
|
156
|
+
: false;
|
|
157
|
+
// A map shows one colour scale: a second layer colouring by a number has nowhere to show its own.
|
|
158
|
+
if (isScaled) {
|
|
159
|
+
if (scaledLayerWhere !== null) {
|
|
160
|
+
throw new Error(`${where}.${colourField}: a map can colour by one number at a time, and ${scaledLayerWhere} already does; colour this layer by category, or leave its colour out.`);
|
|
161
|
+
}
|
|
162
|
+
scaledLayerWhere = where;
|
|
163
|
+
}
|
|
164
|
+
if (layer.type === "density" && layer.weight !== undefined) checkWeightsAreNotNegative(layerTable, { column: layer.weight, where });
|
|
165
|
+
});
|
|
166
|
+
checkMapLayers(plot.layers, { isGlobe: plot.projection === "globe", areOutlinesLoaded: options.areOutlinesLoaded, where: options.where });
|
|
167
|
+
return;
|
|
168
|
+
}
|
|
169
|
+
if ("colour" in plot && plot.colour !== undefined && !("colour_scale" in shape)) {
|
|
170
|
+
const isContinuous = plot.colour_type === "continuous"
|
|
171
|
+
|| (plot.colour_type === undefined && checkColumnIsNumeric(options.table, { column: plot.colour }));
|
|
172
|
+
if (isContinuous) {
|
|
173
|
+
throw new Error(
|
|
174
|
+
`${options.where}.colour: a ${plot.type} plot cannot colour by a number, having no single value per mark. ` +
|
|
175
|
+
'Use a column of categories, or colour_type "categorical".',
|
|
176
|
+
);
|
|
177
|
+
}
|
|
178
|
+
}
|
|
179
|
+
// One rule for which rows become marks, shared with the model, so a range is never judged on rows it will not draw.
|
|
180
|
+
const colour = "colour" in plot ? plot.colour : undefined;
|
|
181
|
+
const isColourCategorical = colour !== undefined && !decideColourIsContinuous(findColumn(options.table, { column: colour }) ?? [], { colourType: "colour_type" in plot ? plot.colour_type : undefined });
|
|
182
|
+
const markColumns = listMarkColumns(plot, { isColourCategorical });
|
|
183
|
+
const isDrawn = (row: number): boolean => checkRowBecomesMark(options.table, { row, ...markColumns });
|
|
184
|
+
if (plot.type === "heatmap") {
|
|
185
|
+
checkColourValues(plot, { colourField: "value", isAlwaysScaled: true, isDrawn, table: options.table, where: options.where });
|
|
186
|
+
} else if ("colour_scale" in shape) {
|
|
187
|
+
checkColourValues(plot, { colourField: "colour", isAlwaysScaled: false, isDrawn, table: options.table, where: options.where });
|
|
188
|
+
}
|
|
189
|
+
// A histogram or density draws the rows with a number in x and, coloured by category, a category: with none there is nothing to draw.
|
|
190
|
+
const rowCount = countTableRows(options.table, { where: options.where, maximumRows: options.limits.maximumRows });
|
|
191
|
+
if ((plot.type === "histogram" || plot.type === "density") && !Array.from({ length: rowCount }, (_, row) => row).some(isDrawn)) {
|
|
192
|
+
throw new Error(plot.colour === undefined
|
|
193
|
+
? `${options.where}.x: "${plot.x}" has no numbers to draw.`
|
|
194
|
+
: `${options.where}.x: no row has both a number in "${plot.x}" and a "${plot.colour}" category, so there is nothing to draw.`);
|
|
195
|
+
}
|
|
196
|
+
// Each curve's bandwidth is the caller's or, with none, worked out from its spread; it is judged by the same rule the model draws with.
|
|
197
|
+
if (plot.type === "density") {
|
|
198
|
+
const xValues = findColumn(options.table, { column: plot.x }) ?? [];
|
|
199
|
+
const colourValues = plot.colour === undefined ? null : findColumn(options.table, { column: plot.colour });
|
|
200
|
+
const numbersByCategory = new Map<string, number[]>();
|
|
201
|
+
for (let row = 0; row < rowCount; row += 1) {
|
|
202
|
+
if (!isDrawn(row)) continue;
|
|
203
|
+
const category = colourValues === null ? "" : String(colourValues[row]);
|
|
204
|
+
// A drawn row's x is a finite number, by the drawn-rows rule.
|
|
205
|
+
const numbers = numbersByCategory.get(category) ?? [];
|
|
206
|
+
numbers.push(xValues[row] as number);
|
|
207
|
+
numbersByCategory.set(category, numbers);
|
|
208
|
+
}
|
|
209
|
+
// Every curve spans the range of all drawn numbers, so they line up.
|
|
210
|
+
const drawnNumbers = Array.from(numbersByCategory.values()).flat();
|
|
211
|
+
const { minimum, maximum } = getNumberRange(drawnNumbers);
|
|
212
|
+
// A data range that overflows defeats every bandwidth, so it is the numbers in x that must change.
|
|
213
|
+
if (!Number.isFinite(maximum - minimum)) {
|
|
214
|
+
throw new Error(`${options.where}.x: the numbers in "${plot.x}" run from ${minimum} to ${maximum}, a range too wide for a number to hold, so no curve width can draw them.`);
|
|
215
|
+
}
|
|
216
|
+
const describeCategory = (category: string): string => (colourValues === null ? "" : ` in "${plot.colour}" category "${category}"`);
|
|
217
|
+
for (const [category, numbers] of numbersByCategory) {
|
|
218
|
+
if (plot.bandwidth === undefined && !checkValuesHaveSpread(numbers)) {
|
|
219
|
+
throw new Error(colourValues === null
|
|
220
|
+
? `${options.where}.x: a density needs numbers in "${plot.x}" whose spread is measurable (not all equal, nor so close together or far apart that it underflows or overflows) to work out its curve's width; set \`bandwidth\` to draw one anyway.`
|
|
221
|
+
: `${options.where}.x: a density needs numbers in "${plot.x}" whose spread is measurable (not all equal, nor so close together or far apart that it underflows or overflows) in each "${plot.colour}" category, and "${category}" has none; set \`bandwidth\` to draw one anyway.`);
|
|
222
|
+
}
|
|
223
|
+
const bandwidth = plot.bandwidth ?? computeSilvermanBandwidth(numbers);
|
|
224
|
+
const fault = findBandwidthFault({ count: numbers.length, minimum, maximum, bandwidth });
|
|
225
|
+
if (fault === null) continue;
|
|
226
|
+
throw new Error(plot.bandwidth === undefined
|
|
227
|
+
? `${options.where}.x: a density's curve width, worked out from the numbers in "${plot.x}"${describeCategory(category)} (Silverman's rule), is ${bandwidth}, which ${fault}; set \`bandwidth\` to draw one anyway.`
|
|
228
|
+
: `${options.where}.bandwidth: ${bandwidth}${describeCategory(category)} ${fault}; choose one nearer the spread of "${plot.x}".`);
|
|
229
|
+
}
|
|
230
|
+
}
|
|
231
|
+
// The model fits one trend line per series over its drawn rows, on a value x axis, by the same fit as here.
|
|
232
|
+
if (plot.type === "scatter" && plot.show_trend_line && decidePlotAxes(plot, { table: options.table }).x?.kind === "value") {
|
|
233
|
+
const xValues = findColumn(options.table, { column: plot.x }) ?? [];
|
|
234
|
+
const yValues = findColumn(options.table, { column: plot.y }) ?? [];
|
|
235
|
+
const { groups } = groupRows(options.table, { rowCount, colour: isColourCategorical ? colour : undefined, style: plot.marker_shape, isDrawn });
|
|
236
|
+
for (const group of groups) {
|
|
237
|
+
// A drawn row's x and y are finite numbers, by the drawn-rows rule.
|
|
238
|
+
if (findLineFit(group.rows.map((row) => ({ x: xValues[row] as number, y: yValues[row] as number }))) !== null) continue;
|
|
239
|
+
const seriesClause = group.name === "" ? "" : ` in each series, and "${group.name}" does not`;
|
|
240
|
+
throw new Error(
|
|
241
|
+
`${options.where}.show_trend_line: a trend line is a least-squares fit, which needs drawn rows with at least two different numbers in "${plot.x}", ` +
|
|
242
|
+
`at a scale where the fit neither underflows nor overflows${seriesClause}; ` +
|
|
243
|
+
"leave the trend line out, or give it rows whose x values differ by an amount a line can be fitted to, with x and y small enough not to overflow.",
|
|
244
|
+
);
|
|
245
|
+
}
|
|
246
|
+
}
|
|
247
|
+
if (plot.type === "pie") {
|
|
248
|
+
const negative = (findColumn(options.table, { column: plot.value }) ?? []).find((value) => typeof value === "number" && value < 0);
|
|
249
|
+
if (negative !== undefined) throw new Error(`${options.where}.value: a slice is a share of the whole and cannot be negative; "${plot.value}" has ${negative}.`);
|
|
250
|
+
}
|
|
251
|
+
// A log scale spaces numbers; a column of text is drawn as categories, which it cannot space.
|
|
252
|
+
if ((plot.type === "line" || plot.type === "scatter") && plot.x_scale === "log" && !checkColumnIsNumeric(options.table, { column: plot.x })) {
|
|
253
|
+
throw new Error(`${options.where}.x_scale: "log" needs a column of numbers; "${plot.x}" holds text, drawn as categories.`);
|
|
254
|
+
}
|
|
255
|
+
// A log axis has nowhere to put zero or less: it needs a positive number to show.
|
|
256
|
+
// A histogram's or density's y is counts the model works out, never a column.
|
|
257
|
+
const scaledColumns = [
|
|
258
|
+
{ field: "x_scale", scale: "x_scale" in plot ? plot.x_scale : undefined, column: "x" in plot ? plot.x : undefined },
|
|
259
|
+
{ field: "y_scale", scale: "y_scale" in plot ? plot.y_scale : undefined, column: plot.type === "histogram" || plot.type === "density" ? undefined : ("y" in plot ? plot.y : undefined) },
|
|
260
|
+
];
|
|
261
|
+
for (const { field, scale, column } of scaledColumns) {
|
|
262
|
+
if (scale !== "log" || column === undefined) continue;
|
|
263
|
+
const hasPositive = (findColumn(options.table, { column }) ?? []).some((value, row) => isDrawn(row) && typeof value === "number" && value > 0);
|
|
264
|
+
if (!hasPositive) throw new Error(`${options.where}.${field}: a log scale needs at least one positive number; "${column}" has none.`);
|
|
265
|
+
}
|
|
266
|
+
if (plot.type === "histogram" && plot.bins !== undefined && plot.bins > options.limits.maximumHistogramBins) {
|
|
267
|
+
throw new Error(`${options.where}.bins: at most ${options.limits.maximumHistogramBins}; got ${plot.bins}.`);
|
|
268
|
+
}
|
|
269
|
+
}
|
|
270
|
+
|
|
271
|
+
/**
|
|
272
|
+
* Check every field of a plot or map layer that names a column, and that
|
|
273
|
+
* colour_type comes with the column it describes.
|
|
274
|
+
*
|
|
275
|
+
* @param record - The plot or layer, through the schema.
|
|
276
|
+
* @param options - Its schema's fields, which columns must be numeric, its table, and where it is.
|
|
277
|
+
*/
|
|
278
|
+
function checkColumnFields(
|
|
279
|
+
record: object,
|
|
280
|
+
options: { shape: Record<string, z.ZodType>; numericColumns: readonly string[]; table: DataTable; where: string },
|
|
281
|
+
): void {
|
|
282
|
+
const values = record as Record<string, unknown>;
|
|
283
|
+
for (const [field, schema] of Object.entries(options.shape)) {
|
|
284
|
+
const column = values[field];
|
|
285
|
+
if (!COLUMN_FIELD_SCHEMAS.has(unwrapField(schema)) || typeof column !== "string") continue;
|
|
286
|
+
checkColumn(options.table, { column, field, where: options.where, isNumeric: options.numericColumns.includes(field) });
|
|
287
|
+
}
|
|
288
|
+
// A regions layer is coloured by its value; everything else by colour.
|
|
289
|
+
const colourField = values.type === "regions" ? "value" : "colour";
|
|
290
|
+
if (values.colour_type !== undefined && values[colourField] === undefined) {
|
|
291
|
+
throw new Error(`${options.where}.colour_type: only meaningful with \`${colourField}\`.`);
|
|
292
|
+
}
|
|
293
|
+
}
|
|
294
|
+
|
|
295
|
+
/**
|
|
296
|
+
* Check a colour that follows a scale has values the scale can show:
|
|
297
|
+
* colour_type "continuous" needs numbers, and the scale needs at least one
|
|
298
|
+
* number (a positive one, on a log scale). Without one the range is empty.
|
|
299
|
+
*
|
|
300
|
+
* @param record - The plot or layer, through the schema.
|
|
301
|
+
* @param options - Which field names the colouring column, whether it is always a scale (a heatmap's value), which rows become marks, its table, and where it is.
|
|
302
|
+
* @returns Whether the colour is a scale.
|
|
303
|
+
*/
|
|
304
|
+
function checkColourValues(
|
|
305
|
+
record: object,
|
|
306
|
+
options: { colourField: "colour" | "value"; isAlwaysScaled: boolean; isDrawn: (row: number) => boolean; table: DataTable; where: string },
|
|
307
|
+
): boolean {
|
|
308
|
+
const values = record as Record<string, unknown>;
|
|
309
|
+
const column = values[options.colourField];
|
|
310
|
+
if (typeof column !== "string") {
|
|
311
|
+
if (values.colour_scale !== undefined) throw new Error(`${options.where}.colour_scale: only meaningful with \`${options.colourField}\`, a column of numbers to colour by.`);
|
|
312
|
+
return false;
|
|
313
|
+
}
|
|
314
|
+
const field = `${options.where}.${options.colourField}`;
|
|
315
|
+
const isNumeric = checkColumnIsNumeric(options.table, { column });
|
|
316
|
+
if (values.colour_type === "continuous" && !isNumeric) {
|
|
317
|
+
throw new Error(`${field}: colour_type "continuous" needs a column of numbers; "${column}" holds text.`);
|
|
318
|
+
}
|
|
319
|
+
const isScaled = options.isAlwaysScaled || values.colour_type === "continuous" || (values.colour_type === undefined && isNumeric);
|
|
320
|
+
if (!isScaled) {
|
|
321
|
+
if (values.colour_scale !== undefined) {
|
|
322
|
+
throw new Error(`${options.where}.colour_scale: "${column}" is coloured by category, which a colour scale does not apply to; colour by a column of numbers, or leave colour_scale out.`);
|
|
323
|
+
}
|
|
324
|
+
return false;
|
|
325
|
+
}
|
|
326
|
+
const isLog = values.colour_scale === "log";
|
|
327
|
+
const isUsable = (value: unknown): boolean => typeof value === "number" && Number.isFinite(value) && (!isLog || value > 0);
|
|
328
|
+
// Judged on the rows that become marks: the model builds the range from those alone.
|
|
329
|
+
if (!(findColumn(options.table, { column }) ?? []).some((value, row) => options.isDrawn(row) && isUsable(value))) {
|
|
330
|
+
throw new Error(isLog
|
|
331
|
+
? `${field}: a log colour scale needs at least one positive number; "${column}" has none.`
|
|
332
|
+
: `${field}: a colour scale needs at least one number; "${column}" has none.`);
|
|
333
|
+
}
|
|
334
|
+
return true;
|
|
335
|
+
}
|
|
336
|
+
|
|
337
|
+
/**
|
|
338
|
+
* Check a density layer's weights: each says how much a place counts, so none may be negative.
|
|
339
|
+
*
|
|
340
|
+
* @param table - The layer's table.
|
|
341
|
+
* @param options - The weight column, and where the layer is.
|
|
342
|
+
*/
|
|
343
|
+
function checkWeightsAreNotNegative(table: DataTable, options: { column: string; where: string }): void {
|
|
344
|
+
const negative = (findColumn(table, { column: options.column }) ?? []).find((value) => typeof value === "number" && value < 0);
|
|
345
|
+
if (negative !== undefined) {
|
|
346
|
+
throw new Error(`${options.where}.weight: weights say how much each place counts and cannot be negative; "${options.column}" has ${negative}.`);
|
|
347
|
+
}
|
|
348
|
+
}
|
|
349
|
+
|
|
350
|
+
/**
|
|
351
|
+
* Find a map layer type's schema.
|
|
352
|
+
*
|
|
353
|
+
* @param type - The layer type.
|
|
354
|
+
* @returns Its schema.
|
|
355
|
+
*/
|
|
356
|
+
function findLayerSchema(type: MapLayer["type"]): (typeof MAP_LAYER_SCHEMAS)[number] {
|
|
357
|
+
const schema = MAP_LAYER_SCHEMAS.find((candidate) => candidate.shape.type.value === type);
|
|
358
|
+
if (schema === undefined) throw new Error(`No schema for map layer type "${type}".`);
|
|
359
|
+
return schema;
|
|
360
|
+
}
|
|
361
|
+
|
|
362
|
+
/**
|
|
363
|
+
* Find a plot type's schema.
|
|
364
|
+
*
|
|
365
|
+
* @param type - The plot type.
|
|
366
|
+
* @returns Its schema.
|
|
367
|
+
*/
|
|
368
|
+
function findPlotSchema(type: Plot["type"]): (typeof PLOT_SCHEMAS)[number] {
|
|
369
|
+
const schema = PLOT_SCHEMAS.find((candidate) => candidate.shape.type.value === type);
|
|
370
|
+
if (schema === undefined) throw new Error(`No schema for plot type "${type}".`);
|
|
371
|
+
return schema;
|
|
372
|
+
}
|
|
373
|
+
|
|
374
|
+
/**
|
|
375
|
+
* Strip a field's optional and default wrappers, down to the schema it was defined with.
|
|
376
|
+
*
|
|
377
|
+
* @param schema - The field's schema as a plot holds it.
|
|
378
|
+
* @returns The schema inside.
|
|
379
|
+
*/
|
|
380
|
+
export function unwrapField(schema: z.ZodType): z.ZodType {
|
|
381
|
+
let inner = schema;
|
|
382
|
+
while (inner instanceof z.ZodOptional || inner instanceof z.ZodDefault) inner = inner.unwrap() as z.ZodType;
|
|
383
|
+
return inner;
|
|
384
|
+
}
|
|
385
|
+
|
|
386
|
+
/**
|
|
387
|
+
* Turn the schema's complaints into one message, each line naming its field.
|
|
388
|
+
*
|
|
389
|
+
* @param issues - The schema's issues.
|
|
390
|
+
* @returns The message.
|
|
391
|
+
*/
|
|
392
|
+
function formatIssues(issues: readonly z.core.$ZodIssue[]): string {
|
|
393
|
+
return issues
|
|
394
|
+
.flatMap((issue) => {
|
|
395
|
+
const where = formatPath(issue.path);
|
|
396
|
+
if (issue.code === "unrecognized_keys") {
|
|
397
|
+
return issue.keys.map((key) => `${where === "" ? key : `${where}.${key}`}: not a field of this plot or figure.`);
|
|
398
|
+
}
|
|
399
|
+
return [`${where === "" ? "figure" : where}: ${issue.message}`];
|
|
400
|
+
})
|
|
401
|
+
.join("\n");
|
|
402
|
+
}
|
|
403
|
+
|
|
404
|
+
/**
|
|
405
|
+
* Write a path the way a caller would point at the field: plots[0].bins.
|
|
406
|
+
*
|
|
407
|
+
* @param path - The path, as the schema reports it.
|
|
408
|
+
* @returns The written path.
|
|
409
|
+
*/
|
|
410
|
+
function formatPath(path: readonly PropertyKey[]): string {
|
|
411
|
+
return path.map((part, index) => (typeof part === "number" ? `[${part}]` : `${index === 0 ? "" : "."}${String(part)}`)).join("");
|
|
412
|
+
}
|
|
@@ -0,0 +1,116 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Built-in region outlines for maps, so an agent can colour US states,
|
|
3
|
+
* Canadian provinces, EU or world countries by naming the set. Built from
|
|
4
|
+
* Natural Earth by `npx tsx scripts/build_boundaries.ts` into `data/boundaries`; each
|
|
5
|
+
* region has a canonical `name` and the `aliases` data may use for it.
|
|
6
|
+
*/
|
|
7
|
+
|
|
8
|
+
import { findColumn, type DataTable } from "../table/data_table";
|
|
9
|
+
import { readFeatureCollection, type FeatureCollection } from "./geojson";
|
|
10
|
+
|
|
11
|
+
/** The sets there are. */
|
|
12
|
+
export type BoundarySetName = "world_countries" | "us_states" | "canada_provinces" | "eu_countries";
|
|
13
|
+
|
|
14
|
+
/** Each set, and what data can name its regions by. */
|
|
15
|
+
export const BOUNDARY_SETS: Readonly<Record<BoundarySetName, string>> = {
|
|
16
|
+
world_countries: "every country (by name, or ISO code: CA, CAN)",
|
|
17
|
+
us_states: "the 50 US states and DC (by name, postal code CA, or US-CA)",
|
|
18
|
+
canada_provinces: "Canada's 13 provinces and territories (by name, postal code ON, or CA-ON)",
|
|
19
|
+
eu_countries: "the 27 EU members, mainland Europe only (by name, or ISO code: FR, FRA)",
|
|
20
|
+
};
|
|
21
|
+
|
|
22
|
+
/** Every set's name, for schemas and checks. */
|
|
23
|
+
export const BOUNDARY_SET_NAMES = Object.keys(BOUNDARY_SETS) as BoundarySetName[];
|
|
24
|
+
|
|
25
|
+
/** How a set is loaded: the site's asset store in the Worker (and in tests). */
|
|
26
|
+
export type BoundarySetLoader = (name: BoundarySetName) => Promise<FeatureCollection>;
|
|
27
|
+
|
|
28
|
+
/** The feature property that holds each region's canonical name. */
|
|
29
|
+
export const BOUNDARY_NAME_PROPERTY = "name";
|
|
30
|
+
|
|
31
|
+
/** How many unmatched names a note lists before saying "and N more". */
|
|
32
|
+
const UNMATCHED_NAMES_SHOWN = 5;
|
|
33
|
+
|
|
34
|
+
/** Where the built-in sets' files are, in this package: data/boundaries/<set>.geojson. */
|
|
35
|
+
export const BOUNDARY_SET_FILE_DIRECTORY = "data/boundaries";
|
|
36
|
+
|
|
37
|
+
/**
|
|
38
|
+
* Build a loader for the built-in sets from a way to read one set's file
|
|
39
|
+
* (BOUNDARY_SET_FILE_DIRECTORY/<set>.geojson, wherever the host keeps it).
|
|
40
|
+
*
|
|
41
|
+
* @param readSetFile - Reads a set's file and returns its parsed JSON.
|
|
42
|
+
* @returns The loader, which checks what it reads is a FeatureCollection.
|
|
43
|
+
*/
|
|
44
|
+
export function createBoundaryLoader(readSetFile: (name: BoundarySetName) => Promise<unknown>): BoundarySetLoader {
|
|
45
|
+
return async (name) => readFeatureCollection(await readSetFile(name), { where: `boundaries ${name}` });
|
|
46
|
+
}
|
|
47
|
+
|
|
48
|
+
/**
|
|
49
|
+
* Put a region name in the form used to match it: lower case, accents and
|
|
50
|
+
* punctuation gone, spaces single. "Québec" and "quebec" match.
|
|
51
|
+
*
|
|
52
|
+
* @param text - A name or code.
|
|
53
|
+
* @returns The form it is matched in.
|
|
54
|
+
*/
|
|
55
|
+
export function normaliseRegionName(text: string): string {
|
|
56
|
+
return text.normalize("NFD").replace(/[̀-ͯ]/g, "").toLowerCase().replace(/[^a-z0-9]+/g, " ").trim();
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
/**
|
|
60
|
+
* Map every alias in a set to its region's canonical name.
|
|
61
|
+
*
|
|
62
|
+
* @param collection - A built-in set.
|
|
63
|
+
* @returns normalised alias → canonical name.
|
|
64
|
+
*/
|
|
65
|
+
export function indexBoundaryAliases(collection: FeatureCollection): Map<string, string> {
|
|
66
|
+
const index = new Map<string, string>();
|
|
67
|
+
for (const feature of collection.features) {
|
|
68
|
+
const properties = (feature.properties ?? {}) as { name?: unknown; aliases?: unknown };
|
|
69
|
+
if (typeof properties.name !== "string") continue;
|
|
70
|
+
const aliases = Array.isArray(properties.aliases) ? properties.aliases : [];
|
|
71
|
+
for (const alias of [properties.name, ...aliases]) if (typeof alias === "string") index.set(normaliseRegionName(alias), properties.name);
|
|
72
|
+
}
|
|
73
|
+
return index;
|
|
74
|
+
}
|
|
75
|
+
|
|
76
|
+
/** A regions layer as resolving needs it (see RegionsLayer in map_layers.ts). */
|
|
77
|
+
type BoundaryLayer = { boundaries?: unknown; geojson?: unknown; feature_property?: string; key: string; data?: DataTable };
|
|
78
|
+
|
|
79
|
+
/**
|
|
80
|
+
* Load a regions layer's built-in set into it, and rewrite the layer's key
|
|
81
|
+
* column to the set's canonical names so every renderer joins on them.
|
|
82
|
+
*
|
|
83
|
+
* @param layer - The regions layer; changed in place.
|
|
84
|
+
* @param options - Its table (the layer's own, the plot's, or the figure's), where it is, and the loader.
|
|
85
|
+
* @returns A note for the agent about rows that matched no region, or null.
|
|
86
|
+
*/
|
|
87
|
+
export async function resolveBoundarySet(
|
|
88
|
+
layer: BoundaryLayer,
|
|
89
|
+
options: { table: DataTable | undefined; where: string; loadBoundarySet: BoundarySetLoader },
|
|
90
|
+
): Promise<string | null> {
|
|
91
|
+
const name = layer.boundaries as BoundarySetName;
|
|
92
|
+
if (!BOUNDARY_SET_NAMES.includes(name)) {
|
|
93
|
+
throw new Error(`${options.where}.boundaries: one of ${BOUNDARY_SET_NAMES.join(", ")}; got "${String(layer.boundaries)}".`);
|
|
94
|
+
}
|
|
95
|
+
if (layer.geojson !== undefined) throw new Error(`${options.where}: give boundaries or geojson, not both.`);
|
|
96
|
+
const collection = await options.loadBoundarySet(name);
|
|
97
|
+
const index = indexBoundaryAliases(collection);
|
|
98
|
+
const column = options.table === undefined ? null : findColumn(options.table, { column: layer.key });
|
|
99
|
+
if (column === null) throw new Error(`${options.where}.key: "${layer.key}" is not a column of the data.`);
|
|
100
|
+
const unmatched: string[] = [];
|
|
101
|
+
const canonical = column.map((value) => {
|
|
102
|
+
if (value === null) return null;
|
|
103
|
+
const match = index.get(normaliseRegionName(String(value)));
|
|
104
|
+
if (match === undefined) unmatched.push(String(value));
|
|
105
|
+
return match ?? value;
|
|
106
|
+
});
|
|
107
|
+
layer.geojson = collection;
|
|
108
|
+
layer.feature_property = BOUNDARY_NAME_PROPERTY;
|
|
109
|
+
// The layer gets its own copy of the table, so other layers keep the names as sent.
|
|
110
|
+
layer.data = { ...options.table, [layer.key]: canonical };
|
|
111
|
+
delete layer.boundaries;
|
|
112
|
+
if (unmatched.length === 0) return null;
|
|
113
|
+
const shown = unmatched.slice(0, UNMATCHED_NAMES_SHOWN).join(", ");
|
|
114
|
+
const more = unmatched.length > UNMATCHED_NAMES_SHOWN ? ` and ${unmatched.length - UNMATCHED_NAMES_SHOWN} more` : "";
|
|
115
|
+
return `${options.where}: ${unmatched.length} row(s) matched no region of ${name}: ${shown}${more}.`;
|
|
116
|
+
}
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The checks only a map needs, once its outlines are loaded. Columns are
|
|
3
|
+
* checked with every other plot's, in validate_plot_figure.
|
|
4
|
+
*/
|
|
5
|
+
|
|
6
|
+
import { readFeatureCollection } from "./geojson";
|
|
7
|
+
import type { MapLayer } from "./map_layers";
|
|
8
|
+
|
|
9
|
+
/**
|
|
10
|
+
* Check a map's layers: outlines loaded and readable, density only on a flat map, throwing a sentence naming the field at fault.
|
|
11
|
+
*
|
|
12
|
+
* @param layers - The map's layers, through the schema and with their outlines loaded.
|
|
13
|
+
* @param options - Whether the map is a globe, whether its outlines are loaded yet (before they are, only what needs none is checked), and where it is in the figure.
|
|
14
|
+
*/
|
|
15
|
+
export function checkMapLayers(layers: readonly MapLayer[], options: { isGlobe: boolean; areOutlinesLoaded: boolean; where: string }): void {
|
|
16
|
+
layers.forEach((layer, index) => {
|
|
17
|
+
const where = `${options.where}.layers[${index}]`;
|
|
18
|
+
if (layer.type === "density" && options.isGlobe) {
|
|
19
|
+
throw new Error(`${where}: density maps are flat only; set projection "flat", or show these as points on the globe.`);
|
|
20
|
+
}
|
|
21
|
+
if (layer.type !== "regions" || !options.areOutlinesLoaded) return;
|
|
22
|
+
const unloaded = layer.boundaries !== undefined ? "boundaries" : layer.geojson_url !== undefined ? "geojson_url" : null;
|
|
23
|
+
if (unloaded !== null) {
|
|
24
|
+
throw new Error(`${where}: outlines named by ${unloaded} are loaded by resolvePlotFigure, which validates as well; call it rather than validatePlotFigure.`);
|
|
25
|
+
}
|
|
26
|
+
if (layer.geojson === undefined) throw new Error(`${where}: give the region outlines as boundaries (a built-in set), geojson or geojson_url.`);
|
|
27
|
+
if (layer.feature_property === undefined) {
|
|
28
|
+
throw new Error(`${where}.feature_property: the GeoJSON property that names each region, e.g. "AREA_NAME".`);
|
|
29
|
+
}
|
|
30
|
+
readFeatureCollection(layer.geojson, { where: `${where}.geojson` });
|
|
31
|
+
});
|
|
32
|
+
}
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Fetch the outlines a regions layer names by address. Fetched once, when the
|
|
3
|
+
* plot is shown, and stored in it, so the map keeps working if the address
|
|
4
|
+
* later changes.
|
|
5
|
+
*/
|
|
6
|
+
|
|
7
|
+
import { readFeatureCollection, type FeatureCollection } from "./geojson";
|
|
8
|
+
import type { MapLayer } from "./map_layers";
|
|
9
|
+
|
|
10
|
+
/**
|
|
11
|
+
* Fetch outlines from a web address, as the host allows (its own checks on the
|
|
12
|
+
* address, the size, and how it identifies itself).
|
|
13
|
+
*
|
|
14
|
+
* @param url - The address the agent gave.
|
|
15
|
+
* @returns The response's text; throws a sentence the agent can act on if it cannot.
|
|
16
|
+
*/
|
|
17
|
+
export type GeoJsonFetcher = (url: string) => Promise<string>;
|
|
18
|
+
|
|
19
|
+
/**
|
|
20
|
+
* Fetch every regions layer's geojson_url, putting the outlines in the spec.
|
|
21
|
+
*
|
|
22
|
+
* @param layers - A map's layers; changed in place.
|
|
23
|
+
* @param options - Where it is in the figure, for error messages, and how the host fetches an address.
|
|
24
|
+
* @returns Nothing.
|
|
25
|
+
*/
|
|
26
|
+
export async function fetchRegionOutlines(layers: MapLayer[], options: { where: string; fetchGeoJson: GeoJsonFetcher }): Promise<void> {
|
|
27
|
+
for (const [index, layer] of layers.entries()) {
|
|
28
|
+
if (layer.type !== "regions" || layer.geojson !== undefined || layer.geojson_url === undefined) continue;
|
|
29
|
+
const where = `${options.where}.layers[${index}].geojson_url`;
|
|
30
|
+
let text: string;
|
|
31
|
+
try {
|
|
32
|
+
text = await options.fetchGeoJson(layer.geojson_url);
|
|
33
|
+
} catch (error) {
|
|
34
|
+
// Rethrown with the field, so the agent knows which address failed.
|
|
35
|
+
throw new Error(`${where}: ${error instanceof Error ? error.message : String(error)}`);
|
|
36
|
+
}
|
|
37
|
+
let parsed: unknown;
|
|
38
|
+
try {
|
|
39
|
+
parsed = JSON.parse(text);
|
|
40
|
+
} catch {
|
|
41
|
+
// Rethrown as a sentence the agent can act on.
|
|
42
|
+
throw new Error(`${where}: ${layer.geojson_url} is not JSON.`);
|
|
43
|
+
}
|
|
44
|
+
const collection: FeatureCollection = readFeatureCollection(parsed, { where });
|
|
45
|
+
layer.geojson = collection;
|
|
46
|
+
delete layer.geojson_url;
|
|
47
|
+
}
|
|
48
|
+
}
|