@compstats/core 0.2.0

package/dist/core/frame.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Column-keyed data frames, and the checks R gets for free.
+ *
+ * The 3D functions of the R package take an R data frame, which guarantees
+ * two things a JavaScript object does not: every column holds one type, and
+ * every column has the same length. `moderation.ts` and the scatter3d module
+ * both need those guarantees, so the questions are asked in one place and
+ * answered the same way for both.
+ *
+ * The port follows `../compstatslib/R/scatter3d_helpers.R`:
+ *
+ * ```r
+ * scatter3d_numeric_cols <- function(data) {
+ *   names(data)[vapply(data, is.numeric, logical(1))]
+ * }
+ * ```
+ *
+ * with two departures, both forced by the language and both pinned by tests.
+ * R reads a vector's declared type, so `is.numeric(numeric(0))` is TRUE and a
+ * column of mixed types cannot exist. A JavaScript array declares nothing, so
+ * this module reads the values: **a column is numeric when it holds at least
+ * one value and every value is a number.** An empty column therefore is not
+ * numeric — it offers no evidence either way, and an empty axis draws nothing
+ * — and a column of numbers with one string in it is not numeric either,
+ * because fitting it would give `NaN` for every coefficient.
+ */
+/**
+ * One column of a data frame.
+ *
+ * Numeric columns carry the statistics. The other two types are here because
+ * `plot_scatter3d()` accepts a categorical column for `color`, which R allows
+ * to be a factor, a character vector, or a logical vector.
+ */
+export type Column = readonly number[] | readonly string[] | readonly boolean[];
+/**
+ * A data frame: named columns of equal length.
+ *
+ * The equal length is a rule, not a type. `frameRows` enforces it.
+ */
+export type DataFrame = {
+    readonly [name: string]: Column;
+};
+/**
+ * Report whether a column holds numbers, and narrow it when it does.
+ *
+ * @param column The column to inspect.
+ * @returns True when the column has at least one value and every value is a
+ *   number. `NaN` counts as a number, as R's missing values do.
+ */
+export declare function isNumericColumn(column: Column): column is readonly number[];
+/**
+ * Name the numeric columns, in the order the frame declares them.
+ *
+ * This is R's `scatter3d_numeric_cols()`. The order matters: the scatter3d
+ * default takes the first three names this returns.
+ *
+ * @param data The frame to inspect.
+ * @returns The names of the numeric columns, in insertion order.
+ */
+export declare function numericColumns(data: DataFrame): string[];
+/**
+ * Refuse a frame that cannot fill three numeric axes.
+ *
+ * This is R's `scatter3d_require_3_numeric()`, which both the plot and the
+ * gadget call with their own name, so that the message says which function
+ * the caller reached.
+ *
+ * @param numeric The numeric column names, from `numericColumns`.
+ * @param caller The name to print, such as `plotScatter3d`.
+ * @throws RangeError If fewer than three names were given.
+ */
+export declare function requireThreeNumericColumns(numeric: readonly string[], caller: string): void;
+/**
+ * Return the number of rows, and refuse a frame that has no single answer.
+ *
+ * @param data The frame to measure.
+ * @returns The shared length of the columns. A frame with no columns has no
+ *   rows.
+ * @throws RangeError If two columns have different lengths. An R data frame
+ *   cannot be built that way, so nothing downstream is written to survive it.
+ */
+export declare function frameRows(data: DataFrame): number;
+/**
+ * Read one numeric column, or explain why it cannot be used.
+ *
+ * The wording follows R's own, which names both the column and the argument
+ * it arrived through: `Column "b" (passed as \`x\`) is not in \`data\`.`
+ *
+ * @param data The frame to read.
+ * @param name The column name the caller asked for.
+ * @param role The option that carried the name, such as `iv` or `mod`. It
+ *   appears in the error, so the caller learns which argument is wrong.
+ * @returns The column.
+ * @throws RangeError If the frame has no such column, or the column is not
+ *   numeric.
+ */
+export declare function requireNumericColumn(data: DataFrame, name: string, role: string): readonly number[];
+//# sourceMappingURL=frame.d.ts.map

