@compstats/core 0.2.0

package/dist/interactive/scatter3d.d.ts

@@ -0,0 +1,124 @@
+/**
+ * The interactive 3D scatterplot: choose the columns, set the style, turn the
+ * cloud, and take the resulting call away with you.
+ *
+ * This is the port of `interactive_scatter3d()` in
+ * `../compstatslib/R/scatter3d_interactive.R`. R builds a shiny gadget with
+ * four pickers and five sliders and re-runs `plot_scatter3d()` on every
+ * change. This module does the same: it owns the controls, the state in them,
+ * and the camera the user turned to, and hands every draw to `plotScatter3d`.
+ * It builds no trace and no layout of its own.
+ *
+ * Four things are worth knowing before reading the code.
+ *
+ * **Everything is checked before anything is built.** R validates the style,
+ * then the axis arguments, then the frame, and only then opens the gadget, so
+ * a bad argument leaves no window and no plot. The order and the wording here
+ * are R's, and the style check is R's own function, imported from the plot
+ * layer rather than written again.
+ *
+ * **Out of range is not the same as invalid.** R's check refuses a style no
+ * plot could be drawn with — an opacity of 0, a negative aspect — and says
+ * nothing about the bounds of its own sliders. `aspect = 12` passes it, and
+ * the widget then clamps the handle to 10. So this component throws exactly
+ * where R throws, and clamps and snaps where R's widget clamps.
+ *
+ * **The camera is captured, not computed.** Plotly reports where the user
+ * turned the plot to through `plotly_relayout`; the component stores that
+ * camera and re-passes it into every later draw, so that changing a column
+ * does not throw the angle away. Turning the plot draws nothing: Plotly has
+ * already moved the picture. The captured camera is also written back into
+ * Plotly's own stored layout, because the modebar's buttons relayout the
+ * scene from that layout and would otherwise snap the view to the default —
+ * a Plotly quirk the R gadget shares, and one deliberate deviation here.
+ *
+ * **Done hands back a state, not a printed call.** R prints a copy-pasteable
+ * `plot_scatter3d(...)` line to the console and returns the same arguments
+ * invisibly. A library has no console, and a string would have to be parsed
+ * to be used again; so `getValues()` returns the options object that
+ * reproduces the picture, and `onDone` receives it. Feeding it back to
+ * `plotScatter3d` — or to this function — is R's `do.call` equivalent.
+ *
+ * One R behavior is absent for R's own reason: the gadget shows no message
+ * about the column choice. `plot_scatter3d()` writes one when it picks the
+ * columns itself, and neither gadget lets it: R passes `input$x`, `input$y`
+ * and `input$z` on every render, as this component passes its own state. The
+ * choice is visible in the pickers instead.
+ */
+import type { DataFrame } from "../core/frame";
+import type { PlotScatter3dOptions, Scatter3dSpec, Scatter3dSpecOptions } from "../plot/scatter3d";
+import type { Plot3dTarget } from "./target";
+/**
+ * Everything the panel holds, and everything that reproduces the picture.
+ *
+ * This is `Scatter3dSpecOptions` with the parts the gadget always settles —
+ * the three axes and the three style numbers — made certain. Hand it to
+ * `plotScatter3d`, or back to `interactiveScatter3d`, to open at the same
+ * view. It is the port's answer to the call R prints on Done.
+ */
+export interface Scatter3dValues extends Scatter3dSpecOptions {
+    /** The column on the first horizontal axis. */
+    readonly x: string;
+    /** The column on the second horizontal axis. */
+    readonly y: string;
+    /** The column on the vertical axis. */
+    readonly z: string;
+    /** The three axis proportions. */
+    readonly aspect: readonly number[];
+    /** How solid each marker is. */
+    readonly opacity: number;
+    /** How large each marker is. */
+    readonly size: number;
+}
+/**
+ * What the component accepts.
+ *
+ * Every option of `plotScatter3d` is a starting value, exactly as in R, and
+ * anything the plot grows later reaches it untouched.
+ */
+export interface InteractiveScatter3dOptions extends PlotScatter3dOptions {
+    /** What to run on `done()`. */
+    readonly onDone?: (values: Scatter3dValues) => void;
+}
+/** What the caller holds after the component starts. */
+export interface InteractiveScatter3dHandle {
+    /**
+     * Return the state the panel stands at: the options that reproduce the
+     * picture, including a camera the user turned to.
+     */
+    getValues(): Scatter3dValues;
+    /**
+     * Return what the last draw specified — its traces, its layout, and the
+     * plot layer's note. Null until the first picture is drawn.
+     */
+    getSpec(): Scatter3dSpec | null;
+    /**
+     * Wait for the drawing now in flight. Drawing is asynchronous, so this is
+     * how a caller — or a test — knows the picture is on the screen.
+     */
+    rendered(): Promise<void>;
+    /** Hand the current state to the `onDone` callback. */
+    done(): void;
+    /** Stop listening, purge the plot, and take back what was built. */
+    destroy(): void;
+}
+/**
+ * Start an interactive 3D scatterplot on a target.
+ *
+ * The component builds its controls, draws once, and redraws on every change.
+ *
+ * @param target A container element, or a plot element and a controls host.
+ *   See `./target.ts`.
+ * @param data The frame to read. It needs three numeric columns.
+ * @param options Starting values, a done callback, and the options of
+ *   `plotScatter3d`.
+ * @returns The handle to the running component. Await `rendered()` for the
+ *   first picture.
+ * @throws RangeError If the style is one no plot could be drawn with, if the
+ *   frame has fewer than three numeric columns, or if an initial column is
+ *   not one the picker could stand on. Nothing is built and nothing is drawn
+ *   in any of those cases.
+ * @throws Error If a canvas is passed as the container.
+ */
+export declare function interactiveScatter3d(target: Plot3dTarget, data: DataFrame, options?: InteractiveScatter3dOptions): InteractiveScatter3dHandle;
+//# sourceMappingURL=scatter3d.d.ts.map

