@compstats/core 0.2.0

package/dist/plot/matrixInverse.d.ts

@@ -0,0 +1,62 @@
+/**
+ * The matrix inverse plot: a matrix and its inverse, each as a parallelogram
+ * with an arrow along each column.
+ *
+ * This is the drawing half of `plot_matrix_inverse()` in
+ * `../compstatslib/R/matrix_inverse_plot.R`. Every number it draws comes from
+ * `invertMatrix` in `src/core/matrix.ts`; this module computes no arithmetic
+ * of its own. The picture teaches one thing: the area of each parallelogram is
+ * the determinant of the matrix that spans it, so a matrix that stretches
+ * space has an inverse that squeezes it, and the two areas are reciprocal.
+ *
+ * Three things here differ from the other plots in this port.
+ *
+ * **A matrix with no inverse leaves the canvas untouched.** `solve(A)` is the
+ * second line of the R function and `plot(NA, ...)` is the fourth, so R stops
+ * with an error before it opens a window. Traced on a null device, the
+ * singular case makes no graphics call at all. This function does the same and
+ * returns the report, which names the reason. A caller that redraws while a
+ * control moves has to clear its own surface, because this function will not.
+ *
+ * **The window does not hold its aspect.** The R call passes no `asp`, unlike
+ * `plot_pca()`, so a square in the data is a square on screen only on a square
+ * plot area. Measured in R, `par("usr")` reads -3.24 3.24 -3.24 3.24 on a 10
+ * by 5 inch device and the same on a 5 by 5 inch one. The parallelograms shear
+ * with the surface, and that is R's picture.
+ *
+ * **The arrowhead is a physical size.** R asks for `length = 0.25`, measured
+ * in inches, so the head does not shrink with a short vector. A vector short
+ * enough loses its arrow altogether: see `MIN_ARROW_PIXELS` in `draw.ts`.
+ */
+import type { Matrix2, MatrixInversion } from "../core/matrix";
+import type { Scale } from "./axes";
+import type { PlotTarget } from "./target";
+/**
+ * Build the scale that `plotMatrixInverse` draws through.
+ *
+ * The window is R's fixed -3 to 3 on both axes. The two axes are scaled
+ * separately, as R scales them: a wide surface makes a wide picture. Unlike R,
+ * the limits are the literal ones — R pads a range by 4% first, and this port
+ * drops that padding everywhere.
+ *
+ * @param width The pixel width of the surface.
+ * @param height The pixel height of the surface.
+ * @returns The map between world values and pixels.
+ */
+export declare function matrixInverseScale(width: number, height: number): Scale;
+/**
+ * Draw the matrix and its inverse.
+ *
+ * A matrix with no inverse draws nothing — not the axes, not the background.
+ * See the note on this module: R stops before it draws, and the report this
+ * function returns says why.
+ *
+ * @param target A canvas, or a context and a size. See `./target.ts`.
+ * @param matrix The matrix, as two columns. See `Matrix2`.
+ * @returns The determinant, the inverse, and the singularity, exactly as
+ *   `invertMatrix` reports them. R returns nothing, but a browser caller needs
+ *   the numbers it has just drawn — and needs the reason when nothing was
+ *   drawn.
+ */
+export declare function plotMatrixInverse(target: PlotTarget, matrix: Matrix2): MatrixInversion;
+//# sourceMappingURL=matrixInverse.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"matrixInverse.d.ts","sourceRoot":"","sources":["../../src/plot/matrixInverse.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAGH,OAAO,KAAK,EAAE,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAE/D,OAAO,KAAK,EAAU,KAAK,EAAE,MAAM,QAAQ,CAAC;AAG5C,OAAO,KAAK,EAAa,UAAU,EAAE,MAAM,UAAU,CAAC;AAwBtD;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,KAAK,CAEvE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,UAAU,EAClB,MAAM,EAAE,OAAO,GACd,eAAe,CA6BjB"}

package/dist/plot/moderation3d.d.ts

