@compstats/core 0.3.0 → 0.4.0

package/dist/core/linalg/ops.d.ts

@@ -0,0 +1,120 @@
+/**
+ * The elementary matrix operations, named as R names them.
+ *
+ * `t()`, `%*%` (`matmul`), `crossprod()`, `tcrossprod()`, `cbind()`,
+ * `rbind()` and `diag()`. Each takes matrices (and, where R allows it, plain
+ * vectors) and returns a new matrix; nothing here modifies its input.
+ *
+ * A bare vector in a product takes the shape R gives it, which is not
+ * always the one that would conform (fixtures 1g and 1h probe the rules).
+ * In `%*%`, a left vector is a row when its length matches the rows of the
+ * right factor and otherwise a column; a right vector is a column when its
+ * length matches the columns of the left factor and otherwise a row; two
+ * vectors give their inner product. In `crossprod` a vector `x` is always
+ * a column, and a vector `y` is a column when its length matches the rows
+ * of `x` and otherwise a row. In `tcrossprod` a vector `x` is a row when
+ * its length matches the columns of a matrix `y` and otherwise a column,
+ * and a vector `y` is a row only when `x` has one row; two vectors are both
+ * columns, the outer product.
+ *
+ * Dimnames travel as they do in R: a transpose swaps them, a product keeps
+ * the row names of the left factor and the column names of the right, and
+ * binding stacks them, with `""` for a bare vector joined to a named matrix.
+ *
+ * The product follows the reference BLAS `dgemm` that R ships: the loop
+ * over `i` innermost walks each column of the left factor in order, and each
+ * product is rounded once into its running sum with `fusedMultiplyAdd`,
+ * because the build the conformance fixtures come from contracts
+ * `C + A * B` into one instruction (the fixture README records this; the LU
+ * and QR here already follow it). Index loops throughout: a product
+ * addresses entries by position. (CLAUDE.md allows an index loop with a
+ * stated reason; that is the reason.)
+ */
+import { type Matrix } from "./matrix";
+import type { Vector } from "./vector";
+/** A matrix, or a vector R would treat as a one-column matrix. */
+export type MatrixOrVector = Matrix | Vector;
+/** R's `t()`. Also exported as `transpose`, for an app whose `t` is already taken. */
+export declare function t(m: Matrix): Matrix;
+/** R's `t()`, under a name that does not collide with an i18n `t`. */
+export declare const transpose: typeof t;
+/**
+ * R's `x %*% y`.
+ *
+ * @param x The left factor. A vector is a row when its length matches the
+ *   rows of `y`, else a column when `y` has one row.
+ * @param y The right factor. A vector is a column when its length matches
+ *   the columns of `x`, else a row when `x` has one column. Two vectors of
+ *   one length give their inner product as a 1 x 1 matrix.
+ * @returns The product, with the row names of `x` and the column names of
+ *   `y`.
+ * @throws RangeError If the inner extents differ: R's "non-conformable
+ *   arguments".
+ */
+export declare function matmul(x: MatrixOrVector, y: MatrixOrVector): Matrix;
+/**
+ * R's `crossprod(x, y)`: `t(x) %*% y`, with `crossprod(x)` for `t(x) %*% x`.
+ * A bare vector `x` is a column; a bare vector `y` is a column when its
+ * length matches the rows of `x`, else a row (fixture 1h).
+ *
+ * @throws RangeError If the row counts differ.
+ */
+export declare function crossprod(x: MatrixOrVector, y?: MatrixOrVector): Matrix;
+/**
+ * R's `tcrossprod(x, y)`: `x %*% t(y)`, with `tcrossprod(x)` for
+ * `x %*% t(x)`. A bare vector `x` is a row when its length matches the
+ * columns of a matrix `y`, else a column; a bare vector `y` is a row only
+ * when `x` has one row, and two bare vectors are both columns (fixture 1h).
+ *
+ * @throws RangeError If the column counts differ.
+ */
+export declare function tcrossprod(x: MatrixOrVector, y?: MatrixOrVector): Matrix;
+/**
+ * Tell a matrix from a vector by shape, and refuse anything else — a typed
+ * array or a stray object — with a TypeError rather than a wrong shape.
+ *
+ * @internal Shared with the other linalg modules; not part of the entry.
+ */
+export declare function isMatrix(value: MatrixOrVector): value is Matrix;
+/**
+ * R's `cbind()`: join matrices and vectors side by side.
+ *
+ * @param parts Matrices, and vectors taken as columns. At least one.
+ * @returns The joined matrix. Row names come from the first part that has
+ *   them. Column names are kept when any part has them, with `""` for a part
+ *   that does not, as R names a bare vector.
+ * @throws RangeError If the row counts differ, in R's words for a matrix
+ *   part and for a vector part. R recycles a short vector with a warning;
+ *   the port refuses.
+ */
+export declare function cbind(...parts: readonly MatrixOrVector[]): Matrix;
+/**
+ * R's `rbind()`: stack matrices and vectors.
+ *
+ * @param parts Matrices, and vectors taken as rows. At least one.
+ * @returns The stacked matrix, with names as `cbind` carries them, rows and
+ *   columns exchanged.
+ * @throws RangeError If the column counts differ.
+ */
+export declare function rbind(...parts: readonly MatrixOrVector[]): Matrix;
+/**
+ * R's `diag()` in its three forms: a vector gives the diagonal matrix of it,
+ * a count gives the identity of that order, and a matrix gives its diagonal.
+ *
+ * The form is chosen by type, not by length, which is R's own gotcha
+ * removed: `diag([5])` is the 1 x 1 matrix `[5]` where R's `diag(c(5))` is
+ * the 5 x 5 identity, and `diag(2.5)` refuses where R truncates to 2 x 2.
+ * The diagonal of a matrix comes back as a plain array; R names it when the
+ * row and column names agree, which the port will do once a named vector
+ * exists (plan Q11).
+ */
+export declare function diag(values: Vector): Matrix;
+export declare function diag(order: number): Matrix;
+export declare function diag(m: Matrix): number[];
+/**
+ * The identity matrix of the given order. R's `diag(n)`.
+ *
+ * @throws RangeError If the order is not a non-negative integer.
+ */
+export declare function identity(order: number): Matrix;
+//# sourceMappingURL=ops.d.ts.map

