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,148 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Ticks for a date axis, listed for both renderers so they print the same
|
|
3
|
+
* labels. A date axis prints its labels to the month, day, minute or
|
|
4
|
+
* second, so a tick inside one of those would print its label twice: over
|
|
5
|
+
* three months Plotly ticks weekly, and 2024.01 shows up four times; ECharts
|
|
6
|
+
* adds unround labels at the axis ends. The ticks are listed here instead, a
|
|
7
|
+
* round calendar step apart and never closer than the label form prints.
|
|
8
|
+
*/
|
|
9
|
+
import { MILLISECONDS_PER_DAY, MILLISECONDS_PER_HOUR, MILLISECONDS_PER_MINUTE, MILLISECONDS_PER_SECOND } from "../fields/read_date_time.js";
|
|
10
|
+
import { listWholeTicks } from "./year_ticks.js";
|
|
11
|
+
/** About how many ticks a date axis gets, as many as a year axis. */
|
|
12
|
+
const TARGET_TICK_COUNT = 6;
|
|
13
|
+
const MONTHS_PER_YEAR = 12;
|
|
14
|
+
/** A month on average, over the Gregorian calendar's 400-year cycle, to turn a span into months. */
|
|
15
|
+
const MILLISECONDS_PER_AVERAGE_MONTH = (365.2425 / MONTHS_PER_YEAR) * MILLISECONDS_PER_DAY;
|
|
16
|
+
/**
|
|
17
|
+
* Where steps of a day or more count from: Monday 1970-01-05, the first
|
|
18
|
+
* Monday since 1970, so 7- and 14-day ticks fall on Mondays, the ISO 8601
|
|
19
|
+
* week start. It is a midnight, so steps shorter than a day still fall on
|
|
20
|
+
* whole minutes and hours.
|
|
21
|
+
*/
|
|
22
|
+
const ISO_WEEK_START_MILLISECONDS = Date.UTC(1970, 0, 5);
|
|
23
|
+
/** The round steps shorter than a month, in milliseconds, as a reader counts time: seconds, minutes, hours, days, weeks. */
|
|
24
|
+
const STEPS_SHORTER_THAN_A_MONTH = [
|
|
25
|
+
...[1, 2, 5, 10, 15, 30].map((seconds) => seconds * MILLISECONDS_PER_SECOND),
|
|
26
|
+
...[1, 2, 5, 10, 15, 30].map((minutes) => minutes * MILLISECONDS_PER_MINUTE),
|
|
27
|
+
...[1, 2, 3, 6, 12].map((hours) => hours * MILLISECONDS_PER_HOUR),
|
|
28
|
+
...[1, 2, 7, 14].map((days) => days * MILLISECONDS_PER_DAY),
|
|
29
|
+
];
|
|
30
|
+
/** The round steps of months shorter than a year; a year or more steps by whole years. */
|
|
31
|
+
const MONTH_STEPS = [1, 2, 3, 6];
|
|
32
|
+
/** The smallest step each form allows, in milliseconds: the unit its labels print to. Months need no entry: they step by months at least. */
|
|
33
|
+
const SMALLEST_STEP = {
|
|
34
|
+
day: MILLISECONDS_PER_DAY, minute: MILLISECONDS_PER_MINUTE, second: MILLISECONDS_PER_SECOND,
|
|
35
|
+
};
|
|
36
|
+
/** How many digits each part of a printed date-time takes, and its milliseconds. */
|
|
37
|
+
const TWO_DIGITS = 2;
|
|
38
|
+
const THREE_DIGITS = 3;
|
|
39
|
+
/**
|
|
40
|
+
* List the ticks of a date axis across its range, a round calendar step apart.
|
|
41
|
+
*
|
|
42
|
+
* @param range - The earliest and latest date, as milliseconds since 1970 with their wall clock read as UTC.
|
|
43
|
+
* @param options - The axis's label form.
|
|
44
|
+
* @returns The ticks as date-times Plotly reads (2024-03-05 14:30:00), ascending.
|
|
45
|
+
*/
|
|
46
|
+
export function listDateTicks(range, options) {
|
|
47
|
+
return listDateTickMilliseconds(range, options).map((tick) => formatDateTime(tick));
|
|
48
|
+
}
|
|
49
|
+
/**
|
|
50
|
+
* List the ticks of a date axis across its range, a round calendar step
|
|
51
|
+
* apart, as milliseconds: the same ticks `listDateTicks` gives Plotly, for
|
|
52
|
+
* ECharts, so both renderers print the same labels.
|
|
53
|
+
*
|
|
54
|
+
* @param range - The earliest and latest date, as milliseconds since 1970 with their wall clock read as UTC.
|
|
55
|
+
* @param options - The axis's label form.
|
|
56
|
+
* @returns The ticks in milliseconds, ascending.
|
|
57
|
+
*/
|
|
58
|
+
export function listDateTickMilliseconds(range, options) {
|
|
59
|
+
const rough = (range.maximum - range.minimum) / TARGET_TICK_COUNT;
|
|
60
|
+
const largestMonthStep = MONTH_STEPS[MONTH_STEPS.length - 1] ?? 1;
|
|
61
|
+
if (rough > largestMonthStep * MILLISECONDS_PER_AVERAGE_MONTH)
|
|
62
|
+
return listYearTicks(range);
|
|
63
|
+
const step = chooseNearestStep(range, { form: options.form });
|
|
64
|
+
return "months" in step ? listMonthTicks(range, { months: step.months }) : listStepTicks(range, { step: step.milliseconds });
|
|
65
|
+
}
|
|
66
|
+
/**
|
|
67
|
+
* Choose the round step whose tick count over the range is nearest the
|
|
68
|
+
* target, among those no finer than the form prints; on a tie, the finer.
|
|
69
|
+
*
|
|
70
|
+
* @param range - The range, in milliseconds.
|
|
71
|
+
* @param options - The axis's label form.
|
|
72
|
+
* @returns The step.
|
|
73
|
+
*/
|
|
74
|
+
function chooseNearestStep(range, options) {
|
|
75
|
+
const smallest = options.form === "month" ? null : SMALLEST_STEP[options.form];
|
|
76
|
+
const candidates = [
|
|
77
|
+
...(smallest === null ? [] : STEPS_SHORTER_THAN_A_MONTH.filter((step) => step >= smallest).map((step) => ({ step: { milliseconds: step }, milliseconds: step }))),
|
|
78
|
+
...MONTH_STEPS.map((months) => ({ step: { months }, milliseconds: months * MILLISECONDS_PER_AVERAGE_MONTH })),
|
|
79
|
+
];
|
|
80
|
+
const span = range.maximum - range.minimum;
|
|
81
|
+
let nearest = candidates[0];
|
|
82
|
+
if (nearest === undefined)
|
|
83
|
+
throw new Error("Expected at least one date step; got none.");
|
|
84
|
+
for (const candidate of candidates) {
|
|
85
|
+
const distance = Math.abs(span / candidate.milliseconds - TARGET_TICK_COUNT);
|
|
86
|
+
if (distance < Math.abs(span / nearest.milliseconds - TARGET_TICK_COUNT))
|
|
87
|
+
nearest = candidate;
|
|
88
|
+
}
|
|
89
|
+
return nearest.step;
|
|
90
|
+
}
|
|
91
|
+
/**
|
|
92
|
+
* List ticks a fixed step apart, on whole multiples of the step counted
|
|
93
|
+
* from a Monday midnight. A range that holds no such tick (one value with a
|
|
94
|
+
* fraction of a second) gets its own start, so an axis never has no labels.
|
|
95
|
+
*
|
|
96
|
+
* @param range - The range, in milliseconds.
|
|
97
|
+
* @param options - The step, in milliseconds.
|
|
98
|
+
* @returns The ticks in milliseconds; at least one.
|
|
99
|
+
*/
|
|
100
|
+
function listStepTicks(range, options) {
|
|
101
|
+
const ticks = [];
|
|
102
|
+
const first = ISO_WEEK_START_MILLISECONDS + Math.ceil((range.minimum - ISO_WEEK_START_MILLISECONDS) / options.step) * options.step;
|
|
103
|
+
for (let tick = first; tick <= range.maximum; tick += options.step)
|
|
104
|
+
ticks.push(tick);
|
|
105
|
+
return ticks.length === 0 ? [range.minimum] : ticks;
|
|
106
|
+
}
|
|
107
|
+
/**
|
|
108
|
+
* List ticks on the first of each year, a round number of years apart.
|
|
109
|
+
*
|
|
110
|
+
* @param range - The range, in milliseconds.
|
|
111
|
+
* @returns The ticks in milliseconds.
|
|
112
|
+
*/
|
|
113
|
+
function listYearTicks(range) {
|
|
114
|
+
const years = listWholeTicks({ minimum: new Date(range.minimum).getUTCFullYear(), maximum: new Date(range.maximum).getUTCFullYear() });
|
|
115
|
+
return years.map((year) => Date.UTC(year, 0, 1)).filter((tick) => tick >= range.minimum);
|
|
116
|
+
}
|
|
117
|
+
/**
|
|
118
|
+
* List ticks on the first of a month, a round number of months apart.
|
|
119
|
+
*
|
|
120
|
+
* @param range - The range, in milliseconds.
|
|
121
|
+
* @param options - The step, in months.
|
|
122
|
+
* @returns The ticks in milliseconds.
|
|
123
|
+
*/
|
|
124
|
+
function listMonthTicks(range, options) {
|
|
125
|
+
const first = new Date(range.minimum);
|
|
126
|
+
const ticks = [];
|
|
127
|
+
const firstMonthIndex = Math.ceil((first.getUTCFullYear() * MONTHS_PER_YEAR + first.getUTCMonth()) / options.months) * options.months;
|
|
128
|
+
for (let monthIndex = firstMonthIndex;; monthIndex += options.months) {
|
|
129
|
+
const tick = Date.UTC(Math.floor(monthIndex / MONTHS_PER_YEAR), monthIndex % MONTHS_PER_YEAR, 1);
|
|
130
|
+
if (tick > range.maximum)
|
|
131
|
+
return ticks;
|
|
132
|
+
if (tick >= range.minimum)
|
|
133
|
+
ticks.push(tick);
|
|
134
|
+
}
|
|
135
|
+
}
|
|
136
|
+
/**
|
|
137
|
+
* Print milliseconds as the date-time Plotly reads, its wall clock as UTC.
|
|
138
|
+
*
|
|
139
|
+
* @param milliseconds - The date-time.
|
|
140
|
+
* @returns The text: 2024-03-05 14:30:00, or 2024-03-05 14:30:05.500 for a tick inside a second (a lone fractional value's own).
|
|
141
|
+
*/
|
|
142
|
+
function formatDateTime(milliseconds) {
|
|
143
|
+
const date = new Date(milliseconds);
|
|
144
|
+
const pad = (part) => String(part).padStart(TWO_DIGITS, "0");
|
|
145
|
+
const fraction = date.getUTCMilliseconds() === 0 ? "" : `.${String(date.getUTCMilliseconds()).padStart(THREE_DIGITS, "0")}`;
|
|
146
|
+
return `${date.getUTCFullYear()}-${pad(date.getUTCMonth() + 1)}-${pad(date.getUTCDate())} ` +
|
|
147
|
+
`${pad(date.getUTCHours())}:${pad(date.getUTCMinutes())}:${pad(date.getUTCSeconds())}${fraction}`;
|
|
148
|
+
}
|
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* A map panel → an ECharts geo component and its series.
|
|
3
|
+
*
|
|
4
|
+
* ECharts draws maps over GeoJSON outlines, not street tiles: every regions
|
|
5
|
+
* layer's outlines, merged into one registered map under the panel's geo, or
|
|
6
|
+
* a world map (registered by the page) under points and lines. Drag and
|
|
7
|
+
* scroll to pan and zoom. ECharts has no globe; a globe map is drawn flat
|
|
8
|
+
* here, and the page says so (Plotly draws the globe).
|
|
9
|
+
*/
|
|
10
|
+
import { type FeatureCollection } from "../map/geojson.ts";
|
|
11
|
+
import type { MapModel } from "../model/panel_model.ts";
|
|
12
|
+
import { type PlotTheme } from "../colour/palette.ts";
|
|
13
|
+
import type { PanelModel } from "../model/panel_model.ts";
|
|
14
|
+
import type { FigureSize, PanelRectangle } from "../model/panel_layout.ts";
|
|
15
|
+
/** The name the page registers the world outline under (see viewer_items.js). */
|
|
16
|
+
export declare const WORLD_MAP_NAME = "plotilla-world";
|
|
17
|
+
/** What an ECharts map panel adds to the option. */
|
|
18
|
+
export type EChartsMapParts = {
|
|
19
|
+
geo: Record<string, unknown>;
|
|
20
|
+
series: Record<string, unknown>[];
|
|
21
|
+
/** Indices (within `series`) the panel's colour scale drives. */
|
|
22
|
+
scaledSeries: number[];
|
|
23
|
+
/** Density series (indices within `series`), each needing its own visual map: ECharts draws no heatmap without one. */
|
|
24
|
+
densitySeries: {
|
|
25
|
+
index: number;
|
|
26
|
+
maximumWeight: number;
|
|
27
|
+
}[];
|
|
28
|
+
/** Outlines the page must register before drawing: a GeoJSON, or "world". */
|
|
29
|
+
maps: Record<string, FeatureCollection | "world">;
|
|
30
|
+
notice: string | null;
|
|
31
|
+
};
|
|
32
|
+
/**
|
|
33
|
+
* Build a map panel's geo component and series for ECharts.
|
|
34
|
+
*
|
|
35
|
+
* @param panel - A panel with a map.
|
|
36
|
+
* @param options - Its index (for geo and series references), its rectangle, the figure's size in pixels, and the theme.
|
|
37
|
+
* @returns The parts to merge into the option.
|
|
38
|
+
*/
|
|
39
|
+
export declare function buildEChartsMap(panel: PanelModel & {
|
|
40
|
+
map: MapModel;
|
|
41
|
+
}, options: {
|
|
42
|
+
panelIndex: number;
|
|
43
|
+
geoIndex: number;
|
|
44
|
+
rectangle: PanelRectangle;
|
|
45
|
+
size: FigureSize;
|
|
46
|
+
theme: PlotTheme;
|
|
47
|
+
}): EChartsMapParts;
|