@@ -0,0 +1,135 @@
+/**
+ * The moderation surface: a fitted regression drawn as a height field over
+ * the IV and the moderator.
+ *
+ * This is the drawing half of `plot_moderation_3d()` of
+ * `../compstatslib/R/moderation_3d_plot.R`. Every number comes from
+ * `moderationSurface` in `src/core/moderation.ts`; this module computes no
+ * statistics of its own. The grid values are pinned in
+ * `.claude/plans/moderation-fixtures.md` section 3.
+ *
+ * Three decisions are worth stating.
+ *
+ * **The engine is Plotly, not lattice.** R draws this surface with
+ * `lattice::wireframe(drape = TRUE, colorkey = FALSE)`, which colors the mesh
+ * by height and hides the key. A Plotly surface is colored by height already,
+ * so the port sets `showscale: false` and keeps the rest. The colors
+ * themselves are Plotly's, not lattice's: a browser has no lattice palette,
+ * and the teaching point of the picture is the twist of the surface, not its
+ * hue.
+ *
+ * **The rotation arguments become a camera, approximately.** Lattice takes
+ * `screen = list(z = z_rot, x = x_rot)`, two rotations of the data. Plotly
+ * takes a camera position. `cameraFromRotations` maps one onto the other, and
+ * says how.
+ *
+ * **The vertical axis carries the outcome.** With the bundled data the
+ * moderator is named `z` and it is drawn on a horizontal axis, while the
+ * outcome `y` stands up. R's help makes the same point, twice.
+ */
+import type { ModerationOptions, ModerationSurface } from "../core/moderation";
+import type { DataFrame } from "../core/frame";
+import type { EyeCamera, PlotlyHTMLElement, PlotlyLayout, PlotlyLike, SurfaceTrace } from "./plotly";
+/** How to look at the surface. */
+export interface Moderation3dViewOptions {
+    /**
+     * The turn about the vertical axis, in degrees. R's `z_rot`, 40 by default.
+     * 0 lays the IV across the screen; 270 lays the moderator across it.
+     */
+    readonly zRot?: number;
+    /**
+     * The tilt, in degrees. R's `x_rot`, −70 by default. −90 looks along the
+     * floor of the plot, and the view rises towards 0.
+     */
+    readonly xRot?: number;
+    /**
+     * The values the vertical axis spans, as `[low, high]`. The range of the
+     * data together with the range of the surface by default, which is R's own
+     * rule and what `moderationSurface` reports as `zlim`.
+     */
+    readonly zlim?: readonly [number, number];
+}
+/** The options of `plotModeration3d`: the model, the view, and the engine. */
+export interface PlotModeration3dOptions extends ModerationOptions, Moderation3dViewOptions {
+    /**
+     * The Plotly engine. `loadPlotly()` by default, which fetches the library on
+     * first use.
+     */
+    readonly plotly?: PlotlyLike;
+}
+/** What a surface and a set of view options draw. */
+export interface Moderation3dSpec {
+    /** The one height field. */
+    readonly traces: readonly SurfaceTrace[];
+    readonly layout: PlotlyLayout;
+    /**
+     * What R says in its `message()` when predictors are held off the axes.
+     * Null when every predictor of the model is drawn.
+     */
+    readonly note: string | null;
+}
+/** A drawn surface: its specification, its fit, its element, and its engine. */
+export interface Moderation3dHandle extends Moderation3dSpec {
+    /** The element Plotly drew into, with its event emitter attached. */
+    readonly element: PlotlyHTMLElement;
+    /** The engine that drew, ready for the next redraw and for teardown. */
+    readonly plotly: PlotlyLike;
+    /** The fit and the grid behind the picture. */
+    readonly surface: ModerationSurface;
+}
+/**
+ * Place the camera for a pair of lattice rotations.
+ *
+ * This is a visual approximation, not an equivalence: lattice rotates the data
+ * and Plotly moves the camera, and the two pictures agree in direction, not
+ * pixel for pixel. The mapping is
+ *
+ * ```text
+ * azimuth   = -90 - zRot degrees
+ * elevation =  90 + xRot degrees
+ * eye       = distance * (cos elevation * cos azimuth,
+ *                         cos elevation * sin azimuth,
+ *                         sin elevation)
+ * ```
+ *
+ * Both anchors of R's own help hold under it. At `zRot = 0` the camera stands
+ * on the moderator axis, so the IV runs across the screen and the IV slope
+ * plane faces the viewer; at `zRot = 270` the camera stands on the IV axis and
+ * the moderator plane faces it. The tilt reads the same way as lattice's: at
+ * `xRot = -90` the camera is level with the floor of the plot, and R's default
+ * −70 lifts it 20 degrees above it.
+ *
+ * @param zRot The turn about the vertical axis, in degrees.
+ * @param xRot The tilt, in degrees.
+ * @returns The camera, as Plotly's `scene.camera`.
+ * @throws RangeError If either angle is not a finite number, which would
+ *   place the camera nowhere.
+ */
+export declare function cameraFromRotations(zRot: number, xRot: number): EyeCamera;
+/**
+ * Build the trace and the layout of a moderation surface.
+ *
+ * @param surface The fit and the grid, from `moderationSurface`.
+ * @param model The columns the surface was fitted over. Their names title the
+ *   axes, and the controls decide whether there is a note.
+ * @param view How to look at the surface.
+ * @returns The trace, the layout, and the note about held predictors.
+ * @throws RangeError If a rotation is not finite, if a given vertical range is
+ *   not two finite numbers, or if any height of the surface is not finite —
+ *   a non-finite height would crash the WebGL engine for the whole page.
+ */
+export declare function moderation3dSpec(surface: ModerationSurface, model: ModerationOptions, view?: Moderation3dViewOptions): Moderation3dSpec;
+/**
+ * Fit the model and draw its surface.
+ *
+ * @param target The element to draw into. Plotly fills it.
+ * @param data The frame holding every column the model names.
+ * @param options The model, the view, and the engine.
+ * @returns The drawn plot: its element, its specification, its engine, and the
+ *   surface behind it.
+ * @throws RangeError Everything `moderationSurface` and `moderation3dSpec`
+ *   throw, as a rejected promise. Nothing reaches the engine until the model
+ *   is fitted and the view is settled.
+ */
+export declare function plotModeration3d(target: HTMLElement, data: DataFrame, options: PlotModeration3dOptions): Promise<Moderation3dHandle>;
+//# sourceMappingURL=moderation3d.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"moderation3d.d.ts","sourceRoot":"","sources":["../../src/plot/moderation3d.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAGH,OAAO,KAAK,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAC/E,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAE/C,OAAO,KAAK,EACV,SAAS,EACT,iBAAiB,EACjB,YAAY,EACZ,UAAU,EACV,YAAY,EAEb,MAAM,UAAU,CAAC;AAiBlB,kCAAkC;AAClC,MAAM,WAAW,uBAAuB;IACtC;;;OAGG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB;;;;OAIG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC3C;AAED,8EAA8E;AAC9E,MAAM,WAAW,uBACf,SAAQ,iBAAiB,EACvB,uBAAuB;IACzB;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,UAAU,CAAC;CAC9B;AAED,qDAAqD;AACrD,MAAM,WAAW,gBAAgB;IAC/B,4BAA4B;IAC5B,QAAQ,CAAC,MAAM,EAAE,SAAS,YAAY,EAAE,CAAC;IACzC,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B;;;OAGG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B;AAED,gFAAgF;AAChF,MAAM,WAAW,kBAAmB,SAAQ,gBAAgB;IAC1D,qEAAqE;IACrE,QAAQ,CAAC,OAAO,EAAE,iBAAiB,CAAC;IACpC,wEAAwE;IACxE,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,+CAA+C;IAC/C,QAAQ,CAAC,OAAO,EAAE,iBAAiB,CAAC;CACrC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,SAAS,CAczE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,iBAAiB,EAC1B,KAAK,EAAE,iBAAiB,EACxB,IAAI,GAAE,uBAA4B,GACjC,gBAAgB,CAqDlB;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,gBAAgB,CACpC,MAAM,EAAE,WAAW,EACnB,IAAI,EAAE,SAAS,EACf,OAAO,EAAE,uBAAuB,GAC/B,OAAO,CAAC,kBAAkB,CAAC,CAQ7B"}