package/dist/core/linalg/ops.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ops.d.ts","sourceRoot":"","sources":["../../../src/core/linalg/ops.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAGH,OAAO,EAAuB,KAAK,MAAM,EAAE,MAAM,UAAU,CAAC;AAC5D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAEvC,kEAAkE;AAClE,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,MAAM,CAAC;AAE7C,sFAAsF;AACtF,wBAAgB,CAAC,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAWnC;AAED,sEAAsE;AACtE,eAAO,MAAM,SAAS,UAAI,CAAC;AAE3B;;;;;;;;;;;;GAYG;AACH,wBAAgB,MAAM,CAAC,CAAC,EAAE,cAAc,EAAE,CAAC,EAAE,cAAc,GAAG,MAAM,CASnE;AAkBD;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,cAAc,EAAE,CAAC,GAAE,cAAkB,GAAG,MAAM,CAS1E;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,cAAc,EAAE,CAAC,GAAE,cAAkB,GAAG,MAAM,CAc3E;AA0CD;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,cAAc,GAAG,KAAK,IAAI,MAAM,CAc/D;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,KAAK,CAAC,GAAG,KAAK,EAAE,SAAS,cAAc,EAAE,GAAG,MAAM,CA8BjE;AAED;;;;;;;GAOG;AACH,wBAAgB,KAAK,CAAC,GAAG,KAAK,EAAE,SAAS,cAAc,EAAE,GAAG,MAAM,CAejE;AAcD;;;;;;;;;;GAUG;AACH,wBAAgB,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC;AAC7C,wBAAgB,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;AAC5C,wBAAgB,IAAI,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;AAmB1C;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAS9C"}

package/dist/core/linalg/prcomp.d.ts

