@compstats/core 0.2.0 → 0.4.0

package/CHANGELOG.md

@@ -3,6 +3,111 @@
 All notable changes to `@compstats/core`. The R package this ports keeps its
 own history in [`NEWS.md`](https://github.com/compstatslib/compstatslib/blob/main/NEWS.md).
 
+## 0.4.0
+
+### Added
+
+* A linear-algebra entry point, `@compstats/core/linalg`, built as
+  `dist/linalg.js` with no dependency and no Plotly. Base R hands the R package
+  `matrix()`, `%*%`, `solve()`, `qr()`, `model.matrix()`, `lm()`, `eigen()` and
+  `prcomp()` for free; a JavaScript application has none of them, so the port
+  writes them in R's vocabulary over a plain column-major `Matrix`
+  (`{ nrow, ncol, data: Float64Array, dimnames }`) — plain data, not a class,
+  so a matrix serializes, clones and crosses a worker boundary as it is. The
+  main entry does not re-export it: a page that draws only the 2D demos never
+  loads it. The names:
+  * matrices — `matrix`, `fromRows`, `fromColumns`, `fromFrame`, `at`, `row`,
+    `column`, `toRows`, `toColumns`;
+  * elementary operations — `t` (also `transpose`, for an app whose `t` is its
+    translation function), `matmul`, `crossprod`, `tcrossprod`, `cbind`,
+    `rbind`, `diag`, `identity`;
+  * vectors — `add`, `sub`, `mul`, `div`, `square`, `dot`, `norm`, `cosine`:
+    R's operators by name, with a scalar recycled and any other length
+    mismatch refused; and the `Vector` type they are written over, which is
+    `readonly number[]` and nothing more — a name for the concept in a
+    signature, erased at compile time, so a plain array is a vector and
+    nothing needs wrapping;
+  * QR — `qr` with `qrCoef`, `qrFitted`, `qrResid`, `qrQty`, `qrQy`, `qrQ`,
+    `qrR`, which is the LINPACK `dqrdc2` factorization `lm.fit()` runs on,
+    promoted out of `leastSquares` (now a wrapper over it, with every existing
+    value unchanged);
+  * LU — `lu`, `solve`, `det`, `determinant`, `rcond`, `matrixNorm`;
+  * models — `modelMatrix`, `lm`, and the `NamedVector` that carries R's named
+    coefficients in R's order (`namedVector`, `lookup`);
+  * multivariate — `cov`, `cor`, `variance`, `eigenSymmetric`, `isSymmetric`,
+    `prcomp`.
+
+  Every routine is verified against R 4.5.3 in
+  `conformance-fixtures/linalg.R` of the R package. The factorizations, the
+  solves, the determinant and the fitted values of `lm` pin bit for bit
+  against R's reference-BLAS build (which contracts a multiply and an add into
+  one rounding, as the port does with `fusedMultiplyAdd`); the summary
+  statistics, eigenvalues and standard deviations are verified at a relative
+  `1e-12`. Where R warns and recycles, or silently reads only half of a
+  matrix, the port refuses, and each such narrowing is stated at the function.
+
+### Changed
+
+* `moderationSurface()` fits through the new `lm()` instead of building R's
+  model matrix itself. Its fitted values and residuals are now R's exactly —
+  all 200 of each, for all three pinned models, against 16 of 200 at 8.6e-15
+  before. R's `lm.fit` reports the residuals its factorization computes and
+  takes the fitted values as the outcome minus them; the old path re-summed
+  `X · β`, which lands a few bits away. Coefficients, grid, surface and `zlim`
+  are unchanged. A caller who compared residuals against `y - fitted` with
+  `===` will now see a difference in the last bit, as R does on 93 of the 200
+  rows.
+
+### Bug fixes
+
+* `eigenSymmetric()` refuses what R's `eigen()` refuses, in R's order and R's
+  words: a non-square matrix, then a 0 x 0 one, then a missing or infinite
+  entry. A NaN used to run the Jacobi sweeps and return a result full of NaN,
+  and a 0 x 0 matrix used to return an empty decomposition.
+* `prcomp()` carries the row names of its input onto the scores, as R does.
+  The rotation already carried the variable names.
+* `leastSquares()` no longer overflows the call stack on a long design. The
+  column norm was `Math.hypot(...column)`, a spread that dies at about a
+  million arguments; it is a fold now, and it follows the BLAS `dnrm2` R runs,
+  which also moved the Householder vectors of the factorization onto R's
+  doubles exactly. No coefficient, fitted value or residual changed.
+* `fusedMultiplyAdd()` keeps the sign of a zero product, as the hardware
+  instruction does: `fma(-1, 0, -0)` is `-0`. No pinned value changed.
+
+## 0.3.0
+
+### Added
+
+* `plotSampling()` takes a `mark` option and marks the chosen statistic on all
+  three panels, in one color. The library computes two of the three numbers:
+  the statistic of the pooled sample, and the average of every statistic drawn
+  so far. It takes the third from the caller, because the true value in the
+  population is a fact about the shape and not about the values in the array. A
+  Cauchy population has no mean, and the arithmetic mean of a finite draw from
+  it is still a number. `mark.populationValue: null` says the population has no
+  such value, and the panel writes `no true <label>` in place of the line. A
+  location statistic draws a line, a spread draws a span around a center, and
+  the third panel always draws a line, because its axis holds the value of the
+  statistic. A mark outside the frozen window draws a caret at that edge, so a
+  clipped mark and an absent mark do not look the same. The new `marks` field
+  of the result reports the three numbers, and reports null for each one that
+  does not exist. A call that passes no `mark` draws what it drew before, and
+  gets `marks: null`. `interactiveSampling()` forwards the option, as it
+  forwards every other plot option.
+
+### Changed
+
+* `plotly.js-dist-min` moves from a runtime dependency to an **optional peer
+  dependency**. Installing `@compstats/core` brought in 5.9 MB of 3D engine
+  even for a page that draws only 2D. It now installs 1.3 MB, and a consumer
+  who uses the `/3d` entry adds `plotly.js-dist-min` to its own dependencies —
+  which the two known consumers already did, because a bundler needs the
+  package named where it is imported. No source and no bundle changed:
+  `dist/3d.js` still reaches Plotly through the same lazy `import()`, and
+  passing your own engine in the `plotly` option still keeps that import
+  unreached. If Plotly is absent, that load now fails with
+  `Cannot find package 'plotly.js-dist-min'` instead of succeeding.
+
 ## 0.2.0
 
 The first npm release. It follows the R package's own 0.8.0 release, which

