plotilla 0.2.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.
- package/README.md +37 -11
- package/data/boundaries/world_countries.geojson +1 -1
- package/dist/colour/colour_scale.d.ts +55 -0
- package/dist/colour/colour_scale.js +80 -0
- package/dist/colour/palette.d.ts +176 -0
- package/dist/colour/palette.js +220 -0
- package/dist/fields/axis_fields.d.ts +56 -0
- package/dist/fields/axis_fields.js +46 -0
- package/dist/fields/colour_fields.d.ts +32 -0
- package/dist/fields/colour_fields.js +31 -0
- package/dist/fields/column_fields.d.ts +52 -0
- package/{src/fields/column_fields.ts → dist/fields/column_fields.js} +15 -29
- package/dist/fields/common_fields.d.ts +9 -0
- package/{src/fields/common_fields.ts → dist/fields/common_fields.js} +3 -6
- package/dist/fields/decide_plot_axes.d.ts +56 -0
- package/dist/fields/decide_plot_axes.js +71 -0
- package/dist/fields/marker_fields.d.ts +8 -0
- package/dist/fields/marker_fields.js +13 -0
- package/dist/fields/read_date_time.d.ts +85 -0
- package/dist/fields/read_date_time.js +199 -0
- package/dist/figure/check_axis_year_formats.d.ts +36 -0
- package/dist/figure/check_axis_year_formats.js +116 -0
- package/dist/figure/check_plot_category_limits.d.ts +128 -0
- package/dist/figure/check_plot_category_limits.js +284 -0
- package/dist/figure/plot_figure.d.ts +861 -0
- package/dist/figure/plot_figure.js +58 -0
- package/dist/figure/resolve_plot_figure.d.ts +28 -0
- package/dist/figure/resolve_plot_figure.js +41 -0
- package/dist/figure/validate_plot_figure.d.ts +50 -0
- package/dist/figure/validate_plot_figure.js +441 -0
- package/dist/map/assign_map_layer_hue_slots.d.ts +89 -0
- package/dist/map/assign_map_layer_hue_slots.js +146 -0
- package/dist/map/boundary_sets.d.ts +65 -0
- package/dist/map/boundary_sets.js +103 -0
- package/dist/map/build_world_outline_across_180.d.ts +21 -0
- package/dist/map/build_world_outline_across_180.js +23 -0
- package/dist/map/check_map_layers.d.ts +16 -0
- package/dist/map/check_map_layers.js +31 -0
- package/dist/map/fetch_region_outlines.d.ts +25 -0
- package/dist/map/fetch_region_outlines.js +39 -0
- package/dist/map/geojson.d.ts +150 -0
- package/dist/map/geojson.js +248 -0
- package/dist/map/join_region_rows.d.ts +40 -0
- package/dist/map/join_region_rows.js +45 -0
- package/dist/map/map_layers.d.ts +229 -0
- package/dist/map/map_layers.js +87 -0
- package/dist/model/find_panel_colour_scale.d.ts +25 -0
- package/dist/model/find_panel_colour_scale.js +27 -0
- package/dist/model/map_model.d.ts +30 -0
- package/dist/model/map_model.js +234 -0
- package/dist/model/panel_layout.d.ts +42 -0
- package/dist/model/panel_layout.js +154 -0
- package/dist/model/panel_model.d.ts +223 -0
- package/dist/model/panel_model.js +7 -0
- package/dist/model/plot_model.d.ts +28 -0
- package/dist/model/plot_model.js +431 -0
- package/dist/model/statistics.d.ts +83 -0
- package/dist/model/statistics.js +107 -0
- package/dist/plots/bar_plot.d.ts +46 -0
- package/dist/plots/bar_plot.js +30 -0
- package/dist/plots/box_plot.d.ts +30 -0
- package/dist/plots/box_plot.js +21 -0
- package/dist/plots/density_plot.d.ts +36 -0
- package/dist/plots/density_plot.js +23 -0
- package/dist/plots/heatmap_plot.d.ts +22 -0
- package/dist/plots/heatmap_plot.js +18 -0
- package/dist/plots/histogram_plot.d.ts +32 -0
- package/dist/plots/histogram_plot.js +24 -0
- package/dist/plots/line_plot.d.ts +44 -0
- package/dist/plots/line_plot.js +25 -0
- package/dist/plots/map_plot.d.ts +92 -0
- package/dist/plots/map_plot.js +35 -0
- package/dist/plots/pie_plot.d.ts +17 -0
- package/dist/plots/pie_plot.js +16 -0
- package/dist/plots/scatter_plot.d.ts +47 -0
- package/dist/plots/scatter_plot.js +27 -0
- package/dist/renderers/date_ticks.d.ts +37 -0
- package/dist/renderers/date_ticks.js +148 -0
- package/dist/renderers/echarts_map.d.ts +47 -0
- package/dist/renderers/echarts_map.js +492 -0
- package/dist/renderers/echarts_options.d.ts +30 -0
- package/dist/renderers/echarts_options.js +449 -0
- package/dist/renderers/echarts_pie_radius.d.ts +52 -0
- package/dist/renderers/echarts_pie_radius.js +158 -0
- package/dist/renderers/escape_html.d.ts +10 -0
- package/dist/renderers/escape_html.js +15 -0
- package/dist/renderers/line_colour_segments.d.ts +39 -0
- package/dist/renderers/line_colour_segments.js +41 -0
- package/dist/renderers/plotly_map.d.ts +48 -0
- package/dist/renderers/plotly_map.js +159 -0
- package/dist/renderers/plotly_options.d.ts +19 -0
- package/dist/renderers/plotly_options.js +345 -0
- package/dist/renderers/year_ticks.d.ts +27 -0
- package/dist/renderers/year_ticks.js +42 -0
- package/dist/table/check_column.d.ts +36 -0
- package/dist/table/check_column.js +46 -0
- package/dist/table/check_values_have_spread.d.ts +30 -0
- package/{src/table/check_values_have_spread.ts → dist/table/check_values_have_spread.js} +16 -17
- package/dist/table/compute_quantile.d.ts +16 -0
- package/dist/table/compute_quantile.js +23 -0
- package/dist/table/data_table.d.ts +59 -0
- package/dist/table/data_table.js +87 -0
- package/dist/table/density_bandwidth.d.ts +64 -0
- package/dist/table/density_bandwidth.js +88 -0
- package/dist/table/find_line_fit.d.ts +30 -0
- package/dist/table/find_line_fit.js +36 -0
- package/dist/table/get_number_range.d.ts +16 -0
- package/{src/table/get_number_range.ts → dist/table/get_number_range.js} +8 -8
- package/dist/table/group_rows.d.ts +40 -0
- package/dist/table/group_rows.js +67 -0
- package/dist/table/list_categories.d.ts +14 -0
- package/{src/table/list_categories.ts → dist/table/list_categories.js} +2 -3
- package/dist/table/read_number.d.ts +12 -0
- package/dist/table/read_number.js +14 -0
- package/package.json +30 -25
- package/src/colour/colour_scale.ts +0 -80
- package/src/colour/palette.ts +0 -220
- package/src/examples/example_figures.ts +0 -320
- package/src/fields/axis_fields.ts +0 -32
- package/src/fields/colour_fields.ts +0 -40
- package/src/fields/decide_plot_axes.ts +0 -77
- package/src/fields/marker_fields.ts +0 -16
- package/src/figure/plot_figure.ts +0 -67
- package/src/figure/resolve_plot_figure.ts +0 -47
- package/src/figure/validate_plot_figure.ts +0 -412
- package/src/map/boundary_sets.ts +0 -116
- package/src/map/check_map_layers.ts +0 -32
- package/src/map/fetch_region_outlines.ts +0 -48
- package/src/map/geojson.ts +0 -174
- package/src/map/map_layers.ts +0 -108
- package/src/model/check_axis_shows_years.ts +0 -58
- package/src/model/map_model.ts +0 -238
- package/src/model/panel_layout.ts +0 -171
- package/src/model/panel_model.ts +0 -85
- package/src/model/plot_model.ts +0 -347
- package/src/model/statistics.ts +0 -134
- package/src/plots/bar_plot.ts +0 -36
- package/src/plots/box_plot.ts +0 -26
- package/src/plots/density_plot.ts +0 -29
- package/src/plots/heatmap_plot.ts +0 -24
- package/src/plots/histogram_plot.ts +0 -29
- package/src/plots/line_plot.ts +0 -29
- package/src/plots/map_plot.ts +0 -46
- package/src/plots/pie_plot.ts +0 -23
- package/src/plots/scatter_plot.ts +0 -32
- package/src/renderers/echarts_map.ts +0 -194
- package/src/renderers/echarts_options.ts +0 -317
- package/src/renderers/plotly_map.ts +0 -170
- package/src/renderers/plotly_options.ts +0 -318
- package/src/table/check_column.ts +0 -34
- package/src/table/compute_quantile.ts +0 -23
- package/src/table/data_table.ts +0 -83
- package/src/table/density_bandwidth.ts +0 -94
- package/src/table/find_line_fit.ts +0 -44
- package/src/table/group_rows.ts +0 -71
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Where each plot of a figure sits: the header (title and legend) at the top,
|
|
3
|
+
* then the panels in their grid. Shared by both renderers, so ECharts and
|
|
4
|
+
* Plotly lay a figure out the same way.
|
|
5
|
+
*
|
|
6
|
+
* Every gap is sized in pixels from what it must hold (tick labels, axis
|
|
7
|
+
* titles, legend rows, colour scales), using the figure's size in pixels from
|
|
8
|
+
* the host, so a small figure never draws one panel's labels over another's.
|
|
9
|
+
*/
|
|
10
|
+
import type { FigureModel } from "./panel_model.ts";
|
|
11
|
+
/** How wide one tick label character is drawn, in pixels: tick fonts are about 11-12 px. */
|
|
12
|
+
export declare const AXIS_LABEL_CHARACTER_PIXELS = 7;
|
|
13
|
+
/** An axis title's line plus its clearance from the tick labels, in pixels. */
|
|
14
|
+
export declare const AXIS_TITLE_ROOM_PIXELS = 24;
|
|
15
|
+
/** A legend appears from two series up; one series is named by the title (dataviz skill). */
|
|
16
|
+
export declare const MINIMUM_SERIES_FOR_LEGEND = 2;
|
|
17
|
+
/** Thrown when the figure is too small for its labels, legend and panels, so a caller can tell it from a bug. */
|
|
18
|
+
export declare class FigureTooSmallError extends Error {
|
|
19
|
+
constructor(message: string);
|
|
20
|
+
}
|
|
21
|
+
/** The figure's size in pixels, as the host draws it. */
|
|
22
|
+
export type FigureSize = {
|
|
23
|
+
width: number;
|
|
24
|
+
height: number;
|
|
25
|
+
};
|
|
26
|
+
/** Where a panel sits, as fractions of the figure measured from the top left. */
|
|
27
|
+
export type PanelRectangle = {
|
|
28
|
+
left: number;
|
|
29
|
+
top: number;
|
|
30
|
+
width: number;
|
|
31
|
+
height: number;
|
|
32
|
+
};
|
|
33
|
+
/**
|
|
34
|
+
* Place each panel in the grid, row by row.
|
|
35
|
+
*
|
|
36
|
+
* @param model - The figure.
|
|
37
|
+
* @param options - The figure's size in pixels, from the host.
|
|
38
|
+
* @returns One rectangle per panel, in panel order.
|
|
39
|
+
*/
|
|
40
|
+
export declare function computePanelRectangles(model: FigureModel, options: {
|
|
41
|
+
size: FigureSize;
|
|
42
|
+
}): PanelRectangle[];
|
|
@@ -0,0 +1,154 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Where each plot of a figure sits: the header (title and legend) at the top,
|
|
3
|
+
* then the panels in their grid. Shared by both renderers, so ECharts and
|
|
4
|
+
* Plotly lay a figure out the same way.
|
|
5
|
+
*
|
|
6
|
+
* Every gap is sized in pixels from what it must hold (tick labels, axis
|
|
7
|
+
* titles, legend rows, colour scales), using the figure's size in pixels from
|
|
8
|
+
* the host, so a small figure never draws one panel's labels over another's.
|
|
9
|
+
*/
|
|
10
|
+
import { formatValue } from "../colour/colour_scale.js";
|
|
11
|
+
import { getNumberRange } from "../table/get_number_range.js";
|
|
12
|
+
/** How wide one tick label character is drawn, in pixels: tick fonts are about 11-12 px. */
|
|
13
|
+
export const AXIS_LABEL_CHARACTER_PIXELS = 7;
|
|
14
|
+
/** An axis title's line plus its clearance from the tick labels, in pixels. */
|
|
15
|
+
export const AXIS_TITLE_ROOM_PIXELS = 24;
|
|
16
|
+
/** A legend appears from two series up; one series is named by the title (dataviz skill). */
|
|
17
|
+
export const MINIMUM_SERIES_FOR_LEGEND = 2;
|
|
18
|
+
/** Thrown when the figure is too small for its labels, legend and panels, so a caller can tell it from a bug. */
|
|
19
|
+
export class FigureTooSmallError extends Error {
|
|
20
|
+
constructor(message) {
|
|
21
|
+
super(message);
|
|
22
|
+
this.name = "FigureTooSmallError";
|
|
23
|
+
}
|
|
24
|
+
}
|
|
25
|
+
/** Space kept at the figure's edges, in pixels. */
|
|
26
|
+
const EDGE_PADDING_PIXELS = 12;
|
|
27
|
+
/** Space between one panel's furniture and the next panel's, in pixels. */
|
|
28
|
+
const PANEL_SPACING_PIXELS = 12;
|
|
29
|
+
/** One line of x tick labels, in pixels. */
|
|
30
|
+
const X_TICK_LABEL_LINE_PIXELS = 18;
|
|
31
|
+
/** The figure's title line, in pixels. */
|
|
32
|
+
const FIGURE_TITLE_ROOM_PIXELS = 30;
|
|
33
|
+
/** One row of legend entries, in pixels. */
|
|
34
|
+
const LEGEND_ROW_PIXELS = 24;
|
|
35
|
+
/** A legend entry's symbol and the gaps around it, in pixels; its name adds a character width per character. */
|
|
36
|
+
const LEGEND_ENTRY_EXTRA_PIXELS = 40;
|
|
37
|
+
const LEGEND_CHARACTER_PIXELS = 7;
|
|
38
|
+
/** A panel's own title line, in pixels. */
|
|
39
|
+
const PANEL_TITLE_ROOM_PIXELS = 22;
|
|
40
|
+
/** A colour scale's bar and the gaps either side of it, in pixels; its labels add a character width per character. */
|
|
41
|
+
const COLOUR_SCALE_BAR_ROOM_PIXELS = 40;
|
|
42
|
+
/** The smallest panel worth drawing, in pixels. */
|
|
43
|
+
const MINIMUM_PANEL_PIXELS = { width: 80, height: 40 };
|
|
44
|
+
/**
|
|
45
|
+
* Measure what a panel needs around it: tick labels and titles of its axes,
|
|
46
|
+
* its own title, and a colour scale beside it.
|
|
47
|
+
*
|
|
48
|
+
* @param panel - The panel.
|
|
49
|
+
* @returns Its room on each side, in pixels.
|
|
50
|
+
*/
|
|
51
|
+
function measurePanelRoom(panel) {
|
|
52
|
+
return {
|
|
53
|
+
left: panel.yAxis === null ? 0 : panel.yAxis.longestLabelCharacters * AXIS_LABEL_CHARACTER_PIXELS + AXIS_TITLE_ROOM_PIXELS,
|
|
54
|
+
right: panel.colourScale === null ? 0 : COLOUR_SCALE_BAR_ROOM_PIXELS + measureColourScaleLabelCharacters(panel.colourScale) * AXIS_LABEL_CHARACTER_PIXELS,
|
|
55
|
+
bottom: panel.xAxis === null ? 0 : X_TICK_LABEL_LINE_PIXELS + AXIS_TITLE_ROOM_PIXELS,
|
|
56
|
+
top: panel.title === null ? 0 : PANEL_TITLE_ROOM_PIXELS,
|
|
57
|
+
};
|
|
58
|
+
}
|
|
59
|
+
/**
|
|
60
|
+
* The widest label a colour scale prints, in characters: its title, its
|
|
61
|
+
* ticks, and its ends (a linear scale's own ticks are numbers like these).
|
|
62
|
+
*
|
|
63
|
+
* @param scale - The panel's colour scale.
|
|
64
|
+
* @returns The widest label's length.
|
|
65
|
+
*/
|
|
66
|
+
function measureColourScaleLabelCharacters(scale) {
|
|
67
|
+
const labels = [scale.label, formatValue(scale.minimum), formatValue(scale.maximum), ...(scale.ticks ?? []).map((tick) => tick.text)];
|
|
68
|
+
return findLargest(labels.map((label) => label.length));
|
|
69
|
+
}
|
|
70
|
+
/**
|
|
71
|
+
* Count the legend's rows at this width: entries are packed left to right
|
|
72
|
+
* and wrap, as both libraries draw a horizontal legend.
|
|
73
|
+
*
|
|
74
|
+
* @param names - The legend's entries.
|
|
75
|
+
* @param options - The width available, in pixels.
|
|
76
|
+
* @returns The number of rows.
|
|
77
|
+
*/
|
|
78
|
+
function countLegendRows(names, options) {
|
|
79
|
+
let rows = 1;
|
|
80
|
+
let used = 0;
|
|
81
|
+
for (const name of names) {
|
|
82
|
+
const entry = LEGEND_ENTRY_EXTRA_PIXELS + name.length * LEGEND_CHARACTER_PIXELS;
|
|
83
|
+
if (used > 0 && used + entry > options.width) {
|
|
84
|
+
rows += 1;
|
|
85
|
+
used = 0;
|
|
86
|
+
}
|
|
87
|
+
used += entry;
|
|
88
|
+
}
|
|
89
|
+
return rows;
|
|
90
|
+
}
|
|
91
|
+
/**
|
|
92
|
+
* The largest of some numbers, or 0 when there are none.
|
|
93
|
+
*
|
|
94
|
+
* @param values - The numbers.
|
|
95
|
+
* @returns The largest.
|
|
96
|
+
*/
|
|
97
|
+
function findLargest(values) {
|
|
98
|
+
return Math.max(0, getNumberRange(values).maximum);
|
|
99
|
+
}
|
|
100
|
+
/**
|
|
101
|
+
* Place each panel in the grid, row by row.
|
|
102
|
+
*
|
|
103
|
+
* @param model - The figure.
|
|
104
|
+
* @param options - The figure's size in pixels, from the host.
|
|
105
|
+
* @returns One rectangle per panel, in panel order.
|
|
106
|
+
*/
|
|
107
|
+
export function computePanelRectangles(model, options) {
|
|
108
|
+
const { size } = options;
|
|
109
|
+
const rooms = model.panels.map(measurePanelRoom);
|
|
110
|
+
const roomsInColumn = (column) => rooms.filter((_, index) => index % model.columns === column);
|
|
111
|
+
const roomsInRow = (row) => rooms.filter((_, index) => Math.floor(index / model.columns) === row);
|
|
112
|
+
const hasLegend = model.legendNames.length >= MINIMUM_SERIES_FOR_LEGEND;
|
|
113
|
+
const legendRows = hasLegend ? countLegendRows(model.legendNames, { width: size.width - 2 * EDGE_PADDING_PIXELS }) : 0;
|
|
114
|
+
const header = EDGE_PADDING_PIXELS + (model.title === null ? 0 : FIGURE_TITLE_ROOM_PIXELS) + legendRows * LEGEND_ROW_PIXELS;
|
|
115
|
+
// Each column starts after its widest left room; each gap also holds the previous column's right room.
|
|
116
|
+
const columnStarts = [];
|
|
117
|
+
let x = EDGE_PADDING_PIXELS;
|
|
118
|
+
for (let column = 0; column < model.columns; column += 1) {
|
|
119
|
+
if (column > 0)
|
|
120
|
+
x += findLargest(roomsInColumn(column - 1).map((room) => room.right)) + PANEL_SPACING_PIXELS;
|
|
121
|
+
x += findLargest(roomsInColumn(column).map((room) => room.left));
|
|
122
|
+
columnStarts.push(x);
|
|
123
|
+
}
|
|
124
|
+
const lastRight = findLargest(roomsInColumn(model.columns - 1).map((room) => room.right));
|
|
125
|
+
const furnitureWidth = x + lastRight + EDGE_PADDING_PIXELS;
|
|
126
|
+
const rowStarts = [];
|
|
127
|
+
let y = header;
|
|
128
|
+
for (let row = 0; row < model.rows; row += 1) {
|
|
129
|
+
// A panel title's own room already separates it from the row above; spacing stands in when there is none.
|
|
130
|
+
const titleRoom = findLargest(roomsInRow(row).map((room) => room.top));
|
|
131
|
+
if (row > 0)
|
|
132
|
+
y += findLargest(roomsInRow(row - 1).map((room) => room.bottom)) + Math.max(titleRoom, PANEL_SPACING_PIXELS);
|
|
133
|
+
else
|
|
134
|
+
y += titleRoom;
|
|
135
|
+
rowStarts.push(y);
|
|
136
|
+
}
|
|
137
|
+
const lastBottom = findLargest(roomsInRow(model.rows - 1).map((room) => room.bottom));
|
|
138
|
+
const furnitureHeight = y + lastBottom + EDGE_PADDING_PIXELS;
|
|
139
|
+
const panelWidth = (size.width - furnitureWidth) / model.columns;
|
|
140
|
+
const panelHeight = (size.height - furnitureHeight) / model.rows;
|
|
141
|
+
if (panelWidth < MINIMUM_PANEL_PIXELS.width || panelHeight < MINIMUM_PANEL_PIXELS.height) {
|
|
142
|
+
const neededWidth = Math.ceil(furnitureWidth + model.columns * MINIMUM_PANEL_PIXELS.width);
|
|
143
|
+
const neededHeight = Math.ceil(furnitureHeight + model.rows * MINIMUM_PANEL_PIXELS.height);
|
|
144
|
+
throw new FigureTooSmallError(`The figure needs at least ${Math.max(neededWidth, size.width)} x ${Math.max(neededHeight, size.height)} pixels `
|
|
145
|
+
+ `for its labels, legend and ${model.panels.length} plot${model.panels.length === 1 ? "" : "s"}; got ${size.width} x ${size.height}.`);
|
|
146
|
+
}
|
|
147
|
+
return model.panels.map((_, index) => {
|
|
148
|
+
const row = Math.floor(index / model.columns);
|
|
149
|
+
const column = index % model.columns;
|
|
150
|
+
const left = (columnStarts[column] ?? 0) + column * panelWidth;
|
|
151
|
+
const top = (rowStarts[row] ?? 0) + row * panelHeight;
|
|
152
|
+
return { left: left / size.width, top: top / size.height, width: panelWidth / size.width, height: panelHeight / size.height };
|
|
153
|
+
});
|
|
154
|
+
}
|
|
@@ -0,0 +1,223 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The renderer-neutral model's types: what a figure, a panel, a series, an
|
|
3
|
+
* axis and a map are once every decision is made. Kept apart from the code
|
|
4
|
+
* that builds them, so the chart model and the map model both use them
|
|
5
|
+
* without importing each other.
|
|
6
|
+
*/
|
|
7
|
+
import type { LineDash, MarkerShape, PlotTheme } from "../colour/palette.ts";
|
|
8
|
+
import type { AxisYearFormat, AxisScale } from "../fields/axis_fields.ts";
|
|
9
|
+
import type { AxisKind } from "../fields/decide_plot_axes.ts";
|
|
10
|
+
import type { Bounds, FeatureCollection } from "../map/geojson.ts";
|
|
11
|
+
import type { MapProjection } from "../plots/map_plot.ts";
|
|
12
|
+
import type { BoxSummary, HistogramBin } from "./statistics.ts";
|
|
13
|
+
/** A value along an axis: a number, or a category's text. */
|
|
14
|
+
export type Value = number | string;
|
|
15
|
+
/**
|
|
16
|
+
* `includesZero`: bars, histograms and densities measure from zero, so their value axis must show it.
|
|
17
|
+
* `longestLabelCharacters`: an estimate of the widest tick label, so a renderer can place the axis title clear of it.
|
|
18
|
+
*/
|
|
19
|
+
export type AxisModel = {
|
|
20
|
+
kind: AxisKind;
|
|
21
|
+
label: string;
|
|
22
|
+
scale: AxisScale;
|
|
23
|
+
categories: string[];
|
|
24
|
+
includesZero: boolean;
|
|
25
|
+
longestLabelCharacters: number;
|
|
26
|
+
labelForm: AxisLabelForm;
|
|
27
|
+
/**
|
|
28
|
+
* The smallest and largest number the axis must show; on an axis of dates,
|
|
29
|
+
* the earliest and latest as milliseconds since 1970, their wall clock read
|
|
30
|
+
* as UTC; null on an axis of categories, or with nothing to show.
|
|
31
|
+
*/
|
|
32
|
+
numberRange: {
|
|
33
|
+
minimum: number;
|
|
34
|
+
maximum: number;
|
|
35
|
+
} | null;
|
|
36
|
+
};
|
|
37
|
+
/**
|
|
38
|
+
* How an axis prints its tick labels, the same in every renderer:
|
|
39
|
+
* `number`: thousands commas, decimals kept, never shortened (1,450; 1,234.57; 1,500,000,000);
|
|
40
|
+
* `YYYY` and `YY`: whole numbers the caller declared as years (1990; 90);
|
|
41
|
+
* `month`: dates that are each the first of a month (2024.01); `day`: other dates, all at midnight (2024.01.15);
|
|
42
|
+
* `minute`: dates where any has a time other than midnight (2024.01.15 08:30);
|
|
43
|
+
* `second`: dates where any has non-zero seconds (2024.01.15 08:30:20);
|
|
44
|
+
* `category`: each category's text.
|
|
45
|
+
*/
|
|
46
|
+
export type AxisLabelForm = "number" | AxisYearFormat | DateLabelForm | "category";
|
|
47
|
+
/** The forms a date axis prints in, from the coarsest (see `AxisLabelForm`). */
|
|
48
|
+
export type DateLabelForm = "month" | "day" | "minute" | "second";
|
|
49
|
+
/** One series of marks, renderer-neutral: what is drawn, in which colour, at which values. */
|
|
50
|
+
export type SeriesModel =
|
|
51
|
+
/** `colour` is null when a number colours the line along its length (`colourValue` per point). */
|
|
52
|
+
{
|
|
53
|
+
mark: "line";
|
|
54
|
+
name: string;
|
|
55
|
+
colour: string | null;
|
|
56
|
+
dash: LineDash;
|
|
57
|
+
showMarkers: boolean;
|
|
58
|
+
isFilled: boolean;
|
|
59
|
+
points: {
|
|
60
|
+
x: Value;
|
|
61
|
+
y: number;
|
|
62
|
+
colourValue: number | null;
|
|
63
|
+
}[];
|
|
64
|
+
} | {
|
|
65
|
+
mark: "scatter";
|
|
66
|
+
name: string;
|
|
67
|
+
colour: string | null;
|
|
68
|
+
shape: MarkerShape;
|
|
69
|
+
points: {
|
|
70
|
+
x: Value;
|
|
71
|
+
y: number;
|
|
72
|
+
sizePixels: number;
|
|
73
|
+
colourValue: number | null;
|
|
74
|
+
}[];
|
|
75
|
+
} | {
|
|
76
|
+
mark: "bar";
|
|
77
|
+
name: string;
|
|
78
|
+
colour: string | null;
|
|
79
|
+
isStacked: boolean;
|
|
80
|
+
isHorizontal: boolean;
|
|
81
|
+
points: {
|
|
82
|
+
x: string;
|
|
83
|
+
y: number;
|
|
84
|
+
colourValue: number | null;
|
|
85
|
+
}[];
|
|
86
|
+
} | {
|
|
87
|
+
mark: "box";
|
|
88
|
+
name: string;
|
|
89
|
+
colour: string;
|
|
90
|
+
showMarkers: boolean;
|
|
91
|
+
boxes: {
|
|
92
|
+
category: string;
|
|
93
|
+
summary: BoxSummary;
|
|
94
|
+
values: number[];
|
|
95
|
+
}[];
|
|
96
|
+
} | {
|
|
97
|
+
mark: "histogram";
|
|
98
|
+
name: string;
|
|
99
|
+
colour: string;
|
|
100
|
+
bins: HistogramBin[];
|
|
101
|
+
} | {
|
|
102
|
+
mark: "heatmap";
|
|
103
|
+
name: string;
|
|
104
|
+
cells: {
|
|
105
|
+
x: string;
|
|
106
|
+
y: string;
|
|
107
|
+
value: number;
|
|
108
|
+
colourValue: number | null;
|
|
109
|
+
}[];
|
|
110
|
+
} | {
|
|
111
|
+
mark: "pie";
|
|
112
|
+
name: string;
|
|
113
|
+
hole: number;
|
|
114
|
+
slices: {
|
|
115
|
+
label: string;
|
|
116
|
+
value: number;
|
|
117
|
+
colour: string;
|
|
118
|
+
}[];
|
|
119
|
+
};
|
|
120
|
+
/** One panel of the grid: its title, axes, series, colour scale and, for a map, the map. */
|
|
121
|
+
export type PanelModel = {
|
|
122
|
+
title: string | null;
|
|
123
|
+
xAxis: AxisModel | null;
|
|
124
|
+
yAxis: AxisModel | null;
|
|
125
|
+
series: SeriesModel[];
|
|
126
|
+
/** Present when colour encodes a number and some mark has a colour value: the range (always finite) and the ramp. Made only by findPanelColourScale. */
|
|
127
|
+
/** `ticks`: legend labels in real values, for scales that transform them (log, quantile maps). */
|
|
128
|
+
colourScale: {
|
|
129
|
+
label: string;
|
|
130
|
+
minimum: number;
|
|
131
|
+
maximum: number;
|
|
132
|
+
colours: readonly string[];
|
|
133
|
+
ticks?: {
|
|
134
|
+
value: number;
|
|
135
|
+
text: string;
|
|
136
|
+
}[];
|
|
137
|
+
} | null;
|
|
138
|
+
/** Present for a map plot: its layers and view. Maps have no axes or series. */
|
|
139
|
+
map?: MapModel;
|
|
140
|
+
};
|
|
141
|
+
/** `legendNames`: every series name, once, in first-seen order; a legend shows from two up. */
|
|
142
|
+
/** `notes`: things the agent should know about the figure (e.g. map regions with no data). */
|
|
143
|
+
export type FigureModel = {
|
|
144
|
+
title: string | null;
|
|
145
|
+
rows: number;
|
|
146
|
+
columns: number;
|
|
147
|
+
isXAxisShared: boolean;
|
|
148
|
+
isYAxisShared: boolean;
|
|
149
|
+
theme: PlotTheme;
|
|
150
|
+
legendNames: string[];
|
|
151
|
+
notes: string[];
|
|
152
|
+
panels: PanelModel[];
|
|
153
|
+
};
|
|
154
|
+
/** A point the model places: where it is, its label, its size in pixels (the marker size with no size column) and colour value. */
|
|
155
|
+
export type MapPoint = {
|
|
156
|
+
longitude: number;
|
|
157
|
+
latitude: number;
|
|
158
|
+
label: string | null;
|
|
159
|
+
sizePixels: number;
|
|
160
|
+
colourValue: number | null;
|
|
161
|
+
};
|
|
162
|
+
/** A map layer with every colour, join and position decided. */
|
|
163
|
+
export type MapLayerModel =
|
|
164
|
+
/** `colour` is null when a number colours the points (the panel's colour scale). */
|
|
165
|
+
{
|
|
166
|
+
kind: "points";
|
|
167
|
+
name: string;
|
|
168
|
+
colour: string | null;
|
|
169
|
+
isCategory: boolean;
|
|
170
|
+
points: MapPoint[];
|
|
171
|
+
} | {
|
|
172
|
+
kind: "density";
|
|
173
|
+
name: string;
|
|
174
|
+
points: {
|
|
175
|
+
longitude: number;
|
|
176
|
+
latitude: number;
|
|
177
|
+
weight: number;
|
|
178
|
+
}[];
|
|
179
|
+
}
|
|
180
|
+
/** Regions carry their own colour when coloured by category; `value` drives the colour scale otherwise. */
|
|
181
|
+
| {
|
|
182
|
+
kind: "regions";
|
|
183
|
+
name: string;
|
|
184
|
+
geojson: FeatureCollection;
|
|
185
|
+
regions: {
|
|
186
|
+
id: string;
|
|
187
|
+
value: number | null;
|
|
188
|
+
colour: string | null;
|
|
189
|
+
label: string;
|
|
190
|
+
}[];
|
|
191
|
+
} | {
|
|
192
|
+
kind: "lines";
|
|
193
|
+
name: string;
|
|
194
|
+
colour: string | null;
|
|
195
|
+
isCategory: boolean;
|
|
196
|
+
lines: {
|
|
197
|
+
path: [number, number][];
|
|
198
|
+
widthPixels: number;
|
|
199
|
+
colourValue: number | null;
|
|
200
|
+
label: string | null;
|
|
201
|
+
}[];
|
|
202
|
+
};
|
|
203
|
+
/** A map panel: its layers, projection, starting view and notes for the agent. */
|
|
204
|
+
export type MapModel = {
|
|
205
|
+
projection: MapProjection;
|
|
206
|
+
/** Where the view starts: [longitude, latitude] and a zoom from 0 (world) up. */
|
|
207
|
+
centre: [number, number];
|
|
208
|
+
zoom: number;
|
|
209
|
+
/** True when the agent set the zoom; a globe then starts that close, else it starts whole. */
|
|
210
|
+
isZoomGiven: boolean;
|
|
211
|
+
/** True when the agent set the centre; else the centre is the fitted one. */
|
|
212
|
+
isCentreGiven: boolean;
|
|
213
|
+
/** Everything shown, for renderers that fit a view to bounds. */
|
|
214
|
+
bounds: Bounds | null;
|
|
215
|
+
/**
|
|
216
|
+
* Everything shown, read the short way round the 180° line (`findFittingBounds`):
|
|
217
|
+
* the area the fitted centre and zoom show. Its east edge may be past 180.
|
|
218
|
+
*/
|
|
219
|
+
fittingBounds: Bounds | null;
|
|
220
|
+
layers: MapLayerModel[];
|
|
221
|
+
/** Things the agent should know, e.g. regions with no data. */
|
|
222
|
+
notes: string[];
|
|
223
|
+
};
|
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The renderer-neutral model's types: what a figure, a panel, a series, an
|
|
3
|
+
* axis and a map are once every decision is made. Kept apart from the code
|
|
4
|
+
* that builds them, so the chart model and the map model both use them
|
|
5
|
+
* without importing each other.
|
|
6
|
+
*/
|
|
7
|
+
export {};
|
|
@@ -0,0 +1,28 @@
|
|
|
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 { type PlotTheme } from "../colour/palette.ts";
|
|
8
|
+
import type { FigureModel } from "./panel_model.ts";
|
|
9
|
+
import type { PlotFigure } from "../figure/plot_figure.ts";
|
|
10
|
+
/**
|
|
11
|
+
* Estimate the widest tick label for numbers on an axis: ticks are round
|
|
12
|
+
* numbers written with thousands separators (2,600,000), or a few decimals
|
|
13
|
+
* below 1 (0.025). One extra character covers ticks just past the data.
|
|
14
|
+
*
|
|
15
|
+
* @param numbers - The values the axis must show.
|
|
16
|
+
* @returns An estimated character count.
|
|
17
|
+
*/
|
|
18
|
+
export declare function estimateNumberLabelCharacters(numbers: number[]): number;
|
|
19
|
+
/**
|
|
20
|
+
* Build the chart model for a validated figure.
|
|
21
|
+
*
|
|
22
|
+
* @param figure - A figure that passed validatePlotFigure.
|
|
23
|
+
* @param options - The theme it is drawn in (default: dark).
|
|
24
|
+
* @returns Panels in grid order (row by row), ready for a renderer.
|
|
25
|
+
*/
|
|
26
|
+
export declare function buildFigureModel(figure: PlotFigure, options?: {
|
|
27
|
+
theme?: PlotTheme;
|
|
28
|
+
}): FigureModel;
|