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
package/README.md CHANGED
@@ -24,8 +24,11 @@ to do both:
24
24
 
25
25
  - **`resolvePlotFigure(figure, { limits, size, loadBoundarySet, fetchGeoJson })`**
26
26
  checks a figure, fills in every default, loads the outlines its map layers
27
- name, and returns it with notes for the agent (region names that matched nothing, what a renderer cannot
28
- draw). `loadBoundarySet` reads the built-in outline sets, which ship in
27
+ name, and returns it with notes for the agent (table rows whose region
28
+ name matched no outline, regions no row matched, rows that repeat a region a
29
+ later row names, map layers with nothing to show, values a log scale cannot
30
+ show).
31
+ `loadBoundarySet` reads the built-in outline sets, which ship in
29
32
  `data/boundaries/` (see `createBoundaryLoader`). `fetchGeoJson` fetches
30
33
  outlines from an address the agent gave, with the host's own rules on
31
34
  addresses, size and identity. `limits` (the most plots, rows and histogram
@@ -39,10 +42,27 @@ to do both:
39
42
  changes size is built again. A figure too small for its content is
40
43
  refused, naming the size it needs.
41
44
 
42
- An ECharts option can carry three things for the page, under keys exported
45
+ An ECharts option can carry four things for the page, under keys exported
43
46
  from `renderers/echarts_options`: maps to register first (`MAPS_OPTION_KEY`),
44
- a notice for the person (`NOTICE_OPTION_KEY`), and axes whose numbers are
45
- years (`PLAIN_NUMBERS_LABEL_KEY`). The page acts on each, then removes it.
47
+ a notice for the person (`NOTICE_OPTION_KEY`), and on an axis label declared
48
+ as years, a formatter to swap in, as a function cannot travel in the option:
49
+ each number as it is (`PLAIN_NUMBERS_LABEL_KEY`, 1990), or its last two
50
+ digits (`TWO_DIGIT_YEARS_LABEL_KEY`, 90). The page acts on each, then removes it.
51
+
52
+ In those maps, an entry whose value is `"world"` asks for the host's world
53
+ outline; every other entry is GeoJSON to register as it is. Register the
54
+ world through `buildWorldOutlineAcross180`, from
55
+ `plotilla/map/build_world_outline_across_180`: it returns the outline plus a
56
+ copy one turn (360°) east, so a view that crosses the 180° line draws land on
57
+ both sides, not sea.
58
+
59
+ ```ts
60
+ import { buildWorldOutlineAcross180 } from "plotilla/map/build_world_outline_across_180";
61
+
62
+ const worldOutline = buildWorldOutlineAcross180(world); // world: the host's GeoJSON countries
63
+ for (const [name, source] of Object.entries(option[MAPS_OPTION_KEY] ?? {}))
64
+ echarts.registerMap(name, source === "world" ? worldOutline : source);
65
+ ```
46
66
 
47
67
  Each module is imported by its own path (`plotilla/figure/resolve_plot_figure`,
48
68
  `plotilla/renderers/echarts_options`): there is no index that re-exports
@@ -55,20 +75,25 @@ groups it uses, so a field means the same on every plot and in either
55
75
  renderer. A field that does not apply is refused, naming it. The JSON Schema
56
76
  a host gives its agents comes from the same definitions
57
77
  (`PLOT_FIGURE_SCHEMA` in `figure/plot_figure`). The rule is
58
- `.claude/rules/plot_interface.md`; `tests/figure/plot_figure.test.ts`
78
+ [`.claude/rules/plot_interface.md`](https://github.com/idin/plotilla/blob/main/.claude/rules/plot_interface.md);
79
+ [`tests/figure/plot_figure.test.ts`](https://github.com/idin/plotilla/blob/main/tests/figure/plot_figure.test.ts)
59
80
  enforces it.
60
81
 
61
82
  ## The catalogue
62
83
 
63
- `playbook/visualisation_catalogue.md` lists every visualisation to support,
64
- each pictured in Plotly and in ECharts. The pictures are drawn by
65
- `scripts/playbook/plotly` (Python, `uv run --project scripts/playbook/plotly`) and `scripts/playbook/echarts`
84
+ [`playbook/visualisation_catalogue.md`](https://github.com/idin/plotilla/blob/main/playbook/visualisation_catalogue.md)
85
+ lists every visualisation to support, each pictured in Plotly and in ECharts.
86
+ The pictures are drawn by [`scripts/playbook/plotly`](https://github.com/idin/plotilla/tree/main/scripts/playbook/plotly)
87
+ (Python, `uv run --project scripts/playbook/plotly`) and
88
+ [`scripts/playbook/echarts`](https://github.com/idin/plotilla/tree/main/scripts/playbook/echarts)
66
89
  (`npx tsx`), which share one palette, size and font.
67
90
 
68
91
  ## The gallery
69
92
 
70
93
  `src/examples/example_figures.ts` has every plot type in a simple form and a
71
- complex one. To see them all, drawn with either library:
94
+ complex one. To see them all, drawn with either library, run
95
+ [`scripts/build_gallery.ts`](https://github.com/idin/plotilla/blob/main/scripts/build_gallery.ts)
96
+ from a clone of the repository:
72
97
 
73
98
  ```sh
74
99
  npx tsx scripts/build_gallery.ts --output dist/gallery.html
@@ -80,4 +105,5 @@ Open the file, or add `#plotly` to its address to start with Plotly.
80
105
 
81
106
  `data/boundaries/` holds world countries, US states, Canadian provinces and
82
107
  EU countries, built from Natural Earth (public domain) by
83
- `npx tsx scripts/build_boundaries.ts`.
108
+ [`scripts/build_boundaries.ts`](https://github.com/idin/plotilla/blob/main/scripts/build_boundaries.ts),
109
+ run with `npx tsx scripts/build_boundaries.ts` in a clone of the repository.