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.
Files changed (52) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +82 -2
  3. package/data/boundaries/canada_provinces.geojson +1 -0
  4. package/data/boundaries/eu_countries.geojson +1 -0
  5. package/data/boundaries/us_states.geojson +1 -0
  6. package/data/boundaries/world_countries.geojson +1 -0
  7. package/package.json +62 -4
  8. package/src/colour/colour_scale.ts +80 -0
  9. package/src/colour/palette.ts +220 -0
  10. package/src/examples/example_figures.ts +320 -0
  11. package/src/fields/axis_fields.ts +32 -0
  12. package/src/fields/colour_fields.ts +40 -0
  13. package/src/fields/column_fields.ts +64 -0
  14. package/src/fields/common_fields.ts +13 -0
  15. package/src/fields/decide_plot_axes.ts +77 -0
  16. package/src/fields/marker_fields.ts +16 -0
  17. package/src/figure/plot_figure.ts +67 -0
  18. package/src/figure/resolve_plot_figure.ts +47 -0
  19. package/src/figure/validate_plot_figure.ts +412 -0
  20. package/src/map/boundary_sets.ts +116 -0
  21. package/src/map/check_map_layers.ts +32 -0
  22. package/src/map/fetch_region_outlines.ts +48 -0
  23. package/src/map/geojson.ts +174 -0
  24. package/src/map/map_layers.ts +108 -0
  25. package/src/model/check_axis_shows_years.ts +58 -0
  26. package/src/model/map_model.ts +238 -0
  27. package/src/model/panel_layout.ts +171 -0
  28. package/src/model/panel_model.ts +85 -0
  29. package/src/model/plot_model.ts +347 -0
  30. package/src/model/statistics.ts +134 -0
  31. package/src/plots/bar_plot.ts +36 -0
  32. package/src/plots/box_plot.ts +26 -0
  33. package/src/plots/density_plot.ts +29 -0
  34. package/src/plots/heatmap_plot.ts +24 -0
  35. package/src/plots/histogram_plot.ts +29 -0
  36. package/src/plots/line_plot.ts +29 -0
  37. package/src/plots/map_plot.ts +46 -0
  38. package/src/plots/pie_plot.ts +23 -0
  39. package/src/plots/scatter_plot.ts +32 -0
  40. package/src/renderers/echarts_map.ts +194 -0
  41. package/src/renderers/echarts_options.ts +317 -0
  42. package/src/renderers/plotly_map.ts +170 -0
  43. package/src/renderers/plotly_options.ts +318 -0
  44. package/src/table/check_column.ts +34 -0
  45. package/src/table/check_values_have_spread.ts +47 -0
  46. package/src/table/compute_quantile.ts +23 -0
  47. package/src/table/data_table.ts +83 -0
  48. package/src/table/density_bandwidth.ts +94 -0
  49. package/src/table/find_line_fit.ts +44 -0
  50. package/src/table/get_number_range.ts +21 -0
  51. package/src/table/group_rows.ts +71 -0
  52. package/src/table/list_categories.ts +17 -0