package/dist/interactive/scatter3d.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scatter3d.d.ts","sourceRoot":"","sources":["../../src/interactive/scatter3d.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAM/C,OAAO,KAAK,EACV,oBAAoB,EACpB,aAAa,EACb,oBAAoB,EACrB,MAAM,mBAAmB,CAAC;AAe3B,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAE7C;;;;;;;GAOG;AACH,MAAM,WAAW,eAAgB,SAAQ,oBAAoB;IAC3D,+CAA+C;IAC/C,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB,gDAAgD;IAChD,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB,uCAAuC;IACvC,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB,kCAAkC;IAClC,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,gCAAgC;IAChC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,gCAAgC;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED;;;;;GAKG;AACH,MAAM,WAAW,2BAA4B,SAAQ,oBAAoB;IACvE,+BAA+B;IAC/B,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,eAAe,KAAK,IAAI,CAAC;CACrD;AAED,wDAAwD;AACxD,MAAM,WAAW,0BAA0B;IACzC;;;OAGG;IACH,SAAS,IAAI,eAAe,CAAC;IAC7B;;;OAGG;IACH,OAAO,IAAI,aAAa,GAAG,IAAI,CAAC;IAChC;;;OAGG;IACH,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1B,uDAAuD;IACvD,IAAI,IAAI,IAAI,CAAC;IACb,oEAAoE;IACpE,OAAO,IAAI,IAAI,CAAC;CACjB;AAmBD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,YAAY,EACpB,IAAI,EAAE,SAAS,EACf,OAAO,GAAE,2BAAgC,GACxC,0BAA0B,CAoT5B"}

package/dist/interactive/tTest.d.ts