package/dist/core/frame.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"frame.d.ts","sourceRoot":"","sources":["../../src/core/frame.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH;;;;;;GAMG;AACH,MAAM,MAAM,MAAM,GAAG,SAAS,MAAM,EAAE,GAAG,SAAS,MAAM,EAAE,GAAG,SAAS,OAAO,EAAE,CAAC;AAEhF;;;;GAIG;AACH,MAAM,MAAM,SAAS,GAAG;IAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAAA;CAAE,CAAC;AAE5D;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,IAAI,SAAS,MAAM,EAAE,CAE3E;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,EAAE,CAIxD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,SAAS,MAAM,EAAE,EAC1B,MAAM,EAAE,MAAM,GACb,IAAI,CAON;AAED;;;;;;;;GAQG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,CAiBjD;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,SAAS,EACf,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,GACX,SAAS,MAAM,EAAE,CAenB"}

package/dist/core/histogram.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Counts of values per cell — R's `hist(plot = FALSE)` with its defaults.
+ *
+ * `plot_sampling()` draws its third panel from this: it accumulates one
+ * statistic per sample and calls `hist()` on the running collection, then
+ * reads `counts` back to place the panel's label. Verified against R 4.5.3 in
+ * `histogram.test.ts`.
+ *
+ * Three rules carry the behavior, and each one is easy to get subtly wrong:
+ *
+ * 1. **How many cells.** Sturges' rule, `ceiling(log2(n) + 1)`, is only a
+ *    suggestion. It goes to `rPretty`, which returns round edges covering the
+ *    data — often a different count.
+ * 2. **Which cell a value belongs to.** Cells are closed on the right,
+ *    `(edge[k], edge[k+1]]`, so a value sitting on an edge counts into the
+ *    cell below it. The lowest edge is the exception: nothing sits below it,
+ *    so it is opened to admit the smallest value.
+ * 3. **Values that land on an edge.** Rounding leaves a value that ought to
+ *    sit on an edge a hair to one side of it. R nudges the edges by a
+ *    millionth of a cell before counting — outward at the bottom, upward
+ *    everywhere else — so such a value still lands where it belongs. The
+ *    reported edges are the unnudged ones.
+ */
+/** What the caller may change. R's drawing arguments are not ported. */
+export interface HistogramOptions {
+    /**
+     * How to place the cell edges.
+     *
+     * A number asks for about that many cells, which `rPretty` rounds off; an
+     * array gives the edges outright. The default is Sturges' rule. R takes the
+     * same two forms in one argument, but cannot tell a one-edge array from a
+     * request for one cell — this port reads an array as edges, always.
+     */
+    readonly breaks?: number | readonly number[];
+}
+/** The counted histogram, in the shape of R's `histogram` object. */
+export interface Histogram {
+    /** The cell edges, in increasing order. One more than there are cells. */
+    readonly breaks: readonly number[];
+    /** How many values fell in each cell. */
+    readonly counts: readonly number[];
+    /** The midpoint of each cell, R's `mids`. */
+    readonly mids: readonly number[];
+}
+/**
+ * Suggest a cell count by Sturges' rule — R's `nclass.Sturges`.
+ *
+ * @param values The observations. Only how many there are matters.
+ * @returns `ceiling(log2(n) + 1)`, or -Infinity for no values. R returns -Inf
+ *   there too, which is what makes its `hist()` stop.
+ */
+export declare function nclassSturges(values: readonly number[]): number;
+/**
+ * Count the values into cells.
+ *
+ * Values that are not finite are dropped first, as R does — including NaN,
+ * which R reads as a missing value and drops here. Note the difference from
+ * `kernelDensity`, which refuses NaN, because R's `density()` refuses it.
+ *
+ * @param values The observations.
+ * @param options How to place the cell edges.
+ * @returns The edges, the count in each cell, and the cell midpoints.
+ * @throws RangeError If no value is finite, if a requested cell count is
+ *   below one or fractional, if fewer than two edges are given, or if the
+ *   given edges leave a value uncounted. R stops in all of those cases too.
+ */
+export declare function histogram(values: readonly number[], options?: HistogramOptions): Histogram;
+//# sourceMappingURL=histogram.d.ts.map

package/dist/core/histogram.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"histogram.d.ts","sourceRoot":"","sources":["../../src/core/histogram.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAQH,wEAAwE;AACxE,MAAM,WAAW,gBAAgB;IAC/B;;;;;;;OAOG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAAC;CAC9C;AAED,qEAAqE;AACrE,MAAM,WAAW,SAAS;IACxB,0EAA0E;IAC1E,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,yCAAyC;IACzC,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,6CAA6C;IAC7C,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;CAClC;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAE/D;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,SAAS,CACvB,MAAM,EAAE,SAAS,MAAM,EAAE,EACzB,OAAO,GAAE,gBAAqB,GAC7B,SAAS,CA2BX"}