@@ -0,0 +1,66 @@
+/**
+ * R's `prcomp()`: principal components of a matrix or a data frame, any
+ * number of variables.
+ *
+ * R centers (and optionally scales) the columns and takes the singular
+ * value decomposition of the result. The port centers and scales the same
+ * way and then decomposes the covariance matrix with `eigenSymmetric`: the
+ * standard deviations are the square roots of its eigenvalues, the rotation
+ * its eigenvectors, and the scores the centered data times the rotation.
+ * The two routes agree to a relative `1e-12` on the standard deviations and
+ * up to the sign of each component on the rest (plan Q1), which the SVD
+ * leaves arbitrary as well; the port's sign rule is `eigenSymmetric`'s.
+ * Verified in `prcomp.test.ts`, including agreement with the two-variable
+ * `principalComponents` of `pca.ts` on the bundled `pcaDegenerate` points.
+ *
+ * As `pca.ts` does, the port returns one component per variable and never
+ * reduces the rank: a collinear input reports a near-zero standard
+ * deviation rather than a shorter result. R's `prcomp` returns `min(n, p)`
+ * components, which is the same unless there are fewer rows than columns.
+ */
+import type { DataFrame } from "../frame";
+import { type Matrix } from "./matrix";
+import type { Vector } from "./vector";
+export interface PrcompOptions {
+    /** Subtract the column means first. True by default, as R's is. */
+    readonly center?: boolean;
+    /**
+     * Divide each column by its root mean square after centering — its
+     * standard deviation, when centered. False by default, as R's is.
+     */
+    readonly scale?: boolean;
+}
+/** R's `prcomp` result. */
+export interface Prcomp {
+    /** The standard deviation along each component, largest first. */
+    readonly sdev: Vector;
+    /**
+     * The loadings: one row per variable, one column per component, named
+     * `PC1`, `PC2`, … with the variable names as row names when the input
+     * has column names.
+     */
+    readonly rotation: Matrix;
+    /** The value subtracted from each column; zeros when not centered. */
+    readonly center: Vector;
+    /** The value each column was divided by, or null when not scaled. */
+    readonly scale: Vector | null;
+    /**
+     * The scores: the centered, scaled data in component coordinates, with
+     * the row names of the input and `PC1`, `PC2`, … as column names, as R's
+     * are (fixture 5e).
+     */
+    readonly x: Matrix;
+}
+/**
+ * Compute the principal components, as R's `prcomp()` does.
+ *
+ * @param input A matrix with one column per variable, or a data frame whose
+ *   numeric columns are the variables.
+ * @param options Whether to center and whether to scale.
+ * @returns The standard deviations, the rotation, the centering and scaling
+ *   applied, and the scores.
+ * @throws RangeError If any value is missing or infinite (R's `svd` refuses
+ *   the same), or if a column to be scaled is constant, in R's words.
+ */
+export declare function prcomp(input: Matrix | DataFrame, options?: PrcompOptions): Prcomp;
+//# sourceMappingURL=prcomp.d.ts.map

package/dist/core/linalg/prcomp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prcomp.d.ts","sourceRoot":"","sources":["../../../src/core/linalg/prcomp.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAG1C,OAAO,EAAmB,KAAK,MAAM,EAAE,MAAM,UAAU,CAAC;AAExD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAEvC,MAAM,WAAW,aAAa;IAC5B,mEAAmE;IACnE,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAC1B;;;OAGG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,2BAA2B;AAC3B,MAAM,WAAW,MAAM;IACrB,kEAAkE;IAClE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,sEAAsE;IACtE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,qEAAqE;IACrE,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B;;;;OAIG;IACH,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,EAAE,OAAO,GAAE,aAAkB,GAAG,MAAM,CAwDrF"}

package/dist/core/linalg/qr.d.ts