@@ -0,0 +1,69 @@
+/**
+ * The interactive t test: move the sliders and watch the power change.
+ *
+ * This is the port of `interactive_t_test()` in
+ * `../compstatslib/R/t_statistic_interactive.R`. R builds a miniUI gadget with
+ * four sliders and a checkbox, and re-runs `plot_t_test()` whenever one moves.
+ * This module does the same: it owns the controls and the values in them, and
+ * hands every draw to `plotTTest`. It contains no drawing code and no
+ * statistics.
+ *
+ * R's `runGadget()` blocks until "Done" and then returns nothing at all —
+ * `stopApp(NULL)`. Nothing blocks in a browser, so this returns a handle at
+ * once. `getValues()` reads the controls and `getStats()` reads what was last
+ * drawn. `done()` reports the current values to the `onDone` callback: R hands
+ * back nothing, but a callback with no argument would only send the caller
+ * back to the handle for the values it just asked about.
+ */
+import type { TTestStats } from "../core/ttest";
+import type { PlotTTestOptions } from "../plot/tTest";
+import type { ControlTarget } from "./target";
+/** Everything the panel of controls holds. */
+export interface TTestValues {
+    /** The difference the alternative hypothesis claims. */
+    readonly diff: number;
+    /** The population standard deviation. */
+    readonly sd: number;
+    /** The sample size. */
+    readonly n: number;
+    /** The significance level. */
+    readonly alpha: number;
+    /** Whether the matrix of the four outcomes is showing. */
+    readonly errorMatrix: boolean;
+}
+/**
+ * What the component accepts.
+ *
+ * The options of `plotTTest` pass through to it, and the four test parameters
+ * double as the starting positions of the sliders. This is the equivalent of
+ * R's `...` forwarding.
+ */
+export interface InteractiveTTestOptions extends PlotTTestOptions {
+    /** What to run on `done()`. */
+    readonly onDone?: (values: TTestValues) => void;
+}
+/** What the caller holds after the component starts. */
+export interface InteractiveTTestHandle {
+    /** Return where the controls stand now. */
+    getValues(): TTestValues;
+    /** Return the statistics behind the last picture drawn. */
+    getStats(): TTestStats;
+    /** Hand the current values to the `onDone` callback. */
+    done(): void;
+    /** Stop listening and take back the controls that were built. */
+    destroy(): void;
+}
+/**
+ * Start an interactive t test on a target.
+ *
+ * The component builds its controls, draws once, and redraws on every change.
+ *
+ * @param target A container element, or a surface and a controls host. See
+ * `./target.ts`.
+ * @param options Starting values, a done callback, and the options of
+ * `plotTTest`.
+ * @returns The handle to the running component.
+ * @throws Error If a canvas gives no 2D context.
+ */
+export declare function interactiveTTest(target: ControlTarget, options?: InteractiveTTestOptions): InteractiveTTestHandle;
+//# sourceMappingURL=tTest.d.ts.map

package/dist/interactive/tTest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tTest.d.ts","sourceRoot":"","sources":["../../src/interactive/tTest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAEhD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAGtD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAE9C,8CAA8C;AAC9C,MAAM,WAAW,WAAW;IAC1B,wDAAwD;IACxD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,yCAAyC;IACzC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,uBAAuB;IACvB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB,8BAA8B;IAC9B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,0DAA0D;IAC1D,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;CAC/B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,uBAAwB,SAAQ,gBAAgB;IAC/D,+BAA+B;IAC/B,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,WAAW,KAAK,IAAI,CAAC;CACjD;AAED,wDAAwD;AACxD,MAAM,WAAW,sBAAsB;IACrC,2CAA2C;IAC3C,SAAS,IAAI,WAAW,CAAC;IACzB,2DAA2D;IAC3D,QAAQ,IAAI,UAAU,CAAC;IACvB,wDAAwD;IACxD,IAAI,IAAI,IAAI,CAAC;IACb,iEAAiE;IACjE,OAAO,IAAI,IAAI,CAAC;CACjB;AA6BD;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,aAAa,EACrB,OAAO,GAAE,uBAA4B,GACpC,sBAAsB,CAyGxB"}

package/dist/interactive/target.d.ts

