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.
Files changed (155) hide show
  1. package/README.md +37 -11
  2. package/data/boundaries/world_countries.geojson +1 -1
  3. package/dist/colour/colour_scale.d.ts +55 -0
  4. package/dist/colour/colour_scale.js +80 -0
  5. package/dist/colour/palette.d.ts +176 -0
  6. package/dist/colour/palette.js +220 -0
  7. package/dist/fields/axis_fields.d.ts +56 -0
  8. package/dist/fields/axis_fields.js +46 -0
  9. package/dist/fields/colour_fields.d.ts +32 -0
  10. package/dist/fields/colour_fields.js +31 -0
  11. package/dist/fields/column_fields.d.ts +52 -0
  12. package/{src/fields/column_fields.ts → dist/fields/column_fields.js} +15 -29
  13. package/dist/fields/common_fields.d.ts +9 -0
  14. package/{src/fields/common_fields.ts → dist/fields/common_fields.js} +3 -6
  15. package/dist/fields/decide_plot_axes.d.ts +56 -0
  16. package/dist/fields/decide_plot_axes.js +71 -0
  17. package/dist/fields/marker_fields.d.ts +8 -0
  18. package/dist/fields/marker_fields.js +13 -0
  19. package/dist/fields/read_date_time.d.ts +85 -0
  20. package/dist/fields/read_date_time.js +199 -0
  21. package/dist/figure/check_axis_year_formats.d.ts +36 -0
  22. package/dist/figure/check_axis_year_formats.js +116 -0
  23. package/dist/figure/check_plot_category_limits.d.ts +128 -0
  24. package/dist/figure/check_plot_category_limits.js +284 -0
  25. package/dist/figure/plot_figure.d.ts +861 -0
  26. package/dist/figure/plot_figure.js +58 -0
  27. package/dist/figure/resolve_plot_figure.d.ts +28 -0
  28. package/dist/figure/resolve_plot_figure.js +41 -0
  29. package/dist/figure/validate_plot_figure.d.ts +50 -0
  30. package/dist/figure/validate_plot_figure.js +441 -0
  31. package/dist/map/assign_map_layer_hue_slots.d.ts +89 -0
  32. package/dist/map/assign_map_layer_hue_slots.js +146 -0
  33. package/dist/map/boundary_sets.d.ts +65 -0
  34. package/dist/map/boundary_sets.js +103 -0
  35. package/dist/map/build_world_outline_across_180.d.ts +21 -0
  36. package/dist/map/build_world_outline_across_180.js +23 -0
  37. package/dist/map/check_map_layers.d.ts +16 -0
  38. package/dist/map/check_map_layers.js +31 -0
  39. package/dist/map/fetch_region_outlines.d.ts +25 -0
  40. package/dist/map/fetch_region_outlines.js +39 -0
  41. package/dist/map/geojson.d.ts +150 -0
  42. package/dist/map/geojson.js +248 -0
  43. package/dist/map/join_region_rows.d.ts +40 -0
  44. package/dist/map/join_region_rows.js +45 -0
  45. package/dist/map/map_layers.d.ts +229 -0
  46. package/dist/map/map_layers.js +87 -0
  47. package/dist/model/find_panel_colour_scale.d.ts +25 -0
  48. package/dist/model/find_panel_colour_scale.js +27 -0
  49. package/dist/model/map_model.d.ts +30 -0
  50. package/dist/model/map_model.js +234 -0
  51. package/dist/model/panel_layout.d.ts +42 -0
  52. package/dist/model/panel_layout.js +154 -0
  53. package/dist/model/panel_model.d.ts +223 -0
  54. package/dist/model/panel_model.js +7 -0
  55. package/dist/model/plot_model.d.ts +28 -0
  56. package/dist/model/plot_model.js +431 -0
  57. package/dist/model/statistics.d.ts +83 -0
  58. package/dist/model/statistics.js +107 -0
  59. package/dist/plots/bar_plot.d.ts +46 -0
  60. package/dist/plots/bar_plot.js +30 -0
  61. package/dist/plots/box_plot.d.ts +30 -0
  62. package/dist/plots/box_plot.js +21 -0
  63. package/dist/plots/density_plot.d.ts +36 -0
  64. package/dist/plots/density_plot.js +23 -0
  65. package/dist/plots/heatmap_plot.d.ts +22 -0
  66. package/dist/plots/heatmap_plot.js +18 -0
  67. package/dist/plots/histogram_plot.d.ts +32 -0
  68. package/dist/plots/histogram_plot.js +24 -0
  69. package/dist/plots/line_plot.d.ts +44 -0
  70. package/dist/plots/line_plot.js +25 -0
  71. package/dist/plots/map_plot.d.ts +92 -0
  72. package/dist/plots/map_plot.js +35 -0
  73. package/dist/plots/pie_plot.d.ts +17 -0
  74. package/dist/plots/pie_plot.js +16 -0
  75. package/dist/plots/scatter_plot.d.ts +47 -0
  76. package/dist/plots/scatter_plot.js +27 -0
  77. package/dist/renderers/date_ticks.d.ts +37 -0
  78. package/dist/renderers/date_ticks.js +148 -0
  79. package/dist/renderers/echarts_map.d.ts +47 -0
  80. package/dist/renderers/echarts_map.js +492 -0
  81. package/dist/renderers/echarts_options.d.ts +30 -0
  82. package/dist/renderers/echarts_options.js +449 -0
  83. package/dist/renderers/echarts_pie_radius.d.ts +52 -0
  84. package/dist/renderers/echarts_pie_radius.js +158 -0
  85. package/dist/renderers/escape_html.d.ts +10 -0
  86. package/dist/renderers/escape_html.js +15 -0
  87. package/dist/renderers/line_colour_segments.d.ts +39 -0
  88. package/dist/renderers/line_colour_segments.js +41 -0
  89. package/dist/renderers/plotly_map.d.ts +48 -0
  90. package/dist/renderers/plotly_map.js +159 -0
  91. package/dist/renderers/plotly_options.d.ts +19 -0
  92. package/dist/renderers/plotly_options.js +345 -0
  93. package/dist/renderers/year_ticks.d.ts +27 -0
  94. package/dist/renderers/year_ticks.js +42 -0
  95. package/dist/table/check_column.d.ts +36 -0
  96. package/dist/table/check_column.js +46 -0
  97. package/dist/table/check_values_have_spread.d.ts +30 -0
  98. package/{src/table/check_values_have_spread.ts → dist/table/check_values_have_spread.js} +16 -17
  99. package/dist/table/compute_quantile.d.ts +16 -0
  100. package/dist/table/compute_quantile.js +23 -0
  101. package/dist/table/data_table.d.ts +59 -0
  102. package/dist/table/data_table.js +87 -0
  103. package/dist/table/density_bandwidth.d.ts +64 -0
  104. package/dist/table/density_bandwidth.js +88 -0
  105. package/dist/table/find_line_fit.d.ts +30 -0
  106. package/dist/table/find_line_fit.js +36 -0
  107. package/dist/table/get_number_range.d.ts +16 -0
  108. package/{src/table/get_number_range.ts → dist/table/get_number_range.js} +8 -8
  109. package/dist/table/group_rows.d.ts +40 -0
  110. package/dist/table/group_rows.js +67 -0
  111. package/dist/table/list_categories.d.ts +14 -0
  112. package/{src/table/list_categories.ts → dist/table/list_categories.js} +2 -3
  113. package/dist/table/read_number.d.ts +12 -0
  114. package/dist/table/read_number.js +14 -0
  115. package/package.json +30 -25
  116. package/src/colour/colour_scale.ts +0 -80
  117. package/src/colour/palette.ts +0 -220
  118. package/src/examples/example_figures.ts +0 -320
  119. package/src/fields/axis_fields.ts +0 -32
  120. package/src/fields/colour_fields.ts +0 -40
  121. package/src/fields/decide_plot_axes.ts +0 -77
  122. package/src/fields/marker_fields.ts +0 -16
  123. package/src/figure/plot_figure.ts +0 -67
  124. package/src/figure/resolve_plot_figure.ts +0 -47
  125. package/src/figure/validate_plot_figure.ts +0 -412
  126. package/src/map/boundary_sets.ts +0 -116
  127. package/src/map/check_map_layers.ts +0 -32
  128. package/src/map/fetch_region_outlines.ts +0 -48
  129. package/src/map/geojson.ts +0 -174
  130. package/src/map/map_layers.ts +0 -108
  131. package/src/model/check_axis_shows_years.ts +0 -58
  132. package/src/model/map_model.ts +0 -238
  133. package/src/model/panel_layout.ts +0 -171
  134. package/src/model/panel_model.ts +0 -85
  135. package/src/model/plot_model.ts +0 -347
  136. package/src/model/statistics.ts +0 -134
  137. package/src/plots/bar_plot.ts +0 -36
  138. package/src/plots/box_plot.ts +0 -26
  139. package/src/plots/density_plot.ts +0 -29
  140. package/src/plots/heatmap_plot.ts +0 -24
  141. package/src/plots/histogram_plot.ts +0 -29
  142. package/src/plots/line_plot.ts +0 -29
  143. package/src/plots/map_plot.ts +0 -46
  144. package/src/plots/pie_plot.ts +0 -23
  145. package/src/plots/scatter_plot.ts +0 -32
  146. package/src/renderers/echarts_map.ts +0 -194
  147. package/src/renderers/echarts_options.ts +0 -317
  148. package/src/renderers/plotly_map.ts +0 -170
  149. package/src/renderers/plotly_options.ts +0 -318
  150. package/src/table/check_column.ts +0 -34
  151. package/src/table/compute_quantile.ts +0 -23
  152. package/src/table/data_table.ts +0 -83
  153. package/src/table/density_bandwidth.ts +0 -94
  154. package/src/table/find_line_fit.ts +0 -44
  155. package/src/table/group_rows.ts +0 -71
