@compstats/core 0.2.0

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

@@ -0,0 +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"}

package/dist/core/ols.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Dense (weighted) least squares for small designs.
+ *
+ * This is the equivalent of R's `lm.wfit()`, and of the solver R runs inside
+ * 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
+ * `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.
+ *
+ * A `null` coefficient is the equivalent of R's `NA`: the column carried no
+ * information beyond the columns to its left, so R aliases it. `linearRegression`
+ * uses the same convention.
+ */
+export interface LeastSquaresFit {
+    /**
+     * One coefficient per design column, in column order. An aliased column
+     * reports null.
+     */
+    readonly coefficients: readonly (number | null)[];
+    /** The fitted response of each row, in input order. */
+    readonly fitted: readonly number[];
+    /** Response minus fit, of each row, in input order. */
+    readonly residuals: readonly number[];
+    /** The number of columns the fit could identify. */
+    readonly rank: number;
+}
+export interface LeastSquaresOptions {
+    /**
+     * One weight per row, on R's `lm.wfit()` scale: the solver applies the
+     * square root itself.
+     *
+     * IRLS is the trap here. `glm.fit` carries square-root weights `w` and
+     * hands `x * w` to its QR routine, so a caller porting that loop passes
+     * `w * w` here, not `w`.
+     *
+     * A weight of zero drops the row from the fit. The row still gets a fitted
+     * value, predicted from the other rows, as it does in R.
+     */
+    readonly weights?: readonly number[];
+    /**
+     * How far a column's norm may collapse before the fit aliases it.
+     *
+     * A column is aliased when its norm, after the columns to its left are
+     * projected out, falls below this fraction of its original norm. The
+     * default is the value `lm.fit()` uses. `glm.fit()` passes
+     * `min(1e-7, epsilon / 1000)`, which is `1e-11` at R's default epsilon.
+     */
+    readonly tolerance?: number;
+}
+/** The rank tolerance of R's `lm.fit()`. */
+export declare const DEFAULT_LEAST_SQUARES_TOLERANCE = 1e-7;
+/**
+ * Fit `y` on the columns of `design` by least squares.
+ *
+ * @param design One row per observation, each row one value per column. A
+ *   model with an intercept carries a leading column of ones. The function
+ *   does not modify it.
+ * @param y The response, one value per row.
+ * @param options Weights and the rank tolerance.
+ * @returns The coefficients, the fit, and the rank.
+ * @throws RangeError if there are no rows, if the shapes disagree, or if a
+ *   weight is negative. R refuses the same inputs: "0 (non-NA) cases" and
+ *   "missing or negative weights not allowed".
+ */
+export declare function leastSquares(design: readonly (readonly number[])[], y: readonly number[], options?: LeastSquaresOptions): LeastSquaresFit;
+//# sourceMappingURL=ols.d.ts.map

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

@@ -0,0 +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"}

package/dist/core/pca.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Principal components of a set of two-dimensional points.
+ *
+ * This is the statistics half of `plot_pca()` in the R package, which calls
+ * `prcomp(mc_points, scale. = FALSE)`. Verified against R in `pca.test.ts`.
+ *
+ * Three things are worth knowing before reading the code.
+ *
+ * **The data is always centered.** R's `plot_pca()` has a `meancenter`
+ * argument, but it does not decide whether the components are computed on
+ * centered data: `prcomp()` centers again on its own, so `sdev`, `rotation`
+ * and the scores come out identical either way (fixture F7 shows the two runs
+ * bit for bit). All `meancenter` changes is where the arrows are anchored on
+ * screen, which is a drawing decision. So this module has no such option, and
+ * the plot layer owns the anchor.
+ *
+ * **The method is a closed form, not R's SVD.** R decomposes the centered
+ * data matrix; this port takes the eigenvectors of the 2x2 covariance matrix,
+ * which for two dimensions is a few lines of algebra with no iteration. The
+ * covariance route squares the data and so gives up a few bits that an SVD
+ * keeps, but at two dimensions the results agree with R far inside the
+ * tolerance the tests demand.
+ *
+ * **Signs are this port's own.** `?prcomp` states that the signs of the
+ * rotation columns are arbitrary and vary between programs and even between
+ * builds of R. Rather than chase LAPACK, this module fixes its own rule: in
+ * each column, the loading of larger magnitude is non-negative, and a tie
+ * goes to a non-negative x. Nothing on screen changes — `plot_pca()` draws
+ * each component as a two-headed arrow through the center, which is symmetric
+ * under a sign flip — but a caller reading the numbers gets one answer for
+ * one input instead of a platform's answer.
+ */
+import type { Point } from "./regression";
+/**
+ * One component's loading vector, as `[x, y]`.
+ *
+ * These are the two entries of one *column* of R's `rotation` matrix: R
+ * prints that matrix with a row per input variable, so R's `rotation["x",
+ * "PC1"]` is `rotation[0][0]` here and `rotation["y", "PC1"]` is
+ * `rotation[0][1]`.
+ */
+export type Loadings = readonly [number, number];
+/** The components of a point set, in the shape of R's `prcomp` result. */
+export interface PcaResult {
+    /**
+     * The standard deviation along each component, largest first. R's `sdev`,
+     * computed with the n − 1 divisor.
+     */
+    readonly sdev: readonly [number, number];
+    /**
+     * The two loading vectors: `rotation[0]` is PC1, `rotation[1]` is PC2.
+     * They are orthonormal, so `rotation[1]` is `rotation[0]` turned a quarter
+     * turn, up to the sign rule described above.
+     */
+    readonly rotation: readonly [Loadings, Loadings];
+    /**
+     * The mean of each coordinate — the point the components pass through.
+     *
+     * R's own `pca$center` reports whatever `prcomp` had left to subtract,
+     * which is near zero when `plot_pca()` centered the data first. This field
+     * is instead the true column mean, which R prints as `mc_diff`.
+     */
+    readonly center: Point;
+    /**
+     * The points in component coordinates, in input order. R's `pca$x`, with
+     * `x` holding the PC1 score and `y` the PC2 score. Both coordinates are
+     * NaN where the point was dropped for a missing value.
+     */
+    readonly scores: readonly Point[];
+}
+/**
+ * Compute the two principal components of the points.
+ *
+ * A single point is a valid input: it has no spread, so both standard
+ * deviations are 0 and the components fall back to the coordinate axes,
+ * which is what `prcomp` reports for the one component it returns at that
+ * size. (R returns `min(n, p)` components and so gives one column there;
+ * this port always returns two, matching its behavior on every other
+ * degenerate input — see the note on rank below.) `plot_pca()` never gets
+ * that far anyway: it draws points and no arrows below three of them.
+ *
+ * Rank is never reduced. R's `prcomp` drops a component only when given a
+ * `tol`, which `plot_pca()` never passes, so collinear, identical and
+ * constant-column inputs all still return two components. This function does
+ * the same and lets a near-zero `sdev[1]` say that the second direction
+ * carries no spread.
+ *
+ * A point with a non-finite coordinate is dropped before the components are
+ * computed, R's `na.omit`; its scores report NaN in both coordinates,
+ * keeping input order (the `na.exclude` padding `moderationSurface` uses).
+ * R's own `prcomp()` errors on a missing value, so the R usage this mirrors
+ * is `prcomp(na.omit(points))` — the fold-in keeps a spreadsheet with one
+ * missing row from blanking the whole picture.
+ *
+ * @param points The observations. The function does not modify them.
+ * @returns The components, or null if no point is complete.
+ */
+export declare function principalComponents(points: readonly Point[]): PcaResult | null;
+//# sourceMappingURL=pca.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"pca.d.ts","sourceRoot":"","sources":["../../src/core/pca.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAIH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AAE1C;;;;;;;GAOG;AACH,MAAM,MAAM,QAAQ,GAAG,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAEjD,0EAA0E;AAC1E,MAAM,WAAW,SAAS;IACxB;;;OAGG;IACH,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACzC;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,EAAE,SAAS,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;IACjD;;;;;;OAMG;IACH,QAAQ,CAAC,MAAM,EAAE,KAAK,CAAC;IACvB;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,SAAS,KAAK,EAAE,CAAC;CACnC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,SAAS,KAAK,EAAE,GACvB,SAAS,GAAG,IAAI,CAuClB"}

package/dist/core/precision.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Report the machine precision of the runtime.
+ *
+ * The value is the smallest number x such that 1 + x is not equal to 1.
+ * It is the equivalent of `.Machine$double.eps` in R.
+ *
+ * @returns The double-precision epsilon.
+ */
+export declare function machinePrecision(): number;
+//# sourceMappingURL=precision.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"precision.d.ts","sourceRoot":"","sources":["../../src/core/precision.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,CAEzC"}

package/dist/core/pretty.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Round numbers covering a range — R's `pretty()`.
+ *
+ * R places histogram cell edges and axis labels with this. It picks a cell
+ * size from the ladder 1, 2, 5, 10 times a power of ten, then rounds the low
+ * end down and the high end up to multiples of that size. The result
+ * therefore **covers** the range it was given, and usually extends past both
+ * ends.
+ *
+ * That widening is the whole point, and it is what separates this from
+ * `prettyTicks` in `src/plot/axes.ts`, which keeps ticks inside a window the
+ * caller has already fixed. Do not swap one for the other: a histogram drawn
+ * on ticks that stop short of the data loses its outer cells, and a fixed
+ * plot window drawn on widened ticks grows past its frame.
+ *
+ * The port follows R's C routine `R_pretty` step for step, including its
+ * rounding guard of 1e-10 and its bias toward 2 and 5 over stepping straight
+ * to the next power of ten. Verified against R 4.5.3 in `pretty.test.ts` and
+ * across a sweep of 5348 random ranges, every one of which it reproduces
+ * edge for edge. R's remaining tuning arguments (`shrink.sml`, `high.u.bias`,
+ * `u5.bias`, `eps.correct`, `f.min`) stay at their defaults: nothing in the
+ * package changes them, and each one is a branch that could only be guessed
+ * at rather than tested.
+ */
+/** What the caller may change. R's tuning arguments are not ported. */
+export interface RPrettyOptions {
+    /**
+     * About how many cells to produce. R's `n`, default 5. It is a wish, not a
+     * count: the returned array can hold more or fewer edges.
+     */
+    readonly n?: number;
+    /**
+     * The fewest cells to accept. R's `min.n`, default `floor(n / 3)`. R's
+     * `hist()` passes 1 here rather than taking this default.
+     */
+    readonly minN?: number;
+}
+/**
+ * Return round numbers that cover the range from `lo` to `up`.
+ *
+ * @param lo The low end of the range to cover.
+ * @param up The high end. It must not be below `lo`.
+ * @param options The wished-for cell count and the fewest cells to accept.
+ * @returns The edges, in increasing order. Always at least two, except for
+ *   the degenerate request of no cells at all.
+ * @throws RangeError If an end is not finite, if `up` is below `lo`, if a
+ *   count is negative or fractional, or if `minN` is above `n` (R stops with
+ *   "invalid 'min.n' argument").
+ */
+export declare function rPretty(lo: number, up: number, options?: RPrettyOptions): number[];
+//# sourceMappingURL=pretty.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"pretty.d.ts","sourceRoot":"","sources":["../../src/core/pretty.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAgBH,uEAAuE;AACvE,MAAM,WAAW,cAAc;IAC7B;;;OAGG;IACH,QAAQ,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,OAAO,CACrB,EAAE,EAAE,MAAM,EACV,EAAE,EAAE,MAAM,EACV,OAAO,GAAE,cAAmB,GAC3B,MAAM,EAAE,CAiCV"}

package/dist/core/regression.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Ordinary least-squares regression of y on x.
+ *
+ * This is the statistics half of `plot_regression()` in the R package. R gets these
+ * numbers from `lm()`, `cor()`, and `summary()$r.squared`. Verified against R
+ * in `regression.test.ts`.
+ */
+/** One observation. R holds these as rows of a data frame. */
+export interface Point {
+    readonly x: number;
+    readonly y: number;
+}
+/**
+ * The indices of the rows a fit may use: both coordinates finite.
+ *
+ * This is R's `na.omit` for a set of points. NaN is this library's missing
+ * value, and an infinity would poison a fit the same way, so "complete" means
+ * finite everywhere — the rule `moderationSurface` set for frames. The point
+ * cores (this module, `logit.ts`, `pca.ts`) share the rule through this
+ * helper.
+ */
+export declare function completePointRows(points: readonly Point[]): readonly number[];
+/**
+ * The result of a fit.
+ *
+ * A `null` field is the equivalent of R's `NA`. R drops a singular predictor
+ * and reports `NA` for its coefficient. This port reports `null`, which makes
+ * strict TypeScript force the caller to handle the degenerate fit.
+ */
+export interface RegressionFit {
+    /** The y value where the line crosses x = 0. */
+    readonly intercept: number;
+    /** The change in y for each unit of x. Null if x has no variation. */
+    readonly slope: number | null;
+    /** Pearson r. Null if x or y has no variation. */
+    readonly correlation: number | null;
+    /** Sum of squares regression. */
+    readonly ssr: number;
+    /** Sum of squares error. */
+    readonly sse: number;
+    /** Sum of squares total. */
+    readonly sst: number;
+    /** The part of SST that the fit explains. Null if SST is 0. */
+    readonly rSquared: number | null;
+    /**
+     * The fitted y value of each point, in input order. NaN where the point
+     * was dropped for a missing value.
+     */
+    readonly fitted: readonly number[];
+}
+/**
+ * Fit a line to the points.
+ *
+ * With no variation in x, the function fits the mean of y and reports no
+ * slope. R does the same: it drops the singular predictor and fits an
+ * intercept-only model. A single point is that same case.
+ *
+ * A point with a non-finite coordinate is dropped before fitting, R's
+ * `na.action = na.omit`; its fitted value reports NaN, keeping input order
+ * (R's `na.exclude` padding, as `moderationSurface` does). R's `lm()` errors
+ * when every row is missing ("0 (non-NA) cases"); this port already answers
+ * null for "nothing to fit", and an all-missing input is that same answer.
+ *
+ * @param points The observations. The function does not modify them.
+ * @returns The fit, or null if no point is complete.
+ */
+export declare function linearRegression(points: readonly Point[]): RegressionFit | null;
+//# sourceMappingURL=regression.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"regression.d.ts","sourceRoot":"","sources":["../../src/core/regression.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,8DAA8D;AAC9D,MAAM,WAAW,KAAK;IACpB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,SAAS,KAAK,EAAE,GAAG,SAAS,MAAM,EAAE,CAI7E;AAED;;;;;;GAMG;AACH,MAAM,WAAW,aAAa;IAC5B,gDAAgD;IAChD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,sEAAsE;IACtE,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,kDAAkD;IAClD,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC,iCAAiC;IACjC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,4BAA4B;IAC5B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,4BAA4B;IAC5B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,+DAA+D;IAC/D,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC;;;OAGG;IACH,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;CACpC;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,SAAS,KAAK,EAAE,GACvB,aAAa,GAAG,IAAI,CAkDtB"}

package/dist/core/rng.d.ts

@@ -0,0 +1,206 @@
+/**
+ * Seedable random draws for the sampling demonstrations.
+ *
+ * R gets these from `runif()`, `rnorm()`, and `sample()`, which all read one
+ * global Mersenne Twister stream. This port makes the generator an argument
+ * instead. A pure core cannot hold a stream, and a demonstration that a
+ * student reloads must show the same numbers.
+ *
+ * The generator does not reproduce R's stream. No JavaScript generator does,
+ * and the port plan does not ask for it. The requirement is that one seed
+ * always gives one sequence, in this run and in every later run.
+ *
+ * The generator is mulberry32 (Tommy Ettinger, public domain): 32 bits of
+ * state, four integer operations per draw, a period of 2^32, and a published
+ * result on the gjrand test suite. It is small enough to read in full below,
+ * which matters more here than statistical strength — these draws teach the
+ * sampling distribution, they do not protect anything. Do not use this module
+ * for cryptography.
+ */
+/** A source of uniform values in the interval [0, 1). */
+export type Rng = () => number;
+/** The parameters of `runif`. The defaults are the defaults of R's `runif`. */
+export interface RunifOptions {
+    /** The low end of the interval. */
+    readonly min?: number;
+    /** The high end of the interval. The generator never returns it. */
+    readonly max?: number;
+}
+/** The parameters of `rnorm`. The defaults are the defaults of R's `rnorm`. */
+export interface RnormOptions {
+    /** The center of the distribution. */
+    readonly mean?: number;
+    /** The standard deviation. A negative value gives NaN, as in R. */
+    readonly sd?: number;
+}
+/**
+ * The parameters of `rlnorm`. The defaults are the defaults of R's `rlnorm`.
+ *
+ * Both name the normal distribution behind the exponential, not the lognormal
+ * distribution itself.
+ */
+export interface RlnormOptions {
+    /** The center of the normal behind the exponential. */
+    readonly meanlog?: number;
+    /**
+     * The standard deviation of the normal behind the exponential. A negative
+     * value gives NaN, as in R.
+     */
+    readonly sdlog?: number;
+}
+/**
+ * The parameters of `rcauchy`. The defaults are the defaults of R's
+ * `rcauchy`.
+ */
+export interface RcauchyOptions {
+    /** The center of the distribution. It is the median, not a mean. */
+    readonly location?: number;
+    /** The half-width at half-maximum. A negative value gives NaN, as in R. */
+    readonly scale?: number;
+}
+/**
+ * Make a generator from a seed.
+ *
+ * Two generators of one seed give the same sequence. The seed keeps only its
+ * integer part, and only the low 32 bits of that.
+ *
+ * @param seed The start state. It must be finite.
+ * @returns A generator of uniform values in [0, 1).
+ * @throws RangeError If the seed is not finite.
+ */
+export declare function seededRng(seed: number): Rng;
+/**
+ * Draw uniform values.
+ *
+ * The function takes one value from the generator for each result, in order.
+ *
+ * An interval with `min` above `max`, or with a bound that is not finite,
+ * gives NaN for every result and takes nothing from the generator. R does the
+ * same, with a warning that a library cannot give.
+ *
+ * @param rng The source of randomness.
+ * @param n How many values to draw. It must be a non-negative integer.
+ * @param options The interval. The default is [0, 1).
+ * @returns The drawn values.
+ * @throws RangeError If n is negative or is not an integer.
+ */
+export declare function runif(rng: Rng, n: number, options?: RunifOptions): number[];
+/**
+ * Draw normal values.
+ *
+ * The function uses the Box-Muller transform, which makes two independent
+ * standard normal values from two uniform values. It takes the values in
+ * pairs: the first value of a pair gives the radius, the second gives the
+ * angle. An odd count discards the second value of the last pair, so the
+ * count of draws from the generator is always `2 * ceil(n / 2)`.
+ *
+ * The radius is `sqrt(-2 * log(1 - u))`, not `sqrt(-2 * log(u))`. The
+ * generator can return an exact 0 but never returns 1, and `log(0)` is not
+ * finite. The subtraction moves the open end of the interval to the point
+ * where the logarithm needs it.
+ *
+ * A `mean` that is not finite, or an `sd` that is negative or not finite,
+ * gives NaN for every result and takes nothing from the generator, as in R.
+ *
+ * @param rng The source of randomness.
+ * @param n How many values to draw. It must be a non-negative integer.
+ * @param options The center and the spread. The default is the standard
+ *   normal distribution.
+ * @returns The drawn values.
+ * @throws RangeError If n is negative or is not an integer.
+ */
+export declare function rnorm(rng: Rng, n: number, options?: RnormOptions): number[];
+/**
+ * Draw Student t values.
+ *
+ * Each value is `z / sqrt(chiSquare / df)`: a standard normal draw over the
+ * square root of a scaled chi-square. The chi-square is the sum of `df`
+ * squared standard normal draws. The draws come in bulk: one `rnorm` call of
+ * length `n` for the numerators, then `df` further calls of length `n`, one
+ * per chi-square component. Each `rnorm` call takes `2 * ceil(n / 2)` values
+ * from the generator, so `rt` takes `(df + 1) * 2 * ceil(n / 2)`.
+ *
+ * R's `rt` accepts any `df > 0`, through a gamma sampler. A gamma sampler
+ * rejects and redraws, so it cannot state a draw count. This port accepts a
+ * positive integer `df` only, which the normal construction covers with a
+ * fixed draw count. A `df` that is not a positive finite integer gives NaN
+ * for every result and takes nothing from the generator, as `rnorm` does for
+ * a bad `sd`.
+ *
+ * @param rng The source of randomness.
+ * @param n How many values to draw. It must be a non-negative integer.
+ * @param df The degrees of freedom. It must be a positive integer.
+ * @returns The drawn values.
+ * @throws RangeError If n is negative or is not an integer.
+ */
+export declare function rt(rng: Rng, n: number, df: number): number[];
+/**
+ * Draw lognormal values.
+ *
+ * A lognormal value is the exponential of a normal one, so this draws from
+ * `rnorm` at `meanlog` and `sdlog` and exponentiates each value. The draw
+ * count is therefore `rnorm`'s, `2 * ceil(n / 2)`.
+ *
+ * The parameters name the normal distribution behind the exponential, not the
+ * distribution the function returns. R names them the same way. Every draw is
+ * above zero, and the shape leans right: the median is `exp(meanlog)` and the
+ * mean sits above it.
+ *
+ * A `meanlog` that is not finite, or an `sdlog` that is negative or not
+ * finite, gives NaN for every result and takes nothing from the generator, as
+ * `rnorm` does.
+ *
+ * @param rng The source of randomness.
+ * @param n How many values to draw. It must be a non-negative integer.
+ * @param options The center and the spread of the normal behind the
+ *   exponential. The default is the standard normal, as in R.
+ * @returns The drawn values.
+ * @throws RangeError If n is negative or is not an integer.
+ */
+export declare function rlnorm(rng: Rng, n: number, options?: RlnormOptions): number[];
+/**
+ * Draw Cauchy values.
+ *
+ * This is R's `rcauchy(n, location, scale)`, by the inverse rule: the Cauchy
+ * quantile function is `location + scale * tan(pi * (u - 0.5))`, so applying
+ * it to uniform draws gives Cauchy draws. The draws come in one `runif` call
+ * of length `n`, so the function takes exactly `n` values from the generator.
+ *
+ * The Cauchy has no mean and no variance. Its center is the `location`, which
+ * is the median, and its spread is the `scale`, the half-width at half of the
+ * peak density. The tails are heavy enough that averages of draws do not
+ * settle, which is what the sampling demonstrations use it for.
+ *
+ * A `location` that is not finite, or a `scale` that is negative or not
+ * finite, gives NaN for every result and takes nothing from the generator,
+ * as in R.
+ *
+ * @param rng The source of randomness.
+ * @param n How many values to draw. It must be a non-negative integer.
+ * @param options The center and the spread. The default is the standard
+ *   Cauchy distribution.
+ * @returns The drawn values.
+ * @throws RangeError If n is negative or is not an integer.
+ */
+export declare function rcauchy(rng: Rng, n: number, options?: RcauchyOptions): number[];
+/**
+ * Take values from a population, without replacement.
+ *
+ * This is R's `sample(values, k)`, which also samples without replacement by
+ * default. The algorithm is a partial Fisher-Yates shuffle: step `i` takes one
+ * value from the generator and swaps position `i` with position
+ * `i + floor(u * (length - i))`, so each step selects from the values that no
+ * earlier step took. The function takes exactly `k` values from the generator.
+ *
+ * The function copies the population. It does not modify the input.
+ *
+ * @param rng The source of randomness.
+ * @param values The population. Any element type is permitted.
+ * @param k How many values to take. It must be a non-negative integer.
+ * @returns The taken values, in the order the algorithm found them.
+ * @throws RangeError If k is negative, is not an integer, or is more than the
+ *   size of the population. R gives the same error: "cannot take a sample
+ *   larger than the population when 'replace = FALSE'".
+ */
+export declare function sampleWithoutReplacement<T>(rng: Rng, values: readonly T[], k: number): T[];
+//# sourceMappingURL=rng.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"rng.d.ts","sourceRoot":"","sources":["../../src/core/rng.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAIH,yDAAyD;AACzD,MAAM,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC;AAE/B,+EAA+E;AAC/E,MAAM,WAAW,YAAY;IAC3B,mCAAmC;IACnC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,oEAAoE;IACpE,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,+EAA+E;AAC/E,MAAM,WAAW,YAAY;IAC3B,sCAAsC;IACtC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,mEAAmE;IACnE,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B,uDAAuD;IACvD,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B;;;OAGG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,oEAAoE;IACpE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,2EAA2E;IAC3E,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;;;GASG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,GAAG,CAa3C;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,KAAK,CACnB,GAAG,EAAE,GAAG,EACR,CAAC,EAAE,MAAM,EACT,OAAO,GAAE,YAAiB,GACzB,MAAM,EAAE,CASV;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,KAAK,CACnB,GAAG,EAAE,GAAG,EACR,CAAC,EAAE,MAAM,EACT,OAAO,GAAE,YAAiB,GACzB,MAAM,EAAE,CAeV;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,CAAC,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,EAAE,CAgB5D;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,MAAM,CACpB,GAAG,EAAE,GAAG,EACR,CAAC,EAAE,MAAM,EACT,OAAO,GAAE,aAAkB,GAC1B,MAAM,EAAE,CAGV;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,OAAO,CACrB,GAAG,EAAE,GAAG,EACR,CAAC,EAAE,MAAM,EACT,OAAO,GAAE,cAAmB,GAC3B,MAAM,EAAE,CAWV;AASD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,wBAAwB,CAAC,CAAC,EACxC,GAAG,EAAE,GAAG,EACR,MAAM,EAAE,SAAS,CAAC,EAAE,EACpB,CAAC,EAAE,MAAM,GACR,CAAC,EAAE,CAmBL"}