@@ -0,0 +1,132 @@
+/**
+ * The target that every interactive component attaches to.
+ *
+ * An interactive component needs two things: a surface to draw on and an
+ * element that reports the clicks. A canvas is both, so a browser caller
+ * passes one canvas.
+ *
+ * A test cannot pass a canvas. happy-dom gives a canvas no 2D context, so
+ * nothing can draw to it. A test therefore passes the two things apart: a
+ * recording surface to draw to, and a real element to dispatch events at. This
+ * split is the pattern for every module in `src/interactive/`.
+ */
+import type { RenderTarget } from "../plot/target";
+/** The part of an element that an interactive component listens to. */
+export type ClickSource = Pick<HTMLElement, "addEventListener" | "removeEventListener" | "getBoundingClientRect">;
+/** A surface and an element, held apart. */
+export interface SplitTarget {
+    /** Where the component draws. */
+    readonly surface: RenderTarget;
+    /** Where the component listens. */
+    readonly element: ClickSource;
+}
+/** What an interactive component accepts. */
+export type InteractiveTarget = HTMLCanvasElement | SplitTarget;
+/**
+ * Reduce an interactive target to a surface and an element.
+ *
+ * @param target A canvas, or a surface and an element.
+ * @returns The two parts.
+ * @throws Error If a canvas gives no 2D context.
+ */
+export declare function resolveInteractiveTarget(target: InteractiveTarget): SplitTarget;
+/**
+ * Convert the position of a mouse event to a pixel of the surface.
+ *
+ * CSS may show a canvas at a size other than its pixel size. The function
+ * therefore scales the position by the ratio of the two. A rectangle of zero
+ * width or height carries no ratio, so the function reads the client position
+ * as a surface pixel. Only a hidden element and a stub report such a
+ * rectangle.
+ *
+ * @param element The element that received the event.
+ * @param surface The drawing surface and its pixel size.
+ * @param event The mouse event.
+ * @returns The pixel column and row of the event.
+ */
+export declare function eventPixel(element: ClickSource, surface: RenderTarget, event: MouseEvent): {
+    readonly x: number;
+    readonly y: number;
+};
+/**
+ * A drawing surface and an element to build controls in, held apart.
+ *
+ * This is the `SplitTarget` idea again, for a component driven by a panel of
+ * controls rather than by clicks on the picture. A test passes the two parts,
+ * so it can drive the inputs without a real layout and without a canvas that
+ * happy-dom cannot give a context to.
+ */
+export interface PanelTarget {
+    /** Where the component draws. */
+    readonly surface: RenderTarget;
+    /** Where the component builds its inputs. The caller keeps this element. */
+    readonly controls: HTMLElement;
+}
+/**
+ * What a control-driven component accepts.
+ *
+ * Pass a container element in a browser and the component fills it. Pass a
+ * `PanelTarget` to hold the two parts apart, which is how the tests run.
+ */
+export type ControlTarget = HTMLElement | PanelTarget;
+/** A resolved panel, and a way to take back anything that was built for it. */
+export interface ResolvedPanel {
+    readonly surface: RenderTarget;
+    readonly controls: HTMLElement;
+    /** Remove what this resolver created. A no-op when the caller supplied it. */
+    release(): void;
+}
+/**
+ * Reduce a control target to a surface and a place to build controls.
+ *
+ * Given a container, this builds the canvas and the controls column inside it
+ * in R's arrangement, and `release()` takes them out again. Given the parts,
+ * it passes them through and `release()` does nothing, because the caller owns
+ * what it supplied.
+ *
+ * @param target A container element, or a surface and a controls host.
+ * @returns The two parts and a way to undo what was built.
+ * @throws Error If a container is a canvas, or if a created canvas gives no 2D
+ * context.
+ */
+export declare function resolveControlTarget(target: ControlTarget): ResolvedPanel;
+/**
+ * An element for Plotly to fill, and an element to build controls in.
+ *
+ * The third target shape of the port, after `SplitTarget` and `PanelTarget`.
+ * The 3D components need it because Plotly draws into an element of its own
+ * rather than onto a canvas: there is no context to hand around, and the
+ * element the plot lives in is the element the engine later purges.
+ */
+export interface Plot3dPanel {
+    /** Where Plotly draws. The component gives this element to the plot. */
+    readonly plot: HTMLElement;
+    /** Where the component builds its inputs. */
+    readonly controls: HTMLElement;
+}
+/**
+ * What a 3D component accepts.
+ *
+ * Pass a container element in a browser and the component fills it. Pass the
+ * two parts to hold them apart, which is how the tests run.
+ */
+export type Plot3dTarget = HTMLElement | Plot3dPanel;
+/** A resolved 3D panel, and a way to take back anything built for it. */
+export interface ResolvedPlot3dPanel extends Plot3dPanel {
+    /** Remove what this resolver created. A no-op when the caller supplied it. */
+    release(): void;
+}
+/**
+ * Reduce a 3D target to a plot element and a place to build controls.
+ *
+ * Given a container, this builds the two elements in R's own arrangement: a
+ * strip of controls across the top, and the plot filling what is left. R's
+ * gadget lays both 3D families out that way (`flex-direction: column`, the
+ * control rows `flex-shrink: 0`, the plot `flex: 1`).
+ *
+ * @param target A container element, or the two parts.
+ * @returns The two parts and a way to undo what was built.
+ * @throws Error If a container is a canvas, which Plotly cannot draw into.
+ */
+export declare function resolvePlot3dTarget(target: Plot3dTarget): ResolvedPlot3dPanel;
+//# sourceMappingURL=target.d.ts.map

