@numero-uno-jpn/rstats 0.0.0-stage → 0.6.1

package/CHANGELOG.md

@@ -0,0 +1,144 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+While the version is 0.x, a minor release (0.y.0) may contain breaking changes;
+they are listed under **Breaking** for each release. From 1.0.0 the project follows
+[Semantic Versioning](https://semver.org/).
+
+## 0.6.1 - 2026-10-24
+
+The first release of the 0.6 series on npm. A `v0.6.0` tag was pushed to GitHub earlier the same
+day but never published to npm and has been withdrawn; use 0.6.1.
+
+### Added
+
+- Everything jStat offers, with R's names and defaults, and a migration guide
+  ([docs/migrating-from-jstat.md](docs/migrating-from-jstat.md)) whose replacements are checked
+  against jStat itself (`test/jstat-replacement.test.ts`):
+  - descriptive statistics (`@numero-uno-jpn/rstats/descriptive`): `sum`, `prod`, `mean` (with `trim`),
+    `weightedMean`, `variance` (R's `var`), `sd`, `median`, `range`, `cumsum`, `cumprod`, `cummax`,
+    `cummin`, `diff`, `quantile` (all nine types), `IQR`, `fivenum`, `mad`, `rank`, `cov` and `cor`
+    for vectors and matrices (Pearson, Kendall, Spearman, with `use`), `tabulate`, `table`, `unique`,
+    `cut`, `findInterval`, `pretty`, `hist`, `ecdf`, `scale`, and `skewness`, `kurtosis` (e1071),
+    `geometricMean`, `modes`, `meanAD`, `cv` (DescTools); sums in double-double;
+  - matrix arithmetic: `matMul`, `add`, `subtract`, `multiply`, `divide`, `outer`, `t`, `diag`,
+    `cbind`, `rbind`, `matrix`, `kronecker`, `seq`, and `lu` (`Matrix::lu`) and `prcomp`;
+  - hypothesis tests: `binomTest`, `poissonTest`, `propTest`, `mcnemarTest`, `varTest`,
+    `bartlettTest`, `kruskalTest`, `friedmanTest`, `quadeTest`, `flignerTest`, `moodTest`,
+    `onewayTest`, `shapiroTest`, `mantelhaenTest`, `ansariTest`, `ksTest`, `pairwiseTTest`,
+    `pairwiseWilcoxTest`, `pairwisePropTest`, `aov` (one way), `TukeyHSD` and `zTest` (BSDA);
+  - linear models: `lm` with a matrix interface and the quantities of `summary.lm`, `confint`,
+    `predict`;
+  - numerical methods (`@numero-uno-jpn/rstats/numerics`): `integrate`, `optimize`, `uniroot` (with
+    `extendInt`), `approx`, `spline`, `splinefun`, `splinefunH`, `barylag` (pracma),
+    `hermiteInterp`, `ode` (fixed-step, deSolve), `grad`, `jacobian`, `hessian` (numDeriv);
+  - distributions outside base R with extraDistr's names: `invgamma`, `kumar`, `pareto`, `triang`,
+    `laplace`, and `arcsine` (d/p/q/r), and `distSummary` (mean, variance, sd, median, mode,
+    skewness, kurtosis) for 23 distributions (all but signrank, wilcox and tukey);
+  - special functions: `gammainc`, `erfinv`, `erfcinv`, `perm`.
+- Subpath exports and per-area CDN files: `@numero-uno-jpn/rstats/distributions`, `/tests`, `/linalg`,
+  `/descriptive`, `/numerics`, `/special` (`dist/<area>.js`, with shared code split out).
+- `choose`, `lchoose`, `factorial` and `lfactorial`, for any real `n` (and `x`).
+- `digamma`, `trigamma` and `psigamma` (derivatives up to 100, negative arguments by
+  reflection; unlike R, also for x < 0 with deriv ≥ 6).
+- `besselI`, `besselK` (with `exponScaled`, R's `expon.scaled`), `besselJ` and `besselY` for any
+  real order, ported from Boost.Math.
+- The option `rCompatible` of `choose`, `lchoose`, `trigamma` and `psigamma` (type
+  `RCompatibleOptions`): by default they follow R at its edge cases (n near an integer in
+  `choose`, infinite arguments); `rCompatible: false` returns the mathematical values there.
+- `erf` and `erfc`, which R lacks (checked against mpmath). `erfc` is now accurate in the far tail:
+  it forms exp(-x^2) from an exact x^2 and no longer flushes subnormal results to 0.
+- `dmultinom`, as a product of binomial probabilities (accurate for large counts).
+- The new functions are checked against R 4.5.2, and against mpmath (100 to 800 digits) where R
+  is inaccurate or fails (docs/differences-from-r.md).
+
+### Changed
+
+- Code that followed the GPL sources of R (and of BSDA, for `zTest`) too closely was re-implemented independently, so that the
+  package stays MIT licensed: `propTest`, the two-sided p-values of `poissonTest` and `binomTest`,
+  the exact 2 × 2 parts of `mantelhaenTest` and `fisherTest`, the intervals of `wilcoxTest`,
+  `zTest`, `approx`, `spline`, `splinefun`, `splinefunH`, `uniroot`, `seq`, `pretty`, `hist` and
+  `quantile`.
+- `uniroot`'s zero finder is now a port of netlib's `zeroin.f` (public domain).
+- **Type change:** `fStatistic` and `fPValue` of `lm`'s result are optional; they are absent for a
+  model with nothing beyond the intercept, as `summary.lm` has no `fstatistic` there.
+- The error messages of `grad`, `jacobian`, `hessian` and `zTest` are worded differently.
+
+### Fixed
+
+- `lbeta` and `beta` with an argument of 2^52 or more: `lbeta(1e17, 31)` was off by 20 and
+  `lbeta(1e100, 31)` returned 0.92 instead of -7063.
+
+- Accuracy of the incomplete beta function behind `pbeta`, `pt`, `pf`, `pbinom` and `pnbinom`
+  (checked against mpmath). The 15 `pnbinom` cases that were excluded as known accuracy
+  problems now pass:
+  - results near 1e-308 kept their exponent only to double precision (up to 1.2e-13 relative);
+  - the continued fraction rounded a + b, losing the digits of a small b (up to 6e-11 relative,
+    e.g. `pnbinom(1e8, 0.01, mu = 1e4)`).
+- With parameters of 2^52 or more the continued fraction stopped advancing its coefficients, and
+  a result could pass through a subnormal intermediate: `pnbinom` with q around 1e17 was off by
+  up to 1e-3 relative, and returned NaN in some cases.
+- `pgamma` and `ppois` with a shape (or lambda) above about 1e6, 5 to 40 standard deviations below
+  the mean (lower tail of `pgamma`, upper tail of `ppois`): off by up to 2e-14 relative, now 2.7e-15.
+  The series is summed in double-double there, which makes those calls about 9 times slower.
+- `pchisq` and `pbeta` with `ncp` around 1000 in the far tails: off by up to 1.4e-13 relative, now
+  below 5e-15 (the terms of the Poisson mixture are corrected to the exact shape a + j).
+- Fixed since the withdrawn `v0.6.0` tag:
+  - `propTest` with missing groups and with `p`; `pairwisePropTest` with missing groups (dropped and
+    the rest renumbered, as in R);
+  - `uniroot` when `f` returns a non-finite value;
+  - default number of points and range of `spline`, now taken from the regularized x;
+  - the third derivative of `splinefunH` and of `splinefun` with `method: "monoH.FC"` is now the
+    exact one; R returns h times it on an interval of width h (see docs/differences-from-r.md);
+  - `lm` with weights of 0 (those rows are left out of the fit, all zero is an error) and with an
+    intercept-only model (R² = 0 and no F test, as in R);
+  - `optimize` with `lower >= upper` is now an error, as in R;
+  - a non-integer `deriv` (`splinefun`, `splinefunH`) is truncated and non-integer lengths (`n`)
+    are rounded up, as in R;
+  - `barylag` with duplicate nodes; `lu` forms its multipliers as LAPACK does;
+  - `TukeyHSD` comparison names (labels, or positions in the list; groups without data left out);
+  - `kruskalTest` and `flignerTest` with an empty group, `mcnemarTest` with different numbers of
+    levels in x and y, `bartlettTest` with infinite values, `poissonTest` with zero counts and
+    zero `T` or `r`, all now as in R;
+  - accuracy of `besselK` and `besselI` for orders near 2.5, the arcsine distribution near its
+    upper end, `gammainc` for large a, `perm` (overflow and non-integer k), the `distSummary` kurtosis of
+    `lnorm` for small sdlog, `psigamma` for large x, `beta` for huge a, and `choose` for
+    non-integer n;
+  - `pretty` no longer overflows for huge ranges.
+
+## 0.5.0 - 2026-10-21
+
+First public version.
+
+### Included
+
+- Special functions: `gamma`, `lgamma`, `beta`, `lbeta`.
+- d/p/q functions with `lowerTail` and `logP` for the normal, t, chi-squared, F, beta, gamma,
+  binomial, Poisson, uniform, exponential, log-normal, logistic, Cauchy, Weibull, geometric,
+  negative binomial, hypergeometric, Wilcoxon signed rank and rank sum, and studentized range
+  distributions, and the non-central chi-squared, t, F and beta (`ncp`).
+- Random numbers that reproduce R's `set.seed()` streams: `setSeed`, `getRandomSeed`,
+  `setRandomSeed`, 20 `r*` functions, `sample` and `sampleInt`.
+- Hypothesis tests returning R's `htest` fields as plain objects: `tTest`, `chisqTest`,
+  `fisherTest` (including r × c tables), `wilcoxTest` (exact and normal approximation, with
+  confidence intervals), `cor`, `corTest` and `pAdjust`.
+- Linear algebra on matrices given as arrays of rows: `crossprod`, `tcrossprod`, `norm`,
+  `backsolve`, `forwardsolve`, `chol`, `chol2inv`, `qr` (R's default limited pivoting and the
+  LAPACK variant) with `qrQ`, `qrR`, `qrX`, `qrCoef`, `qrQy`, `qrQty`, `qrResid`, `qrFitted`,
+  `qrSolve`, `solve`, `det`, `determinant`, `rcond`, `kappa`, `svd`, `eigen` (symmetric and
+  general, including complex eigenvalues) and `ginv`.
+
+### Conventions
+
+- Indices are 0-based, matching JavaScript arrays: `sampleInt(n)` returns integers in `0..n-1`
+  (R's `sample.int()` minus 1, from the same random stream), and the `pivot` of `qr()` and of
+  `chol(x, { pivot: true })` is 0-based.
+- Errors are thrown with English messages, and the class tells the kind of problem: `TypeError`
+  for wrong types or shapes, `RangeError` for values out of range, and `Error` for numerical
+  failures (singular matrix, not positive definite, no convergence, data essentially constant).
+- A single-file minified ES module, `dist/rstats.js`, for loading from a CDN; release tags contain
+  the build output so that jsDelivr can serve it from GitHub.
+- ESM only, no dependencies, tree-shakable. Requires Node.js 22 or later (or another ES2022
+  environment).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 numero-uno-jpn
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.ja.md

@@ -0,0 +1,197 @@
+# rStats.js
+
+[English](README.md) | 日本語
+
+> この文書は [英語版](README.md) の訳です。内容が食い違うときは英語版が正です。
+
+JavaScript とブラウザで使える、R と互換の統計関数のライブラリです。TypeScript で書いています。
+[ブラウザで試す](https://numero-uno-jpn.github.io/rStats.js/demo/) (すべての関数を、R が出す値と並べて試せます)。
+
+- **R と同じ数値を返します。** 関数名・既定値・結果は R に合わせています。すべての関数を R 4.5.2 と
+  比べてテストしています (分布関数は相対誤差 1e-14)。R 自身が不正確なところでは、高精度の参照値と
+  比べています。
+- **JavaScript らしい呼び出し方です。** 必須の引数は位置で渡し、省略できる引数は camelCase のキーを
+  持つオブジェクトで渡します。`pt(q, df, { lowerTail: false })` は R の `pt(q, df, lower.tail = FALSE)` に
+  当たります。結果は素のオブジェクトなので、そのまま `JSON.stringify` できます。
+- **どこでも動きます。** ESM のみで、依存パッケージはなく、Node 専用の API も使っていません。
+  tree-shaking が効きます (`pnorm` だけなら gzip で 1.2 KB)。
+
+状態: **0.6.1。** R の stats パッケージの数値計算の中心
+(分布・記述統計・検定・線形モデル・特殊関数・数値計算・線形代数の基本) を、R と同じ結果でカバーすることを目指しています。残っている作業は
+[ROADMAP.ja.md](ROADMAP.ja.md)、変更履歴は [CHANGELOG.md](CHANGELOG.md) (英語) にあります。
+
+## インストール
+
+```sh
+npm install @numero-uno-jpn/rstats
+```
+
+ES2022 の環境が必要です (現行のブラウザ、Node.js 22 以降、Deno、Bun)。
+
+## 使い方の例
+
+### 分布
+
+```ts
+import { pnorm, qnorm, pt, qbeta, dbinom } from "@numero-uno-jpn/rstats";
+
+pnorm(1.96);                                  // 0.9750021048517795
+qnorm([0.025, 0.975]);                        // [-1.9599639845400545, 1.959963984540054]
+pt(-40, 3);                                   // 1.7190340394579263e-5
+pt(2, 10, { lowerTail: false, logP: true });  // -3.3051415512324533 (log of the upper tail)
+qbeta(1e-10, 2, 3);                           // 4.082494015808333e-6
+dbinom(3, 10, 0.2);                           // 0.20132659200000003
+```
+
+最初の引数には数値・配列・`Float64Array` を渡せます。結果は同じ形で返ります。分布の母数はスカラーです。
+
+### `set.seed()` と同じ乱数
+
+```ts
+import { setSeed, rnorm, sample } from "@numero-uno-jpn/rstats";
+
+setSeed(42);
+rnorm(3);  // [1.3709584471466685, -0.5646981713960887, 0.3631284113373392]
+           // R: set.seed(42); rnorm(3) gives the same numbers (up to the last bit)
+```
+
+R で `set.seed(42); rnorm(3)` とすると、最後のビットまで同じ数値になります。
+
+### 検定
+
+```ts
+import { tTest, fisherTest, pAdjust } from "@numero-uno-jpn/rstats";
+
+const r = tTest([5.1, 4.9, 6.2, 5.8, 6.0, 5.5], [4.1, 4.5, 5.0, 4.8, 4.3]);
+r.pValue;    // 0.0035365308877675647 (Welch, the default in R)
+r.confInt;   // [0.4423253334608047, 1.6443413332058612]
+r.method;    // "Welch Two Sample t-test"
+
+fisherTest([[3, 1], [1, 3]]).pValue;                     // 0.4857142857142857
+pAdjust([0.01, 0.02, 0.03, 0.04], { method: "BH" });    // ≈ [0.04, 0.04, 0.04, 0.04]
+```
+
+`tTest` の既定は、R と同じ Welch の検定です。
+
+### 線形代数
+
+行列は行の配列で表します。
+
+```ts
+import { solve, qr, qrCoef, svd, eigen } from "@numero-uno-jpn/rstats";
+
+solve([[2, 1], [1, 3]]);            // [[0.6, -0.2], [-0.2, 0.4]]
+const q = qr([[1, 1], [1, 2], [1, 3]]);
+qrCoef(q, [1, 3, 4]);               // ≈ [-0.333, 1.5] (least squares)
+svd([[1, 4], [2, 5], [3, 6]]).d;    // [9.50803200069572, 0.7728696356734838]
+eigen([[2, 1], [1, 3]]).values;     // [3.618033988749895, 1.381966011250105]
+```
+
+## 含まれるもの
+
+| 分野 | 関数 (R と名前が違うものは括弧内が R の名前) |
+|---|---|
+| 特殊関数 | `gamma`, `lgamma`, `beta`, `lbeta`, `choose`, `lchoose`, `factorial`, `lfactorial`, `digamma`, `trigamma`, `psigamma`, `besselI`, `besselK`, `besselJ`, `besselY`。R にはない `erf`, `erfc`, `erfinv`, `erfcinv`, `gammainc`, `perm` も |
+| 分布 (d/p/q) | 正規、t、カイ二乗、F、ベータ、ガンマ、二項、ポアソン、一様、指数、対数正規、ロジスティック、コーシー、ワイブル、幾何、負の二項、超幾何、Wilcoxon の符号付き順位と順位和、スチューデント化された範囲 (`ptukey`, `qtukey`)、非心カイ二乗・t・F・ベータ (`ncp`)。多項分布の確率 (`dmultinom`)。逆ガンマ、Kumaraswamy、Pareto、三角、Laplace (extraDistr) と逆正弦。`distSummary` (平均・分散・標準偏差・中央値・最頻値・歪度・尖度) |
+| 乱数 | `setSeed` (`set.seed`), `getRandomSeed`/`setRandomSeed` (`.Random.seed`), 26 個の `r*` 関数, `sample`, `sampleInt` (`sample.int`) |
+| 記述統計 | `sum`, `prod`, `mean`, `weightedMean` (`weighted.mean`), `variance` (`var`), `sd`, `median`, `range`, `cumsum`, `cumprod`, `cummax`, `cummin`, `diff`, `quantile`, `IQR`, `fivenum`, `mad`, `rank`, `cov`, `cor`, `tabulate`, `table`, `unique`, `cut`, `findInterval`, `pretty`, `hist`, `ecdf`, `scale`, `skewness`, `kurtosis`, `geometricMean`, `modes`, `meanAD`, `cv` |
+| 検定 | `tTest`, `chisqTest`, `fisherTest`, `wilcoxTest`, `corTest`, `binomTest`, `poissonTest`, `propTest`, `mcnemarTest`, `varTest`, `bartlettTest`, `kruskalTest`, `friedmanTest`, `quadeTest`, `flignerTest`, `moodTest`, `onewayTest`, `shapiroTest`, `mantelhaenTest`, `ansariTest`, `ksTest`, `pairwiseTTest`, `pairwiseWilcoxTest`, `pairwisePropTest`, `aov`, `TukeyHSD`, `zTest`, `pAdjust` (`p.adjust`) |
+| 線形モデル | `lm` (行列で渡す形。`summary` の値も返す), `confint`, `predict` |
+| 線形代数 | `matMul` (`%*%`), `add`, `subtract`, `multiply`, `divide`, `outer`, `t`, `diag`, `cbind`, `rbind`, `matrix`, `kronecker`, `seq`, `crossprod`, `tcrossprod`, `norm`, `backsolve`, `forwardsolve`, `chol`, `chol2inv`, `qr` と `qrQ`, `qrR`, `qrX`, `qrCoef`, `qrQy`, `qrQty`, `qrResid`, `qrFitted`, `qrSolve` (`qr.Q` …), `solve`, `det`, `determinant`, `rcond`, `kappa`, `svd`, `eigen`, `lu`, `prcomp`, `ginv` (MASS) |
+| 数値計算 | `integrate`, `optimize`, `uniroot`, `approx`, `spline`, `splinefun`, `splinefunH`, `barylag`, `hermiteInterp`, `ode`, `grad`, `jacobian`, `hessian` |
+
+jStat から移るときは [docs/ja/migrating-from-jstat.md](docs/ja/migrating-from-jstat.md) に jStat の全関数の置き換えがあります。
+
+API リファレンスは `npm run docs` (TypeDoc) で作れます (英語)。
+
+## 精度
+
+正解の値は [`oracle/`](oracle) の R のスクリプトで作り、[`test/fixtures/`](test/fixtures) に
+保存してあります。そのため、テストは R がなくても動きます。各ケースは、R と一致するか、R が
+間違っているところでは Rmpfr や gmp で計算した高精度の値と一致すれば合格です。分布の裾の深い
+ところや母数の大きいところでは、rStats.js のほうが R より正確なことがよくあります。指数部を
+double-double 演算で計算しているためです。詳しくは [docs/ja/accuracy.md](docs/ja/accuracy.md) を
+見てください。
+
+## R との違い
+
+違いの多くは、R の精度が落ちるか、R が失敗するケースです。ふだんの使い方に関わる意図的な違いは
+次のとおりです。
+
+- 添字は 0 から始まります。`sampleInt(n)` は `0..n-1` を返します (R の `sample.int()` から 1 を
+  引いた値で、乱数の列は同じ)。`qr` と `chol` のピボットも 0 から始まります。
+- 固有ベクトルと特異ベクトルの符号が R と違うことがあります (どちらも正しい答えです)。
+- 検定は R の警告を出しません。数値の欄と手法の名前はすべて一致します。
+- 分布の母数は、ベクトルとして使い回されません (リサイクルしない)。
+
+すべての違いは [docs/ja/differences-from-r.md](docs/ja/differences-from-r.md) にあります。
+
+## ブラウザで使う
+
+バンドラ (Vite、esbuild、webpack、Rollup) を使う場合は、関数を名前で import してください。
+使わない関数は取り除かれます。minify と gzip をした後のおおよその大きさは次のとおりです。
+
+| import するもの | gzip |
+|---|---|
+| `pnorm` | 1.2 KB |
+| `setSeed`, `rnorm` | 1.7 KB |
+| `solve` / `svd` / `eigen` | 1.7 / 2.0 / 3.7 KB |
+| `wilcoxTest` / `fisherTest` / `tTest` | 8.6 / 13.8 / 16.7 KB |
+| `qbeta` / `pt` と `qt` | 18.5 / 25.5 KB |
+| すべて | 112.4 KB |
+
+(`npm run size` で測れます。)
+
+分野ごとにサブパスからも export しているので、1 つの分野だけを import することもできます。
+`@numero-uno-jpn/rstats/distributions`、`/tests` (検定と、`lm`・`confint`・`predict`)、`/linalg`、
+`/descriptive`、`/numerics`、`/special` です。
+
+バンドラを使わない場合は、1 ファイルにまとめたビルド `dist/rstats.js` (すべての関数を含む minify 済みの
+ES モジュール、gzip で 112 KB) を jsDelivr から読み込めます。jsDelivr は、このリポジトリのリリースの
+タグをそのまま配信します。
+
+```html
+<script type="module">
+  import { pnorm } from "https://cdn.jsdelivr.net/gh/numero-uno-jpn/rStats.js@v0.6.1/dist/rstats.js";
+  console.log(pnorm(1.96)); // 0.9750021048517795
+</script>
+```
+
+一部の分野だけを使うページでは、代わりに分野ごとのバンドルを読み込めます。`dist/distributions.js`、
+`dist/tests.js`、`dist/linalg.js`、`dist/descriptive.js`、`dist/numerics.js`、`dist/special.js` は
+上のサブパスと同じ関数を export し、共通のコードを `dist/chunks/` で共有します。そのため、2 つの分野を
+読み込んでも共通部分は 1 回しか読み込まれません。chunk を含めた 1 分野の転送量は、gzip で 18 KB
+(`numerics`) から 80 KB (`tests`) です。
+
+ビルド結果 (`dist/`) は main ブランチにはなく、リリースのタグにだけ入っています。npm を元にした CDN も
+使えます。たとえば
+`https://cdn.jsdelivr.net/npm/@numero-uno-jpn/rstats@0.6.1/dist/rstats.js` や
+`https://esm.sh/@numero-uno-jpn/rstats` です。
+
+ブラウザ向けのビルドは、headless Chromium でテストしています。バンドラでまとめた場合と、
+`dist/rstats.js` を ES モジュールとして読み込んだ場合の両方です (`npm run test:browser`)。
+
+**デモ:** <https://numero-uno-jpn.github.io/rStats.js/demo/>。[`demo/`](demo) は、`dist/rstats.js` を jsDelivr から読み込んで、すべての関数を試せる
+静的なページです。確率分布 (グラフ付き)・特殊関数・乱数・検定・線形代数を扱います。各フォームには、
+入力に対応する R と JavaScript のコードが表示されます。「R との比較」のタブでは、例題の値を R が
+出力した値と照らし合わせます (`source("examples.R")` で、すべての例題を R で実行できます)。CDN の
+代わりに手元のビルドを使うには、`npm run build` をしてから、リポジトリのルートを静的サーバー
+(たとえば `npx serve .`) で配信し、`/demo/?src=local` を開いてください。
+
+## 版の番号
+
+版が 0.x の間は、minor の版で互換性のない変更が入ることがあります。その場合は変更履歴に
+書きます。1.0.0 からは Semantic Versioning に従います。
+
+## 貢献
+
+R との答え合わせの仕組みと、ライセンスの決まり (R や GPL のパッケージのコードは使わない) は
+[CONTRIBUTING.ja.md](CONTRIBUTING.ja.md) にあります。速さと double-double 演算については
+[docs/ja/performance.md](docs/ja/performance.md) にあります。
+
+## ライセンス
+
+MIT です。数値計算の部品は、SciPy の xsf・scipy.stats・QUADPACK の C 訳 (BSD-3)、Boost.Math
+(BSL-1.0)、statsmodels (BSD-3)、LAPACK の参照実装 (修正 BSD) から移植しています。パブリックドメインの
+LINPACK・EISPACK・Cephes・QUADPACK・netlib のコードも使っています。詳しくは
+[THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) (英語) を見てください。

package/README.md

@@ -1,3 +1,189 @@
-# Temporary Holding Version
+# rStats.js
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+English | [日本語](README.ja.md)
+
+R-compatible statistical functions for JavaScript and the browser, written in TypeScript.
+[Try it in the browser](https://numero-uno-jpn.github.io/rStats.js/demo/) (every function, with the values R gives).
+
+- **Same numbers as R.** Function names, defaults and results follow R. Every function is
+  tested against R 4.5.2 (relative error 1e-14 for distributions), and where R itself is
+  inaccurate, against high-precision reference values.
+- **JavaScript-style calls.** Required arguments are positional, optional ones go in an object
+  with camelCase keys: `pt(q, df, { lowerTail: false })` is R's `pt(q, df, lower.tail = FALSE)`.
+  Results are plain objects that `JSON.stringify` cleanly.
+- **Runs anywhere.** ESM only, no dependencies, no Node-specific APIs, tree-shakable
+  (`pnorm` alone is 1.2 KB gzipped).
+
+Status: **0.6.1.** The goal is to cover the numerical core of R's
+`stats` package (distributions, descriptive statistics, hypothesis tests, linear models, special
+functions, numerical methods and the basics of linear algebra) with R-compatible results; see [ROADMAP.md](ROADMAP.md) for what remains. See [CHANGELOG.md](CHANGELOG.md).
+
+## Install
+
+```sh
+npm install @numero-uno-jpn/rstats
+```
+
+Requires an ES2022 environment (current browsers, Node.js 22 or later, Deno, Bun).
+
+## Examples
+
+### Distributions
+
+```ts
+import { pnorm, qnorm, pt, qbeta, dbinom } from "@numero-uno-jpn/rstats";
+
+pnorm(1.96);                                  // 0.9750021048517795
+qnorm([0.025, 0.975]);                        // [-1.9599639845400545, 1.959963984540054]
+pt(-40, 3);                                   // 1.7190340394579263e-5
+pt(2, 10, { lowerTail: false, logP: true });  // -3.3051415512324533 (log of the upper tail)
+qbeta(1e-10, 2, 3);                           // 4.082494015808333e-6
+dbinom(3, 10, 0.2);                           // 0.20132659200000003
+```
+
+The first argument may be a number, an array or a `Float64Array`; the result has the same shape.
+Distribution parameters are scalars.
+
+### Random numbers that match `set.seed()`
+
+```ts
+import { setSeed, rnorm, sample } from "@numero-uno-jpn/rstats";
+
+setSeed(42);
+rnorm(3);  // [1.3709584471466685, -0.5646981713960887, 0.3631284113373392]
+           // R: set.seed(42); rnorm(3) gives the same numbers (up to the last bit)
+```
+
+### Hypothesis tests
+
+```ts
+import { tTest, fisherTest, pAdjust } from "@numero-uno-jpn/rstats";
+
+const r = tTest([5.1, 4.9, 6.2, 5.8, 6.0, 5.5], [4.1, 4.5, 5.0, 4.8, 4.3]);
+r.pValue;    // 0.0035365308877675647 (Welch, the default in R)
+r.confInt;   // [0.4423253334608047, 1.6443413332058612]
+r.method;    // "Welch Two Sample t-test"
+
+fisherTest([[3, 1], [1, 3]]).pValue;                     // 0.4857142857142857
+pAdjust([0.01, 0.02, 0.03, 0.04], { method: "BH" });    // ≈ [0.04, 0.04, 0.04, 0.04]
+```
+
+### Linear algebra
+
+Matrices are arrays of rows.
+
+```ts
+import { solve, qr, qrCoef, svd, eigen } from "@numero-uno-jpn/rstats";
+
+solve([[2, 1], [1, 3]]);            // [[0.6, -0.2], [-0.2, 0.4]]
+const q = qr([[1, 1], [1, 2], [1, 3]]);
+qrCoef(q, [1, 3, 4]);               // ≈ [-0.333, 1.5] (least squares)
+svd([[1, 4], [2, 5], [3, 6]]).d;    // [9.50803200069572, 0.7728696356734838]
+eigen([[2, 1], [1, 3]]).values;     // [3.618033988749895, 1.381966011250105]
+```
+
+## What is included
+
+| Area | Functions (R names in parentheses where they differ) |
+|---|---|
+| Special functions | `gamma`, `lgamma`, `beta`, `lbeta`, `choose`, `lchoose`, `factorial`, `lfactorial`, `digamma`, `trigamma`, `psigamma`, `besselI`, `besselK`, `besselJ`, `besselY`; also `erf`, `erfc`, `erfinv`, `erfcinv`, `gammainc` and `perm`, which R lacks |
+| Distributions (d/p/q) | normal, t, chi-squared, F, beta, gamma, binomial, Poisson, uniform, exponential, log-normal, logistic, Cauchy, Weibull, geometric, negative binomial, hypergeometric, Wilcoxon signed rank and rank sum, studentized range (`ptukey`, `qtukey`), non-central chi-squared, t, F and beta (`ncp`); the multinomial probability (`dmultinom`); inverse gamma, Kumaraswamy, Pareto, triangular, Laplace (extraDistr) and arcsine; `distSummary` (mean, variance, sd, median, mode, skewness, kurtosis) |
+| Random numbers | `setSeed` (`set.seed`), `getRandomSeed`/`setRandomSeed` (`.Random.seed`), 26 `r*` functions, `sample`, `sampleInt` (`sample.int`) |
+| Descriptive statistics | `sum`, `prod`, `mean`, `weightedMean` (`weighted.mean`), `variance` (`var`), `sd`, `median`, `range`, `cumsum`, `cumprod`, `cummax`, `cummin`, `diff`, `quantile`, `IQR`, `fivenum`, `mad`, `rank`, `cov`, `cor`, `tabulate`, `table`, `unique`, `cut`, `findInterval`, `pretty`, `hist`, `ecdf`, `scale`, `skewness`, `kurtosis`, `geometricMean`, `modes`, `meanAD`, `cv` |
+| Hypothesis tests | `tTest`, `chisqTest`, `fisherTest`, `wilcoxTest`, `corTest`, `binomTest`, `poissonTest`, `propTest`, `mcnemarTest`, `varTest`, `bartlettTest`, `kruskalTest`, `friedmanTest`, `quadeTest`, `flignerTest`, `moodTest`, `onewayTest`, `shapiroTest`, `mantelhaenTest`, `ansariTest`, `ksTest`, `pairwiseTTest`, `pairwiseWilcoxTest`, `pairwisePropTest`, `aov`, `TukeyHSD`, `zTest`, `pAdjust` (`p.adjust`) |
+| Linear models | `lm` (matrix interface, with the `summary` quantities), `confint`, `predict` |
+| Linear algebra | `matMul` (`%*%`), `add`, `subtract`, `multiply`, `divide`, `outer`, `t`, `diag`, `cbind`, `rbind`, `matrix`, `kronecker`, `seq`, `crossprod`, `tcrossprod`, `norm`, `backsolve`, `forwardsolve`, `chol`, `chol2inv`, `qr` with `qrQ`, `qrR`, `qrX`, `qrCoef`, `qrQy`, `qrQty`, `qrResid`, `qrFitted`, `qrSolve` (`qr.Q` …), `solve`, `det`, `determinant`, `rcond`, `kappa`, `svd`, `eigen`, `lu`, `prcomp`, `ginv` (MASS) |
+| Numerical methods | `integrate`, `optimize`, `uniroot`, `approx`, `spline`, `splinefun`, `splinefunH`, `barylag`, `hermiteInterp`, `ode`, `grad`, `jacobian`, `hessian` |
+
+Coming from jStat? [docs/migrating-from-jstat.md](docs/migrating-from-jstat.md) lists the replacement for every jStat function.
+
+An API reference can be generated with `npm run docs` (TypeDoc).
+
+## Accuracy
+
+Expected values are produced by R scripts in [`oracle/`](oracle) and stored in
+[`test/fixtures/`](test/fixtures), so the test suite runs without R. A case passes if it matches
+R, or if R is wrong there and rStats.js matches a high-precision value computed with Rmpfr or
+gmp. In the far tails and for large parameters rStats.js is often more accurate than R, because
+it computes exponents in double-double arithmetic. Details: [docs/accuracy.md](docs/accuracy.md).
+
+## Differences from R
+
+Most differences are cases where R loses accuracy or fails. The deliberate ones that affect
+everyday use:
+
+- Indices are 0-based: `sampleInt(n)` returns `0..n-1` (R's `sample.int()` minus 1, from the
+  same random stream), and pivots of `qr` and `chol` are 0-based.
+- Signs of eigenvectors and singular vectors may differ from R (both are correct).
+- Hypothesis tests do not emit R's warnings; all numeric fields and method names match.
+- Distribution parameters are not recycled as vectors.
+
+Full list: [docs/differences-from-r.md](docs/differences-from-r.md).
+
+## Using it in the browser
+
+With a bundler (Vite, esbuild, webpack, Rollup), import named functions; unused functions are
+removed. Approximate sizes after minification and gzip:
+
+| Import | gzip |
+|---|---|
+| `pnorm` | 1.2 KB |
+| `setSeed`, `rnorm` | 1.7 KB |
+| `solve` / `svd` / `eigen` | 1.7 / 2.0 / 3.7 KB |
+| `wilcoxTest` / `fisherTest` / `tTest` | 8.6 / 13.8 / 16.7 KB |
+| `qbeta` / `pt` and `qt` | 18.5 / 25.5 KB |
+| everything | 112.4 KB |
+
+(`npm run size` measures these.)
+
+Each area is also a subpath export, for importing one area without the rest:
+`@numero-uno-jpn/rstats/distributions`, `/tests` (hypothesis tests, and `lm`, `confint` and
+`predict`), `/linalg`, `/descriptive`, `/numerics` and `/special`.
+
+Without a bundler, load the single-file build `dist/rstats.js` (one minified ES module with every
+function, 112 KB gzipped) from jsDelivr, which serves each release tag of this repository:
+
+```html
+<script type="module">
+  import { pnorm } from "https://cdn.jsdelivr.net/gh/numero-uno-jpn/rStats.js@v0.6.1/dist/rstats.js";
+  console.log(pnorm(1.96)); // 0.9750021048517795
+</script>
+```
+
+A page that needs only some areas can load the per-area bundles instead: `dist/distributions.js`,
+`dist/tests.js`, `dist/linalg.js`, `dist/descriptive.js`, `dist/numerics.js` and `dist/special.js`
+export the same functions as the subpaths above, and share their common code through
+`dist/chunks/`, so loading two areas does not load that code twice. With its chunks, one area
+transfers 18 KB (`numerics`) to 80 KB (`tests`) gzipped.
+
+Release tags contain the build output (`dist/`), which is not on the main branch. npm-based CDNs
+work as well, for example
+`https://cdn.jsdelivr.net/npm/@numero-uno-jpn/rstats@0.6.1/dist/rstats.js` or
+`https://esm.sh/@numero-uno-jpn/rstats`.
+
+The browser build is tested in headless Chromium, both bundled and as `dist/rstats.js` loaded as
+an ES module (`npm run test:browser`).
+
+**Demo:** <https://numero-uno-jpn.github.io/rStats.js/demo/>. [`demo/`](demo) is a static page that loads `dist/rstats.js` from jsDelivr and exercises
+every function: distributions with plots, special functions, random numbers, hypothesis tests and
+linear algebra. Each form shows the equivalent R and JavaScript code for its inputs, and a "Compare
+with R" tab checks curated examples against values printed by R (`source("examples.R")` runs them
+all in R). To use your own build instead of the CDN, run `npm run build`, serve the repository root
+with a static server (for example `npx serve .`) and open `/demo/?src=local`.
+
+## Versioning
+
+While the version is 0.x, a minor release may contain breaking changes; they are listed in the
+changelog. From 1.0.0 the project follows Semantic Versioning.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for how the comparison with R works and the licensing
+rules (no code from R or GPL packages). Notes on speed and the double-double arithmetic are in
+[docs/performance.md](docs/performance.md).
+
+## License
+
+MIT. Numerical kernels are ported from SciPy's xsf, scipy.stats and C translation of QUADPACK
+(BSD-3), Boost.Math (BSL-1.0), statsmodels (BSD-3) and the LAPACK reference implementation
+(modified BSD), plus public-domain LINPACK, EISPACK, Cephes, QUADPACK and netlib code. See [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).