@@ -0,0 +1,134 @@
+/**
+ * The QR factorization, R's `qr()` with `LAPACK = FALSE`.
+ *
+ * R factors a design with LINPACK's `dqrdc2`, a Householder QR with a
+ * limited column-pivoting rule: a column whose norm has collapsed against
+ * the columns to its left is moved to the right edge and its coefficient is
+ * reported as `NA`. That rule is what makes `lm()` and `glm()` report an
+ * aliased coefficient instead of dividing by a near-zero pivot. This module
+ * reproduces it and exposes R's result — the compact `qr` matrix, `qraux`,
+ * `pivot` and `rank` — and R's readers of it: `qr.coef`, `qr.fitted`,
+ * `qr.resid`, `qr.qy`, `qr.qty`, `qr.Q` and `qr.R`. Verified against R in
+ * `qr.test.ts`; `leastSquares` in `../ols.ts` is a wrapper over it.
+ *
+ * Designs here are small — two columns for logit, four for a moderation
+ * surface — so the code follows the LINPACK routines plainly rather than
+ * blocking or vectorizing them. Index loops throughout: a factorization
+ * addresses single entries by position, and this one follows `dqrdc2` and
+ * `dqrsl` step for step so that the fixtures pin bit for bit.
+ */
+import { type Matrix } from "./matrix";
+import type { Vector } from "./vector";
+/** R's `qr()` result. */
+export interface QrDecomposition {
+    /**
+     * The compact factorization, R's `qr$qr`: `R` on and above the diagonal,
+     * the Householder vectors below it, columns in pivot order. Column names
+     * follow the pivot, as R's do.
+     */
+    readonly qr: Matrix;
+    /**
+     * R's `qr$qraux`: for each reflected column, the leading entry of its
+     * Householder reflector; for a column never reflected — the trailing
+     * column of a square or wide design, or an aliased column — its remaining
+     * norm, which is what R reports there (fixtures 2b, 2c, 2g).
+     */
+    readonly qraux: Vector;
+    /**
+     * The column order after pivoting, R's `qr$pivot` **zero-based**:
+     * `pivot[k]` is the original index of the column now at position `k`.
+     * The aliased columns are at the end.
+     */
+    readonly pivot: readonly number[];
+    /** The number of columns the factorization could identify. */
+    readonly rank: number;
+}
+export interface QrOptions {
+    /**
+     * How far a column's norm may collapse before it is aliased: the column is
+     * moved to the end when its remaining norm falls below this fraction of
+     * its original norm. The default is R's `qr()` and `lm.fit()` default.
+     * `glm.fit()` passes `min(1e-7, epsilon / 1000)`. Zero aliases nothing,
+     * as R's `tol = 0` does; a negative or NaN value is refused, where R
+     * would pass it through — a deliberate narrowing.
+     */
+    readonly tolerance?: number;
+}
+/** The rank tolerance of R's `qr()` and `lm.fit()`. */
+export declare const DEFAULT_QR_TOLERANCE = 1e-7;
+/**
+ * Factor a matrix, as R's `qr(x, LAPACK = FALSE)` does.
+ *
+ * @param x The matrix. The function does not modify it. Row names travel
+ *   onto the compact form; column names follow the pivot.
+ * @param options The rank tolerance.
+ * @returns The compact factorization, `qraux`, the pivot, and the rank.
+ * @throws RangeError If the tolerance is negative or NaN, or if an entry is
+ *   not finite — R's "NA/NaN/Inf in foreign function call (arg 1)". NaN is
+ *   this library's missing value; a caller drops incomplete rows first, as
+ *   `modelMatrix` does.
+ * @throws TypeError If `x` is not a matrix.
+ */
+export declare function qr(x: Matrix, options?: QrOptions): QrDecomposition;
+/**
+ * Solve for the coefficients, R's `qr.coef(qr, y)`.
+ *
+ * @param q The factorization.
+ * @param y The response, one value per row — or a matrix with one response
+ *   per column, as R also takes.
+ * @returns One coefficient per column of the factored matrix, **in the
+ *   original column order**, with null for an aliased column (R's `NA`).
+ *   For a matrix `y`, a matrix with one column per response, the factored
+ *   matrix's column names as row names and `y`'s column names as column
+ *   names; an aliased column reads NaN there, since a matrix holds no null.
+ * @throws RangeError If `y` has the wrong number of rows.
+ */
+export declare function qrCoef(q: QrDecomposition, y: Vector): (number | null)[];
+export declare function qrCoef(q: QrDecomposition, y: Matrix): Matrix;
+/**
+ * The fitted values, R's `qr.fitted(qr, y)`: `Q` applied to the first `rank`
+ * entries of `Qᵀy`, the rest set to zero. A matrix `y` gives a matrix with
+ * its column names.
+ *
+ * @throws RangeError If `y` has the wrong number of rows.
+ */
+export declare function qrFitted(q: QrDecomposition, y: Vector): number[];
+export declare function qrFitted(q: QrDecomposition, y: Matrix): Matrix;
+/**
+ * The residuals, R's `qr.resid(qr, y)`: `Q` applied to `Qᵀy` with its first
+ * `rank` entries set to zero. A matrix `y` gives a matrix with its column
+ * names.
+ *
+ * @throws RangeError If `y` has the wrong number of rows.
+ */
+export declare function qrResid(q: QrDecomposition, y: Vector): number[];
+export declare function qrResid(q: QrDecomposition, y: Matrix): Matrix;
+/**
+ * `Qᵀy`, R's `qr.qty(qr, y)`: the reflectors applied first to last. A
+ * matrix `y` gives a matrix with its column names.
+ *
+ * @throws RangeError If `y` has the wrong number of rows.
+ */
+export declare function qrQty(q: QrDecomposition, y: Vector): number[];
+export declare function qrQty(q: QrDecomposition, y: Matrix): Matrix;
+/**
+ * `Qy`, R's `qr.qy(qr, y)`: the reflectors applied last to first. A matrix
+ * `y` gives a matrix with its column names.
+ *
+ * @throws RangeError If `y` has the wrong number of rows.
+ */
+export declare function qrQy(q: QrDecomposition, y: Vector): number[];
+export declare function qrQy(q: QrDecomposition, y: Matrix): Matrix;
+/**
+ * The orthogonal factor, R's `qr.Q(qr)`: `n` rows by `min(n, p)` columns —
+ * `Q` applied to the leading columns of the identity. It carries no names,
+ * as R's does not.
+ */
+export declare function qrQ(q: QrDecomposition): Matrix;
+/**
+ * The triangular factor, R's `qr.R(qr)`: `min(n, p)` rows by `p` columns,
+ * the upper triangle of the compact form, with the leading row names and
+ * the column names in pivot order.
+ */
+export declare function qrR(q: QrDecomposition): Matrix;
+//# sourceMappingURL=qr.d.ts.map

