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.
- package/README.md +37 -11
- package/data/boundaries/world_countries.geojson +1 -1
- package/dist/colour/colour_scale.d.ts +55 -0
- package/dist/colour/colour_scale.js +80 -0
- package/dist/colour/palette.d.ts +176 -0
- package/dist/colour/palette.js +220 -0
- package/dist/fields/axis_fields.d.ts +56 -0
- package/dist/fields/axis_fields.js +46 -0
- package/dist/fields/colour_fields.d.ts +32 -0
- package/dist/fields/colour_fields.js +31 -0
- package/dist/fields/column_fields.d.ts +52 -0
- package/{src/fields/column_fields.ts → dist/fields/column_fields.js} +15 -29
- package/dist/fields/common_fields.d.ts +9 -0
- package/{src/fields/common_fields.ts → dist/fields/common_fields.js} +3 -6
- package/dist/fields/decide_plot_axes.d.ts +56 -0
- package/dist/fields/decide_plot_axes.js +71 -0
- package/dist/fields/marker_fields.d.ts +8 -0
- package/dist/fields/marker_fields.js +13 -0
- package/dist/fields/read_date_time.d.ts +85 -0
- package/dist/fields/read_date_time.js +199 -0
- package/dist/figure/check_axis_year_formats.d.ts +36 -0
- package/dist/figure/check_axis_year_formats.js +116 -0
- package/dist/figure/check_plot_category_limits.d.ts +128 -0
- package/dist/figure/check_plot_category_limits.js +284 -0
- package/dist/figure/plot_figure.d.ts +861 -0
- package/dist/figure/plot_figure.js +58 -0
- package/dist/figure/resolve_plot_figure.d.ts +28 -0
- package/dist/figure/resolve_plot_figure.js +41 -0
- package/dist/figure/validate_plot_figure.d.ts +50 -0
- package/dist/figure/validate_plot_figure.js +441 -0
- package/dist/map/assign_map_layer_hue_slots.d.ts +89 -0
- package/dist/map/assign_map_layer_hue_slots.js +146 -0
- package/dist/map/boundary_sets.d.ts +65 -0
- package/dist/map/boundary_sets.js +103 -0
- package/dist/map/build_world_outline_across_180.d.ts +21 -0
- package/dist/map/build_world_outline_across_180.js +23 -0
- package/dist/map/check_map_layers.d.ts +16 -0
- package/dist/map/check_map_layers.js +31 -0
- package/dist/map/fetch_region_outlines.d.ts +25 -0
- package/dist/map/fetch_region_outlines.js +39 -0
- package/dist/map/geojson.d.ts +150 -0
- package/dist/map/geojson.js +248 -0
- package/dist/map/join_region_rows.d.ts +40 -0
- package/dist/map/join_region_rows.js +45 -0
- package/dist/map/map_layers.d.ts +229 -0
- package/dist/map/map_layers.js +87 -0
- package/dist/model/find_panel_colour_scale.d.ts +25 -0
- package/dist/model/find_panel_colour_scale.js +27 -0
- package/dist/model/map_model.d.ts +30 -0
- package/dist/model/map_model.js +234 -0
- package/dist/model/panel_layout.d.ts +42 -0
- package/dist/model/panel_layout.js +154 -0
- package/dist/model/panel_model.d.ts +223 -0
- package/dist/model/panel_model.js +7 -0
- package/dist/model/plot_model.d.ts +28 -0
- package/dist/model/plot_model.js +431 -0
- package/dist/model/statistics.d.ts +83 -0
- package/dist/model/statistics.js +107 -0
- package/dist/plots/bar_plot.d.ts +46 -0
- package/dist/plots/bar_plot.js +30 -0
- package/dist/plots/box_plot.d.ts +30 -0
- package/dist/plots/box_plot.js +21 -0
- package/dist/plots/density_plot.d.ts +36 -0
- package/dist/plots/density_plot.js +23 -0
- package/dist/plots/heatmap_plot.d.ts +22 -0
- package/dist/plots/heatmap_plot.js +18 -0
- package/dist/plots/histogram_plot.d.ts +32 -0
- package/dist/plots/histogram_plot.js +24 -0
- package/dist/plots/line_plot.d.ts +44 -0
- package/dist/plots/line_plot.js +25 -0
- package/dist/plots/map_plot.d.ts +92 -0
- package/dist/plots/map_plot.js +35 -0
- package/dist/plots/pie_plot.d.ts +17 -0
- package/dist/plots/pie_plot.js +16 -0
- package/dist/plots/scatter_plot.d.ts +47 -0
- package/dist/plots/scatter_plot.js +27 -0
- package/dist/renderers/date_ticks.d.ts +37 -0
- package/dist/renderers/date_ticks.js +148 -0
- package/dist/renderers/echarts_map.d.ts +47 -0
- package/dist/renderers/echarts_map.js +492 -0
- package/dist/renderers/echarts_options.d.ts +30 -0
- package/dist/renderers/echarts_options.js +449 -0
- package/dist/renderers/echarts_pie_radius.d.ts +52 -0
- package/dist/renderers/echarts_pie_radius.js +158 -0
- package/dist/renderers/escape_html.d.ts +10 -0
- package/dist/renderers/escape_html.js +15 -0
- package/dist/renderers/line_colour_segments.d.ts +39 -0
- package/dist/renderers/line_colour_segments.js +41 -0
- package/dist/renderers/plotly_map.d.ts +48 -0
- package/dist/renderers/plotly_map.js +159 -0
- package/dist/renderers/plotly_options.d.ts +19 -0
- package/dist/renderers/plotly_options.js +345 -0
- package/dist/renderers/year_ticks.d.ts +27 -0
- package/dist/renderers/year_ticks.js +42 -0
- package/dist/table/check_column.d.ts +36 -0
- package/dist/table/check_column.js +46 -0
- package/dist/table/check_values_have_spread.d.ts +30 -0
- package/{src/table/check_values_have_spread.ts → dist/table/check_values_have_spread.js} +16 -17
- package/dist/table/compute_quantile.d.ts +16 -0
- package/dist/table/compute_quantile.js +23 -0
- package/dist/table/data_table.d.ts +59 -0
- package/dist/table/data_table.js +87 -0
- package/dist/table/density_bandwidth.d.ts +64 -0
- package/dist/table/density_bandwidth.js +88 -0
- package/dist/table/find_line_fit.d.ts +30 -0
- package/dist/table/find_line_fit.js +36 -0
- package/dist/table/get_number_range.d.ts +16 -0
- package/{src/table/get_number_range.ts → dist/table/get_number_range.js} +8 -8
- package/dist/table/group_rows.d.ts +40 -0
- package/dist/table/group_rows.js +67 -0
- package/dist/table/list_categories.d.ts +14 -0
- package/{src/table/list_categories.ts → dist/table/list_categories.js} +2 -3
- package/dist/table/read_number.d.ts +12 -0
- package/dist/table/read_number.js +14 -0
- package/package.json +30 -25
- package/src/colour/colour_scale.ts +0 -80
- package/src/colour/palette.ts +0 -220
- package/src/examples/example_figures.ts +0 -320
- package/src/fields/axis_fields.ts +0 -32
- package/src/fields/colour_fields.ts +0 -40
- package/src/fields/decide_plot_axes.ts +0 -77
- package/src/fields/marker_fields.ts +0 -16
- package/src/figure/plot_figure.ts +0 -67
- package/src/figure/resolve_plot_figure.ts +0 -47
- package/src/figure/validate_plot_figure.ts +0 -412
- package/src/map/boundary_sets.ts +0 -116
- package/src/map/check_map_layers.ts +0 -32
- package/src/map/fetch_region_outlines.ts +0 -48
- package/src/map/geojson.ts +0 -174
- package/src/map/map_layers.ts +0 -108
- package/src/model/check_axis_shows_years.ts +0 -58
- package/src/model/map_model.ts +0 -238
- package/src/model/panel_layout.ts +0 -171
- package/src/model/panel_model.ts +0 -85
- package/src/model/plot_model.ts +0 -347
- package/src/model/statistics.ts +0 -134
- package/src/plots/bar_plot.ts +0 -36
- package/src/plots/box_plot.ts +0 -26
- package/src/plots/density_plot.ts +0 -29
- package/src/plots/heatmap_plot.ts +0 -24
- package/src/plots/histogram_plot.ts +0 -29
- package/src/plots/line_plot.ts +0 -29
- package/src/plots/map_plot.ts +0 -46
- package/src/plots/pie_plot.ts +0 -23
- package/src/plots/scatter_plot.ts +0 -32
- package/src/renderers/echarts_map.ts +0 -194
- package/src/renderers/echarts_options.ts +0 -317
- package/src/renderers/plotly_map.ts +0 -170
- package/src/renderers/plotly_options.ts +0 -318
- package/src/table/check_column.ts +0 -34
- package/src/table/compute_quantile.ts +0 -23
- package/src/table/data_table.ts +0 -83
- package/src/table/density_bandwidth.ts +0 -94
- package/src/table/find_line_fit.ts +0 -44
- package/src/table/group_rows.ts +0 -71
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The fields of plots coloured by a column. A plot that can colour by a
|
|
3
|
+
* number also takes COLOUR_SCALE_FIELDS; one without them colours by
|
|
4
|
+
* category only, and validation refuses a numeric colour there.
|
|
5
|
+
*/
|
|
6
|
+
import { z } from "zod";
|
|
7
|
+
import { defineColumnField } from "./column_fields.js";
|
|
8
|
+
/** Whether a colouring column's values are categories or a scale. */
|
|
9
|
+
export const COLOUR_TYPES = ["categorical", "continuous"];
|
|
10
|
+
/** How numbers may map to colour, on charts and maps alike. */
|
|
11
|
+
export const COLOUR_SCALES = ["linear", "log", "quantile"];
|
|
12
|
+
/** The colour scale a plot gets when the agent names none. */
|
|
13
|
+
export const DEFAULT_COLOUR_SCALE = "linear";
|
|
14
|
+
/** The fields of a plot or layer coloured by a column. */
|
|
15
|
+
export const COLOUR_FIELDS = {
|
|
16
|
+
colour: defineColumnField("The column that colours the marks: text gives a colour per category, numbers a colour scale.").optional(),
|
|
17
|
+
colour_type: z
|
|
18
|
+
.enum(COLOUR_TYPES)
|
|
19
|
+
.optional()
|
|
20
|
+
.describe('Overrides what the colouring column\'s values imply (colour, or a map region\'s value), e.g. "categorical" for numbered years.'),
|
|
21
|
+
};
|
|
22
|
+
/** The scales, written for an error: "linear", "log" or "quantile". */
|
|
23
|
+
const COLOUR_SCALE_CHOICES = `${COLOUR_SCALES.slice(0, -1).map((scale) => `"${scale}"`).join(", ")} or "${COLOUR_SCALES.at(-1)}"`;
|
|
24
|
+
/** The field of a plot or layer that can colour by a number. */
|
|
25
|
+
export const COLOUR_SCALE_FIELDS = {
|
|
26
|
+
colour_scale: z
|
|
27
|
+
.enum(COLOUR_SCALES, { error: (issue) => `${COLOUR_SCALE_CHOICES}; got ${JSON.stringify(issue.input)}.` })
|
|
28
|
+
// No schema default: a scale sent where colour is not a scale is refused, which needs "not sent" apart from "linear".
|
|
29
|
+
.optional()
|
|
30
|
+
.describe("How numbers map to colour: evenly, by order of magnitude, or by rank so each step holds as many marks. Default: linear. Only with a colour of numbers."),
|
|
31
|
+
};
|
|
@@ -0,0 +1,52 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Fields that name a column of the table. Every one is made by
|
|
3
|
+
* defineColumnField, which records it, so validation finds a plot's column
|
|
4
|
+
* fields from its schema instead of a list kept by hand beside it.
|
|
5
|
+
*/
|
|
6
|
+
import { z } from "zod";
|
|
7
|
+
/** Every column field's schema, so validation can tell which fields name columns. */
|
|
8
|
+
export declare const COLUMN_FIELD_SCHEMAS: Set<z.ZodType>;
|
|
9
|
+
/**
|
|
10
|
+
* Define a field that names a column, and record it as one.
|
|
11
|
+
*
|
|
12
|
+
* @param description - What the column is for, shown to agents in the tool schema.
|
|
13
|
+
* @returns The field's schema.
|
|
14
|
+
*/
|
|
15
|
+
export declare function defineColumnField(description: string): z.ZodString;
|
|
16
|
+
/** The x column, shared by every plot that has one. */
|
|
17
|
+
export declare const X_FIELD: z.ZodString;
|
|
18
|
+
/** The y column, shared by every plot that has one. */
|
|
19
|
+
export declare const Y_FIELD: z.ZodString;
|
|
20
|
+
/** The value column, shared by heatmap, pie and the regions map layer. */
|
|
21
|
+
export declare const VALUE_FIELD: z.ZodString;
|
|
22
|
+
/** The column naming each mark, shared by pie and the map's points and lines. */
|
|
23
|
+
export declare const LABEL_FIELD: z.ZodString;
|
|
24
|
+
/** The column sizing each point, shared by scatter and the map's points. */
|
|
25
|
+
export declare const SIZE_FIELD: z.ZodString;
|
|
26
|
+
/** The columns a chart's row must have to become a mark: present ones, and ones holding a number. */
|
|
27
|
+
export type MarkColumns = {
|
|
28
|
+
present: string[];
|
|
29
|
+
numeric: string[];
|
|
30
|
+
};
|
|
31
|
+
/**
|
|
32
|
+
* List the columns a chart's row needs to become a mark, so validation and
|
|
33
|
+
* the model agree on which rows are drawn: x (and, on a heatmap, y) present,
|
|
34
|
+
* y (or a heatmap's value) a number, and a category in every column the plot
|
|
35
|
+
* groups by (line_type, marker_shape, and colour when it is categorical).
|
|
36
|
+
* A histogram or density draws x itself, so its x must be a number.
|
|
37
|
+
*
|
|
38
|
+
* @param plot - The plot's column fields and type.
|
|
39
|
+
* @param options - Whether its colour is by category, so a row needs one.
|
|
40
|
+
* @returns The columns, by what each must hold.
|
|
41
|
+
*/
|
|
42
|
+
export declare function listMarkColumns(plot: {
|
|
43
|
+
type: string;
|
|
44
|
+
x?: string;
|
|
45
|
+
y?: string;
|
|
46
|
+
value?: string;
|
|
47
|
+
line_type?: string;
|
|
48
|
+
marker_shape?: string;
|
|
49
|
+
colour?: string;
|
|
50
|
+
}, options: {
|
|
51
|
+
isColourCategorical: boolean;
|
|
52
|
+
}): MarkColumns;
|
|
@@ -3,40 +3,30 @@
|
|
|
3
3
|
* defineColumnField, which records it, so validation finds a plot's column
|
|
4
4
|
* fields from its schema instead of a list kept by hand beside it.
|
|
5
5
|
*/
|
|
6
|
-
|
|
7
6
|
import { z } from "zod";
|
|
8
|
-
|
|
9
7
|
/** Every column field's schema, so validation can tell which fields name columns. */
|
|
10
|
-
export const COLUMN_FIELD_SCHEMAS
|
|
11
|
-
|
|
8
|
+
export const COLUMN_FIELD_SCHEMAS = new Set();
|
|
12
9
|
/**
|
|
13
10
|
* Define a field that names a column, and record it as one.
|
|
14
11
|
*
|
|
15
12
|
* @param description - What the column is for, shown to agents in the tool schema.
|
|
16
13
|
* @returns The field's schema.
|
|
17
14
|
*/
|
|
18
|
-
export function defineColumnField(description
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
15
|
+
export function defineColumnField(description) {
|
|
16
|
+
const field = z.string().min(1).describe(description);
|
|
17
|
+
COLUMN_FIELD_SCHEMAS.add(field);
|
|
18
|
+
return field;
|
|
22
19
|
}
|
|
23
|
-
|
|
24
20
|
/** The x column, shared by every plot that has one. */
|
|
25
21
|
export const X_FIELD = defineColumnField("The column along the x axis.");
|
|
26
22
|
/** The y column, shared by every plot that has one. */
|
|
27
23
|
export const Y_FIELD = defineColumnField("The column along the y axis.");
|
|
28
24
|
/** The value column, shared by heatmap, pie and the regions map layer. */
|
|
29
|
-
export const VALUE_FIELD = defineColumnField(
|
|
30
|
-
"The column each mark shows: a pie slice's size or a heatmap cell's colour (numbers), or a map region's colour (numbers for a scale, text for categories).",
|
|
31
|
-
);
|
|
25
|
+
export const VALUE_FIELD = defineColumnField("The column each mark shows: a pie slice's size or a heatmap cell's colour (numbers), or a map region's colour (numbers for a scale, text for categories).");
|
|
32
26
|
/** The column naming each mark, shared by pie and the map's points and lines. */
|
|
33
27
|
export const LABEL_FIELD = defineColumnField("The column that names each mark: a pie slice, a map point, a map line.");
|
|
34
28
|
/** The column sizing each point, shared by scatter and the map's points. */
|
|
35
29
|
export const SIZE_FIELD = defineColumnField("A column of numbers that sizes each point.");
|
|
36
|
-
|
|
37
|
-
/** The columns a chart's row must have to become a mark: present ones, and ones holding a number. */
|
|
38
|
-
export type MarkColumns = { present: string[]; numeric: string[] };
|
|
39
|
-
|
|
40
30
|
/**
|
|
41
31
|
* List the columns a chart's row needs to become a mark, so validation and
|
|
42
32
|
* the model agree on which rows are drawn: x (and, on a heatmap, y) present,
|
|
@@ -48,17 +38,13 @@ export type MarkColumns = { present: string[]; numeric: string[] };
|
|
|
48
38
|
* @param options - Whether its colour is by category, so a row needs one.
|
|
49
39
|
* @returns The columns, by what each must hold.
|
|
50
40
|
*/
|
|
51
|
-
export function listMarkColumns(
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
present: present.filter((column): column is string => column !== undefined),
|
|
61
|
-
numeric: numeric.filter((column): column is string => column !== undefined),
|
|
62
|
-
};
|
|
41
|
+
export function listMarkColumns(plot, options) {
|
|
42
|
+
const grouping = [plot.line_type, plot.marker_shape, options.isColourCategorical ? plot.colour : undefined];
|
|
43
|
+
const isDistribution = plot.type === "histogram" || plot.type === "density";
|
|
44
|
+
const present = plot.type === "heatmap" ? [plot.x, plot.y] : isDistribution ? grouping : [plot.x, ...grouping];
|
|
45
|
+
const numeric = plot.type === "heatmap" ? [plot.value] : isDistribution ? [plot.x] : [plot.y];
|
|
46
|
+
return {
|
|
47
|
+
present: present.filter((column) => column !== undefined),
|
|
48
|
+
numeric: numeric.filter((column) => column !== undefined),
|
|
49
|
+
};
|
|
63
50
|
}
|
|
64
|
-
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
/** The fields every plot has. */
|
|
2
|
+
import { z } from "zod";
|
|
3
|
+
/** A plot's or map layer's own table: one definition, so both mean the same. */
|
|
4
|
+
export declare const DATA_FIELD: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodUnion<readonly [z.ZodNumber, z.ZodPipe<z.ZodString, z.ZodTransform<string | null, string>>, z.ZodNull]>>>>;
|
|
5
|
+
/** The fields every plot has: its own title and, optionally, its own table. */
|
|
6
|
+
export declare const COMMON_FIELDS: {
|
|
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
|
+
};
|
|
@@ -1,13 +1,10 @@
|
|
|
1
1
|
/** The fields every plot has. */
|
|
2
|
-
|
|
3
2
|
import { z } from "zod";
|
|
4
|
-
import { DATA_TABLE_SCHEMA } from "../table/data_table";
|
|
5
|
-
|
|
3
|
+
import { DATA_TABLE_SCHEMA } from "../table/data_table.js";
|
|
6
4
|
/** A plot's or map layer's own table: one definition, so both mean the same. */
|
|
7
5
|
export const DATA_FIELD = DATA_TABLE_SCHEMA.optional().describe("Its own table, used instead of the figure's.");
|
|
8
|
-
|
|
9
6
|
/** The fields every plot has: its own title and, optionally, its own table. */
|
|
10
7
|
export const COMMON_FIELDS = {
|
|
11
|
-
|
|
12
|
-
|
|
8
|
+
title: z.string().min(1).optional().describe("The plot's own title."),
|
|
9
|
+
data: DATA_FIELD,
|
|
13
10
|
};
|
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Which axes a plot has, and of what kind and scale. One rule, read by the
|
|
3
|
+
* model to build each axis and by validation to judge shared axes, so a
|
|
4
|
+
* figure is never refused or accepted on axes the model would not draw.
|
|
5
|
+
* It sits in `fields`, below both `figure` and `model`, as `listMarkColumns` does.
|
|
6
|
+
*/
|
|
7
|
+
import { type DataTable } from "../table/data_table.ts";
|
|
8
|
+
import { type AxisScale } from "./axis_fields.ts";
|
|
9
|
+
/** How an axis places values: spaced numbers, named categories, or dates. */
|
|
10
|
+
export type AxisKind = "value" | "category" | "time";
|
|
11
|
+
/** The plot's own fields an axis can draw: its x or its y. */
|
|
12
|
+
export type PlotField = "x" | "y";
|
|
13
|
+
/**
|
|
14
|
+
* An axis's kind and scale, which decide whether two axes can be linked, and
|
|
15
|
+
* which of the plot's fields it draws: a horizontal bar draws its y (its
|
|
16
|
+
* column, y_scale and y_year_format) on the screen's x axis.
|
|
17
|
+
*/
|
|
18
|
+
export type PlotAxis = {
|
|
19
|
+
kind: AxisKind;
|
|
20
|
+
scale: AxisScale;
|
|
21
|
+
plotField: PlotField;
|
|
22
|
+
};
|
|
23
|
+
/** A plot's axes; null where it has none (a pie, a map). */
|
|
24
|
+
export type PlotAxes = {
|
|
25
|
+
x: PlotAxis | null;
|
|
26
|
+
y: PlotAxis | null;
|
|
27
|
+
};
|
|
28
|
+
/**
|
|
29
|
+
* Decide an axis's kind from the values of its column: numbers are a value
|
|
30
|
+
* axis, values all shaped like an ISO date-time (whitespace around each
|
|
31
|
+
* ignored, as the reader ignores it) a time axis, anything else
|
|
32
|
+
* categories. The time axis's model then reads each value strictly
|
|
33
|
+
* (`readDateTime`), refusing one that is not a real date-time, naming it.
|
|
34
|
+
*
|
|
35
|
+
* @param values - The column's values.
|
|
36
|
+
* @returns The axis kind.
|
|
37
|
+
*/
|
|
38
|
+
export declare function decideAxisKind(values: readonly (number | string | null)[]): AxisKind;
|
|
39
|
+
/**
|
|
40
|
+
* Decide a plot's axes. Bars, boxes and heatmaps put categories on their
|
|
41
|
+
* category axis (a horizontal bar's is y); histograms and densities count
|
|
42
|
+
* numbers in x; lines and scatters take x's kind from its column.
|
|
43
|
+
*
|
|
44
|
+
* @param plot - The plot's type and its axis fields.
|
|
45
|
+
* @param options - The table the plot draws from.
|
|
46
|
+
* @returns Its x and y axes, null where it has none.
|
|
47
|
+
*/
|
|
48
|
+
export declare function decidePlotAxes(plot: {
|
|
49
|
+
type: string;
|
|
50
|
+
x?: string;
|
|
51
|
+
x_scale?: AxisScale;
|
|
52
|
+
y_scale?: AxisScale;
|
|
53
|
+
orientation?: string;
|
|
54
|
+
}, options: {
|
|
55
|
+
table: DataTable;
|
|
56
|
+
}): PlotAxes;
|
|
@@ -0,0 +1,71 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Which axes a plot has, and of what kind and scale. One rule, read by the
|
|
3
|
+
* model to build each axis and by validation to judge shared axes, so a
|
|
4
|
+
* figure is never refused or accepted on axes the model would not draw.
|
|
5
|
+
* It sits in `fields`, below both `figure` and `model`, as `listMarkColumns` does.
|
|
6
|
+
*/
|
|
7
|
+
import { findColumn } from "../table/data_table.js";
|
|
8
|
+
import { DEFAULT_AXIS_SCALE } from "./axis_fields.js";
|
|
9
|
+
import { checkIsDateTimeShaped } from "./read_date_time.js";
|
|
10
|
+
/**
|
|
11
|
+
* Build a category axis: it spaces nothing, so its scale is always the default.
|
|
12
|
+
*
|
|
13
|
+
* @param plotField - Which of the plot's fields it draws.
|
|
14
|
+
* @returns The axis.
|
|
15
|
+
*/
|
|
16
|
+
function buildCategoryAxis(plotField) {
|
|
17
|
+
return { kind: "category", scale: DEFAULT_AXIS_SCALE, plotField };
|
|
18
|
+
}
|
|
19
|
+
/**
|
|
20
|
+
* Decide an axis's kind from the values of its column: numbers are a value
|
|
21
|
+
* axis, values all shaped like an ISO date-time (whitespace around each
|
|
22
|
+
* ignored, as the reader ignores it) a time axis, anything else
|
|
23
|
+
* categories. The time axis's model then reads each value strictly
|
|
24
|
+
* (`readDateTime`), refusing one that is not a real date-time, naming it.
|
|
25
|
+
*
|
|
26
|
+
* @param values - The column's values.
|
|
27
|
+
* @returns The axis kind.
|
|
28
|
+
*/
|
|
29
|
+
export function decideAxisKind(values) {
|
|
30
|
+
const present = values.filter((value) => value !== null);
|
|
31
|
+
if (present.every((value) => typeof value === "number"))
|
|
32
|
+
return "value";
|
|
33
|
+
if (present.every((value) => typeof value === "string" && checkIsDateTimeShaped(value)))
|
|
34
|
+
return "time";
|
|
35
|
+
return "category";
|
|
36
|
+
}
|
|
37
|
+
/**
|
|
38
|
+
* Decide a plot's axes. Bars, boxes and heatmaps put categories on their
|
|
39
|
+
* category axis (a horizontal bar's is y); histograms and densities count
|
|
40
|
+
* numbers in x; lines and scatters take x's kind from its column.
|
|
41
|
+
*
|
|
42
|
+
* @param plot - The plot's type and its axis fields.
|
|
43
|
+
* @param options - The table the plot draws from.
|
|
44
|
+
* @returns Its x and y axes, null where it has none.
|
|
45
|
+
*/
|
|
46
|
+
export function decidePlotAxes(plot, options) {
|
|
47
|
+
const xScale = plot.x_scale ?? DEFAULT_AXIS_SCALE;
|
|
48
|
+
const yScale = plot.y_scale ?? DEFAULT_AXIS_SCALE;
|
|
49
|
+
const valueY = { kind: "value", scale: yScale, plotField: "y" };
|
|
50
|
+
switch (plot.type) {
|
|
51
|
+
case "line":
|
|
52
|
+
case "scatter": {
|
|
53
|
+
const xValues = plot.x === undefined ? [] : (findColumn(options.table, { column: plot.x }) ?? []);
|
|
54
|
+
return { x: { kind: decideAxisKind(xValues), scale: xScale, plotField: "x" }, y: valueY };
|
|
55
|
+
}
|
|
56
|
+
case "bar":
|
|
57
|
+
return plot.orientation === "horizontal" ? { x: valueY, y: buildCategoryAxis("x") } : { x: buildCategoryAxis("x"), y: valueY };
|
|
58
|
+
case "box":
|
|
59
|
+
return { x: buildCategoryAxis("x"), y: valueY };
|
|
60
|
+
case "histogram":
|
|
61
|
+
case "density":
|
|
62
|
+
return { x: { kind: "value", scale: xScale, plotField: "x" }, y: valueY };
|
|
63
|
+
case "heatmap":
|
|
64
|
+
return { x: buildCategoryAxis("x"), y: buildCategoryAxis("y") };
|
|
65
|
+
case "pie":
|
|
66
|
+
case "map":
|
|
67
|
+
return { x: null, y: null };
|
|
68
|
+
default:
|
|
69
|
+
throw new Error(`Expected a known plot type to decide its axes; got "${plot.type}".`);
|
|
70
|
+
}
|
|
71
|
+
}
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
/** The field of plots that can draw a marker for each row of data. */
|
|
2
|
+
import { z } from "zod";
|
|
3
|
+
/** Markers when the agent sends none, except on a line coloured by a number. */
|
|
4
|
+
export declare const DEFAULT_SHOW_MARKERS = false;
|
|
5
|
+
/** The field of plots that can mark each row: line and box. */
|
|
6
|
+
export declare const MARKER_FIELDS: {
|
|
7
|
+
show_markers: z.ZodOptional<z.ZodBoolean>;
|
|
8
|
+
};
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
/** The field of plots that can draw a marker for each row of data. */
|
|
2
|
+
import { z } from "zod";
|
|
3
|
+
/** Markers when the agent sends none, except on a line coloured by a number. */
|
|
4
|
+
export const DEFAULT_SHOW_MARKERS = false;
|
|
5
|
+
/** The field of plots that can mark each row: line and box. */
|
|
6
|
+
export const MARKER_FIELDS = {
|
|
7
|
+
// No schema default: a line coloured by a number needs its markers to carry
|
|
8
|
+
// the colour, so the model tells "not sent" apart from false.
|
|
9
|
+
show_markers: z
|
|
10
|
+
.boolean()
|
|
11
|
+
.optional()
|
|
12
|
+
.describe("Draw a marker for each row of data. Default: off, except on a line coloured by a number, whose markers carry the colour."),
|
|
13
|
+
};
|
|
@@ -0,0 +1,85 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Read an ISO date or date-time (2024-03-05, 2024-03-05T14:30:05+05:00) as
|
|
3
|
+
* the wall-clock parts a reader sees, strictly: a value that is not a real
|
|
4
|
+
* date and time is refused rather than read as some other one. A written
|
|
5
|
+
* UTC offset is kept apart from the wall clock: an axis prints the time as
|
|
6
|
+
* the column wrote it, so the offset only decides whether two values can
|
|
7
|
+
* share one axis.
|
|
8
|
+
*/
|
|
9
|
+
/** A second in milliseconds. */
|
|
10
|
+
export declare const MILLISECONDS_PER_SECOND = 1000;
|
|
11
|
+
/** A minute in milliseconds. */
|
|
12
|
+
export declare const MILLISECONDS_PER_MINUTE: number;
|
|
13
|
+
/** An hour in milliseconds. */
|
|
14
|
+
export declare const MILLISECONDS_PER_HOUR: number;
|
|
15
|
+
/** A day in milliseconds, its wall clock read as UTC, so every day has 24 hours. */
|
|
16
|
+
export declare const MILLISECONDS_PER_DAY: number;
|
|
17
|
+
/** The parts a date-time is made of, its time zero when none is written, and its UTC offset (null when none is written). */
|
|
18
|
+
export type DateTimeParts = {
|
|
19
|
+
year: number;
|
|
20
|
+
month: number;
|
|
21
|
+
day: number;
|
|
22
|
+
hour: number;
|
|
23
|
+
minute: number;
|
|
24
|
+
second: number;
|
|
25
|
+
offset: string | null;
|
|
26
|
+
};
|
|
27
|
+
/**
|
|
28
|
+
* Check whether a value is shaped like an ISO date-time, which makes its
|
|
29
|
+
* column a time axis: it starts with a date and is not a label (the date,
|
|
30
|
+
* a space, then text that is not time-shaped). The column's values are then
|
|
31
|
+
* read by `readDateTime`, which refuses any that is not a real date-time,
|
|
32
|
+
* so an axis draws exactly what the reader accepts.
|
|
33
|
+
*
|
|
34
|
+
* @param value - The value.
|
|
35
|
+
* @returns Whether it has the shape of an ISO date-time.
|
|
36
|
+
*/
|
|
37
|
+
export declare function checkIsDateTimeShaped(value: string): boolean;
|
|
38
|
+
/**
|
|
39
|
+
* Read an ISO date or date-time into its parts.
|
|
40
|
+
*
|
|
41
|
+
* @param text - The date, as ISO 8601 writes it; whitespace around it is ignored.
|
|
42
|
+
* @returns Its parts; seconds may hold a fraction; "Z" reads as the offset +00:00.
|
|
43
|
+
* @throws Error naming the text when it is not an ISO date-time, names a year before 1000, carries the unknown offset -00:00, or names a month, day, hour, minute or second that does not exist.
|
|
44
|
+
*/
|
|
45
|
+
export declare function readDateTime(text: string): DateTimeParts;
|
|
46
|
+
/**
|
|
47
|
+
* Read a column's dates, refusing a column whose values carry different UTC
|
|
48
|
+
* offsets, or an offset beside none: an axis prints each wall clock as
|
|
49
|
+
* written, and one axis cannot show two clocks. A value with no offset is
|
|
50
|
+
* its own clock, since guessing its zone would place it wrongly.
|
|
51
|
+
*
|
|
52
|
+
* @param values - The column's values that are present.
|
|
53
|
+
* @param options - The column's name, for the refusal.
|
|
54
|
+
* @returns Each value's parts, in order.
|
|
55
|
+
* @throws Error naming the column and two of its offsets ("no offset" for none) when they differ, or naming a value that is not a date-time.
|
|
56
|
+
*/
|
|
57
|
+
export declare function readDateColumn(values: readonly string[], options: {
|
|
58
|
+
column: string;
|
|
59
|
+
}): DateTimeParts[];
|
|
60
|
+
/** One of two offsets that differ: where it is in the list, and its name in a refusal. */
|
|
61
|
+
export type OffsetConflictSide = {
|
|
62
|
+
index: number;
|
|
63
|
+
name: string;
|
|
64
|
+
};
|
|
65
|
+
/**
|
|
66
|
+
* Find the first two offsets in a list that differ, a missing offset
|
|
67
|
+
* (null) counting as its own, so every check of "one clock" compares the
|
|
68
|
+
* same way.
|
|
69
|
+
*
|
|
70
|
+
* @param offsets - The offsets, null for a value written with none.
|
|
71
|
+
* @returns The first offset and the first that differs from it, or null when all agree.
|
|
72
|
+
*/
|
|
73
|
+
export declare function findOffsetConflict(offsets: readonly (string | null)[]): {
|
|
74
|
+
first: OffsetConflictSide;
|
|
75
|
+
second: OffsetConflictSide;
|
|
76
|
+
} | null;
|
|
77
|
+
/**
|
|
78
|
+
* Convert a date-time's parts to milliseconds since 1970, reading its wall
|
|
79
|
+
* clock as UTC, so a date's place on an axis never shifts with the zone the
|
|
80
|
+
* renderer runs in or the offset the column wrote.
|
|
81
|
+
*
|
|
82
|
+
* @param parts - The date-time's parts.
|
|
83
|
+
* @returns The milliseconds.
|
|
84
|
+
*/
|
|
85
|
+
export declare function convertDateTimeToMilliseconds(parts: DateTimeParts): number;
|
|
@@ -0,0 +1,199 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Read an ISO date or date-time (2024-03-05, 2024-03-05T14:30:05+05:00) as
|
|
3
|
+
* the wall-clock parts a reader sees, strictly: a value that is not a real
|
|
4
|
+
* date and time is refused rather than read as some other one. A written
|
|
5
|
+
* UTC offset is kept apart from the wall clock: an axis prints the time as
|
|
6
|
+
* the column wrote it, so the offset only decides whether two values can
|
|
7
|
+
* share one axis.
|
|
8
|
+
*/
|
|
9
|
+
/** A second in milliseconds. */
|
|
10
|
+
export const MILLISECONDS_PER_SECOND = 1000;
|
|
11
|
+
/** A minute in milliseconds. */
|
|
12
|
+
export const MILLISECONDS_PER_MINUTE = 60 * MILLISECONDS_PER_SECOND;
|
|
13
|
+
/** An hour in milliseconds. */
|
|
14
|
+
export const MILLISECONDS_PER_HOUR = 60 * MILLISECONDS_PER_MINUTE;
|
|
15
|
+
/** A day in milliseconds, its wall clock read as UTC, so every day has 24 hours. */
|
|
16
|
+
export const MILLISECONDS_PER_DAY = 24 * MILLISECONDS_PER_HOUR;
|
|
17
|
+
/**
|
|
18
|
+
* The start of an ISO date (2024-03-05). A value that starts this way is
|
|
19
|
+
* meant as a date, so its column makes a time axis and each value is read
|
|
20
|
+
* strictly, refused when it is not a real date-time: "2024-03-05T5:00", and
|
|
21
|
+
* text glued straight onto the date ("2024-03-05garbage"), are malformed.
|
|
22
|
+
*/
|
|
23
|
+
const DATE_START_PATTERN = /^\d{4}-\d{2}-\d{2}/;
|
|
24
|
+
/**
|
|
25
|
+
* A date followed by a space and then text that is not time-shaped (any
|
|
26
|
+
* character but digits, colons, dots, Z or a sign): a label such as
|
|
27
|
+
* "2024-03-05 sale", so its column stays categories.
|
|
28
|
+
*/
|
|
29
|
+
const DATE_LABEL_PATTERN = /^\d{4}-\d{2}-\d{2} .*[^\d:.Z+-]/;
|
|
30
|
+
/** An ISO date, optionally a time to the minute, second or fraction, and a UTC offset after a time; nothing after. */
|
|
31
|
+
const DATE_TIME_PATTERN = /^(\d{4})-(\d{2})-(\d{2})(?:[T ](\d{2}):(\d{2})(?::(\d{2}(?:\.\d+)?))?(Z|[+-]\d{2}:\d{2})?)?$/;
|
|
32
|
+
/**
|
|
33
|
+
* The first year read. plotilla's own `formatDateTime` (renderers/date_ticks)
|
|
34
|
+
* writes a year below 1000 unpadded (year 500 as "500-03-05", even when the
|
|
35
|
+
* value is "0500-03-05"), and Plotly's date reader needs a four-digit year,
|
|
36
|
+
* so the ticks fail and no labels are drawn. Below 100 it is worse, since
|
|
37
|
+
* `Date.UTC` reads 0 to 99 as 1900 to 1999. Such a year is far more likely
|
|
38
|
+
* a dropped century than a real date in plotilla's data, so it is refused.
|
|
39
|
+
*/
|
|
40
|
+
const FIRST_YEAR = 1000;
|
|
41
|
+
/** How a refusal names a value written with no UTC offset. */
|
|
42
|
+
const NO_OFFSET_NAME = "no offset";
|
|
43
|
+
/** The largest hour, minute and whole second a wall clock or an offset shows. */
|
|
44
|
+
const LARGEST_HOUR = 23;
|
|
45
|
+
const LARGEST_MINUTE = 59;
|
|
46
|
+
const LARGEST_SECOND = 59;
|
|
47
|
+
/** Each month's days in a common year, January first. */
|
|
48
|
+
const DAYS_PER_MONTH = [31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
|
|
49
|
+
/** February, by its number, and its days in a leap year. */
|
|
50
|
+
const FEBRUARY = 2;
|
|
51
|
+
const LEAP_FEBRUARY_DAYS = 29;
|
|
52
|
+
/** The Gregorian leap-year cycle: every 4th year, except every 100th, except every 400th. */
|
|
53
|
+
const LEAP_YEAR_EVERY = 4;
|
|
54
|
+
const LEAP_YEAR_SKIPPED_EVERY = 100;
|
|
55
|
+
const LEAP_YEAR_KEPT_EVERY = 400;
|
|
56
|
+
/** The offset "Z" writes: UTC itself, which "+00:00" also writes. */
|
|
57
|
+
const UTC_OFFSET = "+00:00";
|
|
58
|
+
/** The offset RFC 3339 writes for a time whose local offset is unknown, so no axis can place it. */
|
|
59
|
+
const UNKNOWN_OFFSET = "-00:00";
|
|
60
|
+
/**
|
|
61
|
+
* Check whether a value is shaped like an ISO date-time, which makes its
|
|
62
|
+
* column a time axis: it starts with a date and is not a label (the date,
|
|
63
|
+
* a space, then text that is not time-shaped). The column's values are then
|
|
64
|
+
* read by `readDateTime`, which refuses any that is not a real date-time,
|
|
65
|
+
* so an axis draws exactly what the reader accepts.
|
|
66
|
+
*
|
|
67
|
+
* @param value - The value.
|
|
68
|
+
* @returns Whether it has the shape of an ISO date-time.
|
|
69
|
+
*/
|
|
70
|
+
export function checkIsDateTimeShaped(value) {
|
|
71
|
+
const text = trimDateText(value);
|
|
72
|
+
return DATE_START_PATTERN.test(text) && !DATE_LABEL_PATTERN.test(text);
|
|
73
|
+
}
|
|
74
|
+
/**
|
|
75
|
+
* Trim the whitespace around a value, the one step both deciding the axis
|
|
76
|
+
* kind and reading a value take first, so they always see the same text:
|
|
77
|
+
* the whitespace carries no meaning, and without the trim a padded
|
|
78
|
+
* date-time would silently become a category.
|
|
79
|
+
*
|
|
80
|
+
* @param value - The value as the column holds it.
|
|
81
|
+
* @returns The value without surrounding whitespace.
|
|
82
|
+
*/
|
|
83
|
+
function trimDateText(value) {
|
|
84
|
+
return value.trim();
|
|
85
|
+
}
|
|
86
|
+
/**
|
|
87
|
+
* Read an ISO date or date-time into its parts.
|
|
88
|
+
*
|
|
89
|
+
* @param text - The date, as ISO 8601 writes it; whitespace around it is ignored.
|
|
90
|
+
* @returns Its parts; seconds may hold a fraction; "Z" reads as the offset +00:00.
|
|
91
|
+
* @throws Error naming the text when it is not an ISO date-time, names a year before 1000, carries the unknown offset -00:00, or names a month, day, hour, minute or second that does not exist.
|
|
92
|
+
*/
|
|
93
|
+
export function readDateTime(text) {
|
|
94
|
+
const match = DATE_TIME_PATTERN.exec(trimDateText(text));
|
|
95
|
+
if (match === null)
|
|
96
|
+
throw new Error(`Expected an ISO date such as 2024-03-05, 2024-03-05T14:30 or 2024-03-05T14:30:05+05:00; got "${text}".`);
|
|
97
|
+
const [, year, month, day, hour, minute, second, offset] = match;
|
|
98
|
+
if (offset === UNKNOWN_OFFSET)
|
|
99
|
+
throw new Error(`Expected a known UTC offset, or Z for UTC; got "${text}", whose ${UNKNOWN_OFFSET} means an unknown offset (RFC 3339), which no axis can place.`);
|
|
100
|
+
const parts = {
|
|
101
|
+
year: Number(year), month: Number(month), day: Number(day),
|
|
102
|
+
hour: Number(hour ?? 0), minute: Number(minute ?? 0), second: Number(second ?? 0),
|
|
103
|
+
offset: offset === undefined ? null : offset === "Z" ? UTC_OFFSET : offset,
|
|
104
|
+
};
|
|
105
|
+
if (parts.year < FIRST_YEAR)
|
|
106
|
+
throw new Error(`Expected a year from ${FIRST_YEAR} on: plotilla's date ticks cannot yet label earlier years, and years 0 to 99 read as 1900 to 1999; got "${text}".`);
|
|
107
|
+
const isInRange = parts.month >= 1 && parts.month <= DAYS_PER_MONTH.length
|
|
108
|
+
&& parts.day >= 1 && parts.day <= countDaysInMonth({ year: parts.year, month: parts.month })
|
|
109
|
+
&& parts.hour <= LARGEST_HOUR && parts.minute <= LARGEST_MINUTE && Math.floor(parts.second) <= LARGEST_SECOND
|
|
110
|
+
&& (parts.offset === null || checkOffsetIsInRange(parts.offset));
|
|
111
|
+
if (!isInRange)
|
|
112
|
+
throw new Error(`Expected a date and time that exist (month 1 to 12, a day in that month, hour 0 to 23, minutes and seconds 0 to 59); got "${text}".`);
|
|
113
|
+
return parts;
|
|
114
|
+
}
|
|
115
|
+
/**
|
|
116
|
+
* Read a column's dates, refusing a column whose values carry different UTC
|
|
117
|
+
* offsets, or an offset beside none: an axis prints each wall clock as
|
|
118
|
+
* written, and one axis cannot show two clocks. A value with no offset is
|
|
119
|
+
* its own clock, since guessing its zone would place it wrongly.
|
|
120
|
+
*
|
|
121
|
+
* @param values - The column's values that are present.
|
|
122
|
+
* @param options - The column's name, for the refusal.
|
|
123
|
+
* @returns Each value's parts, in order.
|
|
124
|
+
* @throws Error naming the column and two of its offsets ("no offset" for none) when they differ, or naming a value that is not a date-time.
|
|
125
|
+
*/
|
|
126
|
+
export function readDateColumn(values, options) {
|
|
127
|
+
const dates = values.map((value) => readDateTime(value));
|
|
128
|
+
const conflict = findOffsetConflict(dates.map((date) => date.offset));
|
|
129
|
+
if (conflict !== null) {
|
|
130
|
+
throw new Error(`Expected every date in "${options.column}" to carry the same UTC offset, since one axis shows one clock; ` +
|
|
131
|
+
`got ${conflict.first.name} and ${conflict.second.name}.`);
|
|
132
|
+
}
|
|
133
|
+
return dates;
|
|
134
|
+
}
|
|
135
|
+
/**
|
|
136
|
+
* Find the first two offsets in a list that differ, a missing offset
|
|
137
|
+
* (null) counting as its own, so every check of "one clock" compares the
|
|
138
|
+
* same way.
|
|
139
|
+
*
|
|
140
|
+
* @param offsets - The offsets, null for a value written with none.
|
|
141
|
+
* @returns The first offset and the first that differs from it, or null when all agree.
|
|
142
|
+
*/
|
|
143
|
+
export function findOffsetConflict(offsets) {
|
|
144
|
+
const [firstOffset] = offsets;
|
|
145
|
+
const secondIndex = offsets.findIndex((offset) => offset !== firstOffset);
|
|
146
|
+
if (firstOffset === undefined || secondIndex === -1)
|
|
147
|
+
return null;
|
|
148
|
+
return {
|
|
149
|
+
first: { index: 0, name: nameOffset(firstOffset) },
|
|
150
|
+
second: { index: secondIndex, name: nameOffset(offsets[secondIndex] ?? null) },
|
|
151
|
+
};
|
|
152
|
+
}
|
|
153
|
+
/**
|
|
154
|
+
* Name an offset for a refusal.
|
|
155
|
+
*
|
|
156
|
+
* @param offset - The offset, null for none.
|
|
157
|
+
* @returns The offset as written, or "no offset".
|
|
158
|
+
*/
|
|
159
|
+
function nameOffset(offset) {
|
|
160
|
+
return offset ?? NO_OFFSET_NAME;
|
|
161
|
+
}
|
|
162
|
+
/**
|
|
163
|
+
* Convert a date-time's parts to milliseconds since 1970, reading its wall
|
|
164
|
+
* clock as UTC, so a date's place on an axis never shifts with the zone the
|
|
165
|
+
* renderer runs in or the offset the column wrote.
|
|
166
|
+
*
|
|
167
|
+
* @param parts - The date-time's parts.
|
|
168
|
+
* @returns The milliseconds.
|
|
169
|
+
*/
|
|
170
|
+
export function convertDateTimeToMilliseconds(parts) {
|
|
171
|
+
return Date.UTC(parts.year, parts.month - 1, parts.day, parts.hour, parts.minute, 0) + parts.second * MILLISECONDS_PER_SECOND;
|
|
172
|
+
}
|
|
173
|
+
/**
|
|
174
|
+
* Count the days in a month, leap years included.
|
|
175
|
+
*
|
|
176
|
+
* @param month - The year and the month (1 to 12).
|
|
177
|
+
* @returns The days.
|
|
178
|
+
*/
|
|
179
|
+
function countDaysInMonth(month) {
|
|
180
|
+
const isLeapYear = month.year % LEAP_YEAR_EVERY === 0 && (month.year % LEAP_YEAR_SKIPPED_EVERY !== 0 || month.year % LEAP_YEAR_KEPT_EVERY === 0);
|
|
181
|
+
if (month.month === FEBRUARY && isLeapYear)
|
|
182
|
+
return LEAP_FEBRUARY_DAYS;
|
|
183
|
+
const days = DAYS_PER_MONTH[month.month - 1];
|
|
184
|
+
if (days === undefined)
|
|
185
|
+
throw new Error(`Expected a month from 1 to 12; got ${month.month}.`);
|
|
186
|
+
return days;
|
|
187
|
+
}
|
|
188
|
+
/**
|
|
189
|
+
* Check that a UTC offset (+05:30) names hours 0 to 23 and minutes 0 to 59.
|
|
190
|
+
*
|
|
191
|
+
* @param offset - The offset, as ±HH:MM.
|
|
192
|
+
* @returns Whether it is in range.
|
|
193
|
+
*/
|
|
194
|
+
function checkOffsetIsInRange(offset) {
|
|
195
|
+
const [hours, minutes] = offset.slice(1).split(":").map(Number);
|
|
196
|
+
if (hours === undefined || minutes === undefined)
|
|
197
|
+
throw new Error(`Expected an offset written ±HH:MM; got "${offset}".`);
|
|
198
|
+
return hours <= LARGEST_HOUR && minutes <= LARGEST_MINUTE;
|
|
199
|
+
}
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Check a plot's declared year formats (x_year_format, y_year_format)
|
|
3
|
+
* against what its axes hold. Years are whole numbers, so a declaration on
|
|
4
|
+
* text, dates or fractions could only print something false, and is refused
|
|
5
|
+
* naming the field rather than ignored (`.claude/rules/plot_interface.md`).
|
|
6
|
+
* Years are also a calendar, not a magnitude, so a year format on a log axis
|
|
7
|
+
* is refused too: ECharts ticks such an axis only at powers of ten, so no
|
|
8
|
+
* year would be labelled (issue #97).
|
|
9
|
+
*/
|
|
10
|
+
import { type DataTable } from "../table/data_table.ts";
|
|
11
|
+
import { type Plot, type PlotFigure } from "./plot_figure.ts";
|
|
12
|
+
/**
|
|
13
|
+
* Check each year format a plot declares: its axis's scale is not "log",
|
|
14
|
+
* its axis holds numbers, and every drawn one is whole.
|
|
15
|
+
*
|
|
16
|
+
* @param plot - The plot, through the schema.
|
|
17
|
+
* @param options - Its table, which rows become marks, and where it is in the figure.
|
|
18
|
+
*/
|
|
19
|
+
export declare function checkAxisYearFormats(plot: Plot, options: {
|
|
20
|
+
table: DataTable;
|
|
21
|
+
isDrawn: (row: number) => boolean;
|
|
22
|
+
where: string;
|
|
23
|
+
}): void;
|
|
24
|
+
/**
|
|
25
|
+
* Check that plots on a shared axis declare one year format: a shared
|
|
26
|
+
* axis is drawn once, so it prints its numbers one way. Each plot's format
|
|
27
|
+
* is the one of the field `decidePlotAxes` puts on that axis (a horizontal
|
|
28
|
+
* bar's y on the shared x), the same rule its scale follows. The refusal
|
|
29
|
+
* names a plot that declares a format, so the field it names always exists.
|
|
30
|
+
*
|
|
31
|
+
* @param figure - The figure, its shared axes checked to be linkable.
|
|
32
|
+
* @param options - Which axis is shared.
|
|
33
|
+
*/
|
|
34
|
+
export declare function checkSharedAxisYearFormats(figure: PlotFigure, options: {
|
|
35
|
+
direction: "x" | "y";
|
|
36
|
+
}): void;
|