@@ -0,0 +1,21 @@
1
+ /**
2
+ * Find the smallest and largest of a column of numbers.
3
+ *
4
+ * This loops instead of calling `Math.min(...values)`: spreading a column as
5
+ * call arguments throws `RangeError: Maximum call stack size exceeded` past
6
+ * about 200,000 values, and a host may allow tables bigger than that. It
7
+ * keeps `Math.min` and `Math.max` semantics otherwise: an empty column gives
8
+ * `Infinity` and `-Infinity`, and a `NaN` makes both `NaN`.
9
+ *
10
+ * @param values - The numbers to scan.
11
+ * @returns The smallest and largest value.
12
+ */
13
+ export function getNumberRange(values: readonly number[]): { minimum: number; maximum: number } {
14
+ let minimum = Infinity;
15
+ let maximum = -Infinity;
16
+ for (const value of values) {
17
+ minimum = Math.min(minimum, value);
18
+ maximum = Math.max(maximum, value);
19
+ }
20
+ return { minimum, maximum };
21
+ }
@@ -0,0 +1,71 @@
1
+ /**
2
+ * Which drawn rows make which series. One rule, read by the model to build
3
+ * each series and by validation to judge each series' trend line, so a
4
+ * figure is never accepted on groups the model would not draw.
5
+ */
6
+
7
+ import { findOptionalColumn, type DataTable } from "./data_table";
8
+ import { listCategories } from "./list_categories";
9
+
10
+ /** A row's group: the categories it has for each grouping field. */
11
+ export type Grouping = { colourCategories: string[]; styleCategories: string[] };
12
+
13
+ /** One series' rows, with the indices of its colour and style categories and its name. */
14
+ export type RowGroup = { colourIndex: number; styleIndex: number; name: string; rows: number[] };
15
+
16
+ /**
17
+ * Split the drawn rows into series, one per colour and style category.
18
+ * Category indices count every category in the column, drawn or not, so a
19
+ * category with nothing drawn takes no series yet the others keep the
20
+ * colours and styles they would have had.
21
+ *
22
+ * @param table - The data table.
23
+ * @param options - The row count, the colour and style columns, and which rows become marks.
24
+ * @returns The categories of each grouping column, the groups, each with at least one drawn row, and every
25
+ * drawn row in table order: the only rows an axis may read, so a row never drawn sets no range or category.
26
+ */
27
+ export function groupRows(
28
+ table: DataTable,
29
+ options: { rowCount: number; colour: string | undefined; style: string | undefined; isDrawn: (row: number) => boolean },
30
+ ): { grouping: Grouping; groups: RowGroup[]; drawnRows: number[] } {
31
+ const colourValues = findOptionalColumn(table, { column: options.colour });
32
+ const styleValues = findOptionalColumn(table, { column: options.style });
33
+ const grouping: Grouping = {
34
+ colourCategories: colourValues === null ? [] : listCategories(colourValues),
35
+ styleCategories: styleValues === null ? [] : listCategories(styleValues),
36
+ };
37
+ // A Map per category list, so each drawn row finds its index in constant time, not by scanning the list.
38
+ const colourIndexes = buildFirstIndexMap(grouping.colourCategories);
39
+ const styleIndexes = buildFirstIndexMap(grouping.styleCategories);
40
+ const groups = new Map<string, RowGroup>();
41
+ const drawnRows: number[] = [];
42
+ for (let row = 0; row < options.rowCount; row += 1) {
43
+ if (!options.isDrawn(row)) continue;
44
+ const colourText = colourValues === null ? null : colourValues[row] === null ? null : String(colourValues[row]);
45
+ const styleText = styleValues === null ? null : styleValues[row] === null ? null : String(styleValues[row]);
46
+ const colourIndex = colourText === null ? 0 : colourIndexes.get(colourText) ?? -1;
47
+ const styleIndex = styleText === null ? 0 : styleIndexes.get(styleText) ?? -1;
48
+ const parts = [colourText, styleText !== colourText ? styleText : null].filter((part) => part !== null);
49
+ const name = parts.join(" · ");
50
+ const key = `${colourIndex}/${styleIndex}`;
51
+ const group = groups.get(key) ?? { colourIndex, styleIndex, name, rows: [] };
52
+ group.rows.push(row);
53
+ drawnRows.push(row);
54
+ groups.set(key, group);
55
+ }
56
+ return { grouping, groups: [...groups.values()], drawnRows };
57
+ }
58
+
59
+ /**
60
+ * Map each category to the index of its first occurrence, as indexOf finds it.
61
+ *
62
+ * @param categories - The category texts in order.
63
+ * @returns The first index of each text.
64
+ */
65
+ function buildFirstIndexMap(categories: string[]): Map<string, number> {
66
+ const indexes = new Map<string, number>();
67
+ categories.forEach((category, index) => {
68
+ if (!indexes.has(category)) indexes.set(category, index);
69
+ });
70
+ return indexes;
71
+ }
@@ -0,0 +1,17 @@
1
+ /**
2
+ * The categories a column holds. It sits in `table`, below `model`, so the
3
+ * plot and map models read one definition rather than keeping copies that
4
+ * could drift.
5
+ */
6
+
7
+ /**
8
+ * List a column's distinct values as text, in the order they first appear.
9
+ * Numbers count as categories by their text, so 2024 and "2024" are one
10
+ * category; missing values are no category.
11
+ *
12
+ * @param values - The column, or the rows of it to read.
13
+ * @returns Each distinct value's text, first appearance first.
14
+ */
15
+ export function listCategories(values: readonly (number | string | null)[]): string[] {
16
+ return [...new Set(values.filter((value) => value !== null).map(String))];
17
+ }