package/README.md

@@ -2,21 +2,22 @@
 
 [![CI](https://github.com/compstatslib/compstatslib-ts/actions/workflows/ci.yml/badge.svg)](https://github.com/compstatslib/compstatslib-ts/actions/workflows/ci.yml)
 
-Interactive gadgets and plotting functions for data sets and statistical
-concepts, in two and three dimensions. This is the browser port of the R
-package [`compstatslib`](https://github.com/compstatslib/compstatslib).
-
-Some of it works on **your own data**. Explore any data frame as a rotatable
-3D point cloud. Fit a moderated (interaction) regression and rotate its
-surface to see how the interaction twists it away from a plane. The rest
-**simulates a concept** instead of plotting your data — sampling
-distributions, confidence intervals, t-statistics, matrix inversion. That part
-is built for class demonstrations, homework, and self-study.
-
-The R original runs in RStudio. This port runs in a browser, with no R
-installation and no server. The 2D plots draw on a plain Canvas 2D context.
-The 3D plots draw through Plotly, behind a separate entry point, so a page
-that shows only 2D never loads it.
+**Statistical routines for TypeScript, checked against R.**
+
+The package brings statistical primitives and visualization tools to the TypeScript/JavaScript ecosystem. In both sets of features, this package seeks to attain reasonable parity with equivalent functions from the [R platform](https://www.r-project.org) where statistical routines are well vetted. The routines are largely ported from R implementations and the test suite compares each routine against equivalent procedures run in R on the same input and pins the answer to R's output, given a tolerance. The long-term vision of this package is to bring more of R's statistical judgment and rigor into TypeScript/JavaScript.
+
+**For statistical tasks**, this package: (1) provides types for vector, dataframe, and matrix representations; and (2) fits linear models, factors matrices, finds principal components, and evaluates distributions. The statistical routines can run browser-side or server-side, and can be used in both TypeScript and JavaScript.
+
+- **Matrices and linear algebra.** A plain matrix type with multiplication, transpose, inverse, determinant, condition number, and the two workhorse factorizations (QR and LU) that every solver and model fit is built on, plus covariance and correlation matrices, symmetric eigendecomposition and principal components.
+- **Models.** Fit a linear model from a table of columns and a list of terms, interactions included, and read back coefficients, standard errors, t and p values, R², the F statistic, fitted values and residuals. Fit logistic regression using data with a binary column.
+- **Distributions and random draws.** The Student t distribution — density, cumulative probability and quantiles — and reproducible draws from the uniform, normal, t, log-normal and Cauchy distributions, all from a seeded generator you pass in, so a demonstration or a test repeats exactly.
+- **Summaries and shaping.** Means, medians, standard deviations and quantiles that follow the same definitions R uses; kernel density estimation with its bandwidth rule; histogram binning with its bin-count rule; and the algorithm that picks readable axis tick marks.
+
+**For visualization tasks** this package ports functions from its R sibling [`compstatslib`](https://github.com/compstatslib/compstatslib). Explore any table as a rotatable 3D point cloud. Fit a moderated (interaction) regression and turn its surface to watch the interaction twist it away from a plane. Click points onto a canvas and see a regression line, a logistic curve or a principal-component axis follow your mouse. Other components simulate a concept rather than your data — sampling distributions, confidence intervals, t-tests, matrix inversion — for class demonstrations, homework and self-study. Those demonstrations are also what the statistics were built for, and they are the standing proof that the statistics work.
+
+The 2D plots draw on a plain Canvas 2D context. The 3D plots draw through Plotly.
+
+**Vision.** This package aims to bring more of R's core algorithms to TypeScript/JavaScript. The statistical routines currently support the visualization tools and demonstrations. As of now, there is no general framework for generalized linear models beyond logistic regression, and no singular value decomposition. But such features will likely be added in the future based on demand.
 
 ## Install
 
@@ -26,13 +27,52 @@ npm install @compstats/core
 bun add @compstats/core
 ```
 
-Plotly is only needed for the 3D functions. See
-[3D and Plotly](#3d-and-plotly) below.
+The core install is small, because it has no large dependencies. Plotly is an **optional peer dependency**: the package declares it, but no package manager installs it for you. A page that only computes statistics, or only plots in 2D, never downloads it.
+
+Add Plotly yourself when you use the 3D functions:
+
+```bash
+npm install plotly.js-dist-min
+# or
+bun add plotly.js-dist-min
+```
+
+See [3D and Plotly](#3d-and-plotly) below.
 
 ## Quick start
 
-Give an interactive component a canvas. It draws at once, and it redraws on
-every click.
+Fit a model. Your data is a table of columns; the model is the outcome and a list of terms, where an array of names is an interaction:
+
+```js
+import { lm } from "@compstats/core/linalg";
+import { moderationData } from "@compstats/core";
+
+const fit = lm(moderationData, { outcome: "y", terms: ["x", "z", ["x", "z"]] });
+
+fit.coefficients.names;         // ["(Intercept)", "x", "z", "x:z"]
+fit.coefficients.values;        // [-0.0452945…, 0.4720139…, 0.3136202…, 0.8481828…]
+fit.standardErrors.values[3];   // 0.019869806719131564
+fit.pValues.values[3];          // 3.4056449407081656e-101
+fit.rSquared;                   // 0.9203966770597701
+fit.sigma;                      // 1.0301490130678368
+```
+
+Summaries, correlations and reproducible random draws come the same way. The generator is passed in, never taken from `Math.random`, so the same seed gives the same numbers on every run and in every browser:
+
+```js
+import { cor } from "@compstats/core/linalg";
+import { sd, quantile, seededRng, rnorm } from "@compstats/core";
+
+cor(moderationData.x, moderationData.z);   // -0.08036538677894722
+sd(moderationData.y);                      //  3.6235641115369814
+
+const draws = rnorm(seededRng(42), 1000, { mean: 100, sd: 15 });
+quantile(draws, 0.975);                    // 129.24422658630283
+```
+
+Every number above is produced by the package and matched against the value R returns for the same input.
+
+None of that touches the DOM, so it runs under Node and Bun as readily as in a browser. When you do want a picture, hand a component a canvas — it draws at once and redraws on every click:
 
 ```html
 <canvas id="plot" width="640" height="480"></canvas>
@@ -51,8 +91,7 @@ every click.
 </script>
 ```
 
-The plot functions draw the same picture from data you already hold, and
-return what they computed:
+The plot functions draw the same picture from data you already hold, and return what they computed:
 
 ```js
 import { plotRegression } from "@compstats/core";
@@ -66,20 +105,9 @@ const fit = plotRegression(canvas, [
 console.log(fit.slope, fit.rSquared);
 ```
 
-The statistics are separate from the drawing. Import them alone when you want
-the numbers and not the picture:
-
-```js
-import { linearRegression, principalComponents, tTestStats } from "@compstats/core";
-```
-
-Nothing in the `core/` layer touches the DOM, so it also runs under Node or
-Bun.
-
 ## Use from a CDN
 
-The main bundle is self-contained browser ESM with no imports of its own. A
-page can load it directly, with no build step:
+The main bundle is self-contained browser ESM with no imports of its own. A page can load it directly, with no build step:
 
 ```html
 <script type="module">
@@ -103,9 +131,7 @@ The 3D functions live behind the `@compstats/core/3d` entry point:
 import { interactiveScatter3d, moderationData } from "@compstats/core/3d";
 ```
 
-That entry does not load Plotly either. It reaches the library through a
-dynamic import the first time it draws. A caller that passes its own engine in
-the `plotly` option never triggers that import:
+That entry does not load Plotly either. It reaches the library through a dynamic import the first time it draws. A caller that passes its own engine in the `plotly` option never triggers that import:
 
 ```html
 <script src="https://cdn.jsdelivr.net/npm/plotly.js-dist-min"></script>
@@ -122,9 +148,9 @@ the `plotly` option never triggers that import:
 </script>
 ```
 
-Pass `plotly` when you load the 3D entry from a raw file CDN such as jsDelivr,
-because nothing there resolves the bare `plotly.js-dist-min` specifier. esm.sh
-rewrites bare specifiers, so on esm.sh both ways work.
+Pass `plotly` when you load the 3D entry from a raw file CDN such as jsDelivr, because nothing there resolves the bare `plotly.js-dist-min` specifier. esm.sh rewrites bare specifiers, so on esm.sh both ways work.
+
+Under a bundler, the dynamic import needs Plotly in your own dependencies. If it is absent, the load fails with `Cannot find package 'plotly.js-dist-min'`. The two cures are the same two paths: install the optional peer, or pass your own engine in the `plotly` option and let the dynamic import stay unreached.
 
 ## How the functions are organized
 
@@ -132,16 +158,13 @@ Every family has three parts, and you can use any one of them alone:
 
 - a **core** function that computes the statistics and touches no DOM,
 - a **plot** function that draws it on a target you give it,
-- an **interactive** component that owns the input and hands each draw to the
-  plot function.
+- an **interactive** component that owns the input and hands each draw to the plot function.
 
-The families are grouped below by what they are *for*, because that varies
-more than the interaction style does.
+The families are grouped below by what they are *for*, because that varies more than the interaction style does.
 
 ### Data sets in 3D
 
-These accept any data frame, with control over axes, color mapping, aspect
-ratio, and camera. They come from `@compstats/core/3d`.
+These accept any data frame, with control over axes, color mapping, aspect ratio, and camera. They come from `@compstats/core/3d`.
 
 | Function | What it does |
 | --- | --- |
@@ -153,11 +176,7 @@ ratio, and camera. They come from `@compstats/core/3d`.
 
 ### 2D relationships
 
-These plot x / y points you supply, together with a fitted model. They are
-sized for small data — points clicked in by hand, or a modest table — and not
-for arbitrary data. `plotRegression` draws in a window of -5 to 50 unless you
-give it `xlim` and `ylim`, and the PCA functions expect points with an `x` and
-a `y`.
+These plot x / y points you supply, together with a fitted model. They are sized for small data — points clicked in by hand, or a modest table — and not for arbitrary data. `plotRegression` draws in a window of -5 to 50 unless you give it `xlim` and `ylim`, and the PCA functions expect points with an `x` and a `y`.
 
 | Function | What it does |
 | --- | --- |
@@ -171,8 +190,7 @@ a `y`.
 
 ### Simulations and concept demonstrations
 
-These do not plot your data. They simulate a process, or draw a geometric
-object, so that a concept can be watched instead of described.
+These do not plot your data. They simulate a process, or draw a geometric object, so that a concept can be watched instead of described.
 
 | Function | What it does |
 | --- | --- |
@@ -187,11 +205,7 @@ object, so that a concept can be watched instead of described.
 
 ### Statistics without a picture
 
-The R package never had to ship these. `mean()`, `sd()`, `quantile()`, `dt()`,
-`rnorm()`, `density()`, `hist()`, `pretty()`, `solve()` and `lm.fit()` are all
-in base R, and its functions call them. JavaScript has no statistics standard
-library, so the port wrote them — and exports them, because an application
-built on this package needs them for the same reason the package did.
+The routines the plots are built on are exported in their own right, because an application built on this package needs them for the same reason the plots did. Each follows the definition R uses — there is more than one reasonable definition of a quantile, of a histogram's bin count, of a kernel bandwidth, and picking a different one silently changes results — and the test suite pins each to the value R returns.
 
 | Group | Functions |
 | --- | --- |
@@ -200,12 +214,9 @@ built on this package needs them for the same reason the package did.
 | Seeded random draws | `seededRng`, `runif`, `rnorm`, `rt`, `rlnorm`, `rcauchy`, `sampleWithoutReplacement` |
 | Binning and density | `histogram`, `nclassSturges`, `kernelDensity`, `bwNrd0` |
 | Axis ticks | `rPretty`, `prettyTicks` |
-| Linear algebra | `leastSquares`, `determinant`, `invertMatrix` |
+| Fitting and 2x2 matrices | `leastSquares`, `determinant`, `invertMatrix` |
 
-Each one follows its R counterpart, down to the rule and the argument names:
-`quantile` is type 7, `nclassSturges` is Sturges' rule, `bwNrd0` is R's
-`nrd0` bandwidth, `rPretty` is `pretty()`, and the samplers take R's own
-parameters. The test suite pins them to values computed in R.
+The names say which rule was followed, for anyone checking: `quantile` is type 7, `nclassSturges` is Sturges' rule, `bwNrd0` is the `nrd0` bandwidth, `rPretty` is R's `pretty()`, and the samplers take R's own parameters. The general matrix routines — solving, factorizing, model fitting, principal components — live under [Linear algebra](#linear-algebra) below.
 
 The draws take a generator you pass in, so a demonstration repeats exactly:
 
@@ -217,25 +228,53 @@ const draws = rnorm(rng, 1000, { mean: 100, sd: 15 });
 quantile(draws, 0.975);
 ```
 
+### Linear algebra
+
+Matrix arithmetic, the factorizations that solvers and model fits are built on, and the multivariate routines that sit on top of them. They have their own entry point, so a page that only draws never loads them, and they keep R's names — an application that needs a QR decomposition is usually being written by someone who can already read one:
+
+```js
+import { matrix, matmul, solve, lm, prcomp } from "@compstats/core/linalg";
+```
+
+A matrix is plain data, laid out as R lays it out — **column-major**, with `nrow`, `ncol`, a `Float64Array` of the entries column by column, and optional `dimnames`. `matrix(values, { nrow })` fills column by column as R's `matrix()` does, and `byrow: true` fills by rows. Operations are functions that take matrices and return new ones; nothing modifies its input. Indices are zero-based. A vector is a plain array of numbers: the exported `Vector` type is a name for `readonly number[]` and nothing more, so a JavaScript caller passes an array as it always did.
+
+| Group | Functions |
+| --- | --- |
+| Building | `matrix`, `fromRows`, `fromColumns`, `fromFrame`, `at`, `row`, `column`, `toRows`, `toColumns` |
+| Elementary operations | `t` (or `transpose`), `matmul`, `crossprod`, `tcrossprod`, `cbind`, `rbind`, `diag`, `identity` |
+| Vectors | `add`, `sub`, `mul`, `div`, `square`, `dot`, `norm`, `cosine` |
+| QR | `qr`, `qrCoef`, `qrFitted`, `qrResid`, `qrQty`, `qrQy`, `qrQ`, `qrR` |
+| LU | `lu`, `solve`, `det`, `determinant`, `rcond`, `matrixNorm` |
+| Models | `modelMatrix`, `lm`, `namedVector`, `lookup` |
+| Multivariate | `cov`, `cor`, `variance`, `eigenSymmetric`, `isSymmetric`, `prcomp` |
+
+A model is a term list rather than a formula — R's `y ~ x * z + w` is `{ outcome: "y", terms: ["x", "z", "w", ["x", "z"]] }` — and `lm` returns the coefficients as a named vector in R's order, with `null` where R prints `NA`:
+
+```js
+import { lm, solve, matrix } from "@compstats/core/linalg";
+import { moderationData } from "@compstats/core";
+
+const fit = lm(moderationData, { outcome: "y", terms: ["x", "z", "w", ["x", "z"]] });
+fit.coefficients.names;   // ["(Intercept)", "x", "z", "w", "x:z"]
+fit.rSquared;             // 0.9204001958847745
+
+const a = matrix([2, 1, -1, 1, 3, 2, 1, -1, 4], { nrow: 3 });
+solve(a, [1, 2, 3]);      // [-0.06666666666666665, 0.8, 0.3333333333333333]
+```
+
+Each routine follows R down to the arithmetic of its LAPACK and LINPACK calls, so the factorizations, the solves and the fitted values match R's doubles exactly, and the rest is verified at a stated tolerance. Where R warns and recycles a mismatched length, or silently reads only the lower triangle of a matrix, this entry refuses and says so at the function.
+
 ### Bundled data
 
-`moderationData` (200 rows of `y`, `x`, `z`, `w`) and `pcaDegenerate` (16 rows
-of `x`, `y`) are the same tables as in the R package, exported from R rather
-than regenerated. Both are defaults, so a call with no data still gives a
-working demonstration.
+`moderationData` (200 rows of `y`, `x`, `z`, `w`) and `pcaDegenerate` (16 rows of `x`, `y`) are the same tables as in the R package, exported from R rather than regenerated. Both are defaults, so a call with no data still gives a working demonstration.
 
 ### Targets
 
-The click-to-add-points components take a `<canvas>`. The components that own
-sliders or menus take a container element and build their controls inside it.
-Each one also accepts an explicit `{ surface, element }` pair when you want to
-place the drawing surface and the controls yourself.
+The click-to-add-points components take a `<canvas>`. The components that own sliders or menus take a container element and build their controls inside it. Each one also accepts an explicit `{ surface, element }` pair when you want to place the drawing surface and the controls yourself.
 
 ## Reproducing an interactive session
 
-R's gadgets block until you click Done, and then print the `plot_*()` call
-that reproduces the screen. Nothing blocks in a browser. Each component
-returns a handle at once, and the handle carries the same state:
+R's gadgets block until you click Done, and then print the `plot_*()` call that reproduces the screen. Nothing blocks in a browser. Each component returns a handle at once, and the handle carries the same state:
 
 ```js
 const handle = interactiveTTest(container);
@@ -246,40 +285,22 @@ handle.done(); // hand the state to the onDone callback
 handle.destroy(); // stop listening and remove what was built
 ```
 
-`getValues()` returns the options that draw the same picture again. Pass them
-straight back to the matching plot function, or to the component itself. State
-you would not retype has its own accessor: `getFit()` for PCA, `getState()`
-for the accumulated sampling draws, `getSpec()` for the traces and layout of a
-3D draw.
+`getValues()` returns the options that draw the same picture again. Pass them straight back to the matching plot function, or to the component itself. State you would not retype has its own accessor: `getFit()` for PCA, `getState()` for the accumulated sampling draws, `getSpec()` for the traces and layout of a 3D draw.
 
 ## Differences from the R package
 
-The two packages compute the same statistics and draw the same pictures. The
-R idioms that a browser has no answer for are handled like this:
-
-- **Names.** `snake_case` becomes `camelCase`. `plot_regr()` is
-  `plotRegression()`, as it is in R since 0.8.0.
-- **Signatures.** R's positional arguments and `...` become a data argument
-  and one options object.
-- **Formulas.** `y ~ x * z` has no TypeScript counterpart. Name the columns
-  instead: `{ outcome: "y", iv: "x", mod: "z" }`.
-- **Data frames.** Point sets are arrays of records. Bundled tables are
-  objects of columns.
-- **Random numbers.** Draws take an injectable seeded generator, so a demo
-  repeats exactly. The stream does not match R's Mersenne Twister, and it is
-  not meant to.
-- **Devices.** Every plot function takes an explicit target. There is no
-  current device.
-
-One thing the port adds. It exports the statistical primitives that base R
-hands the R package for free — descriptives, the t distribution, seeded
-samplers, binning, density, axis ticks and small linear algebra, listed under
-[Statistics without a picture](#statistics-without-a-picture). This is an
-addition, not a divergence: each one follows its R counterpart's rule and is
-tested against R's output.
-
-The core statistics are asserted against values computed in R. The fixtures
-live in the R package under `conformance-fixtures/`.
+The two packages compute the same statistics and draw the same pictures. The R idioms that a browser has no answer for are handled like this:
+
+- **Names.** `snake_case` becomes `camelCase`. `plot_regr()` is `plotRegression()`, as it is in R since 0.8.0.
+- **Signatures.** R's positional arguments and `...` become a data argument and one options object.
+- **Formulas.** `y ~ x * z` has no TypeScript counterpart. Name the columns instead: `{ outcome: "y", iv: "x", mod: "z" }`.
+- **Data frames.** Point sets are arrays of records. Bundled tables are objects of columns.
+- **Random numbers.** Draws take an injectable seeded generator, so a demo repeats exactly. The stream does not match R's Mersenne Twister, and it is not meant to.
+- **Devices.** Every plot function takes an explicit target. There is no current device.
+
+Two things the port adds. It exports the statistical primitives that base R hands the R package for free — descriptives, the t distribution, seeded samplers, binning, density, axis ticks and small linear algebra, listed under [Statistics without a picture](#statistics-without-a-picture). And it carries a general [linear-algebra entry](#linear-algebra) — a column-major matrix, `solve`, `qr`, `lm`, `prcomp` and the rest — for the same reason. Both are additions, not divergences: each routine follows its R counterpart's rule and is tested against R's output.
+
+The core statistics are asserted against values computed in R. The fixtures live in the R package under `conformance-fixtures/`.
 
 ## Development
 
@@ -291,17 +312,13 @@ bun run build
 bun run dev      # demo site on http://localhost:3000
 ```
 
-Bun is the toolchain: runtime, package manager, test runner, and bundler. The
-demo site runs one page per function family and is the fastest way to see a
-change.
+Bun is the toolchain: runtime, package manager, test runner, and bundler. The demo site runs one page per function family and is the fastest way to see a change.
 
 ## Contributors
 
 `@compstats/core` and `compstatslib` are maintained by Soumya Ray.
 
-Daniele Melotti is a co-author of the R package. Several of the plotting and
-interactive functions grew out of work he did as a student under Soumya Ray's
-supervision, and were then folded back into the package.
+Daniele Melotti is a co-author of the R package. Several of the plotting and interactive functions grew out of work he did as a student under Soumya Ray's supervision, and were then folded back into the package.
 
 Issues and pull requests are welcome.