package/dist/core/linalg/qr.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"qr.d.ts","sourceRoot":"","sources":["../../../src/core/linalg/qr.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAGH,OAAO,EAAuB,KAAK,MAAM,EAAE,MAAM,UAAU,CAAC;AAE5D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAEvC,yBAAyB;AACzB,MAAM,WAAW,eAAe;IAC9B;;;;OAIG;IACH,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB;;;;;OAKG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB;;;;OAIG;IACH,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,8DAA8D;IAC9D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,SAAS;IACxB;;;;;;;OAOG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,uDAAuD;AACvD,eAAO,MAAM,oBAAoB,OAAO,CAAC;AAEzC;;;;;;;;;;;;GAYG;AACH,wBAAgB,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,GAAE,SAAc,GAAG,eAAe,CAgCtE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,MAAM,CAAC,CAAC,EAAE,eAAe,EAAE,CAAC,EAAE,MAAM,GAAG,CAAC,MAAM,GAAG,IAAI,CAAC,EAAE,CAAC;AACzE,wBAAgB,MAAM,CAAC,CAAC,EAAE,eAAe,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;AA0C9D;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,eAAe,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;AAClE,wBAAgB,QAAQ,CAAC,CAAC,EAAE,eAAe,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;AAOhE;;;;;;GAMG;AACH,wBAAgB,OAAO,CAAC,CAAC,EAAE,eAAe,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;AACjE,wBAAgB,OAAO,CAAC,CAAC,EAAE,eAAe,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;AAO/D;;;;;GAKG;AACH,wBAAgB,KAAK,CAAC,CAAC,EAAE,eAAe,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;AAC/D,wBAAgB,KAAK,CAAC,CAAC,EAAE,eAAe,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;AAK7D;;;;;GAKG;AACH,wBAAgB,IAAI,CAAC,CAAC,EAAE,eAAe,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;AAC9D,wBAAgB,IAAI,CAAC,CAAC,EAAE,eAAe,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;AA6C5D;;;;GAIG;AACH,wBAAgB,GAAG,CAAC,CAAC,EAAE,eAAe,GAAG,MAAM,CAU9C;AAED;;;;GAIG;AACH,wBAAgB,GAAG,CAAC,CAAC,EAAE,eAAe,GAAG,MAAM,CAY9C"}