package/dist/interactive/target.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"target.d.ts","sourceRoot":"","sources":["../../src/interactive/target.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAEnD,uEAAuE;AACvE,MAAM,MAAM,WAAW,GAAG,IAAI,CAC5B,WAAW,EACX,kBAAkB,GAAG,qBAAqB,GAAG,uBAAuB,CACrE,CAAC;AAEF,4CAA4C;AAC5C,MAAM,WAAW,WAAW;IAC1B,iCAAiC;IACjC,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC;IAC/B,mCAAmC;IACnC,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC;CAC/B;AAED,6CAA6C;AAC7C,MAAM,MAAM,iBAAiB,GAAG,iBAAiB,GAAG,WAAW,CAAC;AAEhE;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,iBAAiB,GACxB,WAAW,CAKb;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,UAAU,CACxB,OAAO,EAAE,WAAW,EACpB,OAAO,EAAE,YAAY,EACrB,KAAK,EAAE,UAAU,GAChB;IAAE,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAA;CAAE,CAQ5C;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,WAAW;IAC1B,iCAAiC;IACjC,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC;IAC/B,4EAA4E;IAC5E,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC;CAChC;AAED;;;;;GAKG;AACH,MAAM,MAAM,aAAa,GAAG,WAAW,GAAG,WAAW,CAAC;AAEtD,+EAA+E;AAC/E,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC;IAC/B,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC;IAC/B,8EAA8E;IAC9E,OAAO,IAAI,IAAI,CAAC;CACjB;AAOD;;;;;;;;;;;;GAYG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,aAAa,GAAG,aAAa,CAoEzE;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,WAAW;IAC1B,wEAAwE;IACxE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,6CAA6C;IAC7C,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC;CAChC;AAED;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GAAG,WAAW,GAAG,WAAW,CAAC;AAErD,yEAAyE;AACzE,MAAM,WAAW,mBAAoB,SAAQ,WAAW;IACtD,8EAA8E;IAC9E,OAAO,IAAI,IAAI,CAAC;CACjB;AAKD;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,YAAY,GAAG,mBAAmB,CA0C7E"}

package/dist/plot/axes.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Shared 2D scales, ticks, and axis drawing.
+ *
+ * Every 2D plot in this library maps a world window onto a pixel rectangle and
+ * draws the same style of axis box. That work lives here so no plot repeats
+ * it. R gets the equivalent from `plot()` and `pretty()`.
+ *
+ * The scale is pure geometry: it holds numbers and returns numbers. Only
+ * `drawAxes` touches a context, and it receives that context as an argument.
+ */
+import type { Context2D } from "./target";
+/** A closed range of world values. */
+export interface Extent {
+    readonly min: number;
+    readonly max: number;
+}
+/** Pixels reserved outside the plot area for ticks, labels, and titles. */
+export interface Margins {
+    readonly top: number;
+    readonly right: number;
+    readonly bottom: number;
+    readonly left: number;
+}
+/** The pixel rectangle that holds the data. */
+export interface PlotArea {
+    readonly left: number;
+    readonly right: number;
+    readonly top: number;
+    readonly bottom: number;
+    readonly width: number;
+    readonly height: number;
+}
+/** What `createScale` needs: a surface size and a world window. */
+export interface ScaleOptions {
+    readonly width: number;
+    readonly height: number;
+    readonly x: Extent;
+    readonly y: Extent;
+    readonly margins?: Margins;
+}
+/** A two-way map between world values and pixels. */
+export interface Scale {
+    readonly area: PlotArea;
+    readonly world: {
+        readonly x: Extent;
+        readonly y: Extent;
+    };
+    /** Return the pixel column of a world x value. */
+    toPixelX(x: number): number;
+    /** Return the pixel row of a world y value. Pixel rows grow downward. */
+    toPixelY(y: number): number;
+    /** Return the world x value of a pixel column. */
+    toWorldX(px: number): number;
+    /** Return the world y value of a pixel row. */
+    toWorldY(py: number): number;
+}
+/** What to draw around the plot area. */
+export interface AxesOptions {
+    /** Title under the x axis. Omit for no title. */
+    readonly xLabel?: string;
+    /** Title beside the y axis, rotated. Omit for no title. */
+    readonly yLabel?: string;
+    /** Ticks to aim for on each axis. The tick rule may give a few more or less. */
+    readonly tickCount?: number;
+    /**
+     * Draw the box around the plot area. True by default.
+     *
+     * R's `plot()` draws the box under `frame.plot = TRUE` and drops it under
+     * `frame.plot = FALSE`, keeping the two axis lines either way. The t-test
+     * plot passes `frame = FALSE`, as its R original does.
+     */
+    readonly frame?: boolean;
+    /**
+     * Draw the y axis, its ticks and its labels. True by default.
+     *
+     * R's `yaxt = "n"` drops the vertical axis and leaves the horizontal one.
+     * The sampling plot asks for that on each of its three panels, where the
+     * height is a density or a count that no reader needs to measure.
+     */
+    readonly yAxis?: boolean;
+}
+/** Margins wide enough for two-digit tick labels and an axis title. */
+export declare const DEFAULT_MARGINS: Margins;
+/** Read a pair of limits as a range, whichever way round it was written. */
+export declare function extentOf(limits: readonly [number, number]): Extent;
+/**
+ * Build a scale for one surface and one world window.
+ *
+ * A world range of zero width maps to the middle of the plot area, which keeps
+ * a degenerate data set visible instead of dividing by zero.
+ */
+export declare function createScale(options: ScaleOptions): Scale;
+/**
+ * Report whether a pixel lies in the plot area. An edge counts as inside.
+ *
+ * The interactive components ask this of every click, to keep a click on the
+ * margin — the tick labels and the axis titles — from becoming a data point.
+ *
+ * @param area The plot area, from a scale.
+ * @param pixel A position on the surface, in layout pixels.
+ * @returns Whether the position is in the area, edges included.
+ */
+export declare function pixelInArea(area: PlotArea, pixel: {
+    readonly x: number;
+    readonly y: number;
+}): boolean;
+/**
+ * Choose readable tick values inside an extent.
+ *
+ * The step is 1, 2, or 5 times a power of ten, as in R's `pretty()`. Unlike
+ * `pretty()`, this keeps every tick inside the extent instead of widening the
+ * range to round numbers, because the plot window is fixed before the ticks
+ * are chosen.
+ *
+ * @param extent The range to cover. A reversed range gives the same ticks.
+ * @param count The number of intervals to aim for.
+ * @returns The tick values, ascending. A range of zero width gives one tick.
+ */
+export declare function prettyTicks(extent: Extent, count?: number): number[];
+/**
+ * Draw the axis box, the ticks, the tick labels, and the axis titles.
+ *
+ * @param ctx The context to draw to.
+ * @param scale The scale that fixes the plot area and the world window.
+ * @param options Titles and tick count. All are optional.
+ */
+export declare function drawAxes(ctx: Context2D, scale: Scale, options?: AxesOptions): void;
+//# sourceMappingURL=axes.d.ts.map