package/dist/core/kde.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Gaussian kernel density estimate — R's `density()` with its defaults.
+ *
+ * `plot_sampling()` in the R package draws two of these panels: one over the
+ * population and one over the pooled samples. Both calls are `density(x)` with
+ * no other argument, so this module ports that default path: the Gaussian
+ * kernel, the `nrd0` bandwidth, a 512-point output grid, `cut = 3`, and
+ * `ext = 4`. It also ports R's `from` and `to` arguments, which freeze the
+ * ends of the reported window — the sampling plot uses them to keep one axis
+ * across redraws. Verified against R 4.5.3 in `kde.test.ts`.
+ *
+ * The estimate is a convolution, and R computes it with an FFT rather than by
+ * summing a kernel over every point. This port copies that: the cost is
+ * linear in the count of values plus a fixed 1024-point transform, so pooling
+ * a million sampled values stays fast. The steps, in R's own order:
+ *
+ * 1. Pick the bandwidth with `bwNrd0`.
+ * 2. Set the reported window to `range(x) ± 3 * bw` (`cut = 3`), and the
+ *    wider working window to `range(x) ± 7 * bw` (a further `ext = 4`).
+ * 3. Spread the mass of the values over 512 equally spaced points of the
+ *    working window, splitting each value between its two neighbors.
+ * 4. Convolve that with a Gaussian of standard deviation `bw`, using a
+ *    1024-point FFT, and clamp negative rounding noise to zero.
+ * 5. Interpolate the result back onto the reported window.
+ *
+ * The two windows are different widths and must not be confused. A port that
+ * runs the FFT over the reported window gives a visibly narrower curve.
+ */
+/** What the caller may change. R's other arguments are not ported. */
+export interface KernelDensityOptions {
+    /**
+     * The bandwidth, the standard deviation of the kernel.
+     *
+     * The default is `bwNrd0(values)`, R's `bw = "nrd0"`. Giving the bandwidth
+     * skips that selection, and with it the rule that the selection needs two
+     * values — R does the same.
+     */
+    readonly bw?: number;
+    /**
+     * The low end of the reported window, R's `from`.
+     *
+     * The default is `min(x) - 3 * bw`, R's `cut = 3`. The working window still
+     * reaches 4 bandwidths further out, and `binDist` drops the mass beyond it,
+     * as R's `BinDist` does. So a window narrower than the data cuts the tails
+     * off, and a wider one pads the curve with near-zero density — the frozen
+     * axis the sampling plot needs across redraws.
+     */
+    readonly from?: number;
+    /** The high end of the reported window, R's `to`. Same rules as `from`. */
+    readonly to?: number;
+}
+/** The curve, in the shape of R's `density` object. */
+export interface KernelDensityEstimate {
+    /**
+     * The 512 grid points. They run from `min(x) - 3 * bw` to
+     * `max(x) + 3 * bw`, unless the caller froze an end with `from` or `to`.
+     */
+    readonly x: readonly number[];
+    /** The density at each grid point. Never negative. */
+    readonly y: readonly number[];
+    /** The bandwidth the estimate used. */
+    readonly bw: number;
+    /**
+     * The count of values the caller gave, before any were dropped. R reports
+     * the same count, and scales the curve by the share that it kept.
+     */
+    readonly n: number;
+}
+/**
+ * Pick a bandwidth by Silverman's rule, R's `bw.nrd0()`.
+ *
+ * The rule is `0.9 * min(sd, IQR / 1.34) * n^(-1/5)`. When that smaller of
+ * the two spreads is 0 — every value the same, or every value repeated past
+ * the quartiles — R walks a chain of fallbacks and takes the first that is
+ * not 0: the standard deviation, then the size of the first value, then 1.
+ * This keeps the rule from returning a bandwidth of 0, which would leave the
+ * estimate undrawable.
+ *
+ * @param values The observations. All must be finite.
+ * @returns The bandwidth. Always positive.
+ * @throws RangeError Below two values. R stops with "need at least 2 data
+ *   points", since the spread of one value has no meaning.
+ */
+export declare function bwNrd0(values: readonly number[]): number;
+/**
+ * Estimate the density of the values.
+ *
+ * R takes a matrix here and flattens it. This port takes the flat array, so a
+ * caller that pools several samples flattens them first. R flattens a matrix
+ * column by column, which for `plot_sampling()` means one whole sample after
+ * another.
+ *
+ * Values that are infinite are dropped, and the curve is scaled by the share
+ * of values that remain, as in R. A value that is NaN is refused: R reads it
+ * as a missing value and stops.
+ *
+ * @param values The observations.
+ * @param options The bandwidth and the window ends, if the caller sets them.
+ * @returns The grid, the density on it, the bandwidth, and the count of
+ *   values given.
+ * @throws RangeError If the bandwidth has to be selected from fewer than two
+ *   values, if a given bandwidth is not positive and finite, if a given
+ *   window end is not finite, if a value is NaN, or if no value is finite.
+ */
+export declare function kernelDensity(values: readonly number[], options?: KernelDensityOptions): KernelDensityEstimate;
+//# sourceMappingURL=kde.d.ts.map