package/dist/plot/pca.d.ts

@@ -0,0 +1,79 @@
+/**
+ * The PCA plot: the points, and an arrow along each principal component.
+ *
+ * This is the drawing half of `plot_pca()` in `../compstatslib/R/pca_plot.R`.
+ * Every number it draws comes from `principalComponents` in
+ * `src/core/pca.ts`; this module computes no statistics of its own.
+ *
+ * Two things here differ from every earlier plot in this port.
+ *
+ * **The window keeps equal units on both axes.** R's call passes `asp = 1`,
+ * which makes a right angle on the data look like a right angle on screen —
+ * the whole point of a picture about perpendicular components. R holds the
+ * limits it was given on whichever axis constrains the fit and widens the
+ * other about its middle; `pcaScale` does the same. Measured from R on a null
+ * device with `xlim = ylim = c(-50, 50)`: a 10 by 5 inch device reports
+ * `par("usr")` of `-149.696 149.696 -54 54`, and a 5 by 10 inch device
+ * reports `-54 54 -117.191 117.191`.
+ *
+ * **Mean-centering is not a statistical option.** It moves the arrows'
+ * anchor and nothing else. The components are the same either way, because
+ * R's `prcomp` centers internally whatever it is handed (fixture F7 shows the
+ * two runs agreeing bit for bit), and the points on screen are the raw ones —
+ * R plots `points`, not `mc_points`.
+ */
+import type { PcaResult } from "../core/pca";
+import type { Point } from "../core/regression";
+import type { Scale } from "./axes";
+import type { PlotTarget } from "./target";
+/** R's `plot_pca()` arguments, less the points. */
+export interface PlotPcaOptions {
+    /**
+     * Anchor the arrows on the middle of the data. True by default, as in R.
+     *
+     * False anchors them on the origin instead. Nothing else changes: not the
+     * components, not the points, only where the arrows are drawn.
+     */
+    readonly meancenter?: boolean;
+    /** The x limits, R's `xlim`. Both default to R's `c(-50, 50)`. */
+    readonly xlim?: readonly [number, number];
+    /** The y limits, R's `ylim`. */
+    readonly ylim?: readonly [number, number];
+}
+/**
+ * Build the scale that `plotPca` draws through, with equal units per pixel.
+ *
+ * The interactive layer needs this to turn a click into a world coordinate.
+ * It reads the scale from here so the window rule stays in one place.
+ *
+ * Both requested ranges are honoured or widened, never narrowed: the axis
+ * that needs the most world per pixel keeps its limits, and the other grows
+ * about its middle until the two agree. Unlike R, the constraining axis keeps
+ * the literal limits it was given — R would pad them by 4% first, and this
+ * port drops that padding everywhere.
+ *
+ * @param width The pixel width of the surface.
+ * @param height The pixel height of the surface.
+ * @param options The limits. A reversed pair reads as the range it spans, not
+ *   as a flipped axis.
+ * @returns The map between world values and pixels.
+ */
+export declare function pcaScale(width: number, height: number, options?: PlotPcaOptions): Scale;
+/**
+ * Draw the points and the arrows along their principal components.
+ *
+ * R guards this drawing at three sizes, and so does this. With no points it
+ * draws an empty pair of axes. Below three points it draws the points alone:
+ * two points always lie on a line, so the second component would be an arrow
+ * of no length and the first would say only what the eye already sees. The
+ * core will answer for one or two points; this asks it only from three, which
+ * is R's own `nrow(points) >= 3`.
+ *
+ * @param target A canvas, or a context and a size. See `./target.ts`.
+ * @param points The observations, in world coordinates.
+ * @param options The anchor and the window.
+ * @returns The components drawn, or null below three points. R returns the
+ *   same `prcomp` result, invisibly, and NULL at the same two guards.
+ */
+export declare function plotPca(target: PlotTarget, points: readonly Point[], options?: PlotPcaOptions): PcaResult | null;
+//# sourceMappingURL=pca.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"pca.d.ts","sourceRoot":"","sources":["../../src/plot/pca.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAEhD,OAAO,KAAK,EAAU,KAAK,EAAE,MAAM,QAAQ,CAAC;AAG5C,OAAO,KAAK,EAAa,UAAU,EAAE,MAAM,UAAU,CAAC;AAEtD,mDAAmD;AACnD,MAAM,WAAW,cAAc;IAC7B;;;;;OAKG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC;IAC9B,kEAAkE;IAClE,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC1C,gCAAgC;IAChC,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC3C;AAaD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,QAAQ,CACtB,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,cAAmB,GAC3B,KAAK,CAuBP;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,OAAO,CACrB,MAAM,EAAE,UAAU,EAClB,MAAM,EAAE,SAAS,KAAK,EAAE,EACxB,OAAO,GAAE,cAAmB,GAC3B,SAAS,GAAG,IAAI,CA+BlB"}