package/dist/core/linalg/vector.d.ts

@@ -0,0 +1,68 @@
+/**
+ * R's operators over vectors, by name.
+ *
+ * R vectors are not objects with methods: `a + 1`, `a * b` and `sum(a * b)`
+ * are functions over plain vectors, with a scalar recycled to the length of
+ * the other argument. This module is those functions with the operator
+ * spelled out — `add(a, 1)`, `mul(a, b)`, `dot(a, b)` — over `Vector`,
+ * which is `Vector` and nothing more: a bare array is a vector
+ * (plan Q11, Q12).
+ *
+ * R recycles any shorter vector, with a warning when the lengths do not
+ * divide. The port recycles a scalar only and refuses every other mismatch:
+ * a silent recycle lets a typo fit the wrong model.
+ */
+/**
+ * A numeric vector: R's atomic double vector, which here is a plain array of
+ * numbers. `NaN` is the missing value, as `NA_real_` is in R.
+ *
+ * The name is erased at compile time and structural, not nominal. Any
+ * `number[]` is a `Vector` and any `Vector` is an array, with nothing to wrap
+ * at either end. It names the concept in a signature and carries this note to
+ * every place one is taken; it constrains nothing, and in particular it does
+ * not check a length.
+ *
+ * A function *takes* a `Vector` and *returns* a fresh `number[]` — R's
+ * copy-on-modify, and the reason there is no mutable counterpart to this
+ * name. A vector is never an object with methods (plan Q12).
+ */
+export type Vector = readonly number[];
+/** A vector, or a scalar to recycle to the vector's length. */
+export type VectorOrScalar = Vector | number;
+/** R's `a + b`. */
+export declare function add(a: Vector, b: VectorOrScalar): number[];
+/** R's `a - b`. */
+export declare function sub(a: Vector, b: VectorOrScalar): number[];
+/** R's `a * b`. With a scalar, `2 * a`. */
+export declare function mul(a: Vector, b: VectorOrScalar): number[];
+/** R's `a / b`. */
+export declare function div(a: Vector, b: VectorOrScalar): number[];
+/** R's `a^2`. */
+export declare function square(a: Vector): number[];
+/**
+ * R's `sum(a * b)`: the inner product.
+ *
+ * @throws RangeError If the lengths differ.
+ */
+export declare function dot(a: Vector, b: Vector): number;
+/**
+ * R's `sqrt(sum(a^2))`: the Euclidean length.
+ *
+ * Written as a sum, not `Math.hypot(...a)`: the spread overflows the call
+ * stack on a long vector, and the sum is the form R computes, so the two
+ * round the same way.
+ */
+export declare function norm(a: Vector): number;
+/**
+ * The cosine of the angle between two vectors: `dot(a, b) / (norm(a) * norm(b))`.
+ *
+ * Computed in exactly that order, which is the order a reader writes it in
+ * R, so the port and R land on the same double — including
+ * `cosine(a, a) = 1.0000000000000002` for a vector whose norm does not
+ * square back to its sum of squares. A zero vector gives NaN, as `0 / 0` does
+ * in R.
+ *
+ * @throws RangeError If the lengths differ.
+ */
+export declare function cosine(a: Vector, b: Vector): number;
+//# sourceMappingURL=vector.d.ts.map

package/dist/core/linalg/vector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vector.d.ts","sourceRoot":"","sources":["../../../src/core/linalg/vector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,MAAM,GAAG,SAAS,MAAM,EAAE,CAAC;AAEvC,+DAA+D;AAC/D,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,MAAM,CAAC;AAsB7C,mBAAmB;AACnB,wBAAgB,GAAG,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,cAAc,GAAG,MAAM,EAAE,CAE1D;AAED,mBAAmB;AACnB,wBAAgB,GAAG,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,cAAc,GAAG,MAAM,EAAE,CAE1D;AAED,2CAA2C;AAC3C,wBAAgB,GAAG,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,cAAc,GAAG,MAAM,EAAE,CAE1D;AAED,mBAAmB;AACnB,wBAAgB,GAAG,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,cAAc,GAAG,MAAM,EAAE,CAE1D;AAED,iBAAiB;AACjB,wBAAgB,MAAM,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAE1C;AAED;;;;GAIG;AACH,wBAAgB,GAAG,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAGhD;AAED;;;;;;GAMG;AACH,wBAAgB,IAAI,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAEtC;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,MAAM,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAEnD"}