@@ -0,0 +1,229 @@
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
+ import { z } from "zod";
7
+ /** Pins or bubbles at a longitude and latitude, coloured and sized by columns. */
8
+ export declare const POINTS_LAYER_SCHEMA: z.ZodObject<{
9
+ colour: z.ZodOptional<z.ZodString>;
10
+ colour_type: z.ZodOptional<z.ZodEnum<{
11
+ categorical: "categorical";
12
+ continuous: "continuous";
13
+ }>>;
14
+ colour_scale: z.ZodOptional<z.ZodEnum<{
15
+ linear: "linear";
16
+ log: "log";
17
+ quantile: "quantile";
18
+ }>>;
19
+ type: z.ZodLiteral<"points">;
20
+ longitude: z.ZodString;
21
+ latitude: z.ZodString;
22
+ label: z.ZodOptional<z.ZodString>;
23
+ size: z.ZodOptional<z.ZodString>;
24
+ data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodUnion<readonly [z.ZodNumber, z.ZodPipe<z.ZodString, z.ZodTransform<string | null, string>>, z.ZodNull]>>>>;
25
+ }, z.core.$strict>;
26
+ /** Where places are dense, drawn as heat, optionally weighted. */
27
+ export declare const DENSITY_LAYER_SCHEMA: z.ZodObject<{
28
+ type: z.ZodLiteral<"density">;
29
+ longitude: z.ZodString;
30
+ latitude: z.ZodString;
31
+ weight: z.ZodOptional<z.ZodString>;
32
+ data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodUnion<readonly [z.ZodNumber, z.ZodPipe<z.ZodString, z.ZodTransform<string | null, string>>, z.ZodNull]>>>>;
33
+ }, z.core.$strict>;
34
+ /** Areas from outlines, joined to the table by name and coloured by a value (a choropleth). */
35
+ export declare const REGIONS_LAYER_SCHEMA: z.ZodObject<{
36
+ colour_scale: z.ZodOptional<z.ZodEnum<{
37
+ linear: "linear";
38
+ log: "log";
39
+ quantile: "quantile";
40
+ }>>;
41
+ type: z.ZodLiteral<"regions">;
42
+ boundaries: z.ZodOptional<z.ZodEnum<{
43
+ canada_provinces: "canada_provinces";
44
+ eu_countries: "eu_countries";
45
+ us_states: "us_states";
46
+ world_countries: "world_countries";
47
+ }>>;
48
+ geojson: z.ZodOptional<z.ZodUnknown>;
49
+ geojson_url: z.ZodOptional<z.ZodURL>;
50
+ feature_property: z.ZodOptional<z.ZodString>;
51
+ key: z.ZodString;
52
+ value: z.ZodOptional<z.ZodString>;
53
+ colour_type: z.ZodOptional<z.ZodEnum<{
54
+ categorical: "categorical";
55
+ continuous: "continuous";
56
+ }>>;
57
+ data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodUnion<readonly [z.ZodNumber, z.ZodPipe<z.ZodString, z.ZodTransform<string | null, string>>, z.ZodNull]>>>>;
58
+ }, z.core.$strict>;
59
+ /** Lines between two places, following the curve of the earth. */
60
+ export declare const LINES_LAYER_SCHEMA: z.ZodObject<{
61
+ colour: z.ZodOptional<z.ZodString>;
62
+ colour_type: z.ZodOptional<z.ZodEnum<{
63
+ categorical: "categorical";
64
+ continuous: "continuous";
65
+ }>>;
66
+ colour_scale: z.ZodOptional<z.ZodEnum<{
67
+ linear: "linear";
68
+ log: "log";
69
+ quantile: "quantile";
70
+ }>>;
71
+ type: z.ZodLiteral<"lines">;
72
+ from_longitude: z.ZodString;
73
+ from_latitude: z.ZodString;
74
+ to_longitude: z.ZodString;
75
+ to_latitude: z.ZodString;
76
+ label: z.ZodOptional<z.ZodString>;
77
+ width: z.ZodOptional<z.ZodString>;
78
+ data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodUnion<readonly [z.ZodNumber, z.ZodPipe<z.ZodString, z.ZodTransform<string | null, string>>, z.ZodNull]>>>>;
79
+ }, z.core.$strict>;
80
+ /** Every map layer type's schema. */
81
+ export declare const MAP_LAYER_SCHEMAS: readonly [z.ZodObject<{
82
+ colour: z.ZodOptional<z.ZodString>;
83
+ colour_type: z.ZodOptional<z.ZodEnum<{
84
+ categorical: "categorical";
85
+ continuous: "continuous";
86
+ }>>;
87
+ colour_scale: z.ZodOptional<z.ZodEnum<{
88
+ linear: "linear";
89
+ log: "log";
90
+ quantile: "quantile";
91
+ }>>;
92
+ type: z.ZodLiteral<"points">;
93
+ longitude: z.ZodString;
94
+ latitude: z.ZodString;
95
+ label: z.ZodOptional<z.ZodString>;
96
+ size: z.ZodOptional<z.ZodString>;
97
+ data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodUnion<readonly [z.ZodNumber, z.ZodPipe<z.ZodString, z.ZodTransform<string | null, string>>, z.ZodNull]>>>>;
98
+ }, z.core.$strict>, z.ZodObject<{
99
+ type: z.ZodLiteral<"density">;
100
+ longitude: z.ZodString;
101
+ latitude: z.ZodString;
102
+ weight: z.ZodOptional<z.ZodString>;
103
+ data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodUnion<readonly [z.ZodNumber, z.ZodPipe<z.ZodString, z.ZodTransform<string | null, string>>, z.ZodNull]>>>>;
104
+ }, z.core.$strict>, z.ZodObject<{
105
+ colour_scale: z.ZodOptional<z.ZodEnum<{
106
+ linear: "linear";
107
+ log: "log";
108
+ quantile: "quantile";
109
+ }>>;
110
+ type: z.ZodLiteral<"regions">;
111
+ boundaries: z.ZodOptional<z.ZodEnum<{
112
+ canada_provinces: "canada_provinces";
113
+ eu_countries: "eu_countries";
114
+ us_states: "us_states";
115
+ world_countries: "world_countries";
116
+ }>>;
117
+ geojson: z.ZodOptional<z.ZodUnknown>;
118
+ geojson_url: z.ZodOptional<z.ZodURL>;
119
+ feature_property: z.ZodOptional<z.ZodString>;
120
+ key: z.ZodString;
121
+ value: z.ZodOptional<z.ZodString>;
122
+ colour_type: z.ZodOptional<z.ZodEnum<{
123
+ categorical: "categorical";
124
+ continuous: "continuous";
125
+ }>>;
126
+ data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodUnion<readonly [z.ZodNumber, z.ZodPipe<z.ZodString, z.ZodTransform<string | null, string>>, z.ZodNull]>>>>;
127
+ }, z.core.$strict>, z.ZodObject<{
128
+ colour: z.ZodOptional<z.ZodString>;
129
+ colour_type: z.ZodOptional<z.ZodEnum<{
130
+ categorical: "categorical";
131
+ continuous: "continuous";
132
+ }>>;
133
+ colour_scale: z.ZodOptional<z.ZodEnum<{
134
+ linear: "linear";
135
+ log: "log";
136
+ quantile: "quantile";
137
+ }>>;
138
+ type: z.ZodLiteral<"lines">;
139
+ from_longitude: z.ZodString;
140
+ from_latitude: z.ZodString;
141
+ to_longitude: z.ZodString;
142
+ to_latitude: z.ZodString;
143
+ label: z.ZodOptional<z.ZodString>;
144
+ width: z.ZodOptional<z.ZodString>;
145
+ data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodUnion<readonly [z.ZodNumber, z.ZodPipe<z.ZodString, z.ZodTransform<string | null, string>>, z.ZodNull]>>>>;
146
+ }, z.core.$strict>];
147
+ /** Any one map layer, told apart by its type. */
148
+ export declare const MAP_LAYER_SCHEMA: z.ZodDiscriminatedUnion<readonly [z.ZodObject<{
149
+ colour: z.ZodOptional<z.ZodString>;
150
+ colour_type: z.ZodOptional<z.ZodEnum<{
151
+ categorical: "categorical";
152
+ continuous: "continuous";
153
+ }>>;
154
+ colour_scale: z.ZodOptional<z.ZodEnum<{
155
+ linear: "linear";
156
+ log: "log";
157
+ quantile: "quantile";
158
+ }>>;
159
+ type: z.ZodLiteral<"points">;
160
+ longitude: z.ZodString;
161
+ latitude: z.ZodString;
162
+ label: z.ZodOptional<z.ZodString>;
163
+ size: z.ZodOptional<z.ZodString>;
164
+ data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodUnion<readonly [z.ZodNumber, z.ZodPipe<z.ZodString, z.ZodTransform<string | null, string>>, z.ZodNull]>>>>;
165
+ }, z.core.$strict>, z.ZodObject<{
166
+ type: z.ZodLiteral<"density">;
167
+ longitude: z.ZodString;
168
+ latitude: z.ZodString;
169
+ weight: z.ZodOptional<z.ZodString>;
170
+ data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodUnion<readonly [z.ZodNumber, z.ZodPipe<z.ZodString, z.ZodTransform<string | null, string>>, z.ZodNull]>>>>;
171
+ }, z.core.$strict>, z.ZodObject<{
172
+ colour_scale: z.ZodOptional<z.ZodEnum<{
173
+ linear: "linear";
174
+ log: "log";
175
+ quantile: "quantile";
176
+ }>>;
177
+ type: z.ZodLiteral<"regions">;
178
+ boundaries: z.ZodOptional<z.ZodEnum<{
179
+ canada_provinces: "canada_provinces";
180
+ eu_countries: "eu_countries";
181
+ us_states: "us_states";
182
+ world_countries: "world_countries";
183
+ }>>;
184
+ geojson: z.ZodOptional<z.ZodUnknown>;
185
+ geojson_url: z.ZodOptional<z.ZodURL>;
186
+ feature_property: z.ZodOptional<z.ZodString>;
187
+ key: z.ZodString;
188
+ value: z.ZodOptional<z.ZodString>;
189
+ colour_type: z.ZodOptional<z.ZodEnum<{
190
+ categorical: "categorical";
191
+ continuous: "continuous";
192
+ }>>;
193
+ data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodUnion<readonly [z.ZodNumber, z.ZodPipe<z.ZodString, z.ZodTransform<string | null, string>>, z.ZodNull]>>>>;
194
+ }, z.core.$strict>, z.ZodObject<{
195
+ colour: z.ZodOptional<z.ZodString>;
196
+ colour_type: z.ZodOptional<z.ZodEnum<{
197
+ categorical: "categorical";
198
+ continuous: "continuous";
199
+ }>>;
200
+ colour_scale: z.ZodOptional<z.ZodEnum<{
201
+ linear: "linear";
202
+ log: "log";
203
+ quantile: "quantile";
204
+ }>>;
205
+ type: z.ZodLiteral<"lines">;
206
+ from_longitude: z.ZodString;
207
+ from_latitude: z.ZodString;
208
+ to_longitude: z.ZodString;
209
+ to_latitude: z.ZodString;
210
+ label: z.ZodOptional<z.ZodString>;
211
+ width: z.ZodOptional<z.ZodString>;
212
+ data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodUnion<readonly [z.ZodNumber, z.ZodPipe<z.ZodString, z.ZodTransform<string | null, string>>, z.ZodNull]>>>>;
213
+ }, z.core.$strict>], "type">;
214
+ /** Any one map layer, through the schema. */
215
+ export type MapLayer = z.infer<typeof MAP_LAYER_SCHEMA>;
216
+ /** A points layer, through the schema. */
217
+ export type PointsLayer = z.infer<typeof POINTS_LAYER_SCHEMA>;
218
+ /** A density layer, through the schema. */
219
+ export type DensityLayer = z.infer<typeof DENSITY_LAYER_SCHEMA>;
220
+ /** A regions layer, through the schema. */
221
+ export type RegionsLayer = z.infer<typeof REGIONS_LAYER_SCHEMA>;
222
+ /** A lines layer, through the schema. */
223
+ export type LinesLayer = z.infer<typeof LINES_LAYER_SCHEMA>;
224
+ /** Each layer type's column fields that must hold numbers. */
225
+ export declare const LAYER_NUMERIC_COLUMNS: {
226
+ readonly [Type in MapLayer["type"]]: readonly (keyof Extract<MapLayer, {
227
+ type: Type;
228
+ }>)[];
229
+ };
@@ -0,0 +1,87 @@
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
+ import { z } from "zod";
7
+ import { COLOUR_FIELDS, COLOUR_SCALE_FIELDS } from "../fields/colour_fields.js";
8
+ import { LABEL_FIELD, SIZE_FIELD, VALUE_FIELD, defineColumnField } from "../fields/column_fields.js";
9
+ import { DATA_FIELD } from "../fields/common_fields.js";
10
+ import { BOUNDARY_SET_NAMES } from "./boundary_sets.js";
11
+ const LONGITUDE_FIELD = defineColumnField("The column of longitudes, in degrees.");
12
+ const LATITUDE_FIELD = defineColumnField("The column of latitudes, in degrees.");
13
+ /** Pins or bubbles at a longitude and latitude, coloured and sized by columns. */
14
+ export const POINTS_LAYER_SCHEMA = z.strictObject({
15
+ type: z.literal("points"),
16
+ longitude: LONGITUDE_FIELD,
17
+ latitude: LATITUDE_FIELD,
18
+ label: LABEL_FIELD.optional(),
19
+ ...COLOUR_FIELDS,
20
+ ...COLOUR_SCALE_FIELDS,
21
+ size: SIZE_FIELD.optional(),
22
+ data: DATA_FIELD,
23
+ });
24
+ /** Where places are dense, drawn as heat, optionally weighted. */
25
+ export const DENSITY_LAYER_SCHEMA = z.strictObject({
26
+ type: z.literal("density"),
27
+ longitude: LONGITUDE_FIELD,
28
+ latitude: LATITUDE_FIELD,
29
+ weight: defineColumnField("A column of numbers that weights each place's share of the heat.").optional(),
30
+ data: DATA_FIELD,
31
+ });
32
+ /** Where a regions layer's outlines may come from: exactly one is given. */
33
+ const REGION_OUTLINE_SOURCES = ["boundaries", "geojson", "geojson_url"];
34
+ /** Areas from outlines, joined to the table by name and coloured by a value (a choropleth). */
35
+ export const REGIONS_LAYER_SCHEMA = z.strictObject({
36
+ type: z.literal("regions"),
37
+ boundaries: z
38
+ .enum(BOUNDARY_SET_NAMES)
39
+ .optional()
40
+ .describe("A built-in set of outlines; the key column then holds its region names."),
41
+ geojson: z.unknown().optional().describe("The outlines, as a GeoJSON FeatureCollection."),
42
+ geojson_url: z.url().optional().describe("An address to fetch the outlines from, once, when the plot is shown."),
43
+ feature_property: z
44
+ .string()
45
+ .min(1)
46
+ .optional()
47
+ .describe('The GeoJSON property that names each region, e.g. "AREA_NAME". Not needed with boundaries.'),
48
+ key: defineColumnField("The column of region names, matching the outlines."),
49
+ value: VALUE_FIELD.optional(),
50
+ colour_type: COLOUR_FIELDS.colour_type,
51
+ ...COLOUR_SCALE_FIELDS,
52
+ data: DATA_FIELD,
53
+ }).superRefine((layer, context) => {
54
+ // Outlines come from one place; a second source would be silently ignored.
55
+ const sources = REGION_OUTLINE_SOURCES.filter((source) => layer[source] !== undefined);
56
+ if (sources.length > 1) {
57
+ context.addIssue({ code: "custom", message: `give one of ${REGION_OUTLINE_SOURCES.join(", ")}; got ${sources.join(" and ")}.` });
58
+ }
59
+ // A built-in set names its regions by its own property, which would replace this one.
60
+ if (layer.boundaries !== undefined && layer.feature_property !== undefined) {
61
+ context.addIssue({ code: "custom", path: ["feature_property"], message: "a built-in boundary set names its regions itself; leave feature_property out." });
62
+ }
63
+ });
64
+ /** Lines between two places, following the curve of the earth. */
65
+ export const LINES_LAYER_SCHEMA = z.strictObject({
66
+ type: z.literal("lines"),
67
+ from_longitude: defineColumnField("The column of each line's starting longitude."),
68
+ from_latitude: defineColumnField("The column of each line's starting latitude."),
69
+ to_longitude: defineColumnField("The column of each line's ending longitude."),
70
+ to_latitude: defineColumnField("The column of each line's ending latitude."),
71
+ label: LABEL_FIELD.optional(),
72
+ ...COLOUR_FIELDS,
73
+ ...COLOUR_SCALE_FIELDS,
74
+ width: defineColumnField("A column of numbers that sets each line's width.").optional(),
75
+ data: DATA_FIELD,
76
+ });
77
+ /** Every map layer type's schema. */
78
+ export const MAP_LAYER_SCHEMAS = [POINTS_LAYER_SCHEMA, DENSITY_LAYER_SCHEMA, REGIONS_LAYER_SCHEMA, LINES_LAYER_SCHEMA];
79
+ /** Any one map layer, told apart by its type. */
80
+ export const MAP_LAYER_SCHEMA = z.discriminatedUnion("type", MAP_LAYER_SCHEMAS);
81
+ /** Each layer type's column fields that must hold numbers. */
82
+ export const LAYER_NUMERIC_COLUMNS = {
83
+ points: ["longitude", "latitude", "size"],
84
+ density: ["longitude", "latitude", "weight"],
85
+ regions: [],
86
+ lines: ["from_longitude", "from_latitude", "to_longitude", "to_latitude", "width"],
87
+ };
@@ -0,0 +1,25 @@
1
+ /**
2
+ * The one place a panel's colour scale is made, for plots and maps alike.
3
+ *
4
+ * A colour scale's range comes from the values it colours. With no values
5
+ * there is no range: `getNumberRange` would give Infinity to -Infinity,
6
+ * and a renderer would draw a colour bar for marks that do not exist
7
+ * (ECharts did; Plotly, with no trace to carry one, did not). Building
8
+ * every scale here, and returning null when there is nothing to colour,
9
+ * keeps `PanelModel.colourScale`'s range finite and both renderers agreed.
10
+ */
11
+ import type { PanelModel } from "./panel_model.ts";
12
+ /**
13
+ * Find the colour scale for the values a panel colours.
14
+ *
15
+ * @param values - The colour values of the marks drawn (already transformed by the colour_scale), missing ones left out.
16
+ * @param options - The legend's label, and its ticks in real values when the scale transforms them.
17
+ * @returns The colour scale, or null when there is no value to colour, so no colour bar is drawn.
18
+ */
19
+ export declare function findPanelColourScale(values: readonly number[], options: {
20
+ label: string;
21
+ ticks: {
22
+ value: number;
23
+ text: string;
24
+ }[] | undefined;
25
+ }): PanelModel["colourScale"];
@@ -0,0 +1,27 @@
1
+ /**
2
+ * The one place a panel's colour scale is made, for plots and maps alike.
3
+ *
4
+ * A colour scale's range comes from the values it colours. With no values
5
+ * there is no range: `getNumberRange` would give Infinity to -Infinity,
6
+ * and a renderer would draw a colour bar for marks that do not exist
7
+ * (ECharts did; Plotly, with no trace to carry one, did not). Building
8
+ * every scale here, and returning null when there is nothing to colour,
9
+ * keeps `PanelModel.colourScale`'s range finite and both renderers agreed.
10
+ */
11
+ import { SEQUENTIAL_COLOURS } from "../colour/palette.js";
12
+ import { getNumberRange } from "../table/get_number_range.js";
13
+ /**
14
+ * Find the colour scale for the values a panel colours.
15
+ *
16
+ * @param values - The colour values of the marks drawn (already transformed by the colour_scale), missing ones left out.
17
+ * @param options - The legend's label, and its ticks in real values when the scale transforms them.
18
+ * @returns The colour scale, or null when there is no value to colour, so no colour bar is drawn.
19
+ */
20
+ export function findPanelColourScale(values, options) {
21
+ if (values.length === 0)
22
+ return null;
23
+ return {
24
+ label: options.label, ...getNumberRange(values), colours: SEQUENTIAL_COLOURS,
25
+ ...(options.ticks === undefined ? {} : { ticks: options.ticks }),
26
+ };
27
+ }
@@ -0,0 +1,30 @@
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
+ import { type PlotTheme } from "../colour/palette.ts";
7
+ import { type DataTable } from "../table/data_table.ts";
8
+ import type { PanelModel } from "./panel_model.ts";
9
+ import { type Bounds } from "../map/geojson.ts";
10
+ import type { MapPlot } from "../plots/map_plot.ts";
11
+ /**
12
+ * Pick a starting zoom that shows the whole of some bounds.
13
+ *
14
+ * @param bounds - [west, south, east, north].
15
+ * @returns A zoom from 0 up.
16
+ */
17
+ export declare function fitZoom(bounds: Bounds): number;
18
+ /**
19
+ * Build the panel for a map plot.
20
+ *
21
+ * @param plot - A validated map plot.
22
+ * @param options - The figure's table and the theme.
23
+ * @returns The panel, with its map model.
24
+ */
25
+ export declare function buildMapPanel(plot: MapPlot, options: {
26
+ table: DataTable;
27
+ theme: PlotTheme;
28
+ }): PanelModel;
29
+ /** The neutral fill for regions with no data, per theme. */
30
+ export declare function pickNoDataColour(theme: PlotTheme): string;
@@ -0,0 +1,234 @@
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
+ import { DEFAULT_LINE_WIDTH_PIXELS, describeCount, LINE_WIDTH_RANGE_PIXELS, MARKER_SIZE, pickCategoricalColour, PLOT_THEMES, scaleToPixels, SIZE_RANGE_PIXELS } from "../colour/palette.js";
7
+ import { findColumn } from "../table/data_table.js";
8
+ import { listCategories } from "../table/list_categories.js";
9
+ import { applyColourScale, decideColourIsContinuous } from "../colour/colour_scale.js";
10
+ import { buildGreatCircleArc, findBounds, findFittingBounds, listPositions, normaliseLongitude } from "../map/geojson.js";
11
+ import { joinRegionRows, nameRegion, trimAndLowerCaseRegionName } from "../map/join_region_rows.js";
12
+ import { assignMapLayerHueSlots, readCategorySlot } from "../map/assign_map_layer_hue_slots.js";
13
+ import { findPanelColourScale } from "./find_panel_colour_scale.js";
14
+ import { readNumber } from "../table/read_number.js";
15
+ /** With nothing to fit, the map shows the whole world centred here. */
16
+ const WORLD_VIEW = { centre: [0, 20], zoom: 1 };
17
+ /** Degrees of longitude a zoom-0 view spans. */
18
+ const WORLD_SPAN_DEGREES = 360;
19
+ /** Latitude spans count this much more than longitude when fitting (maps are wider than tall). */
20
+ const LATITUDE_WEIGHT = 1.6;
21
+ /** Zoom levels to back off after fitting, so the edges are not at the rim. */
22
+ const FIT_MARGIN_ZOOM = 0.6;
23
+ /** The closest a fitted view zooms, so a single point does not land at street level. */
24
+ const MAXIMUM_FITTED_ZOOM = 12;
25
+ /**
26
+ * Pick a starting zoom that shows the whole of some bounds.
27
+ *
28
+ * @param bounds - [west, south, east, north].
29
+ * @returns A zoom from 0 up.
30
+ */
31
+ export function fitZoom(bounds) {
32
+ const [west, south, east, north] = bounds;
33
+ const span = Math.max(east - west, (north - south) * LATITUDE_WEIGHT, Number.EPSILON);
34
+ return Math.max(0, Math.min(MAXIMUM_FITTED_ZOOM, Math.log2(WORLD_SPAN_DEGREES / span) - FIT_MARGIN_ZOOM));
35
+ }
36
+ /** Bottom to top. */
37
+ const DRAW_ORDER = { regions: 0, density: 1, lines: 2, points: 3 };
38
+ function buildLayer(layer, options) {
39
+ const table = layer.data ?? options.table;
40
+ const column = (name) => (name === undefined ? null : findColumn(table, { column: name }));
41
+ const rowCount = (Object.values(table)[0] ?? []).length;
42
+ const rows = Array.from({ length: rowCount }, (_, row) => row);
43
+ if (layer.type === "density") {
44
+ const [longitudes, latitudes, weights] = [column(layer.longitude), column(layer.latitude), column(layer.weight)];
45
+ const points = rows.flatMap((row) => {
46
+ const [longitude, latitude] = [readNumber(longitudes?.[row]), readNumber(latitudes?.[row])];
47
+ return longitude === null || latitude === null ? [] : [{ longitude, latitude, weight: weights === null ? 1 : (readNumber(weights[row]) ?? 0) }];
48
+ });
49
+ if (points.length === 0) {
50
+ options.notes.push(`The density layer has no places to show: no row has both a "${layer.longitude}" and a "${layer.latitude}" number.`);
51
+ }
52
+ else if (points.every((point) => point.weight <= 0)) {
53
+ options.notes.push(`The density layer has no heat to show: every "${layer.weight ?? "weight"}" is zero.`);
54
+ }
55
+ return [{ kind: "density", name: "density", points }];
56
+ }
57
+ if (layer.type === "regions") {
58
+ const keys = column(layer.key);
59
+ const values = column(layer.value);
60
+ const isContinuous = values !== null && decideColourIsContinuous(values, { colourType: layer.colour_type });
61
+ const geojson = layer.geojson;
62
+ // Validation requires it, and built-in outlines set it, so it is always here by now.
63
+ const featureProperty = layer.feature_property;
64
+ if (featureProperty === undefined)
65
+ throw new Error("Expected a regions layer to name its feature property by now; it did not.");
66
+ // Only rows that name an outline are drawn, so only they set the range (a quantile ranks among them alone).
67
+ const { outlineNames, rowByName, joinedRows } = joinRegionRows(geojson, { keys, featureProperty });
68
+ const isMatched = (row) => joinedRows.has(row);
69
+ // Colour follows the scaled value; labels keep the real one.
70
+ const transform = isContinuous && values !== null
71
+ ? applyColourScale(values.map((value, row) => (isMatched(row) ? readNumber(value) : null)), { scale: layer.colour_scale, label: layer.value ?? "value", notes: options.notes })
72
+ : null;
73
+ const scaled = new Map((transform?.values ?? []).map((value, row) => [row, value]));
74
+ const seen = new Set();
75
+ const regions = [];
76
+ const features = geojson.features.map((feature, index) => {
77
+ const name = nameRegion(feature, { featureProperty, index });
78
+ const id = `${options.layerIndex}:${index}`;
79
+ const row = rowByName.get(trimAndLowerCaseRegionName(name));
80
+ if (row !== undefined)
81
+ seen.add(trimAndLowerCaseRegionName(name));
82
+ const raw = row === undefined || values === null ? null : values[row];
83
+ const value = isContinuous ? (scaled.get(row ?? -1) ?? null) : null;
84
+ const colour = !isContinuous && raw !== null && raw !== undefined
85
+ ? pickCategoricalColour(readCategorySlot(String(raw), options), { theme: options.theme })
86
+ : null;
87
+ regions.push({ id, value, colour, label: raw === null || raw === undefined ? name : `${name}: ${raw}` });
88
+ return { ...feature, id, properties: { ...feature.properties, plotilla_id: id, plotilla_name: name } };
89
+ });
90
+ const missing = regions.filter((region) => region.value === null && region.colour === null).length;
91
+ if (values !== null && missing > 0)
92
+ options.notes.push(`${missing} of ${describeCount(regions.length, { singular: "region", plural: "regions" })} had no matching row in the table, ` +
93
+ `so ${missing === 1 ? "it is" : "they are"} left grey.`);
94
+ const unused = keys.filter((key) => key !== null && !seen.has(trimAndLowerCaseRegionName(String(key)))).length;
95
+ if (unused > 0)
96
+ options.notes.push(`${describeCount(unused, { singular: "table row", plural: "table rows" })} named no region in the outlines (matched on "${layer.feature_property}").`);
97
+ // Disjoint from the note above: these rows do name an outline, but a later row for the same region wins.
98
+ const superseded = keys.filter((key, row) => {
99
+ if (key === null)
100
+ return false;
101
+ const name = trimAndLowerCaseRegionName(String(key));
102
+ return outlineNames.has(name) && rowByName.get(name) !== row;
103
+ }).length;
104
+ if (superseded > 0)
105
+ options.notes.push(`${describeCount(superseded, { singular: "table row repeats", plural: "table rows repeat" })} a region named by a later row, ` +
106
+ `so ${superseded === 1 ? "it is" : "they are"} not drawn (the later row wins; matched on "${layer.feature_property}").`);
107
+ if (isContinuous && values !== null && layer.value !== undefined) {
108
+ options.scales.push({ label: layer.value, values: regions.flatMap((region) => (region.value === null ? [] : [region.value])), ticks: transform?.ticks });
109
+ }
110
+ return [{ kind: "regions", name: layer.value ?? "regions", geojson: { type: "FeatureCollection", features }, regions }];
111
+ }
112
+ // Points and lines: split into one layer per colour category, like chart series.
113
+ const colours = column(layer.colour);
114
+ const isContinuous = colours !== null && decideColourIsContinuous(colours, { colourType: layer.colour_type });
115
+ const categories = colours === null || isContinuous ? [""] : listCategories(colours);
116
+ // A row is drawn when every coordinate is a number and, coloured by category, it has a category (a layer to be in).
117
+ // Drawing and every range below use this one rule, so a row that is not drawn never sets a range.
118
+ const coordinates = (layer.type === "points" ? [layer.longitude, layer.latitude] : [layer.from_longitude, layer.from_latitude, layer.to_longitude, layer.to_latitude]).map(column);
119
+ const isDrawn = (row) => coordinates.every((values) => readNumber(values?.[row]) !== null)
120
+ && (colours === null || isContinuous || (colours[row] !== null && colours[row] !== undefined));
121
+ const transform = isContinuous && colours !== null
122
+ ? applyColourScale(colours.map((value, row) => (isDrawn(row) ? readNumber(value) : null)), { scale: layer.colour_scale, label: layer.colour ?? "colour", notes: options.notes })
123
+ : null;
124
+ if (transform !== null && layer.colour !== undefined) {
125
+ options.scales.push({ label: layer.colour, values: transform.values.flatMap((value) => (value === null ? [] : [value])), ticks: transform.ticks });
126
+ }
127
+ // Sizes and widths scale once over the layer's drawn rows, across categories, so one value is one size on the whole map.
128
+ const sizeColumn = layer.type === "points" ? column(layer.size) : null;
129
+ const sizePixels = sizeColumn === null ? null : scaleToPixels(sizeColumn.map((value, row) => (isDrawn(row) ? readNumber(value) : null)), { range: SIZE_RANGE_PIXELS, fallback: MARKER_SIZE });
130
+ const widthColumn = layer.type === "lines" ? column(layer.width) : null;
131
+ 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 });
132
+ const labels = column(layer.label);
133
+ const drawnRows = rows.filter(isDrawn);
134
+ return categories.map((category) => {
135
+ const inCategory = drawnRows.filter((row) => colours === null || isContinuous || String(colours[row]) === category);
136
+ // A category takes its map-wide slot, shared with every layer of that label; a layer with no colour column takes the slot after every category.
137
+ const isCategory = colours !== null && !isContinuous;
138
+ const colour = isContinuous ? null : pickCategoricalColour(isCategory ? readCategorySlot(category, options) : readHueSlot(options), { theme: options.theme });
139
+ const name = category === "" ? layer.type : category;
140
+ const label = (row) => (labels === null || labels[row] === null || labels[row] === undefined ? null : String(labels[row]));
141
+ const colourValue = (row) => (transform === null ? null : (transform.values[row] ?? null));
142
+ if (layer.type === "points") {
143
+ const [longitudes, latitudes] = [column(layer.longitude), column(layer.latitude)];
144
+ return {
145
+ kind: "points", name, colour, isCategory,
146
+ points: inCategory.flatMap((row) => {
147
+ const [longitude, latitude] = [readNumber(longitudes?.[row]), readNumber(latitudes?.[row])];
148
+ return longitude === null || latitude === null ? [] : [{ longitude, latitude, label: label(row), sizePixels: sizePixels === null ? MARKER_SIZE : (sizePixels[row] ?? MARKER_SIZE), colourValue: colourValue(row) }];
149
+ }),
150
+ };
151
+ }
152
+ const [fromLongitudes, fromLatitudes, toLongitudes, toLatitudes] = [column(layer.from_longitude), column(layer.from_latitude), column(layer.to_longitude), column(layer.to_latitude)];
153
+ return {
154
+ kind: "lines", name, colour, isCategory,
155
+ lines: inCategory.flatMap((row) => {
156
+ const ends = [fromLongitudes?.[row], fromLatitudes?.[row], toLongitudes?.[row], toLatitudes?.[row]].map(readNumber);
157
+ if (ends.some((value) => value === null))
158
+ return [];
159
+ const [fromLongitude, fromLatitude, toLongitude, toLatitude] = ends;
160
+ return [{
161
+ path: buildGreatCircleArc([fromLongitude, fromLatitude], { to: [toLongitude, toLatitude] }),
162
+ widthPixels: widthPixels === null ? DEFAULT_LINE_WIDTH_PIXELS : (widthPixels[row] ?? DEFAULT_LINE_WIDTH_PIXELS), colourValue: colourValue(row), label: label(row),
163
+ }];
164
+ }),
165
+ };
166
+ });
167
+ }
168
+ /**
169
+ * Read the hue slot of an uncoloured points or lines layer.
170
+ *
171
+ * @param options - The layer's place in the map and the map's slots.
172
+ * @returns The slot.
173
+ * @throws Error when the layer was given no slot, which assignMapLayerHueSlots gives every uncoloured points or lines layer.
174
+ */
175
+ function readHueSlot(options) {
176
+ const slot = options.hueSlots.uncolouredSlots[options.layerIndex] ?? null;
177
+ if (slot === null)
178
+ throw new Error(`Expected map layer ${options.layerIndex}, uncoloured, to have a hue slot; it had none.`);
179
+ return slot;
180
+ }
181
+ /**
182
+ * Build the panel for a map plot.
183
+ *
184
+ * @param plot - A validated map plot.
185
+ * @param options - The figure's table and the theme.
186
+ * @returns The panel, with its map model.
187
+ */
188
+ export function buildMapPanel(plot, options) {
189
+ const notes = [];
190
+ const scales = [];
191
+ // Drawn bottom to top: areas, then heat, then routes, with places on top so nothing hides them.
192
+ const table = plot.data ?? options.table;
193
+ const hueSlots = assignMapLayerHueSlots(plot.layers, { table, areOutlinesLoaded: true });
194
+ const layers = plot.layers
195
+ .flatMap((layer, layerIndex) => buildLayer(layer, { table, theme: options.theme, layerIndex, hueSlots, notes, scales }))
196
+ .sort((first, second) => DRAW_ORDER[first.kind] - DRAW_ORDER[second.kind]);
197
+ // One colour scale per map: validation refuses a second layer colouring by a number, naming it.
198
+ const positions = layers.flatMap((layer) => {
199
+ if (layer.kind === "regions")
200
+ return listPositions(layer.geojson);
201
+ if (layer.kind === "lines")
202
+ return layer.lines.flatMap((line) => line.path);
203
+ return layer.points.map((point) => [point.longitude, point.latitude]);
204
+ });
205
+ const bounds = findBounds(positions);
206
+ // The view is fitted allowing for the 180° line, so Alaska's Aleutians do not pull a US map out to the whole world.
207
+ const fitting = findFittingBounds(positions);
208
+ const fitted = fitting === null
209
+ ? WORLD_VIEW
210
+ : { centre: [normaliseLongitude((fitting[0] + fitting[2]) / 2), (fitting[1] + fitting[3]) / 2], zoom: fitZoom(fitting) };
211
+ const scale = scales[0];
212
+ return {
213
+ title: plot.title ?? null,
214
+ xAxis: null,
215
+ yAxis: null,
216
+ series: [],
217
+ colourScale: scale === undefined ? null : findPanelColourScale(scale.values, { label: scale.label, ticks: scale.ticks }),
218
+ map: {
219
+ projection: plot.projection,
220
+ centre: plot.centre ?? fitted.centre,
221
+ zoom: plot.zoom ?? fitted.zoom,
222
+ isZoomGiven: plot.zoom !== undefined,
223
+ isCentreGiven: plot.centre !== undefined,
224
+ bounds,
225
+ fittingBounds: fitting,
226
+ layers,
227
+ notes,
228
+ },
229
+ };
230
+ }
231
+ /** The neutral fill for regions with no data, per theme. */
232
+ export function pickNoDataColour(theme) {
233
+ return PLOT_THEMES[theme].gridLine;
234
+ }