package/dist/plot/plotly.d.ts

@@ -0,0 +1,209 @@
+/**
+ * The seam between this library and Plotly.js.
+ *
+ * The two 3D plots of the R package are drawn by Plotly (`plot_scatter3d()`)
+ * and by lattice (`plot_moderation_3d()`). In a browser there is one sensible
+ * engine for both, and the R package already chose it for the scatterplot, so
+ * both 3D plots of this port draw through Plotly.
+ *
+ * Plotly is four megabytes of code. Three rules keep that weight off everyone
+ * who does not draw in three dimensions.
+ *
+ * 1. **The 2D entry never names it.** The 3D plots live behind their own entry
+ *    point, `src/3d.ts`, which the package exports as `compstatslib/3d`.
+ * 2. **The 3D entry does not carry it either.** `loadPlotly()` reaches the
+ *    library through a dynamic `import`, which a bundler keeps in a chunk of
+ *    its own and a browser fetches only when a plot is drawn.
+ * 3. **The engine is an argument.** Both plot functions take a `plotly`
+ *    option. The tests pass a recorder (`test/recording-plotly.ts`) and never
+ *    load Plotly at all: happy-dom has no WebGL, and the work this port does
+ *    is the trace and the layout it builds, not the picture Plotly makes.
+ *
+ * `PlotlyLike` lists the exact calls the port makes, in the manner of
+ * `Context2D` in `./target.ts`. The real library satisfies it, and so does
+ * any object with those two methods.
+ *
+ * The trace and layout types below are equally narrow. They describe the
+ * fields this port sets, not the several hundred Plotly accepts.
+ */
+/** A point in three dimensions, as Plotly writes one. */
+export interface Vector3 {
+    readonly x: number;
+    readonly y: number;
+    readonly z: number;
+}
+/**
+ * Where the camera stands, where it looks, and which way is up. Plotly's
+ * `scene.camera`. Every part is optional: Plotly supplies its own.
+ */
+export interface PlotlyCamera {
+    readonly eye?: Vector3;
+    readonly center?: Vector3;
+    readonly up?: Vector3;
+}
+/**
+ * A camera whose position is known. `cameraFromRotations` returns one, so a
+ * caller can read the eye without asking whether it is there.
+ */
+export interface EyeCamera extends PlotlyCamera {
+    readonly eye: Vector3;
+}
+/** How the markers of a 3D scatterplot are drawn. */
+export interface Scatter3dMarker {
+    /** R's `opacity`, in (0, 1]. */
+    readonly opacity: number;
+    /** R's `size`, in pixels. */
+    readonly size: number;
+    /** One value per point, when a numeric column drives the color. */
+    readonly color?: readonly number[];
+    /** The scale those values are read through. */
+    readonly colorscale?: string;
+    /** Whether the scale is drawn beside the plot as a color bar. */
+    readonly showscale?: boolean;
+}
+/** A cloud of points. */
+export interface Scatter3dTrace {
+    readonly type: "scatter3d";
+    readonly mode: "markers";
+    readonly x: readonly number[];
+    readonly y: readonly number[];
+    readonly z: readonly number[];
+    readonly marker: Scatter3dMarker;
+    /** The level this trace holds, when a categorical column splits the data. */
+    readonly name?: string;
+    /** Whether the level is listed in the legend. */
+    readonly showlegend?: boolean;
+}
+/**
+ * A height field.
+ *
+ * `z[j][i]` is the height above `x[i]` and `y[j]` — the row index runs along
+ * `y`, which is why the moderation plot writes the moderator into the rows.
+ */
+export interface SurfaceTrace {
+    readonly type: "surface";
+    readonly x: readonly number[];
+    readonly y: readonly number[];
+    readonly z: readonly (readonly number[])[];
+    /** Whether the height scale is drawn beside the plot. */
+    readonly showscale: boolean;
+}
+/** Anything this port draws. */
+export type PlotlyTrace = Scatter3dTrace | SurfaceTrace;
+/** One axis of a 3D scene. */
+export interface PlotlyAxis {
+    /**
+     * The axis label, in Plotly's object form. Plotly v2 silently drops a
+     * bare-string title, so the type refuses the shorthand that would compile
+     * and then show nothing.
+     */
+    readonly title: {
+        readonly text: string;
+    };
+    /**
+     * The values the axis spans, as `[low, high]`. Plotly fits the data when
+     * the range is absent.
+     */
+    readonly range?: readonly [number, number];
+}
+/** The 3D scene: three axes, the shape of the box, and the camera. */
+export interface PlotlyScene {
+    /** `"manual"` reads the ratio below. The others are Plotly's own rules. */
+    readonly aspectmode?: "auto" | "cube" | "data" | "manual";
+    readonly aspectratio?: Vector3;
+    readonly xaxis: PlotlyAxis;
+    readonly yaxis: PlotlyAxis;
+    readonly zaxis: PlotlyAxis;
+    /**
+     * A name for the view. Plotly keeps the rotation and the zoom across a
+     * redraw while this string does not change, which is how a slider can
+     * rebuild the plot without throwing away the angle the user chose.
+     */
+    readonly uirevision?: string;
+    readonly camera?: PlotlyCamera;
+}
+/** The layout of a 3D plot. */
+export interface PlotlyLayout {
+    readonly uirevision: string;
+    readonly scene: PlotlyScene;
+}
+/** The behavior of the plot, as opposed to its content. */
+export interface PlotlyConfig {
+    /** Whether the plot follows the size of the element that holds it. */
+    readonly responsive?: boolean;
+}
+/**
+ * What Plotly reports after the user moves the plot.
+ *
+ * The camera arrives under the key `scene.camera`, which is a path, not a
+ * nested object. The other keys depend on what moved.
+ */
+export interface PlotlyRelayoutEvent {
+    readonly "scene.camera"?: PlotlyCamera;
+    readonly [key: string]: unknown;
+}
+/**
+ * A change pushed at a plot that is already drawn.
+ *
+ * Plotly's `relayout` takes the layout attribute by its path, so the camera
+ * arrives under the same `scene.camera` key it is reported under.
+ */
+export interface PlotlyRelayoutUpdate {
+    readonly "scene.camera"?: PlotlyCamera;
+}
+/**
+ * The element Plotly hands back after it has drawn.
+ *
+ * Plotly adds an event emitter to that element, which is the only way to learn
+ * that the user rotated the plot.
+ */
+export interface PlotlyHTMLElement extends HTMLElement {
+    on(event: "plotly_relayout", handler: (event: PlotlyRelayoutEvent) => void): void;
+    removeAllListeners(event: string): void;
+}
+/**
+ * The part of Plotly this library calls.
+ *
+ * `react` both draws and updates: on an empty element it builds the plot, and
+ * on one that already holds a plot it changes only what differs.
+ *
+ * `relayout` exists for one case that `react` cannot serve. The layouts of
+ * this port carry a constant `uirevision`, which is what keeps a user's own
+ * rotation across a redraw; Plotly honours that literally, so once the user
+ * has dragged the plot, a `react` carrying a different `scene.camera` is
+ * ignored. The rotation sliders of the moderation surface would then move
+ * nothing. `relayout` is an instruction rather than a preference, so it moves
+ * the camera whatever the user did before, and it is called only when a
+ * slider asks for a view the plot is not already at.
+ */
+export interface PlotlyLike {
+    react(element: HTMLElement, data: readonly PlotlyTrace[], layout: PlotlyLayout, config?: PlotlyConfig): Promise<PlotlyHTMLElement>;
+    /** Change one part of the layout of a plot that is already drawn. */
+    relayout(element: HTMLElement, update: PlotlyRelayoutUpdate): Promise<PlotlyHTMLElement>;
+    /** Remove the plot, and everything it attached to the element. */
+    purge(element: HTMLElement): void;
+}
+/**
+ * Whether two cameras stand at the same view.
+ *
+ * The interactive components write a camera the user dragged to back into the
+ * live layout, and the `relayout` that does so fires `plotly_relayout` again
+ * with the same camera as a fresh object. Comparing by value is what lets the
+ * capture handlers recognize that echo and stop, so this must never be
+ * replaced with a reference comparison.
+ *
+ * @param a One camera, or nothing.
+ * @param b The other, or nothing.
+ * @returns True when both are absent, or both present with equal parts.
+ */
+export declare function sameCamera(a: PlotlyCamera | undefined, b: PlotlyCamera | undefined): boolean;
+/**
+ * Load Plotly.js.
+ *
+ * The library is fetched once. Every later call gets the same promise, so two
+ * plots on one page load one copy.
+ *
+ * @returns The library, narrowed to the calls this port makes.
+ */
+export declare function loadPlotly(): Promise<PlotlyLike>;
+//# sourceMappingURL=plotly.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"plotly.d.ts","sourceRoot":"","sources":["../../src/plot/plotly.ts"],"names":[],"mappings":"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"}