package/dist/core/moderation.d.ts

@@ -19,8 +19,11 @@
  * **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.
+ * `(Intercept), x, z, w, x:z`. This module names the terms and hands them to
+ * `linalg/lm`, which is `model.matrix()` followed by `lm.fit()` and puts the
+ * columns in that order, so a caller can read the coefficients next to R's.
+ * Going through `lm` also makes the fitted values `y` minus the residuals of
+ * the factorization, which is R's own definition, rather than `X · β`.
  *
  * **Controls are held at their mean, and only numbers are accepted.** R's
  * `hold_value()` also handles factors (first level), characters (first in
@@ -28,7 +31,7 @@
  * 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.
+ * `.claude/plans/001-PLAN-port/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

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

@@ -1 +1 @@
-{"version":3,"file":"moderation.d.ts","sourceRoot":"","sources":["../../src/core/moderation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAGH,OAAO,EAAmC,KAAK,SAAS,EAAE,MAAM,SAAS,CAAC;AAS1E,oCAAoC;AACpC,MAAM,WAAW,iBAAiB;IAChC,gEAAgE;IAChE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,kDAAkD;IAClD,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,mDAAmD;IACnD,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;IAC/B;;;OAGG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACvC;AAED,4CAA4C;AAC5C,MAAM,WAAW,cAAc;IAC7B;;;OAGG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B;AAED,kDAAkD;AAClD,MAAM,WAAW,iBAAiB;IAChC,mDAAmD;IACnD,QAAQ,CAAC,YAAY,EAAE,SAAS,cAAc,EAAE,CAAC;IACjD;;;OAGG;IACH,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC;;;OAGG;IACH,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,8EAA8E;IAC9E,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,+DAA+D;IAC/D,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC;;;;OAIG;IACH,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IACxC;;;;;OAKG;IACH,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACzC,iEAAiE;IACjE,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CAClD;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,SAAS,EACf,OAAO,EAAE,iBAAiB,GACzB,iBAAiB,CAoInB"}
+{"version":3,"file":"moderation.d.ts","sourceRoot":"","sources":["../../src/core/moderation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAGH,OAAO,EAAmC,KAAK,SAAS,EAAE,MAAM,SAAS,CAAC;AAS1E,oCAAoC;AACpC,MAAM,WAAW,iBAAiB;IAChC,gEAAgE;IAChE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,kDAAkD;IAClD,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,mDAAmD;IACnD,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;IAC/B;;;OAGG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACvC;AAED,4CAA4C;AAC5C,MAAM,WAAW,cAAc;IAC7B;;;OAGG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B;AAED,kDAAkD;AAClD,MAAM,WAAW,iBAAiB;IAChC,mDAAmD;IACnD,QAAQ,CAAC,YAAY,EAAE,SAAS,cAAc,EAAE,CAAC;IACjD;;;OAGG;IACH,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC;;;OAGG;IACH,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,8EAA8E;IAC9E,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,+DAA+D;IAC/D,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC;;;;OAIG;IACH,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IACxC;;;;;OAKG;IACH,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACzC,iEAAiE;IACjE,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CAClD;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,SAAS,EACf,OAAO,EAAE,iBAAiB,GACzB,iBAAiB,CAyGnB"}

package/dist/core/ols.d.ts

@@ -5,14 +5,11 @@
  * every step of `glm.fit()`'s IRLS loop. R factors the design with `dqrdc2`,
  * a Householder QR with a limited column-pivoting rule: a column whose norm
  * has collapsed against the columns to its left is moved to the right edge
- * and its coefficient is reported as `NA`. The port reproduces that rule,
- * because it is what makes `lm()` and `glm()` report an aliased coefficient
- * instead of dividing by a near-zero pivot. Verified against R in
+ * and its coefficient is reported as `NA`. That factorization lives in
+ * `linalg/qr.ts` as R's `qr()`; this module is the `lm.wfit()` wrapper over
+ * it — the square-root weighting, the row-array interface the fitting
+ * functions use, and the fitted values as `X · β`. Verified against R in
  * `ols.test.ts`.
- *
- * Designs here are tiny — two columns for logit, four for a moderation
- * surface — so the code follows the LINPACK routine plainly rather than
- * blocking or vectorizing it.
  */
 /**
  * The result of a fit.

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

@@ -1 +1 @@
-{"version":3,"file":"ols.d.ts","sourceRoot":"","sources":["../../src/core/ols.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAIH;;;;;;GAMG;AACH,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,QAAQ,CAAC,YAAY,EAAE,SAAS,CAAC,MAAM,GAAG,IAAI,CAAC,EAAE,CAAC;IAClD,uDAAuD;IACvD,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,uDAAuD;IACvD,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,oDAAoD;IACpD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,mBAAmB;IAClC;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC;;;;;;;OAOG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,4CAA4C;AAC5C,eAAO,MAAM,+BAA+B,OAAO,CAAC;AAEpD;;;;;;;;;;;;GAYG;AACH,wBAAgB,YAAY,CAC1B,MAAM,EAAE,SAAS,CAAC,SAAS,MAAM,EAAE,CAAC,EAAE,EACtC,CAAC,EAAE,SAAS,MAAM,EAAE,EACpB,OAAO,GAAE,mBAAwB,GAChC,eAAe,CA2DjB"}
+{"version":3,"file":"ols.d.ts","sourceRoot":"","sources":["../../src/core/ols.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAMH;;;;;;GAMG;AACH,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,QAAQ,CAAC,YAAY,EAAE,SAAS,CAAC,MAAM,GAAG,IAAI,CAAC,EAAE,CAAC;IAClD,uDAAuD;IACvD,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,uDAAuD;IACvD,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,oDAAoD;IACpD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,mBAAmB;IAClC;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC;;;;;;;OAOG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,4CAA4C;AAC5C,eAAO,MAAM,+BAA+B,OAAO,CAAC;AAEpD;;;;;;;;;;;;GAYG;AACH,wBAAgB,YAAY,CAC1B,MAAM,EAAE,SAAS,CAAC,SAAS,MAAM,EAAE,CAAC,EAAE,EACtC,CAAC,EAAE,SAAS,MAAM,EAAE,EACpB,OAAO,GAAE,mBAAwB,GAChC,eAAe,CAyDjB"}

package/dist/data/moderationData.d.ts

@@ -20,8 +20,8 @@
  * regenerated** — the draw used `set.seed(42)` under R's own generator, so a
  * JavaScript regeneration would produce different numbers and silently change
  * every default demo. Source of the printed values:
- * `.claude/plans/moderation-data.tsv`, checked against the column checksums of
- * `.claude/plans/moderation-fixtures.md` in `moderationData.test.ts`.
+ * `.claude/plans/001-PLAN-port/moderation-data.tsv`, checked against the column checksums of
+ * `.claude/plans/001-PLAN-port/moderation-fixtures.md` in `moderationData.test.ts`.
  *
  * The columns are in the order of the R data frame — `y, x, z, w`, not
  * alphabetical and not `x, y, z`. That order is load-bearing: `plot_scatter3d()`

package/dist/data/pcaDegenerate.d.ts

@@ -10,7 +10,7 @@
  * (`../compstatslib/data/pca_degenerate.rda`), printed at 17 significant
  * digits, which round-trips an IEEE-754 double. **Exported from R, never
  * regenerated** — a JavaScript regeneration would silently change the demo.
- * Source of the printed values: `.claude/plans/pca-fixtures.md`, section F1.
+ * Source of the printed values: `.claude/plans/001-PLAN-port/pca-fixtures.md`, section F1.
  */
 import type { Point } from "../core/regression";
 /** The 16 rows of the R `pca_degenerate` data frame, in file order. */