package/dist/core/kde.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kde.d.ts","sourceRoot":"","sources":["../../src/core/kde.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAmBH,sEAAsE;AACtE,MAAM,WAAW,oBAAoB;IACnC;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;;;;OAQG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,2EAA2E;IAC3E,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,uDAAuD;AACvD,MAAM,WAAW,qBAAqB;IACpC;;;OAGG;IACH,QAAQ,CAAC,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC9B,sDAAsD;IACtD,QAAQ,CAAC,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC9B,uCAAuC;IACvC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAWxD;AAkBD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,SAAS,MAAM,EAAE,EACzB,OAAO,GAAE,oBAAyB,GACjC,qBAAqB,CAiCvB"}

package/dist/core/logit.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Logistic regression, the statistics half of `plot_logit()` in the R package.
+ *
+ * R gets these numbers from `glm(formula, family = binomial)`, which fits by
+ * iteratively reweighted least squares: each pass builds a working response
+ * and a set of weights from the current fit, then solves an ordinary weighted
+ * least-squares problem. This module follows `stats::glm.fit` step for step,
+ * down to its starting values, its convergence test, and the two clamped link
+ * functions R implements in C. Verified against R in `logit.test.ts`.
+ *
+ * The clamps are not a detail. R's `linkinv` pins a linear predictor beyond
+ * ±30 to a probability one machine epsilon away from 0 or 1, which is what
+ * keeps a perfectly separated fit — the classroom case where every low x is a
+ * 0 and every high x is a 1 — producing finite numbers instead of dividing by
+ * zero.
+ */
+import type { Point } from "./regression";
+/** The convergence threshold and iteration cap of R's `glm.control()`. */
+export declare const DEFAULT_LOGIT_EPSILON = 1e-8;
+export declare const DEFAULT_LOGIT_MAX_ITERATIONS = 25;
+export interface LogitOptions {
+    /**
+     * How small the relative change in deviance must be to stop. R's
+     * `glm.control(epsilon =)`.
+     */
+    readonly epsilon?: number;
+    /** How many IRLS passes to allow. R's `glm.control(maxit =)`. */
+    readonly maxIterations?: number;
+}
+/**
+ * The result of a fit.
+ *
+ * A `null` slope is the equivalent of R's `NA`: with no variation in x the
+ * QR aliases the column and R reports "1 not defined because of
+ * singularities". `linearRegression` uses the same convention.
+ */
+export interface LogitFit {
+    /** The linear predictor at x = 0. */
+    readonly intercept: number;
+    /** The change in the log odds for each unit of x. Null if x is constant. */
+    readonly slope: number | null;
+    /**
+     * The fitted probability of each point, in input order. NaN where the
+     * point was dropped for a missing value.
+     */
+    readonly fitted: readonly number[];
+    /**
+     * The log odds of each point, in input order. NaN where the point was
+     * dropped for a missing value.
+     */
+    readonly linearPredictors: readonly number[];
+    /** Residual deviance of the fitted model. */
+    readonly deviance: number;
+    /** Deviance of the intercept-only model. */
+    readonly nullDeviance: number;
+    /** Akaike information criterion, the fit statistic `plot_logit` displays. */
+    readonly aic: number;
+    /** How many coefficients the fit could identify. */
+    readonly rank: number;
+    /** How many IRLS passes ran. */
+    readonly iterations: number;
+    /** Whether the deviance settled before the iteration cap. */
+    readonly converged: boolean;
+    /**
+     * Whether any fitted probability landed within `10 * Number.EPSILON` of 0
+     * or 1.
+     *
+     * This is the condition behind R's "fitted probabilities numerically 0 or 1
+     * occurred" warning, which `plot_logit` suppresses. It reports separation:
+     * the data admit no maximum likelihood estimate and only the iteration cap
+     * stopped the coefficients from growing. A browser library cannot warn, so
+     * the fit reports the condition and lets the caller decide.
+     */
+    readonly saturated: boolean;
+}
+/**
+ * Fit the log odds of y as a straight line in x.
+ *
+ * With no variation in x the fit reports an intercept and no slope, the way
+ * R's aliasing does. A single point is that same case: R fits the intercept
+ * and reports the slope as `NA`. `plot_logit` never reaches either — it draws
+ * the points and returns before fitting fewer than two of them — so the guard
+ * belongs to the plot layer and this function reports the honest degenerate
+ * fit.
+ *
+ * A point with a non-finite coordinate is dropped before fitting, R's
+ * `na.action = na.omit`; its fitted probability and linear predictor report
+ * NaN, keeping input order (R's `na.exclude` padding, as `moderationSurface`
+ * does). The 0-or-1 rule below applies to the rows that remain: R's
+ * `na.omit` removes an incomplete row before `glm()` ever sees its outcome.
+ *
+ * @param points The observations. Each complete y must be 0 or 1. The
+ *   function does not modify them.
+ * @param options The convergence controls.
+ * @returns The fit, or null if no point is complete.
+ * @throws RangeError if a complete row's y is not 0 or 1. R accepts any y in
+ *   [0, 1] for the binomial family; this port does not, because the points
+ *   come from clicks and because the AIC below assumes a 0/1 outcome.
+ */
+export declare function logisticRegression(points: readonly Point[], options?: LogitOptions): LogitFit | null;
+/**
+ * The fitted probability at one x.
+ *
+ * `plot_logit` draws its curve from 500 of these. An aliased slope holds the
+ * curve flat, which is what R's `predict()` does with an `NA` coefficient
+ * dropped from the model.
+ */
+export declare function predictLogit(fit: LogitFit, x: number): number;
+//# sourceMappingURL=logit.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"logit.d.ts","sourceRoot":"","sources":["../../src/core/logit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAKH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AAE1C,0EAA0E;AAC1E,eAAO,MAAM,qBAAqB,OAAO,CAAC;AAC1C,eAAO,MAAM,4BAA4B,KAAK,CAAC;AAE/C,MAAM,WAAW,YAAY;IAC3B;;;OAGG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,iEAAiE;IACjE,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CACjC;AAED;;;;;;GAMG;AACH,MAAM,WAAW,QAAQ;IACvB,qCAAqC;IACrC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,4EAA4E;IAC5E,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B;;;OAGG;IACH,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC;;;OAGG;IACH,QAAQ,CAAC,gBAAgB,EAAE,SAAS,MAAM,EAAE,CAAC;IAC7C,6CAA6C;IAC7C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,4CAA4C;IAC5C,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,6EAA6E;IAC7E,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,oDAAoD;IACpD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,gCAAgC;IAChC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,6DAA6D;IAC7D,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B;;;;;;;;;OASG;IACH,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC7B;AAOD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,SAAS,KAAK,EAAE,EACxB,OAAO,GAAE,YAAiB,GACzB,QAAQ,GAAG,IAAI,CA0HjB;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,QAAQ,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAE7D"}