package/dist/plot/regression.d.ts

@@ -0,0 +1,52 @@
+/**
+ * The regression plot: points, the mean crosshair, the fitted line, and a
+ * block of statistics.
+ *
+ * This is the drawing half of `plot_regression()` in
+ * `../compstatslib/R/regression_plot.R`. Every number it draws comes from
+ * `linearRegression` in `src/core/regression.ts`; this module computes no
+ * statistics of its own.
+ */
+import type { Point, RegressionFit } from "../core/regression";
+import type { Scale } from "./axes";
+import type { PlotTarget } from "./target";
+/** What to show, and where. The toggles default to true, as in R. */
+export interface PlotRegressionOptions {
+    /** Draw the mean crosshair and the fitted line. */
+    readonly regression?: boolean;
+    /** List the statistics at the top left. Needs `regression`. */
+    readonly stats?: boolean;
+    /** The x limits, R's `xlim`. Both default to R's `c(-5, 50)`. */
+    readonly xlim?: readonly [number, number];
+    /** The y limits, R's `ylim`. */
+    readonly ylim?: readonly [number, number];
+}
+/**
+ * Build the scale that `plotRegression` draws through.
+ *
+ * The interactive layer needs this to turn a click into a world coordinate.
+ * It reads the scale from here so that the world 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 options The limits. A reversed pair reads as the range it spans, not
+ *   as a flipped axis. Omitted limits keep the R teaching window.
+ * @returns The map between world values and pixels.
+ */
+export declare function regressionScale(width: number, height: number, options?: PlotRegressionOptions): Scale;
+/**
+ * Draw the points and their regression.
+ *
+ * With no points, the function draws empty axes. With one point, it draws the
+ * point alone, because a single point has no line to fit. R stops at the same
+ * two places.
+ *
+ * @param target A canvas, or a context and a size. See `./target.ts`.
+ * @param points The observations, in world coordinates.
+ * @param options What to show.
+ * @returns The fit that the plot drew, or null if there are no points. R
+ * returns the points instead, which the caller already holds.
+ */
+export declare function plotRegression(target: PlotTarget, points: readonly Point[], options?: PlotRegressionOptions): RegressionFit | null;
+//# sourceMappingURL=regression.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"regression.d.ts","sourceRoot":"","sources":["../../src/plot/regression.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,KAAK,EAAE,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAG/D,OAAO,KAAK,EAAU,KAAK,EAAE,MAAM,QAAQ,CAAC;AAG5C,OAAO,KAAK,EAAa,UAAU,EAAE,MAAM,UAAU,CAAC;AAEtD,qEAAqE;AACrE,MAAM,WAAW,qBAAqB;IACpC,mDAAmD;IACnD,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC;IAC9B,+DAA+D;IAC/D,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IACzB,iEAAiE;IACjE,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC1C,gCAAgC;IAChC,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC3C;AAaD;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,qBAA0B,GAClC,KAAK,CAOP;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,UAAU,EAClB,MAAM,EAAE,SAAS,KAAK,EAAE,EACxB,OAAO,GAAE,qBAA0B,GAClC,aAAa,GAAG,IAAI,CA2BtB"}

