plotilla 1.0.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 +28 -23
  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,30 @@
1
+ /** The bar plot: a bar per category, grouped or stacked by colour. */
2
+ import { z } from "zod";
3
+ import { AXIS_LABEL_FIELDS, Y_SCALE_FIELDS } from "../fields/axis_fields.js";
4
+ import { COLOUR_FIELDS, COLOUR_SCALE_FIELDS } from "../fields/colour_fields.js";
5
+ import { X_FIELD, Y_FIELD } from "../fields/column_fields.js";
6
+ import { COMMON_FIELDS } from "../fields/common_fields.js";
7
+ /** How bars of different colours share a category. */
8
+ export const BAR_MODES = ["grouped", "stacked"];
9
+ /** The mode bars get when the agent names none. */
10
+ export const DEFAULT_BAR_MODE = "grouped";
11
+ /** Whether bars stand up or lie down. */
12
+ export const BAR_ORIENTATIONS = ["vertical", "horizontal"];
13
+ /** The orientation bars get when the agent names none. */
14
+ export const DEFAULT_BAR_ORIENTATION = "vertical";
15
+ /** A bar plot as an agent sends it. */
16
+ export const BAR_PLOT_SCHEMA = z.strictObject({
17
+ type: z.literal("bar"),
18
+ ...COMMON_FIELDS,
19
+ ...AXIS_LABEL_FIELDS,
20
+ // No y_year_format: a bar's length is an amount from zero, never a year.
21
+ ...Y_SCALE_FIELDS,
22
+ ...COLOUR_FIELDS,
23
+ ...COLOUR_SCALE_FIELDS,
24
+ x: X_FIELD,
25
+ y: Y_FIELD,
26
+ mode: z.enum(BAR_MODES).default(DEFAULT_BAR_MODE).describe("How bars of different colours share a category: side by side, or one on another."),
27
+ orientation: z.enum(BAR_ORIENTATIONS).default(DEFAULT_BAR_ORIENTATION).describe("Whether bars stand up or lie along the x axis."),
28
+ });
29
+ /** The column fields that must hold numbers. */
30
+ export const BAR_NUMERIC_COLUMNS = ["y"];
@@ -0,0 +1,30 @@
1
+ /** The box plot: a box summarising y: quartiles, whiskers at 1.5 interquartile ranges, outliers. One box per x category. */
2
+ import { z } from "zod";
3
+ /** A box plot as an agent sends it. */
4
+ export declare const BOX_PLOT_SCHEMA: z.ZodObject<{
5
+ colour: z.ZodOptional<z.ZodString>;
6
+ colour_type: z.ZodOptional<z.ZodEnum<{
7
+ categorical: "categorical";
8
+ continuous: "continuous";
9
+ }>>;
10
+ x_label: z.ZodOptional<z.ZodString>;
11
+ y_label: z.ZodOptional<z.ZodString>;
12
+ y_scale: z.ZodDefault<z.ZodEnum<{
13
+ linear: "linear";
14
+ log: "log";
15
+ }>>;
16
+ y_year_format: z.ZodOptional<z.ZodEnum<{
17
+ YY: "YY";
18
+ YYYY: "YYYY";
19
+ }>>;
20
+ title: z.ZodOptional<z.ZodString>;
21
+ 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]>>>>;
22
+ show_markers: z.ZodOptional<z.ZodBoolean>;
23
+ type: z.ZodLiteral<"box">;
24
+ y: z.ZodString;
25
+ x: z.ZodOptional<z.ZodString>;
26
+ }, z.core.$strict>;
27
+ /** A box plot, through the schema. */
28
+ export type BoxPlot = z.infer<typeof BOX_PLOT_SCHEMA>;
29
+ /** The column fields that must hold numbers. */
30
+ export declare const BOX_NUMERIC_COLUMNS: readonly (keyof BoxPlot)[];
@@ -0,0 +1,21 @@
1
+ /** The box plot: a box summarising y: quartiles, whiskers at 1.5 interquartile ranges, outliers. One box per x category. */
2
+ import { z } from "zod";
3
+ import { AXIS_LABEL_FIELDS, Y_YEAR_FORMAT_FIELDS, Y_SCALE_FIELDS } from "../fields/axis_fields.js";
4
+ import { COLOUR_FIELDS } from "../fields/colour_fields.js";
5
+ import { X_FIELD, Y_FIELD } from "../fields/column_fields.js";
6
+ import { COMMON_FIELDS } from "../fields/common_fields.js";
7
+ import { MARKER_FIELDS } from "../fields/marker_fields.js";
8
+ /** A box plot as an agent sends it. */
9
+ export const BOX_PLOT_SCHEMA = z.strictObject({
10
+ type: z.literal("box"),
11
+ ...COMMON_FIELDS,
12
+ ...AXIS_LABEL_FIELDS,
13
+ ...Y_YEAR_FORMAT_FIELDS,
14
+ ...Y_SCALE_FIELDS,
15
+ ...COLOUR_FIELDS,
16
+ ...MARKER_FIELDS,
17
+ y: Y_FIELD,
18
+ x: X_FIELD.optional(),
19
+ });
20
+ /** The column fields that must hold numbers. */
21
+ export const BOX_NUMERIC_COLUMNS = ["y"];
@@ -0,0 +1,36 @@
1
+ /** The density plot: a smooth curve of how x is spread (kernel density), one per colour category. */
2
+ import { z } from "zod";
3
+ /** Whether a density curve is filled when the agent does not say: no. */
4
+ export declare const DEFAULT_SHOW_AREA = false;
5
+ /** A density plot as an agent sends it. */
6
+ export declare const DENSITY_PLOT_SCHEMA: z.ZodObject<{
7
+ colour: z.ZodOptional<z.ZodString>;
8
+ colour_type: z.ZodOptional<z.ZodEnum<{
9
+ categorical: "categorical";
10
+ continuous: "continuous";
11
+ }>>;
12
+ x_label: z.ZodOptional<z.ZodString>;
13
+ y_label: z.ZodOptional<z.ZodString>;
14
+ x_scale: z.ZodDefault<z.ZodEnum<{
15
+ linear: "linear";
16
+ log: "log";
17
+ }>>;
18
+ y_scale: z.ZodDefault<z.ZodEnum<{
19
+ linear: "linear";
20
+ log: "log";
21
+ }>>;
22
+ x_year_format: z.ZodOptional<z.ZodEnum<{
23
+ YY: "YY";
24
+ YYYY: "YYYY";
25
+ }>>;
26
+ title: z.ZodOptional<z.ZodString>;
27
+ 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]>>>>;
28
+ type: z.ZodLiteral<"density">;
29
+ x: z.ZodString;
30
+ bandwidth: z.ZodOptional<z.ZodNumber>;
31
+ show_area: z.ZodDefault<z.ZodBoolean>;
32
+ }, z.core.$strict>;
33
+ /** A density plot, through the schema. */
34
+ export type DensityPlot = z.infer<typeof DENSITY_PLOT_SCHEMA>;
35
+ /** The column fields that must hold numbers. */
36
+ export declare const DENSITY_NUMERIC_COLUMNS: readonly (keyof DensityPlot)[];
@@ -0,0 +1,23 @@
1
+ /** The density plot: a smooth curve of how x is spread (kernel density), one per colour category. */
2
+ import { z } from "zod";
3
+ import { AXIS_LABEL_FIELDS, X_YEAR_FORMAT_FIELDS, X_SCALE_FIELDS, Y_SCALE_FIELDS } from "../fields/axis_fields.js";
4
+ import { COLOUR_FIELDS } from "../fields/colour_fields.js";
5
+ import { X_FIELD } from "../fields/column_fields.js";
6
+ import { COMMON_FIELDS } from "../fields/common_fields.js";
7
+ /** Whether a density curve is filled when the agent does not say: no. */
8
+ export const DEFAULT_SHOW_AREA = false;
9
+ /** A density plot as an agent sends it. */
10
+ export const DENSITY_PLOT_SCHEMA = z.strictObject({
11
+ type: z.literal("density"),
12
+ ...COMMON_FIELDS,
13
+ ...AXIS_LABEL_FIELDS,
14
+ ...X_YEAR_FORMAT_FIELDS,
15
+ ...X_SCALE_FIELDS,
16
+ ...Y_SCALE_FIELDS,
17
+ ...COLOUR_FIELDS,
18
+ x: X_FIELD,
19
+ bandwidth: z.number().positive().optional().describe("How smooth the curve is, in x's units. Default: Silverman's rule, from the data."),
20
+ show_area: z.boolean().default(DEFAULT_SHOW_AREA).describe("Fill the area under each curve."),
21
+ });
22
+ /** The column fields that must hold numbers. */
23
+ export const DENSITY_NUMERIC_COLUMNS = ["x"];
@@ -0,0 +1,22 @@
1
+ /** The heatmap plot: a grid of cells, one row of the table per cell, coloured by value. */
2
+ import { z } from "zod";
3
+ /** A heatmap as an agent sends it. */
4
+ export declare const HEATMAP_PLOT_SCHEMA: z.ZodObject<{
5
+ colour_scale: z.ZodOptional<z.ZodEnum<{
6
+ linear: "linear";
7
+ log: "log";
8
+ quantile: "quantile";
9
+ }>>;
10
+ x_label: z.ZodOptional<z.ZodString>;
11
+ y_label: z.ZodOptional<z.ZodString>;
12
+ title: z.ZodOptional<z.ZodString>;
13
+ 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]>>>>;
14
+ type: z.ZodLiteral<"heatmap">;
15
+ x: z.ZodString;
16
+ y: z.ZodString;
17
+ value: z.ZodString;
18
+ }, z.core.$strict>;
19
+ /** A heatmap, through the schema. */
20
+ export type HeatmapPlot = z.infer<typeof HEATMAP_PLOT_SCHEMA>;
21
+ /** The column fields that must hold numbers. */
22
+ export declare const HEATMAP_NUMERIC_COLUMNS: readonly (keyof HeatmapPlot)[];
@@ -0,0 +1,18 @@
1
+ /** The heatmap plot: a grid of cells, one row of the table per cell, coloured by value. */
2
+ import { z } from "zod";
3
+ import { AXIS_LABEL_FIELDS } from "../fields/axis_fields.js";
4
+ import { COLOUR_SCALE_FIELDS } from "../fields/colour_fields.js";
5
+ import { VALUE_FIELD, X_FIELD, Y_FIELD } from "../fields/column_fields.js";
6
+ import { COMMON_FIELDS } from "../fields/common_fields.js";
7
+ /** A heatmap as an agent sends it. */
8
+ export const HEATMAP_PLOT_SCHEMA = z.strictObject({
9
+ type: z.literal("heatmap"),
10
+ ...COMMON_FIELDS,
11
+ ...AXIS_LABEL_FIELDS,
12
+ ...COLOUR_SCALE_FIELDS,
13
+ x: X_FIELD,
14
+ y: Y_FIELD,
15
+ value: VALUE_FIELD,
16
+ });
17
+ /** The column fields that must hold numbers. */
18
+ export const HEATMAP_NUMERIC_COLUMNS = ["value"];
@@ -0,0 +1,32 @@
1
+ /** The histogram plot: counts of x in equal-width bins, one set of bars per colour category on one shared range. */
2
+ import { z } from "zod";
3
+ /** Whether a histogram is scaled to area 1 when the agent does not say: no. */
4
+ export declare const DEFAULT_IS_NORMALISED = false;
5
+ /** A histogram as an agent sends it. */
6
+ export declare const HISTOGRAM_PLOT_SCHEMA: z.ZodObject<{
7
+ colour: z.ZodOptional<z.ZodString>;
8
+ colour_type: z.ZodOptional<z.ZodEnum<{
9
+ categorical: "categorical";
10
+ continuous: "continuous";
11
+ }>>;
12
+ x_label: z.ZodOptional<z.ZodString>;
13
+ y_label: z.ZodOptional<z.ZodString>;
14
+ y_scale: z.ZodDefault<z.ZodEnum<{
15
+ linear: "linear";
16
+ log: "log";
17
+ }>>;
18
+ x_year_format: z.ZodOptional<z.ZodEnum<{
19
+ YY: "YY";
20
+ YYYY: "YYYY";
21
+ }>>;
22
+ title: z.ZodOptional<z.ZodString>;
23
+ 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]>>>>;
24
+ type: z.ZodLiteral<"histogram">;
25
+ x: z.ZodString;
26
+ bins: z.ZodOptional<z.ZodNumber>;
27
+ is_normalised: z.ZodDefault<z.ZodBoolean>;
28
+ }, z.core.$strict>;
29
+ /** A histogram, through the schema. */
30
+ export type HistogramPlot = z.infer<typeof HISTOGRAM_PLOT_SCHEMA>;
31
+ /** The column fields that must hold numbers. */
32
+ export declare const HISTOGRAM_NUMERIC_COLUMNS: readonly (keyof HistogramPlot)[];
@@ -0,0 +1,24 @@
1
+ /** The histogram plot: counts of x in equal-width bins, one set of bars per colour category on one shared range. */
2
+ import { z } from "zod";
3
+ import { AXIS_LABEL_FIELDS, X_YEAR_FORMAT_FIELDS, Y_SCALE_FIELDS } from "../fields/axis_fields.js";
4
+ import { COLOUR_FIELDS } from "../fields/colour_fields.js";
5
+ import { X_FIELD } from "../fields/column_fields.js";
6
+ import { COMMON_FIELDS } from "../fields/common_fields.js";
7
+ /** Whether a histogram is scaled to area 1 when the agent does not say: no. */
8
+ export const DEFAULT_IS_NORMALISED = false;
9
+ /** A histogram as an agent sends it. */
10
+ export const HISTOGRAM_PLOT_SCHEMA = z.strictObject({
11
+ type: z.literal("histogram"),
12
+ ...COMMON_FIELDS,
13
+ ...AXIS_LABEL_FIELDS,
14
+ ...X_YEAR_FORMAT_FIELDS,
15
+ // No x_scale: bins are equal widths on a linear axis, the same in both renderers.
16
+ // No y_year_format: its y is counts from zero, never a year.
17
+ ...Y_SCALE_FIELDS,
18
+ ...COLOUR_FIELDS,
19
+ x: X_FIELD,
20
+ bins: z.number().int().min(1).optional().describe("How many bins. Default: Sturges' rule, from the row count."),
21
+ is_normalised: z.boolean().default(DEFAULT_IS_NORMALISED).describe("Scale heights so the bars' area is 1, to compare groups of different sizes."),
22
+ });
23
+ /** The column fields that must hold numbers. */
24
+ export const HISTOGRAM_NUMERIC_COLUMNS = ["x"];
@@ -0,0 +1,44 @@
1
+ /** The line plot: a line through the points in x order, one line per colour category. */
2
+ import { z } from "zod";
3
+ /** A line plot as an agent sends it. */
4
+ export declare const LINE_PLOT_SCHEMA: z.ZodObject<{
5
+ colour: z.ZodOptional<z.ZodString>;
6
+ colour_type: z.ZodOptional<z.ZodEnum<{
7
+ categorical: "categorical";
8
+ continuous: "continuous";
9
+ }>>;
10
+ colour_scale: z.ZodOptional<z.ZodEnum<{
11
+ linear: "linear";
12
+ log: "log";
13
+ quantile: "quantile";
14
+ }>>;
15
+ x_label: z.ZodOptional<z.ZodString>;
16
+ y_label: z.ZodOptional<z.ZodString>;
17
+ x_scale: z.ZodDefault<z.ZodEnum<{
18
+ linear: "linear";
19
+ log: "log";
20
+ }>>;
21
+ y_scale: z.ZodDefault<z.ZodEnum<{
22
+ linear: "linear";
23
+ log: "log";
24
+ }>>;
25
+ x_year_format: z.ZodOptional<z.ZodEnum<{
26
+ YY: "YY";
27
+ YYYY: "YYYY";
28
+ }>>;
29
+ y_year_format: z.ZodOptional<z.ZodEnum<{
30
+ YY: "YY";
31
+ YYYY: "YYYY";
32
+ }>>;
33
+ title: z.ZodOptional<z.ZodString>;
34
+ 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]>>>>;
35
+ show_markers: z.ZodOptional<z.ZodBoolean>;
36
+ type: z.ZodLiteral<"line">;
37
+ x: z.ZodString;
38
+ y: z.ZodString;
39
+ line_type: z.ZodOptional<z.ZodString>;
40
+ }, z.core.$strict>;
41
+ /** A line plot, through the schema. */
42
+ export type LinePlot = z.infer<typeof LINE_PLOT_SCHEMA>;
43
+ /** The column fields that must hold numbers. */
44
+ export declare const LINE_NUMERIC_COLUMNS: readonly (keyof LinePlot)[];
@@ -0,0 +1,25 @@
1
+ /** The line plot: a line through the points in x order, one line per colour category. */
2
+ import { z } from "zod";
3
+ import { AXIS_LABEL_FIELDS, X_YEAR_FORMAT_FIELDS, X_SCALE_FIELDS, Y_YEAR_FORMAT_FIELDS, Y_SCALE_FIELDS } from "../fields/axis_fields.js";
4
+ import { COLOUR_FIELDS, COLOUR_SCALE_FIELDS } from "../fields/colour_fields.js";
5
+ import { X_FIELD, Y_FIELD, defineColumnField } from "../fields/column_fields.js";
6
+ import { COMMON_FIELDS } from "../fields/common_fields.js";
7
+ import { MARKER_FIELDS } from "../fields/marker_fields.js";
8
+ /** A line plot as an agent sends it. */
9
+ export const LINE_PLOT_SCHEMA = z.strictObject({
10
+ type: z.literal("line"),
11
+ ...COMMON_FIELDS,
12
+ ...AXIS_LABEL_FIELDS,
13
+ ...X_YEAR_FORMAT_FIELDS,
14
+ ...Y_YEAR_FORMAT_FIELDS,
15
+ ...X_SCALE_FIELDS,
16
+ ...Y_SCALE_FIELDS,
17
+ ...COLOUR_FIELDS,
18
+ ...COLOUR_SCALE_FIELDS,
19
+ ...MARKER_FIELDS,
20
+ x: X_FIELD,
21
+ y: Y_FIELD,
22
+ line_type: defineColumnField("A column whose categories each get their own dash.").optional(),
23
+ });
24
+ /** The column fields that must hold numbers. */
25
+ export const LINE_NUMERIC_COLUMNS = ["y"];
@@ -0,0 +1,92 @@
1
+ /** The map plot: layers of points, density, regions and lines. Without a centre and zoom, it fits everything shown. */
2
+ import { z } from "zod";
3
+ /** How a map is drawn: flat, or as a globe. */
4
+ export declare const MAP_PROJECTIONS: readonly ["flat", "globe"];
5
+ /** One of MAP_PROJECTIONS. */
6
+ export type MapProjection = (typeof MAP_PROJECTIONS)[number];
7
+ /** The projection a map gets when the agent names none. */
8
+ export declare const DEFAULT_MAP_PROJECTION: MapProjection;
9
+ /** The most zoomed-in a map may start: street level. */
10
+ export declare const MAXIMUM_MAP_ZOOM = 20;
11
+ /** A map plot as an agent sends it. */
12
+ export declare const MAP_PLOT_SCHEMA: z.ZodObject<{
13
+ title: z.ZodOptional<z.ZodString>;
14
+ 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]>>>>;
15
+ type: z.ZodLiteral<"map">;
16
+ projection: z.ZodDefault<z.ZodEnum<{
17
+ flat: "flat";
18
+ globe: "globe";
19
+ }>>;
20
+ centre: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>;
21
+ zoom: z.ZodOptional<z.ZodNumber>;
22
+ layers: z.ZodArray<z.ZodDiscriminatedUnion<readonly [z.ZodObject<{
23
+ colour: z.ZodOptional<z.ZodString>;
24
+ colour_type: z.ZodOptional<z.ZodEnum<{
25
+ categorical: "categorical";
26
+ continuous: "continuous";
27
+ }>>;
28
+ colour_scale: z.ZodOptional<z.ZodEnum<{
29
+ linear: "linear";
30
+ log: "log";
31
+ quantile: "quantile";
32
+ }>>;
33
+ type: z.ZodLiteral<"points">;
34
+ longitude: z.ZodString;
35
+ latitude: z.ZodString;
36
+ label: z.ZodOptional<z.ZodString>;
37
+ size: z.ZodOptional<z.ZodString>;
38
+ 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]>>>>;
39
+ }, z.core.$strict>, z.ZodObject<{
40
+ type: z.ZodLiteral<"density">;
41
+ longitude: z.ZodString;
42
+ latitude: z.ZodString;
43
+ weight: z.ZodOptional<z.ZodString>;
44
+ 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]>>>>;
45
+ }, z.core.$strict>, z.ZodObject<{
46
+ colour_scale: z.ZodOptional<z.ZodEnum<{
47
+ linear: "linear";
48
+ log: "log";
49
+ quantile: "quantile";
50
+ }>>;
51
+ type: z.ZodLiteral<"regions">;
52
+ boundaries: z.ZodOptional<z.ZodEnum<{
53
+ canada_provinces: "canada_provinces";
54
+ eu_countries: "eu_countries";
55
+ us_states: "us_states";
56
+ world_countries: "world_countries";
57
+ }>>;
58
+ geojson: z.ZodOptional<z.ZodUnknown>;
59
+ geojson_url: z.ZodOptional<z.ZodURL>;
60
+ feature_property: z.ZodOptional<z.ZodString>;
61
+ key: z.ZodString;
62
+ value: z.ZodOptional<z.ZodString>;
63
+ colour_type: z.ZodOptional<z.ZodEnum<{
64
+ categorical: "categorical";
65
+ continuous: "continuous";
66
+ }>>;
67
+ 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]>>>>;
68
+ }, z.core.$strict>, z.ZodObject<{
69
+ colour: z.ZodOptional<z.ZodString>;
70
+ colour_type: z.ZodOptional<z.ZodEnum<{
71
+ categorical: "categorical";
72
+ continuous: "continuous";
73
+ }>>;
74
+ colour_scale: z.ZodOptional<z.ZodEnum<{
75
+ linear: "linear";
76
+ log: "log";
77
+ quantile: "quantile";
78
+ }>>;
79
+ type: z.ZodLiteral<"lines">;
80
+ from_longitude: z.ZodString;
81
+ from_latitude: z.ZodString;
82
+ to_longitude: z.ZodString;
83
+ to_latitude: z.ZodString;
84
+ label: z.ZodOptional<z.ZodString>;
85
+ width: z.ZodOptional<z.ZodString>;
86
+ 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]>>>>;
87
+ }, z.core.$strict>], "type">>;
88
+ }, z.core.$strict>;
89
+ /** A map plot, through the schema. */
90
+ export type MapPlot = z.infer<typeof MAP_PLOT_SCHEMA>;
91
+ /** The column fields that must hold numbers: a map's columns are on its layers. */
92
+ export declare const MAP_NUMERIC_COLUMNS: readonly (keyof MapPlot)[];
@@ -0,0 +1,35 @@
1
+ /** The map plot: layers of points, density, regions and lines. Without a centre and zoom, it fits everything shown. */
2
+ import { z } from "zod";
3
+ import { COMMON_FIELDS } from "../fields/common_fields.js";
4
+ import { MAP_LAYER_SCHEMA } from "../map/map_layers.js";
5
+ /** How a map is drawn: flat, or as a globe. */
6
+ export const MAP_PROJECTIONS = ["flat", "globe"];
7
+ /** The projection a map gets when the agent names none. */
8
+ export const DEFAULT_MAP_PROJECTION = "flat";
9
+ /** The most zoomed-in a map may start: street level. */
10
+ export const MAXIMUM_MAP_ZOOM = 20;
11
+ /** The widest a longitude and a latitude can be, in degrees. */
12
+ const MAXIMUM_LONGITUDE = 180;
13
+ const MAXIMUM_LATITUDE = 90;
14
+ /** A map plot as an agent sends it. */
15
+ export const MAP_PLOT_SCHEMA = z.strictObject({
16
+ type: z.literal("map"),
17
+ ...COMMON_FIELDS,
18
+ projection: z
19
+ .enum(MAP_PROJECTIONS)
20
+ .default(DEFAULT_MAP_PROJECTION)
21
+ .describe("A flat, zoomable street map, or a globe you can spin."),
22
+ centre: z
23
+ .tuple([z.number().min(-MAXIMUM_LONGITUDE).max(MAXIMUM_LONGITUDE), z.number().min(-MAXIMUM_LATITUDE).max(MAXIMUM_LATITUDE)])
24
+ .optional()
25
+ .describe("Where the view starts, [longitude, latitude] in degrees. Default: fitted to everything shown."),
26
+ zoom: z
27
+ .number()
28
+ .min(0)
29
+ .max(MAXIMUM_MAP_ZOOM)
30
+ .optional()
31
+ .describe(`How close the view starts: 0 is the whole world, ${MAXIMUM_MAP_ZOOM} street level. Default: fitted to everything shown.`),
32
+ layers: z.array(MAP_LAYER_SCHEMA).min(1, "a map needs at least one layer.").describe("The layers, drawn regions first, then density, lines and points."),
33
+ });
34
+ /** The column fields that must hold numbers: a map's columns are on its layers. */
35
+ export const MAP_NUMERIC_COLUMNS = [];
@@ -0,0 +1,17 @@
1
+ /** The pie plot: slices of a whole, one per row; a donut when it has a hole. */
2
+ import { z } from "zod";
3
+ /** A pie's hole when the agent names none: none, a full pie. */
4
+ export declare const DEFAULT_HOLE = 0;
5
+ /** A pie plot as an agent sends it. */
6
+ export declare const PIE_PLOT_SCHEMA: z.ZodObject<{
7
+ title: z.ZodOptional<z.ZodString>;
8
+ 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]>>>>;
9
+ type: z.ZodLiteral<"pie">;
10
+ label: z.ZodString;
11
+ value: z.ZodString;
12
+ hole: z.ZodDefault<z.ZodNumber>;
13
+ }, z.core.$strict>;
14
+ /** A pie plot, through the schema. */
15
+ export type PiePlot = z.infer<typeof PIE_PLOT_SCHEMA>;
16
+ /** The column fields that must hold numbers. */
17
+ export declare const PIE_NUMERIC_COLUMNS: readonly (keyof PiePlot)[];
@@ -0,0 +1,16 @@
1
+ /** The pie plot: slices of a whole, one per row; a donut when it has a hole. */
2
+ import { z } from "zod";
3
+ import { LABEL_FIELD, VALUE_FIELD } from "../fields/column_fields.js";
4
+ import { COMMON_FIELDS } from "../fields/common_fields.js";
5
+ /** A pie's hole when the agent names none: none, a full pie. */
6
+ export const DEFAULT_HOLE = 0;
7
+ /** A pie plot as an agent sends it. */
8
+ export const PIE_PLOT_SCHEMA = z.strictObject({
9
+ type: z.literal("pie"),
10
+ ...COMMON_FIELDS,
11
+ label: LABEL_FIELD,
12
+ value: VALUE_FIELD,
13
+ hole: z.number().min(0).lt(1).default(DEFAULT_HOLE).describe("The hole's share of the radius: 0 for a pie, up to 1 for a donut."),
14
+ });
15
+ /** The column fields that must hold numbers. */
16
+ export const PIE_NUMERIC_COLUMNS = ["value"];
@@ -0,0 +1,47 @@
1
+ /** The scatter plot: a point per row. */
2
+ import { z } from "zod";
3
+ /** Whether a scatter gets a trend line when the agent does not say: no. */
4
+ export declare const DEFAULT_SHOW_TREND_LINE = false;
5
+ /** A scatter plot as an agent sends it. */
6
+ export declare const SCATTER_PLOT_SCHEMA: z.ZodObject<{
7
+ colour: z.ZodOptional<z.ZodString>;
8
+ colour_type: z.ZodOptional<z.ZodEnum<{
9
+ categorical: "categorical";
10
+ continuous: "continuous";
11
+ }>>;
12
+ colour_scale: z.ZodOptional<z.ZodEnum<{
13
+ linear: "linear";
14
+ log: "log";
15
+ quantile: "quantile";
16
+ }>>;
17
+ x_label: z.ZodOptional<z.ZodString>;
18
+ y_label: z.ZodOptional<z.ZodString>;
19
+ x_scale: z.ZodDefault<z.ZodEnum<{
20
+ linear: "linear";
21
+ log: "log";
22
+ }>>;
23
+ y_scale: z.ZodDefault<z.ZodEnum<{
24
+ linear: "linear";
25
+ log: "log";
26
+ }>>;
27
+ x_year_format: z.ZodOptional<z.ZodEnum<{
28
+ YY: "YY";
29
+ YYYY: "YYYY";
30
+ }>>;
31
+ y_year_format: z.ZodOptional<z.ZodEnum<{
32
+ YY: "YY";
33
+ YYYY: "YYYY";
34
+ }>>;
35
+ title: z.ZodOptional<z.ZodString>;
36
+ 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]>>>>;
37
+ type: z.ZodLiteral<"scatter">;
38
+ x: z.ZodString;
39
+ y: z.ZodString;
40
+ marker_shape: z.ZodOptional<z.ZodString>;
41
+ size: z.ZodOptional<z.ZodString>;
42
+ show_trend_line: z.ZodDefault<z.ZodBoolean>;
43
+ }, z.core.$strict>;
44
+ /** A scatter plot, through the schema. */
45
+ export type ScatterPlot = z.infer<typeof SCATTER_PLOT_SCHEMA>;
46
+ /** The column fields that must hold numbers. */
47
+ export declare const SCATTER_NUMERIC_COLUMNS: readonly (keyof ScatterPlot)[];
@@ -0,0 +1,27 @@
1
+ /** The scatter plot: a point per row. */
2
+ import { z } from "zod";
3
+ import { AXIS_LABEL_FIELDS, X_YEAR_FORMAT_FIELDS, X_SCALE_FIELDS, Y_YEAR_FORMAT_FIELDS, Y_SCALE_FIELDS } from "../fields/axis_fields.js";
4
+ import { COLOUR_FIELDS, COLOUR_SCALE_FIELDS } from "../fields/colour_fields.js";
5
+ import { SIZE_FIELD, X_FIELD, Y_FIELD, defineColumnField } from "../fields/column_fields.js";
6
+ import { COMMON_FIELDS } from "../fields/common_fields.js";
7
+ /** Whether a scatter gets a trend line when the agent does not say: no. */
8
+ export const DEFAULT_SHOW_TREND_LINE = false;
9
+ /** A scatter plot as an agent sends it. */
10
+ export const SCATTER_PLOT_SCHEMA = z.strictObject({
11
+ type: z.literal("scatter"),
12
+ ...COMMON_FIELDS,
13
+ ...AXIS_LABEL_FIELDS,
14
+ ...X_YEAR_FORMAT_FIELDS,
15
+ ...Y_YEAR_FORMAT_FIELDS,
16
+ ...X_SCALE_FIELDS,
17
+ ...Y_SCALE_FIELDS,
18
+ ...COLOUR_FIELDS,
19
+ ...COLOUR_SCALE_FIELDS,
20
+ x: X_FIELD,
21
+ y: Y_FIELD,
22
+ marker_shape: defineColumnField("A column whose categories each get their own marker shape.").optional(),
23
+ size: SIZE_FIELD.optional(),
24
+ show_trend_line: z.boolean().default(DEFAULT_SHOW_TREND_LINE).describe("Draw a least-squares line per combination of colour category and marker_shape category (one line when neither splits the points). Needs x to be a column of numbers (not text or dates), and each series to have drawn rows with at least two different x values."),
25
+ });
26
+ /** The column fields that must hold numbers. */
27
+ export const SCATTER_NUMERIC_COLUMNS = ["y", "size"];
@@ -0,0 +1,37 @@
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 type { DateLabelForm } from "../model/panel_model.ts";
10
+ /**
11
+ * List the ticks of a date axis across its range, a round calendar step apart.
12
+ *
13
+ * @param range - The earliest and latest date, as milliseconds since 1970 with their wall clock read as UTC.
14
+ * @param options - The axis's label form.
15
+ * @returns The ticks as date-times Plotly reads (2024-03-05 14:30:00), ascending.
16
+ */
17
+ export declare function listDateTicks(range: {
18
+ minimum: number;
19
+ maximum: number;
20
+ }, options: {
21
+ form: DateLabelForm;
22
+ }): string[];
23
+ /**
24
+ * List the ticks of a date axis across its range, a round calendar step
25
+ * apart, as milliseconds: the same ticks `listDateTicks` gives Plotly, for
26
+ * ECharts, so both renderers print the same labels.
27
+ *
28
+ * @param range - The earliest and latest date, as milliseconds since 1970 with their wall clock read as UTC.
29
+ * @param options - The axis's label form.
30
+ * @returns The ticks in milliseconds, ascending.
31
+ */
32
+ export declare function listDateTickMilliseconds(range: {
33
+ minimum: number;
34
+ maximum: number;
35
+ }, options: {
36
+ form: DateLabelForm;
37
+ }): number[];