package/dist/core/matrix.d.ts

@@ -0,0 +1,135 @@
+/**
+ * The determinant and the inverse of a 2x2 matrix.
+ *
+ * This is the arithmetic half of `plot_matrix_inverse()` in the R package,
+ * which builds `A <- matrix(c(x1, y1, x2, y2), nrow = 2)` and calls
+ * `solve(A)` before it draws anything. Verified against R in
+ * `matrix.test.ts`.
+ *
+ * Four things are worth knowing before reading the code.
+ *
+ * **The matrix is two columns.** R fills a matrix column by column, so
+ * `(x1, y1)` is column 1 and `(x2, y2)` is column 2. The R plot draws each
+ * column as an arrow from the origin, and the parallelogram they span has the
+ * determinant as its area. The field names are R's argument names, so nothing
+ * has to be transposed on the way in or out.
+ *
+ * **R's answers come from a factorization, not from the closed form.** Both
+ * `det()` and `solve()` factor the matrix first (LAPACK `dgetrf`, partial
+ * pivoting), and `det()` then exponentiates a sum of logarithms. The closed
+ * forms `x1*y2 - x2*y1` and `[[y2, -x2], [-y1, x1]]/det` give different last
+ * bits: for the default matrix of the interactive gadget the closed form gives
+ * exactly -3 where R gives -2.9999999999999996. This module follows the
+ * factorization, so its numbers are R's.
+ *
+ * **Two operations there are not the obvious ones.** The factorization scales
+ * the column below the pivot by `1 / pivot` instead of dividing by the pivot,
+ * and it rounds the rank-one update once (see `fusedMultiplyAdd`). Both
+ * change what a near-singular matrix reports: dividing turns R's
+ * "computationally singular" into "exactly singular" for four equal entries at
+ * `1e-5`, and rounding twice moves a cancelled determinant by a factor of two.
+ *
+ * **A singular matrix is data, not an error.** R stops with an error, which
+ * ends the R function before it draws. A component that redraws while a slider
+ * moves cannot throw, so this module reports the singularity in its result and
+ * lets the caller decide. The two kinds R distinguishes are kept apart,
+ * because they describe different things: an exactly zero pivot, and a matrix
+ * that is invertible on paper but too ill-conditioned to invert in doubles.
+ */
+/**
+ * A 2x2 matrix, held as R's `plot_matrix_inverse` arguments.
+ *
+ * `(x1, y1)` is the first column and `(x2, y2)` is the second, which is how
+ * `matrix(c(x1, y1, x2, y2), nrow = 2)` fills it. Written as a table of rows,
+ * the matrix is `[[x1, x2], [y1, y2]]`.
+ */
+export interface Matrix2 {
+    /** Row 1 of column 1. R's `A[1,1]`. */
+    readonly x1: number;
+    /** Row 2 of column 1. R's `A[2,1]`. */
+    readonly y1: number;
+    /** Row 1 of column 2. R's `A[1,2]`. */
+    readonly x2: number;
+    /** Row 2 of column 2. R's `A[2,2]`. */
+    readonly y2: number;
+}
+/**
+ * Why a matrix has no inverse, in the two kinds R reports.
+ *
+ * `"exact"` is R's "Lapack routine dgesv: system is exactly singular:
+ * U[i,i] = 0": the factorization found a pivot that is the literal value zero.
+ * `"computational"` is R's "system is computationally singular: reciprocal
+ * condition number = ...": the factorization completed, but the condition
+ * number is below R's tolerance of one machine epsilon.
+ */
+export type Singularity = "exact" | "computational";
+/** What `invertMatrix` reports about one matrix. */
+export interface MatrixInversion {
+    /**
+     * The determinant, as R's `det()` computes it. It is exactly zero for an
+     * exactly singular matrix, and it is not a test for singularity: a matrix
+     * with a determinant of `2e-16` can still be too ill-conditioned to invert,
+     * and one with a determinant of `0.01` inverts without trouble.
+     */
+    readonly determinant: number;
+    /**
+     * The inverse, or null if R's `solve()` would have stopped with an error.
+     * The port could report the huge and meaningless numbers that a
+     * computationally singular matrix produces, and does not: a null says the
+     * same thing as R's error, in a form a caller can branch on.
+     */
+    readonly inverse: Matrix2 | null;
+    /** Which kind of singularity, or null if the matrix inverts. */
+    readonly singularity: Singularity | null;
+    /**
+     * The reciprocal condition number in the one-norm:
+     * `1 / (norm(A) * norm(inverse))`. R's bar for a usable matrix is
+     * `rcond >= Number.EPSILON`, and this port keeps that bar.
+     *
+     * R's `solve()` reads an estimate of the same number from LAPACK's
+     * `dgecon` rather than computing it. Near the bar the two agree to the last
+     * bit — every fixture at the edge of singularity does — while for a well
+     * conditioned matrix R's estimate can be up to about twice this value,
+     * because the estimator only bounds the norm of the inverse from below. The
+     * two never disagreed about a matrix over a sweep of 20000 slider settings.
+     *
+     * It is 0 for an exactly singular matrix. R computes no condition number
+     * there — the factorization has already failed — and zero is the limit.
+     */
+    readonly rcond: number;
+    /**
+     * Which pivot was exactly zero: the `i` of R's message `U[i,i] = 0`. It is
+     * 1 only when the whole first column is zero, and null unless the
+     * singularity is exact.
+     */
+    readonly zeroPivot: 1 | 2 | null;
+}
+/**
+ * Return the determinant, as R's `det()` reports it.
+ *
+ * R factors the matrix and then computes `sign * exp(sum(log(abs(pivot))))`,
+ * so an integer determinant does not always come back as an integer. A
+ * singular matrix gives a positive zero, whatever its rows: R leaves the sign
+ * of the interchange unread on that path.
+ *
+ * @param matrix The matrix. The function does not modify it.
+ * @returns The determinant. It is NaN if an entry is NaN, and it overflows to
+ *   an infinity for entries large enough, both as R's does.
+ */
+export declare function determinant(matrix: Matrix2): number;
+/**
+ * Invert the matrix, and report what R's `solve()` would have done with it.
+ *
+ * The function does not throw. An entry of NaN spreads into every number of
+ * the report, which is what R's `solve()` does with it too. An infinite entry
+ * gives an infinite norm and so a condition number of zero, and the report
+ * says the matrix is computationally singular. R returns an inverse of zeros
+ * there instead, but only because its condition test cannot judge a matrix of
+ * infinite norm: R's own `rcond()` stops with an error on the same matrix.
+ *
+ * @param matrix The matrix. The function does not modify it.
+ * @returns The inverse and the determinant, or the kind of singularity that
+ *   stops the matrix from having an inverse.
+ */
+export declare function invertMatrix(matrix: Matrix2): MatrixInversion;
+//# sourceMappingURL=matrix.d.ts.map