package/dist/plot/axes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"axes.d.ts","sourceRoot":"","sources":["../../src/plot/axes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAE1C,sCAAsC;AACtC,MAAM,WAAW,MAAM;IACrB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAED,2EAA2E;AAC3E,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,+CAA+C;AAC/C,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,mEAAmE;AACnE,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED,qDAAqD;AACrD,MAAM,WAAW,KAAK;IACpB,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE;QAAE,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC3D,kDAAkD;IAClD,QAAQ,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC5B,yEAAyE;IACzE,QAAQ,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC5B,kDAAkD;IAClD,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAAC;IAC7B,+CAA+C;IAC/C,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAAC;CAC9B;AAED,yCAAyC;AACzC,MAAM,WAAW,WAAW;IAC1B,iDAAiD;IACjD,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,2DAA2D;IAC3D,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,gFAAgF;IAChF,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B;;;;;;OAMG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IACzB;;;;;;OAMG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,uEAAuE;AACvE,eAAO,MAAM,eAAe,EAAE,OAK7B,CAAC;AAUF,4EAA4E;AAC5E,wBAAgB,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAElE;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,YAAY,GAAG,KAAK,CA+CxD;AAED;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CACzB,IAAI,EAAE,QAAQ,EACd,KAAK,EAAE;IAAE,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAA;CAAE,GAChD,OAAO,CAOT;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CACzB,MAAM,EAAE,MAAM,EACd,KAAK,GAAE,MAA2B,GACjC,MAAM,EAAE,CAkBV;AAED;;;;;;GAMG;AACH,wBAAgB,QAAQ,CACtB,GAAG,EAAE,SAAS,EACd,KAAK,EAAE,KAAK,EACZ,OAAO,GAAE,WAAgB,GACxB,IAAI,CAiFN"}