package/dist/plot/sampleCi.d.ts

@@ -0,0 +1,82 @@
+/**
+ * One row per sample, each showing what that sample says about the mean it
+ * came from — the drawing half of `plot_sample_ci()` in
+ * `../compstatslib/R/sample_ci_plot.R`.
+ *
+ * The population is simulated, so its mean is known and drawn as a vertical
+ * line. Each sample gets a row: a wide 99% interval, a 95% interval over it,
+ * and a diamond at the sample mean. Rows whose intervals miss the true mean
+ * are drawn again in coral over the blue, which is the whole lesson of the
+ * picture — at 95% confidence, about one row in twenty should miss.
+ *
+ * Drawing order is faithful to R and is not incidental. R draws every row in
+ * the good colors, then draws the missing ones again on top, then the mean
+ * line last:
+ *
+ * ```r
+ * segments_ci(..., good = TRUE)              # every row, skyblue
+ * segments_ci(...[bad], bad, good = FALSE)   # the misses again, coral
+ * abline(v = mean(population_data))
+ * ```
+ *
+ * Within one of those calls R works in three vectorised passes — every 99%
+ * span, then every 95% span, then every point — rather than finishing a row
+ * at a time. This does the same, so overlapping neighbours stack as they do
+ * in R.
+ *
+ * The statistics all come from `simulateSampleCi` in `src/core/sampling.ts`;
+ * this module computes none of its own.
+ */
+import type { Rng } from "../core/rng";
+import type { SampleCiOptions, SampleCiSimulation } from "../core/sampling";
+import type { Scale } from "./axes";
+import type { PlotTarget } from "./target";
+/** What to draw. R's `plot_sample_ci()` arguments, plus the generator. */
+export interface PlotSampleCiOptions extends SampleCiOptions {
+    /**
+     * Where the randomness comes from.
+     *
+     * One call draws one picture, so unlike the sampling plot there is nothing
+     * to carry between calls and the default is harmless. It is still built the
+     * same way — a stream seeded once from `Math.random()` — so a page that
+     * says nothing about seeds gets a fresh picture each time, and
+     * `seededRng(42)` repeats one exactly.
+     */
+    readonly rng?: Rng;
+}
+/**
+ * Build the scale the plot draws through.
+ *
+ * The window is R's: half a standard deviation of the population each side of
+ * its mean, which is deliberately too narrow to hold every interval — the
+ * ones that run off the edge are the interesting ones. Rows count upward from
+ * one, so the first sample sits at the foot of the panel.
+ *
+ * A population with no spread leaves the width undefined. R stops there, on
+ * a non-finite `xlim`. This opens a unit window around the mean instead, so
+ * the frame and its axes still draw.
+ *
+ * @param width The pixel width of the surface.
+ * @param height The pixel height of the surface.
+ * @param simulation What `simulateSampleCi` returned.
+ * @returns The map between world values and pixels.
+ */
+export declare function sampleCiScale(width: number, height: number, simulation: SampleCiSimulation): Scale;
+/**
+ * Simulate a population, sample it, and draw what each sample says.
+ *
+ * A sample too small to have a spread gives an interval of NaN, which R would
+ * report as NA. Such a row is left undrawn rather than turned into a shape at
+ * a meaningless coordinate; the row still appears in the returned simulation,
+ * where the caller can see the NaN for what it is.
+ *
+ * @param target A canvas, or a context and a size. See `./target.ts`.
+ * @param options The sizes, the population's distribution, and the generator.
+ * @returns The simulation drawn — the population's mean and spread, and every
+ *   sample's interval — so a caller need not run it again to read it.
+ * @throws RangeError If the sample size is larger than the population, or a
+ *   count is negative or fractional. Both come from the core, which is where
+ *   R's own refusals live.
+ */
+export declare function plotSampleCi(target: PlotTarget, options?: PlotSampleCiOptions): SampleCiSimulation;
+//# sourceMappingURL=sampleCi.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sampleCi.d.ts","sourceRoot":"","sources":["../../src/plot/sampleCi.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,aAAa,CAAC;AAGvC,OAAO,KAAK,EACV,eAAe,EACf,kBAAkB,EAEnB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,QAAQ,CAAC;AAGpC,OAAO,KAAK,EAAa,UAAU,EAAE,MAAM,UAAU,CAAC;AAEtD,0EAA0E;AAC1E,MAAM,WAAW,mBAAoB,SAAQ,eAAe;IAC1D;;;;;;;;OAQG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE,GAAG,CAAC;CACpB;AAmCD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,aAAa,CAC3B,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,kBAAkB,GAC7B,KAAK,CAcP;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,YAAY,CAC1B,MAAM,EAAE,UAAU,EAClB,OAAO,GAAE,mBAAwB,GAChC,kBAAkB,CAqCpB"}