package/dist/core/matrix.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"matrix.d.ts","sourceRoot":"","sources":["../../src/core/matrix.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAYH;;;;;;GAMG;AACH,MAAM,WAAW,OAAO;IACtB,uCAAuC;IACvC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,uCAAuC;IACvC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,uCAAuC;IACvC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,uCAAuC;IACvC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,WAAW,GAAG,OAAO,GAAG,eAAe,CAAC;AAEpD,oDAAoD;AACpD,MAAM,WAAW,eAAe;IAC9B;;;;;OAKG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IACjC,gEAAgE;IAChE,QAAQ,CAAC,WAAW,EAAE,WAAW,GAAG,IAAI,CAAC;IACzC;;;;;;;;;;;;;;OAcG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB;;;;OAIG;IACH,QAAQ,CAAC,SAAS,EAAE,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC;CAClC;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,CAEnD;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,OAAO,GAAG,eAAe,CAwC7D"}

package/dist/core/moderation.d.ts

@@ -0,0 +1,127 @@
+/**
+ * The fitted surface of a moderated regression.
+ *
+ * This is the statistics half of `plot_moderation_3d()` in the R package,
+ * which fits `lm(formula, data)`, predicts over a 15 by 15 grid of the IV and
+ * the moderator, and hands the grid to `lattice::wireframe()`. Verified
+ * against R in `moderation.test.ts`.
+ *
+ * Four things are worth knowing before reading the code.
+ *
+ * **Columns, not a formula.** R names the model with `y ~ x * z`. TypeScript
+ * has no such notation, so the model arrives as column names, per CLAUDE.md:
+ * an outcome, an IV, a moderator, an optional list of controls, and a flag
+ * for the interaction. The three models the fixtures pin are
+ * `{outcome: "y", iv: "x", mod: "z"}` (R's `y ~ x * z`), the same with
+ * `interaction: false` (`y ~ x + z`), and the same with `controls: ["w"]`
+ * (`y ~ x + z + w + x:z`).
+ *
+ * **The design follows R's model matrix, not the option order.** R's
+ * `model.matrix` puts every main effect before any interaction, whatever
+ * order the formula was typed in, so `y ~ x + z + w + x:z` gives the columns
+ * `(Intercept), x, z, w, x:z`. This module builds them in that order, which
+ * is what lets a caller read the coefficients next to R's.
+ *
+ * **Controls are held at their mean, and only numbers are accepted.** R's
+ * `hold_value()` also handles factors (first level), characters (first in
+ * sort order) and logicals (always FALSE). The bundled data has no such
+ * column and no doc example uses one, so this port supports the numeric
+ * branch alone and refuses the rest, rather than shipping three rules nothing
+ * exercises. The other rules are recorded in
+ * `.claude/plans/moderation-fixtures.md` section 4 if they are ever wanted.
+ *
+ * **Missing values leave the fit, as R's do.** `lm()` drops incomplete rows
+ * through `na.omit` and `hold_value()` averages with `na.rm = TRUE`; this
+ * port does the same, with NaN standing in for `NA` and any non-finite value
+ * counting as missing. The details — the `na.exclude`-style NaN padding of
+ * `fitted` and `residuals`, the one departure on `zlim` — are on
+ * `moderationSurface` itself.
+ */
+import { type DataFrame } from "./frame";
+/** Which columns make the model. */
+export interface ModerationOptions {
+    /** The column to predict — the vertical axis of the surface. */
+    readonly outcome: string;
+    /** The predictor on the first horizontal axis. */
+    readonly iv: string;
+    /** The predictor on the second horizontal axis. */
+    readonly mod: string;
+    /**
+     * Whether the model carries the IV by moderator product. True by default,
+     * which is R's `y ~ x * z`. False gives R's additive `y ~ x + z`, whose
+     * surface is a plane with no twist.
+     */
+    readonly interaction?: boolean;
+    /**
+     * Further predictors to fit but not to plot. Each is held at its own mean
+     * over the grid, R's `hold_value()` for a numeric column. Empty by default.
+     */
+    readonly controls?: readonly string[];
+}
+/** One fitted term, named as R names it. */
+export interface ModerationTerm {
+    /**
+     * R's coefficient name: `(Intercept)`, a column name, or `iv:mod` for the
+     * product term.
+     */
+    readonly name: string;
+    /**
+     * The coefficient, or null where R reports `NA` — a column the fit could
+     * not tell apart from the columns before it.
+     */
+    readonly value: number | null;
+}
+/** A fitted model and the surface it predicts. */
+export interface ModerationSurface {
+    /** The fitted terms, in R's model-matrix order. */
+    readonly coefficients: readonly ModerationTerm[];
+    /**
+     * The fitted outcome of each data row, in input order. NaN where the row
+     * was dropped for a missing value, as R's `na.exclude` pads.
+     */
+    readonly fitted: readonly number[];
+    /**
+     * The outcome minus the fit, of each data row, in input order. NaN where
+     * the row was dropped for a missing value.
+     */
+    readonly residuals: readonly number[];
+    /** The 15 IV values of the grid, from the column's minimum to its maximum. */
+    readonly ivValues: readonly number[];
+    /** The 15 moderator values of the grid, over the same span. */
+    readonly modValues: readonly number[];
+    /**
+     * The 225 predicted outcomes, **with the IV varying fastest**: index
+     * `j * 15 + i` holds the prediction at `ivValues[i]` and `modValues[j]`.
+     * This is the row order of R's `expand.grid(seq_iv, seq_mod)`.
+     */
+    readonly predictions: readonly number[];
+    /**
+     * The vertical range to draw, as `[low, high]`: the range of the observed
+     * outcome together with the range of the surface. Which of the two reaches
+     * further depends on the model — an interaction usually swings the surface
+     * past the data at the corners of the grid, while a plane stays inside it.
+     */
+    readonly zlim: readonly [number, number];
+    /** The value each control is held at over the grid: its mean. */
+    readonly holds: Readonly<Record<string, number>>;
+}
+/**
+ * Fit the model and predict its surface.
+ *
+ * Rows with a missing (non-finite) value in any model column are dropped
+ * before fitting, R's `na.action = na.omit`; their fitted values and
+ * residuals report NaN, keeping input order. The grid and zlim span the
+ * finite values of their columns, and a control is held at its finite mean —
+ * R's `hold_value()` with `na.rm = TRUE`. (R itself computes zlim with no
+ * `na.rm` and fails on a missing outcome; the port draws what it can fit, a
+ * stated departure.)
+ *
+ * @param data The frame holding every column the options name.
+ * @param options Which column plays which part in the model.
+ * @returns The fit, the grid, the surface, and the vertical range.
+ * @throws RangeError If a named column is absent, empty, or not numeric, if
+ *   the IV and the moderator are the same column, if a control repeats
+ *   another named column, if the frame is ragged, or if no row is complete.
+ */
+export declare function moderationSurface(data: DataFrame, options: ModerationOptions): ModerationSurface;
+//# sourceMappingURL=moderation.d.ts.map