package/dist/plot/draw.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Shared drawing primitives for the 2D plots.
+ *
+ * The post-port reuse audit found each of these written out in most of the
+ * `plot/` modules, byte for byte. They live here so a change to any of them
+ * reaches every plot at once. `axes.ts` keeps what belongs to an axis: the
+ * world-to-pixel scale, the tick rule, and the frame.
+ *
+ * Nothing here reads a scale's world window. Each function takes pixels, so a
+ * caller keeps its own world geometry and this file stays about the canvas.
+ */
+import type { PlotArea, Scale } from "./axes";
+import type { Context2D } from "./target";
+import type { Point } from "../core/regression";
+/** R: `lty = "dotted"`. */
+export declare const DOTTED: number[];
+/** Paint the whole surface white, the color of a fresh R device. */
+export declare function clearSurface(ctx: Context2D, width: number, height: number): void;
+/**
+ * Keep drawing inside the plot area, as base graphics does by default.
+ *
+ * R's device clips the plot region and canvas clips nothing, so every plot
+ * that can put ink outside its window needs this. The caller saves and
+ * restores around it: the clip lifts with the state it was set in.
+ */
+export declare function clipToArea(ctx: Context2D, area: PlotArea): void;
+/** Draw each point as a filled dot. R: `pch = 19, cex = 2, col = "gray"`. */
+export declare function drawDots(ctx: Context2D, scale: Scale, points: readonly Point[]): void;
+/** How an arrow is drawn. The defaults are R's `arrows()` defaults. */
+export interface ArrowOptions {
+    /** The length of an arrowhead edge, in pixels. R measures it in inches. */
+    readonly headLength: number;
+    /** The dash pattern. R's `lty` covers the head as well as the shaft. */
+    readonly dash?: readonly number[];
+    readonly color?: string;
+    readonly lineWidth?: number;
+}
+/**
+ * Draw one arrow between two pixel positions.
+ *
+ * The head goes at the tip alone, which is what `arrows()` does with its
+ * default `code = 2`. An arrow too short to have a direction is skipped
+ * whole: see `MIN_ARROW_PIXELS`.
+ */
+export declare function drawArrow(ctx: Context2D, tail: readonly [number, number], tip: readonly [number, number], options: ArrowOptions): void;
+//# sourceMappingURL=draw.d.ts.map

package/dist/plot/draw.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"draw.d.ts","sourceRoot":"","sources":["../../src/plot/draw.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,QAAQ,CAAC;AAC9C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAC1C,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAEhD,2BAA2B;AAC3B,eAAO,MAAM,MAAM,UAAS,CAAC;AA6B7B,oEAAoE;AACpE,wBAAgB,YAAY,CAC1B,GAAG,EAAE,SAAS,EACd,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,GACb,IAAI,CAIN;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,SAAS,EAAE,IAAI,EAAE,QAAQ,GAAG,IAAI,CAI/D;AAED,6EAA6E;AAC7E,wBAAgB,QAAQ,CACtB,GAAG,EAAE,SAAS,EACd,KAAK,EAAE,KAAK,EACZ,MAAM,EAAE,SAAS,KAAK,EAAE,GACvB,IAAI,CAgBN;AAED,uEAAuE;AACvE,MAAM,WAAW,YAAY;IAC3B,2EAA2E;IAC3E,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,wEAAwE;IACxE,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CACvB,GAAG,EAAE,SAAS,EACd,IAAI,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,EAC/B,GAAG,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,EAC9B,OAAO,EAAE,YAAY,GACpB,IAAI,CAkCN"}

package/dist/plot/format.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Number formatting shared by the plots.
+ *
+ * R writes numbers into a plot through `round(x, 2)` and its own coercion to
+ * text. Both the regression stats block and the t-test error matrix need that
+ * same treatment, so it lives here rather than in either of them.
+ */
+/**
+ * Round to two decimals for display, and report a missing value as R does.
+ *
+ * R prints `round(x, 2)`, which drops a trailing zero, so 2.50 reads as "2.5".
+ * R rounds half to even and this rounds half away from zero; the two differ
+ * only on an exact half at the third decimal.
+ *
+ * @param value The number to show. Null and non-finite read as "NA".
+ * @returns The text to draw.
+ */
+export declare function formatStat(value: number | null): string;
+/**
+ * Write a number the way R's `as.character()` does.
+ *
+ * R keeps 15 significant digits and drops what follows, so `1 - 0.07` prints
+ * as "0.93". JavaScript's `String()` instead keeps every digit needed to
+ * identify the double, and prints the same subtraction as
+ * "0.9299999999999999". The t-test error matrix draws `1 - alpha` untouched,
+ * and alpha steps in hundredths, so without this the panel shows that run of
+ * nines at one of its ten settings.
+ *
+ * @param value The number to show.
+ * @returns The text to draw. Non-finite reads as "NA", as elsewhere.
+ */
+export declare function formatNumber(value: number): string;
+//# sourceMappingURL=format.d.ts.map

package/dist/plot/format.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../../src/plot/format.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAKvD;AAKD;;;;;;;;;;;;GAYG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAKlD"}

package/dist/plot/logit.d.ts

