plotilla 0.0.0-stage → 1.0.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,174 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* GeoJSON the map needs: checking what agents send, the bounds of what is
|
|
3
|
+
* shown, and great-circle arcs for lines between places.
|
|
4
|
+
*/
|
|
5
|
+
|
|
6
|
+
/** A GeoJSON geometry, loosely typed: this package passes geometries through, only reading coordinates for bounds. */
|
|
7
|
+
export type Geometry = { type: string; coordinates?: unknown; geometries?: Geometry[] };
|
|
8
|
+
|
|
9
|
+
/** A GeoJSON feature. */
|
|
10
|
+
export type Feature = { type: "Feature"; geometry: Geometry | null; properties?: Record<string, unknown> | null; id?: string | number };
|
|
11
|
+
|
|
12
|
+
/** A GeoJSON feature collection. */
|
|
13
|
+
export type FeatureCollection = { type: "FeatureCollection"; features: Feature[] };
|
|
14
|
+
|
|
15
|
+
/** [west, south, east, north] in degrees. */
|
|
16
|
+
export type Bounds = [number, number, number, number];
|
|
17
|
+
|
|
18
|
+
/** Points along a great-circle arc: enough for a smooth curve at any zoom. */
|
|
19
|
+
export const ARC_POINTS = 64;
|
|
20
|
+
|
|
21
|
+
const DEGREES_TO_RADIANS = Math.PI / 180;
|
|
22
|
+
|
|
23
|
+
/**
|
|
24
|
+
* Check a value is a GeoJSON FeatureCollection (or a single Feature, which is wrapped).
|
|
25
|
+
*
|
|
26
|
+
* @param value - Parsed JSON from the agent or a URL.
|
|
27
|
+
* @param options - Where it came from, for error messages.
|
|
28
|
+
* @returns The feature collection.
|
|
29
|
+
*/
|
|
30
|
+
export function readFeatureCollection(value: unknown, options: { where: string }): FeatureCollection {
|
|
31
|
+
if (typeof value !== "object" || value === null) throw new Error(`${options.where}: expected GeoJSON, got ${typeof value}.`);
|
|
32
|
+
const record = value as Record<string, unknown>;
|
|
33
|
+
if (record.type === "Feature") return readFeatureCollection({ type: "FeatureCollection", features: [record] }, options);
|
|
34
|
+
if (record.type !== "FeatureCollection" || !Array.isArray(record.features)) {
|
|
35
|
+
throw new Error(`${options.where}: expected a GeoJSON FeatureCollection; got type "${String(record.type)}".`);
|
|
36
|
+
}
|
|
37
|
+
record.features.forEach((feature, index) => {
|
|
38
|
+
const item = feature as Record<string, unknown> | null;
|
|
39
|
+
if (typeof item !== "object" || item === null || item.type !== "Feature") {
|
|
40
|
+
throw new Error(`${options.where}: features[${index}] is not a GeoJSON Feature.`);
|
|
41
|
+
}
|
|
42
|
+
});
|
|
43
|
+
return value as FeatureCollection;
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
function collectPositions(coordinates: unknown, into: [number, number][]): void {
|
|
47
|
+
if (!Array.isArray(coordinates)) return;
|
|
48
|
+
if (typeof coordinates[0] === "number" && typeof coordinates[1] === "number") {
|
|
49
|
+
into.push([coordinates[0], coordinates[1]]);
|
|
50
|
+
return;
|
|
51
|
+
}
|
|
52
|
+
for (const part of coordinates) collectPositions(part, into);
|
|
53
|
+
}
|
|
54
|
+
|
|
55
|
+
/**
|
|
56
|
+
* Find the bounds of a set of positions.
|
|
57
|
+
*
|
|
58
|
+
* @param positions - [longitude, latitude] pairs.
|
|
59
|
+
* @returns The bounds, or null when there are none.
|
|
60
|
+
*/
|
|
61
|
+
export function findBounds(positions: [number, number][]): Bounds | null {
|
|
62
|
+
if (positions.length === 0) return null;
|
|
63
|
+
let [west, south, east, north] = [Infinity, Infinity, -Infinity, -Infinity];
|
|
64
|
+
for (const [longitude, latitude] of positions) {
|
|
65
|
+
west = Math.min(west, longitude);
|
|
66
|
+
east = Math.max(east, longitude);
|
|
67
|
+
south = Math.min(south, latitude);
|
|
68
|
+
north = Math.max(north, latitude);
|
|
69
|
+
}
|
|
70
|
+
return [west, south, east, north];
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
/**
|
|
74
|
+
* Find the bounds to fit a view to, allowing for the 180° line: places that
|
|
75
|
+
* straddle it (Alaska's Aleutians, Russia's east, Fiji) span less when
|
|
76
|
+
* longitudes west of 0° are counted from 180° to 360°. The narrower reading
|
|
77
|
+
* wins; its east edge may then be past 180.
|
|
78
|
+
*
|
|
79
|
+
* @param positions - [longitude, latitude] pairs.
|
|
80
|
+
* @returns [west, south, east, north], or null if there are none.
|
|
81
|
+
*/
|
|
82
|
+
export function findFittingBounds(positions: [number, number][]): Bounds | null {
|
|
83
|
+
const plain = findBounds(positions);
|
|
84
|
+
if (plain === null) return null;
|
|
85
|
+
const shifted = findBounds(positions.map(([longitude, latitude]): [number, number] => [longitude < 0 ? longitude + FULL_TURN_DEGREES : longitude, latitude]));
|
|
86
|
+
if (shifted === null) return plain;
|
|
87
|
+
// Only a real saving counts: shifting places that never cross the line changes the span by rounding noise alone.
|
|
88
|
+
return (plain[2] - plain[0]) - (shifted[2] - shifted[0]) > WRAP_TOLERANCE_DEGREES ? shifted : plain;
|
|
89
|
+
}
|
|
90
|
+
|
|
91
|
+
/** How much narrower the wrapped reading must be to win (degrees): far above rounding noise, far below any real place. */
|
|
92
|
+
const WRAP_TOLERANCE_DEGREES = 1e-6;
|
|
93
|
+
|
|
94
|
+
/** Degrees in a full turn of longitude. */
|
|
95
|
+
const FULL_TURN_DEGREES = 360;
|
|
96
|
+
|
|
97
|
+
/**
|
|
98
|
+
* Bring a longitude back into -180…180.
|
|
99
|
+
*
|
|
100
|
+
* @param longitude - Any longitude, e.g. past 180 after a wrap-aware fit.
|
|
101
|
+
* @returns The same meridian, between -180 and 180.
|
|
102
|
+
*/
|
|
103
|
+
export function normaliseLongitude(longitude: number): number {
|
|
104
|
+
return ((((longitude + FULL_TURN_DEGREES / 2) % FULL_TURN_DEGREES) + FULL_TURN_DEGREES) % FULL_TURN_DEGREES) - FULL_TURN_DEGREES / 2;
|
|
105
|
+
}
|
|
106
|
+
|
|
107
|
+
/**
|
|
108
|
+
* List every position in a feature collection.
|
|
109
|
+
*
|
|
110
|
+
* @param collection - The features.
|
|
111
|
+
* @returns [longitude, latitude] pairs.
|
|
112
|
+
*/
|
|
113
|
+
export function listPositions(collection: FeatureCollection): [number, number][] {
|
|
114
|
+
const positions: [number, number][] = [];
|
|
115
|
+
const visit = (geometry: Geometry | null): void => {
|
|
116
|
+
if (geometry === null) return;
|
|
117
|
+
if (geometry.type === "GeometryCollection") for (const part of geometry.geometries ?? []) visit(part);
|
|
118
|
+
else collectPositions(geometry.coordinates, positions);
|
|
119
|
+
};
|
|
120
|
+
for (const feature of collection.features) visit(feature.geometry);
|
|
121
|
+
return positions;
|
|
122
|
+
}
|
|
123
|
+
|
|
124
|
+
/**
|
|
125
|
+
* Points along the great circle between two places, so a line follows the
|
|
126
|
+
* curve of the earth (it bends on a flat map, and hugs the globe).
|
|
127
|
+
*
|
|
128
|
+
* @param from - [longitude, latitude].
|
|
129
|
+
* @param options - Where it goes, and how many points to use.
|
|
130
|
+
* @returns The arc's positions, from start to end.
|
|
131
|
+
*/
|
|
132
|
+
export function buildGreatCircleArc(
|
|
133
|
+
from: [number, number],
|
|
134
|
+
options: { to: [number, number]; pointCount?: number },
|
|
135
|
+
): [number, number][] {
|
|
136
|
+
const pointCount = options.pointCount ?? ARC_POINTS;
|
|
137
|
+
const [longitude1, latitude1] = from.map((degrees) => degrees * DEGREES_TO_RADIANS) as [number, number];
|
|
138
|
+
const [longitude2, latitude2] = options.to.map((degrees) => degrees * DEGREES_TO_RADIANS) as [number, number];
|
|
139
|
+
const distance = 2 * Math.asin(Math.sqrt(
|
|
140
|
+
Math.sin((latitude2 - latitude1) / 2) ** 2 + Math.cos(latitude1) * Math.cos(latitude2) * Math.sin((longitude2 - longitude1) / 2) ** 2,
|
|
141
|
+
));
|
|
142
|
+
if (distance === 0) return [from, options.to];
|
|
143
|
+
const positions: [number, number][] = [];
|
|
144
|
+
for (let index = 0; index <= pointCount; index += 1) {
|
|
145
|
+
const fraction = index / pointCount;
|
|
146
|
+
const a = Math.sin((1 - fraction) * distance) / Math.sin(distance);
|
|
147
|
+
const b = Math.sin(fraction * distance) / Math.sin(distance);
|
|
148
|
+
const x = a * Math.cos(latitude1) * Math.cos(longitude1) + b * Math.cos(latitude2) * Math.cos(longitude2);
|
|
149
|
+
const y = a * Math.cos(latitude1) * Math.sin(longitude1) + b * Math.cos(latitude2) * Math.sin(longitude2);
|
|
150
|
+
const z = a * Math.sin(latitude1) + b * Math.sin(latitude2);
|
|
151
|
+
positions.push([Math.atan2(y, x) / DEGREES_TO_RADIANS, Math.atan2(z, Math.sqrt(x * x + y * y)) / DEGREES_TO_RADIANS]);
|
|
152
|
+
}
|
|
153
|
+
// Keep longitudes continuous across the antimeridian, so the line does not jump.
|
|
154
|
+
for (let index = 1; index < positions.length; index += 1) {
|
|
155
|
+
const previous = (positions[index - 1] as [number, number])[0];
|
|
156
|
+
const current = positions[index] as [number, number];
|
|
157
|
+
while (current[0] - previous > 180) current[0] -= 360;
|
|
158
|
+
while (current[0] - previous < -180) current[0] += 360;
|
|
159
|
+
}
|
|
160
|
+
return positions;
|
|
161
|
+
}
|
|
162
|
+
|
|
163
|
+
/**
|
|
164
|
+
* Read a feature's property by name, among its own properties only: a
|
|
165
|
+
* property name like "constructor" would otherwise find Object's member.
|
|
166
|
+
*
|
|
167
|
+
* @param feature - The feature.
|
|
168
|
+
* @param options - The property's name.
|
|
169
|
+
* @returns Its value, or undefined when the feature has no such property.
|
|
170
|
+
*/
|
|
171
|
+
export function findFeatureProperty(feature: Feature, options: { property: string }): unknown {
|
|
172
|
+
const properties = feature.properties;
|
|
173
|
+
return properties !== null && properties !== undefined && Object.hasOwn(properties, options.property) ? properties[options.property] : undefined;
|
|
174
|
+
}
|
|
@@ -0,0 +1,108 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The layers of a map plot: points, density, regions and lines. Each is
|
|
3
|
+
* built from the shared field groups, so `colour`, `colour_scale` and `data`
|
|
4
|
+
* mean on a layer what they mean on a chart.
|
|
5
|
+
*/
|
|
6
|
+
|
|
7
|
+
import { z } from "zod";
|
|
8
|
+
import { COLOUR_FIELDS, COLOUR_SCALE_FIELDS } from "../fields/colour_fields";
|
|
9
|
+
import { LABEL_FIELD, SIZE_FIELD, VALUE_FIELD, defineColumnField } from "../fields/column_fields";
|
|
10
|
+
import { DATA_FIELD } from "../fields/common_fields";
|
|
11
|
+
import { BOUNDARY_SET_NAMES, type BoundarySetName } from "./boundary_sets";
|
|
12
|
+
|
|
13
|
+
const LONGITUDE_FIELD = defineColumnField("The column of longitudes, in degrees.");
|
|
14
|
+
const LATITUDE_FIELD = defineColumnField("The column of latitudes, in degrees.");
|
|
15
|
+
|
|
16
|
+
/** Pins or bubbles at a longitude and latitude, coloured and sized by columns. */
|
|
17
|
+
export const POINTS_LAYER_SCHEMA = z.strictObject({
|
|
18
|
+
type: z.literal("points"),
|
|
19
|
+
longitude: LONGITUDE_FIELD,
|
|
20
|
+
latitude: LATITUDE_FIELD,
|
|
21
|
+
label: LABEL_FIELD.optional(),
|
|
22
|
+
...COLOUR_FIELDS,
|
|
23
|
+
...COLOUR_SCALE_FIELDS,
|
|
24
|
+
size: SIZE_FIELD.optional(),
|
|
25
|
+
data: DATA_FIELD,
|
|
26
|
+
});
|
|
27
|
+
|
|
28
|
+
/** Where places are dense, drawn as heat, optionally weighted. */
|
|
29
|
+
export const DENSITY_LAYER_SCHEMA = z.strictObject({
|
|
30
|
+
type: z.literal("density"),
|
|
31
|
+
longitude: LONGITUDE_FIELD,
|
|
32
|
+
latitude: LATITUDE_FIELD,
|
|
33
|
+
weight: defineColumnField("A column of numbers that weights each place's share of the heat.").optional(),
|
|
34
|
+
data: DATA_FIELD,
|
|
35
|
+
});
|
|
36
|
+
|
|
37
|
+
/** Where a regions layer's outlines may come from: exactly one is given. */
|
|
38
|
+
const REGION_OUTLINE_SOURCES = ["boundaries", "geojson", "geojson_url"] as const;
|
|
39
|
+
|
|
40
|
+
/** Areas from outlines, joined to the table by name and coloured by a value (a choropleth). */
|
|
41
|
+
export const REGIONS_LAYER_SCHEMA = z.strictObject({
|
|
42
|
+
type: z.literal("regions"),
|
|
43
|
+
boundaries: z
|
|
44
|
+
.enum(BOUNDARY_SET_NAMES as [BoundarySetName, ...BoundarySetName[]])
|
|
45
|
+
.optional()
|
|
46
|
+
.describe("A built-in set of outlines; the key column then holds its region names."),
|
|
47
|
+
geojson: z.unknown().optional().describe("The outlines, as a GeoJSON FeatureCollection."),
|
|
48
|
+
geojson_url: z.url().optional().describe("An address to fetch the outlines from, once, when the plot is shown."),
|
|
49
|
+
feature_property: z
|
|
50
|
+
.string()
|
|
51
|
+
.min(1)
|
|
52
|
+
.optional()
|
|
53
|
+
.describe('The GeoJSON property that names each region, e.g. "AREA_NAME". Not needed with boundaries.'),
|
|
54
|
+
key: defineColumnField("The column of region names, matching the outlines."),
|
|
55
|
+
value: VALUE_FIELD.optional(),
|
|
56
|
+
colour_type: COLOUR_FIELDS.colour_type,
|
|
57
|
+
...COLOUR_SCALE_FIELDS,
|
|
58
|
+
data: DATA_FIELD,
|
|
59
|
+
}).superRefine((layer, context) => {
|
|
60
|
+
// Outlines come from one place; a second source would be silently ignored.
|
|
61
|
+
const sources = REGION_OUTLINE_SOURCES.filter((source) => layer[source] !== undefined);
|
|
62
|
+
if (sources.length > 1) {
|
|
63
|
+
context.addIssue({ code: "custom", message: `give one of ${REGION_OUTLINE_SOURCES.join(", ")}; got ${sources.join(" and ")}.` });
|
|
64
|
+
}
|
|
65
|
+
// A built-in set names its regions by its own property, which would replace this one.
|
|
66
|
+
if (layer.boundaries !== undefined && layer.feature_property !== undefined) {
|
|
67
|
+
context.addIssue({ code: "custom", path: ["feature_property"], message: "a built-in boundary set names its regions itself; leave feature_property out." });
|
|
68
|
+
}
|
|
69
|
+
});
|
|
70
|
+
|
|
71
|
+
/** Lines between two places, following the curve of the earth. */
|
|
72
|
+
export const LINES_LAYER_SCHEMA = z.strictObject({
|
|
73
|
+
type: z.literal("lines"),
|
|
74
|
+
from_longitude: defineColumnField("The column of each line's starting longitude."),
|
|
75
|
+
from_latitude: defineColumnField("The column of each line's starting latitude."),
|
|
76
|
+
to_longitude: defineColumnField("The column of each line's ending longitude."),
|
|
77
|
+
to_latitude: defineColumnField("The column of each line's ending latitude."),
|
|
78
|
+
label: LABEL_FIELD.optional(),
|
|
79
|
+
...COLOUR_FIELDS,
|
|
80
|
+
...COLOUR_SCALE_FIELDS,
|
|
81
|
+
width: defineColumnField("A column of numbers that sets each line's width.").optional(),
|
|
82
|
+
data: DATA_FIELD,
|
|
83
|
+
});
|
|
84
|
+
|
|
85
|
+
/** Every map layer type's schema. */
|
|
86
|
+
export const MAP_LAYER_SCHEMAS = [POINTS_LAYER_SCHEMA, DENSITY_LAYER_SCHEMA, REGIONS_LAYER_SCHEMA, LINES_LAYER_SCHEMA] as const;
|
|
87
|
+
|
|
88
|
+
/** Any one map layer, told apart by its type. */
|
|
89
|
+
export const MAP_LAYER_SCHEMA = z.discriminatedUnion("type", MAP_LAYER_SCHEMAS);
|
|
90
|
+
|
|
91
|
+
/** Any one map layer, through the schema. */
|
|
92
|
+
export type MapLayer = z.infer<typeof MAP_LAYER_SCHEMA>;
|
|
93
|
+
/** A points layer, through the schema. */
|
|
94
|
+
export type PointsLayer = z.infer<typeof POINTS_LAYER_SCHEMA>;
|
|
95
|
+
/** A density layer, through the schema. */
|
|
96
|
+
export type DensityLayer = z.infer<typeof DENSITY_LAYER_SCHEMA>;
|
|
97
|
+
/** A regions layer, through the schema. */
|
|
98
|
+
export type RegionsLayer = z.infer<typeof REGIONS_LAYER_SCHEMA>;
|
|
99
|
+
/** A lines layer, through the schema. */
|
|
100
|
+
export type LinesLayer = z.infer<typeof LINES_LAYER_SCHEMA>;
|
|
101
|
+
|
|
102
|
+
/** Each layer type's column fields that must hold numbers. */
|
|
103
|
+
export const LAYER_NUMERIC_COLUMNS: { readonly [Type in MapLayer["type"]]: readonly (keyof Extract<MapLayer, { type: Type }>)[] } = {
|
|
104
|
+
points: ["longitude", "latitude", "size"],
|
|
105
|
+
density: ["longitude", "latitude", "weight"],
|
|
106
|
+
regions: [],
|
|
107
|
+
lines: ["from_longitude", "from_latitude", "to_longitude", "to_latitude", "width"],
|
|
108
|
+
};
|
|
@@ -0,0 +1,58 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Decide whether a value axis shows years, which print plainly (1952), or
|
|
3
|
+
* amounts, which keep their thousands separators (1,450). The values alone
|
|
4
|
+
* cannot tell: rents of 1450-1890 and years built of 1952-2004 are the same
|
|
5
|
+
* shape. So an axis reads as years only when its values look like years and
|
|
6
|
+
* the column it shows is named for years.
|
|
7
|
+
*/
|
|
8
|
+
|
|
9
|
+
/** Whole numbers in this range can be years. */
|
|
10
|
+
const YEAR_RANGE = { first: 1000, last: 2999 };
|
|
11
|
+
|
|
12
|
+
/**
|
|
13
|
+
* Words that name a column of years, matched as whole words of the column name.
|
|
14
|
+
* "yearly" is left out: a yearly rent or income is an amount per year, not a year.
|
|
15
|
+
*/
|
|
16
|
+
const YEAR_WORDS: readonly string[] = [
|
|
17
|
+
// The year itself: year, census_years.
|
|
18
|
+
"year", "years",
|
|
19
|
+
// Events dated by the year they happened: year_built, founded, established, opened, born.
|
|
20
|
+
"built", "founded", "established", "opened", "born",
|
|
21
|
+
// Groupings named by their year: a sports season, a wine's vintage, a student cohort.
|
|
22
|
+
"season", "vintage", "cohort",
|
|
23
|
+
];
|
|
24
|
+
|
|
25
|
+
/** Where a column name breaks into words: underscores, spaces and hyphens. */
|
|
26
|
+
const WORD_SEPARATOR_PATTERN = /[_\s-]+/;
|
|
27
|
+
/** A camelCase boundary: a lowercase letter or digit followed by an uppercase one (yearOpened). */
|
|
28
|
+
const CAMEL_CASE_BOUNDARY_PATTERN = /([a-z0-9])([A-Z])/g;
|
|
29
|
+
|
|
30
|
+
/**
|
|
31
|
+
* Split a column name into lowercase words, on underscores, spaces, hyphens
|
|
32
|
+
* and camelCase boundaries: "yearOpened" and "year_opened" give the same words.
|
|
33
|
+
*
|
|
34
|
+
* @param column - The column name.
|
|
35
|
+
* @returns Its words, lowercase.
|
|
36
|
+
*/
|
|
37
|
+
function splitColumnWords(column: string): string[] {
|
|
38
|
+
return column
|
|
39
|
+
.replace(CAMEL_CASE_BOUNDARY_PATTERN, "$1 $2")
|
|
40
|
+
.split(WORD_SEPARATOR_PATTERN)
|
|
41
|
+
.filter((word) => word !== "")
|
|
42
|
+
.map((word) => word.toLowerCase());
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
/**
|
|
46
|
+
* Decide whether an axis's numbers are years: all whole, all from 1000 to
|
|
47
|
+
* 2999, and the column holding them has a year word in its name. The axis
|
|
48
|
+
* label is not read: it is the caller's wording, the column is the data's.
|
|
49
|
+
*
|
|
50
|
+
* @param options - The column the axis shows (null when it shows none, as a
|
|
51
|
+
* histogram's count axis), and the drawn numbers on it.
|
|
52
|
+
* @returns True when the axis prints its numbers as years.
|
|
53
|
+
*/
|
|
54
|
+
export function checkAxisShowsYears(options: { column: string | null; numbers: number[] }): boolean {
|
|
55
|
+
if (options.column === null || options.numbers.length === 0) return false;
|
|
56
|
+
const looksLikeYears = options.numbers.every((value) => Number.isInteger(value) && value >= YEAR_RANGE.first && value <= YEAR_RANGE.last);
|
|
57
|
+
return looksLikeYears && splitColumnWords(options.column).some((word) => YEAR_WORDS.includes(word));
|
|
58
|
+
}
|
|
@@ -0,0 +1,238 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The renderer-neutral model of a map plot: layers with every colour, join
|
|
3
|
+
* and position decided, and where the view starts. The Plotly and ECharts map
|
|
4
|
+
* mappers only translate this.
|
|
5
|
+
*/
|
|
6
|
+
|
|
7
|
+
import { DEFAULT_LINE_WIDTH_PIXELS, LINE_WIDTH_RANGE_PIXELS, MARKER_SIZE, pickCategoricalColour, PLOT_THEMES, scaleToPixels, SEQUENTIAL_COLOURS, SIZE_RANGE_PIXELS, type PlotTheme } from "../colour/palette";
|
|
8
|
+
import { findColumn, type DataTable } from "../table/data_table";
|
|
9
|
+
import { listCategories } from "../table/list_categories";
|
|
10
|
+
import { applyColourScale, decideColourIsContinuous } from "../colour/colour_scale";
|
|
11
|
+
import type { MapLayerModel, PanelModel } from "./panel_model";
|
|
12
|
+
import { buildGreatCircleArc, findBounds, findFittingBounds, listPositions, normaliseLongitude, findFeatureProperty, type Bounds, type Feature, type FeatureCollection } from "../map/geojson";
|
|
13
|
+
import type { MapPlot } from "../plots/map_plot";
|
|
14
|
+
import type { MapLayer } from "../map/map_layers";
|
|
15
|
+
import { getNumberRange } from "../table/get_number_range";
|
|
16
|
+
|
|
17
|
+
/** With nothing to fit, the map shows the whole world centred here. */
|
|
18
|
+
const WORLD_VIEW = { centre: [0, 20] as [number, number], zoom: 1 };
|
|
19
|
+
/** Degrees of longitude a zoom-0 view spans. */
|
|
20
|
+
const WORLD_SPAN_DEGREES = 360;
|
|
21
|
+
/** Latitude spans count this much more than longitude when fitting (maps are wider than tall). */
|
|
22
|
+
const LATITUDE_WEIGHT = 1.6;
|
|
23
|
+
/** Zoom levels to back off after fitting, so the edges are not at the rim. */
|
|
24
|
+
const FIT_MARGIN_ZOOM = 0.6;
|
|
25
|
+
/** The closest a fitted view zooms, so a single point does not land at street level. */
|
|
26
|
+
const MAXIMUM_FITTED_ZOOM = 12;
|
|
27
|
+
|
|
28
|
+
function readNumber(value: number | string | null | undefined): number | null {
|
|
29
|
+
return typeof value === "number" && Number.isFinite(value) ? value : null;
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
/**
|
|
33
|
+
* Pick a starting zoom that shows the whole of some bounds.
|
|
34
|
+
*
|
|
35
|
+
* @param bounds - [west, south, east, north].
|
|
36
|
+
* @returns A zoom from 0 up.
|
|
37
|
+
*/
|
|
38
|
+
export function fitZoom(bounds: Bounds): number {
|
|
39
|
+
const [west, south, east, north] = bounds;
|
|
40
|
+
const span = Math.max(east - west, (north - south) * LATITUDE_WEIGHT, Number.EPSILON);
|
|
41
|
+
return Math.max(0, Math.min(MAXIMUM_FITTED_ZOOM, Math.log2(WORLD_SPAN_DEGREES / span) - FIT_MARGIN_ZOOM));
|
|
42
|
+
}
|
|
43
|
+
|
|
44
|
+
type ScaleSource = { label: string; values: number[]; ticks: { value: number; text: string }[] | undefined };
|
|
45
|
+
|
|
46
|
+
/** Bottom to top. */
|
|
47
|
+
const DRAW_ORDER: Readonly<Record<MapLayerModel["kind"], number>> = { regions: 0, density: 1, lines: 2, points: 3 };
|
|
48
|
+
|
|
49
|
+
function buildLayer(
|
|
50
|
+
layer: MapLayer,
|
|
51
|
+
options: { table: DataTable; theme: PlotTheme; layerIndex: number; notes: string[]; scales: ScaleSource[] },
|
|
52
|
+
): MapLayerModel[] {
|
|
53
|
+
const table = layer.data ?? options.table;
|
|
54
|
+
const column = (name: string | undefined): (number | string | null)[] | null => (name === undefined ? null : findColumn(table, { column: name }));
|
|
55
|
+
const rowCount = (Object.values(table)[0] ?? []).length;
|
|
56
|
+
const rows = Array.from({ length: rowCount }, (_, row) => row);
|
|
57
|
+
|
|
58
|
+
if (layer.type === "density") {
|
|
59
|
+
const [longitudes, latitudes, weights] = [column(layer.longitude), column(layer.latitude), column(layer.weight)];
|
|
60
|
+
const points = rows.flatMap((row) => {
|
|
61
|
+
const [longitude, latitude] = [readNumber(longitudes?.[row]), readNumber(latitudes?.[row])];
|
|
62
|
+
return longitude === null || latitude === null ? [] : [{ longitude, latitude, weight: weights === null ? 1 : (readNumber(weights[row]) ?? 0) }];
|
|
63
|
+
});
|
|
64
|
+
if (points.length === 0) {
|
|
65
|
+
options.notes.push(`The density layer has no places to show: no row has both a "${layer.longitude}" and a "${layer.latitude}" number.`);
|
|
66
|
+
} else if (points.every((point) => point.weight <= 0)) {
|
|
67
|
+
options.notes.push(`The density layer has no heat to show: every "${layer.weight ?? "weight"}" is zero.`);
|
|
68
|
+
}
|
|
69
|
+
return [{ kind: "density", name: "density", points }];
|
|
70
|
+
}
|
|
71
|
+
|
|
72
|
+
if (layer.type === "regions") {
|
|
73
|
+
const keys = column(layer.key) as (number | string | null)[];
|
|
74
|
+
const values = column(layer.value);
|
|
75
|
+
const isContinuous = values !== null && decideColourIsContinuous(values, { colourType: layer.colour_type });
|
|
76
|
+
const categories = values === null || isContinuous ? [] : listCategories(values);
|
|
77
|
+
const geojson = layer.geojson as FeatureCollection;
|
|
78
|
+
// Validation requires it, and built-in outlines set it, so it is always here by now.
|
|
79
|
+
const featureProperty = layer.feature_property;
|
|
80
|
+
if (featureProperty === undefined) throw new Error("Expected a regions layer to name its feature property by now; it did not.");
|
|
81
|
+
const nameRegion = (feature: Feature, index: number): string => String(findFeatureProperty(feature, { property: featureProperty }) ?? `region ${index + 1}`);
|
|
82
|
+
// Only rows that name an outline are drawn, so only they set the range (a quantile ranks among them alone).
|
|
83
|
+
const outlineNames = new Set(geojson.features.map((feature, index) => nameRegion(feature, index).trim().toLowerCase()));
|
|
84
|
+
// Each outline joins to the last row naming it, so an earlier row repeating the name is never drawn.
|
|
85
|
+
const byKey = new Map<string, number>();
|
|
86
|
+
keys.forEach((key, row) => { if (key !== null) byKey.set(String(key).trim().toLowerCase(), row); });
|
|
87
|
+
const isMatched = (row: number): boolean => {
|
|
88
|
+
const key = keys[row];
|
|
89
|
+
if (key === null || key === undefined) return false;
|
|
90
|
+
const name = String(key).trim().toLowerCase();
|
|
91
|
+
return outlineNames.has(name) && byKey.get(name) === row;
|
|
92
|
+
};
|
|
93
|
+
// Colour follows the scaled value; labels keep the real one.
|
|
94
|
+
const transform = isContinuous && values !== null
|
|
95
|
+
? applyColourScale(values.map((value, row) => (isMatched(row) ? readNumber(value) : null)), { scale: layer.colour_scale, label: layer.value ?? "value", notes: options.notes })
|
|
96
|
+
: null;
|
|
97
|
+
const scaled = new Map<number, number | null>((transform?.values ?? []).map((value, row) => [row, value]));
|
|
98
|
+
const seen = new Set<string>();
|
|
99
|
+
const regions: { id: string; value: number | null; colour: string | null; label: string }[] = [];
|
|
100
|
+
const features = geojson.features.map((feature, index) => {
|
|
101
|
+
const name = nameRegion(feature, index);
|
|
102
|
+
const id = `${options.layerIndex}:${index}`;
|
|
103
|
+
const row = byKey.get(name.trim().toLowerCase());
|
|
104
|
+
if (row !== undefined) seen.add(name.trim().toLowerCase());
|
|
105
|
+
const raw = row === undefined || values === null ? null : values[row];
|
|
106
|
+
const value = isContinuous ? (scaled.get(row ?? -1) ?? null) : null;
|
|
107
|
+
const colour = !isContinuous && raw !== null && raw !== undefined
|
|
108
|
+
? pickCategoricalColour(categories.indexOf(String(raw)), { theme: options.theme })
|
|
109
|
+
: null;
|
|
110
|
+
regions.push({ id, value, colour, label: raw === null || raw === undefined ? name : `${name}: ${raw}` });
|
|
111
|
+
return { ...feature, id, properties: { ...feature.properties, plotilla_id: id, plotilla_name: name } };
|
|
112
|
+
});
|
|
113
|
+
const missing = regions.filter((region) => region.value === null && region.colour === null).length;
|
|
114
|
+
if (values !== null && missing > 0) options.notes.push(`${missing} of ${regions.length} regions had no matching row in the table, so they are left grey.`);
|
|
115
|
+
const unused = keys.filter((key) => key !== null && !seen.has(String(key).trim().toLowerCase())).length;
|
|
116
|
+
if (unused > 0) options.notes.push(`${unused} table row(s) named no region in the outlines (matched on "${layer.feature_property}").`);
|
|
117
|
+
// Disjoint from the note above: these rows do name an outline, but a later row for the same region wins.
|
|
118
|
+
const superseded = keys.filter((key, row) => {
|
|
119
|
+
if (key === null) return false;
|
|
120
|
+
const name = String(key).trim().toLowerCase();
|
|
121
|
+
return outlineNames.has(name) && byKey.get(name) !== row;
|
|
122
|
+
}).length;
|
|
123
|
+
if (superseded > 0) options.notes.push(`${superseded} table row(s) repeat a region named by a later row, so they are not drawn (the later row wins; matched on "${layer.feature_property}").`);
|
|
124
|
+
if (isContinuous && values !== null && layer.value !== undefined) {
|
|
125
|
+
options.scales.push({ label: layer.value, values: regions.flatMap((region) => (region.value === null ? [] : [region.value])), ticks: transform?.ticks });
|
|
126
|
+
}
|
|
127
|
+
return [{ kind: "regions", name: layer.value ?? "regions", geojson: { type: "FeatureCollection", features }, regions }];
|
|
128
|
+
}
|
|
129
|
+
|
|
130
|
+
// Points and lines: split into one layer per colour category, like chart series.
|
|
131
|
+
const colours = column(layer.colour);
|
|
132
|
+
const isContinuous = colours !== null && decideColourIsContinuous(colours, { colourType: layer.colour_type });
|
|
133
|
+
const categories = colours === null || isContinuous ? [""] : listCategories(colours);
|
|
134
|
+
// A row is drawn when every coordinate is a number and, coloured by category, it has a category (a layer to be in).
|
|
135
|
+
// Drawing and every range below use this one rule, so a row that is not drawn never sets a range.
|
|
136
|
+
const coordinates = (layer.type === "points" ? [layer.longitude, layer.latitude] : [layer.from_longitude, layer.from_latitude, layer.to_longitude, layer.to_latitude]).map(column);
|
|
137
|
+
const isDrawn = (row: number): boolean => coordinates.every((values) => readNumber(values?.[row]) !== null)
|
|
138
|
+
&& (colours === null || isContinuous || (colours[row] !== null && colours[row] !== undefined));
|
|
139
|
+
const transform = isContinuous && colours !== null
|
|
140
|
+
? applyColourScale(colours.map((value, row) => (isDrawn(row) ? readNumber(value) : null)), { scale: layer.colour_scale, label: layer.colour ?? "colour", notes: options.notes })
|
|
141
|
+
: null;
|
|
142
|
+
if (transform !== null && layer.colour !== undefined) {
|
|
143
|
+
options.scales.push({ label: layer.colour, values: transform.values.flatMap((value) => (value === null ? [] : [value])), ticks: transform.ticks });
|
|
144
|
+
}
|
|
145
|
+
// Sizes and widths scale once over the layer's drawn rows, across categories, so one value is one size on the whole map.
|
|
146
|
+
const sizeColumn = layer.type === "points" ? column(layer.size) : null;
|
|
147
|
+
const sizePixels = sizeColumn === null ? null : scaleToPixels(sizeColumn.map((value, row) => (isDrawn(row) ? readNumber(value) : null)), { range: SIZE_RANGE_PIXELS, fallback: MARKER_SIZE });
|
|
148
|
+
const widthColumn = layer.type === "lines" ? column(layer.width) : null;
|
|
149
|
+
const widthPixels = widthColumn === null ? null : scaleToPixels(widthColumn.map((value, row) => (isDrawn(row) ? readNumber(value) : null)), { range: LINE_WIDTH_RANGE_PIXELS, fallback: DEFAULT_LINE_WIDTH_PIXELS });
|
|
150
|
+
const labels = column(layer.label);
|
|
151
|
+
const drawnRows = rows.filter(isDrawn);
|
|
152
|
+
return categories.map((category, categoryIndex) => {
|
|
153
|
+
const inCategory = drawnRows.filter((row) => colours === null || isContinuous || String(colours[row]) === category);
|
|
154
|
+
// Categories take palette slots in order; a layer with no colour column takes the slot of its position, so layers differ.
|
|
155
|
+
const isCategory = colours !== null && !isContinuous;
|
|
156
|
+
const colour = isContinuous ? null : pickCategoricalColour(isCategory ? categoryIndex : options.layerIndex, { theme: options.theme });
|
|
157
|
+
const name = category === "" ? layer.type : category;
|
|
158
|
+
const label = (row: number): string | null => (labels === null || labels[row] === null || labels[row] === undefined ? null : String(labels[row]));
|
|
159
|
+
const colourValue = (row: number): number | null => (transform === null ? null : (transform.values[row] ?? null));
|
|
160
|
+
if (layer.type === "points") {
|
|
161
|
+
const [longitudes, latitudes] = [column(layer.longitude), column(layer.latitude)];
|
|
162
|
+
return {
|
|
163
|
+
kind: "points" as const, name, colour, isCategory,
|
|
164
|
+
points: inCategory.flatMap((row) => {
|
|
165
|
+
const [longitude, latitude] = [readNumber(longitudes?.[row]), readNumber(latitudes?.[row])];
|
|
166
|
+
return longitude === null || latitude === null ? [] : [{ longitude, latitude, label: label(row), sizePixels: sizePixels === null ? MARKER_SIZE : (sizePixels[row] ?? MARKER_SIZE), colourValue: colourValue(row) }];
|
|
167
|
+
}),
|
|
168
|
+
};
|
|
169
|
+
}
|
|
170
|
+
const [fromLongitudes, fromLatitudes, toLongitudes, toLatitudes] =
|
|
171
|
+
[column(layer.from_longitude), column(layer.from_latitude), column(layer.to_longitude), column(layer.to_latitude)];
|
|
172
|
+
return {
|
|
173
|
+
kind: "lines" as const, name, colour, isCategory,
|
|
174
|
+
lines: inCategory.flatMap((row) => {
|
|
175
|
+
const ends = [fromLongitudes?.[row], fromLatitudes?.[row], toLongitudes?.[row], toLatitudes?.[row]].map(readNumber);
|
|
176
|
+
if (ends.some((value) => value === null)) return [];
|
|
177
|
+
const [fromLongitude, fromLatitude, toLongitude, toLatitude] = ends as number[];
|
|
178
|
+
return [{
|
|
179
|
+
path: buildGreatCircleArc([fromLongitude as number, fromLatitude as number], { to: [toLongitude as number, toLatitude as number] }),
|
|
180
|
+
widthPixels: widthPixels === null ? DEFAULT_LINE_WIDTH_PIXELS : (widthPixels[row] ?? DEFAULT_LINE_WIDTH_PIXELS), colourValue: colourValue(row), label: label(row),
|
|
181
|
+
}];
|
|
182
|
+
}),
|
|
183
|
+
};
|
|
184
|
+
});
|
|
185
|
+
}
|
|
186
|
+
|
|
187
|
+
/**
|
|
188
|
+
* Build the panel for a map plot.
|
|
189
|
+
*
|
|
190
|
+
* @param plot - A validated map plot.
|
|
191
|
+
* @param options - The figure's table and the theme.
|
|
192
|
+
* @returns The panel, with its map model.
|
|
193
|
+
*/
|
|
194
|
+
export function buildMapPanel(plot: MapPlot, options: { table: DataTable; theme: PlotTheme }): PanelModel {
|
|
195
|
+
const notes: string[] = [];
|
|
196
|
+
const scales: ScaleSource[] = [];
|
|
197
|
+
// Drawn bottom to top: areas, then heat, then routes, with places on top so nothing hides them.
|
|
198
|
+
const layers = plot.layers
|
|
199
|
+
.flatMap((layer, layerIndex) => buildLayer(layer, { table: plot.data ?? options.table, theme: options.theme, layerIndex, notes, scales }))
|
|
200
|
+
.sort((first, second) => DRAW_ORDER[first.kind] - DRAW_ORDER[second.kind]);
|
|
201
|
+
// One colour scale per map: validation refuses a second layer colouring by a number, naming it.
|
|
202
|
+
|
|
203
|
+
const positions: [number, number][] = layers.flatMap((layer) => {
|
|
204
|
+
if (layer.kind === "regions") return listPositions(layer.geojson);
|
|
205
|
+
if (layer.kind === "lines") return layer.lines.flatMap((line) => line.path);
|
|
206
|
+
return layer.points.map((point): [number, number] => [point.longitude, point.latitude]);
|
|
207
|
+
});
|
|
208
|
+
const bounds = findBounds(positions);
|
|
209
|
+
// The view is fitted allowing for the 180° line, so Alaska's Aleutians do not pull a US map out to the whole world.
|
|
210
|
+
const fitting = findFittingBounds(positions);
|
|
211
|
+
const fitted = fitting === null
|
|
212
|
+
? WORLD_VIEW
|
|
213
|
+
: { centre: [normaliseLongitude((fitting[0] + fitting[2]) / 2), (fitting[1] + fitting[3]) / 2] as [number, number], zoom: fitZoom(fitting) };
|
|
214
|
+
const scale = scales[0];
|
|
215
|
+
return {
|
|
216
|
+
title: plot.title ?? null,
|
|
217
|
+
xAxis: null,
|
|
218
|
+
yAxis: null,
|
|
219
|
+
series: [],
|
|
220
|
+
colourScale: scale === undefined || scale.values.length === 0
|
|
221
|
+
? null
|
|
222
|
+
: { label: scale.label, ...getNumberRange(scale.values), colours: SEQUENTIAL_COLOURS, ...(scale.ticks === undefined ? {} : { ticks: scale.ticks }) },
|
|
223
|
+
map: {
|
|
224
|
+
projection: plot.projection,
|
|
225
|
+
centre: plot.centre ?? fitted.centre,
|
|
226
|
+
zoom: plot.zoom ?? fitted.zoom,
|
|
227
|
+
isZoomGiven: plot.zoom !== undefined,
|
|
228
|
+
bounds,
|
|
229
|
+
layers,
|
|
230
|
+
notes,
|
|
231
|
+
},
|
|
232
|
+
};
|
|
233
|
+
}
|
|
234
|
+
|
|
235
|
+
/** The neutral fill for regions with no data, per theme. */
|
|
236
|
+
export function pickNoDataColour(theme: PlotTheme): string {
|
|
237
|
+
return PLOT_THEMES[theme].gridLine;
|
|
238
|
+
}
|