@@ -0,0 +1,68 @@
+/**
+ * The logistic-regression plot: the points, the fitted probability curve, and
+ * a small block of statistics.
+ *
+ * This is the drawing half of `plot_logit()` and `plot_points_logit()` in
+ * `../compstatslib/R/logit_plot.R`. Every number it draws comes from
+ * `logisticRegression` in `src/core/logit.ts`; this module computes no
+ * statistics of its own.
+ */
+import type { LogitFit } from "../core/logit";
+import type { Point } from "../core/regression";
+import type { Scale } from "./axes";
+import type { PlotTarget } from "./target";
+/**
+ * Which corner of the plot area the statistics block sits in.
+ *
+ * R's `legend()` takes nine positions. These four are the ones a block of
+ * text reads well in, and one of them is R's own default here.
+ */
+export type LegendLocation = "topleft" | "topright" | "bottomleft" | "bottomright";
+/** What to draw. R's defaults throughout. */
+export interface PlotLogitOptions {
+    /** Fit the model and draw its curve. True by default. */
+    readonly regression?: boolean;
+    /** List the statistics in a corner. Needs `regression`. True by default. */
+    readonly stats?: boolean;
+    /** Left edge of the window, before the data widen it. R's `min_x`, 0. */
+    readonly minX?: number;
+    /** Right edge of the window, before the data widen it. R's `max_x`, 1. */
+    readonly maxX?: number;
+    /** Corner for the statistics. R's `legend_loc`, "topleft". */
+    readonly legendLoc?: LegendLocation;
+}
+/**
+ * Build the scale that `plotLogit` draws through.
+ *
+ * Unlike the regression plot, whose window is fixed, this one follows the
+ * data: R starts at `min_x` and `max_x` and then widens them to cover every
+ * point (`max_x <- max(max_x, points[[x_name]])`). The vertical window is
+ * always a probability, 0 to 1.
+ *
+ * The interactive layer reads the scale from here, so the window stays
+ * defined in one place. Nothing outside this module may restate it.
+ *
+ * @param width The pixel width of the surface.
+ * @param height The pixel height of the surface.
+ * @param points The observations the window has to cover.
+ * @param options The same options `plotLogit` takes.
+ * @returns The map between world values and pixels.
+ */
+export declare function logitScale(width: number, height: number, points: readonly Point[], options?: PlotLogitOptions): Scale;
+/**
+ * Draw the points and their fitted probability curve.
+ *
+ * With fewer than two points the function draws what it has and fits nothing.
+ * R stops at the same two places: it returns before `glm()` on an empty frame,
+ * and again on a single point. The core would fit that single point — R's
+ * `glm()` does, reporting a saturated intercept and no slope — but the plot
+ * never asks it to, so neither does this.
+ *
+ * @param target A canvas, or a context and a size. See `./target.ts`.
+ * @param points The observations. Each y must be 0 or 1.
+ * @param options What to show and how wide to open the window.
+ * @returns The fit the plot drew, or null if it drew none. R returns the
+ * points instead, which the caller already holds.
+ */
+export declare function plotLogit(target: PlotTarget, points: readonly Point[], options?: PlotLogitOptions): LogitFit | null;
+//# sourceMappingURL=logit.d.ts.map

package/dist/plot/logit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logit.d.ts","sourceRoot":"","sources":["../../src/plot/logit.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAEhD,OAAO,KAAK,EAAU,KAAK,EAAE,MAAM,QAAQ,CAAC;AAI5C,OAAO,KAAK,EAAa,UAAU,EAAE,MAAM,UAAU,CAAC;AAEtD;;;;;GAKG;AACH,MAAM,MAAM,cAAc,GACtB,SAAS,GACT,UAAU,GACV,YAAY,GACZ,aAAa,CAAC;AAElB,6CAA6C;AAC7C,MAAM,WAAW,gBAAgB;IAC/B,yDAAyD;IACzD,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC;IAC9B,4EAA4E;IAC5E,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IACzB,yEAAyE;IACzE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,0EAA0E;IAC1E,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,8DAA8D;IAC9D,QAAQ,CAAC,SAAS,CAAC,EAAE,cAAc,CAAC;CACrC;AAwBD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,UAAU,CACxB,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,SAAS,KAAK,EAAE,EACxB,OAAO,GAAE,gBAAqB,GAC7B,KAAK,CAaP;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,SAAS,CACvB,MAAM,EAAE,UAAU,EAClB,MAAM,EAAE,SAAS,KAAK,EAAE,EACxB,OAAO,GAAE,gBAAqB,GAC7B,QAAQ,GAAG,IAAI,CA6BjB"}