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

package/CHANGELOG.md

@@ -0,0 +1,43 @@
+# 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.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,181 @@
+# rStats.js
+
+[English](README.md) | 日本語
+
+> この文書は [英語版](README.md) の訳です。内容が食い違うときは英語版が正です。
+
+JavaScript とブラウザで使える、R と互換の統計関数のライブラリです。TypeScript で書いています。
+
+- **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.5.0。** R の stats パッケージの数値計算の中心
+(分布・検定・特殊関数・線形代数の基本) を、R と同じ結果でカバーすることを目指しています。残っている作業は
+[ROADMAP.md](ROADMAP.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` |
+| 分布 (d/p/q) | 正規、t、カイ二乗、F、ベータ、ガンマ、二項、ポアソン、一様、指数、対数正規、ロジスティック、コーシー、ワイブル、幾何、負の二項、超幾何、Wilcoxon の符号付き順位と順位和、スチューデント化された範囲 (`ptukey`, `qtukey`)、非心カイ二乗・t・F・ベータ (`ncp`) |
+| 乱数 | `setSeed` (`set.seed`), `getRandomSeed`/`setRandomSeed` (`.Random.seed`), 20 個の `r*` 関数, `sample`, `sampleInt` (`sample.int`) |
+| 検定 | `tTest`, `chisqTest`, `fisherTest`, `wilcoxTest`, `cor`, `corTest`, `pAdjust` (`p.adjust`) |
+| 線形代数 | `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`, `ginv` (MASS) |
+
+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` | 7.9 / 13.2 / 16.3 KB |
+| `qbeta` / `pt` と `qt` | 17.3 / 25.0 KB |
+| すべて | 72.2 KB |
+
+(`npm run size` で測れます。)
+
+バンドラを使わない場合は、1 ファイルにまとめたビルド `dist/rstats.js` (すべての関数を含む minify 済みの
+ES モジュール、gzip で 72 KB) を jsDelivr から読み込めます。jsDelivr は、このリポジトリのリリースの
+タグをそのまま配信します。
+
+```html
+<script type="module">
+  import { pnorm } from "https://cdn.jsdelivr.net/gh/numero-uno-jpn/rStats.js@v0.5.0/dist/rstats.js";
+  console.log(pnorm(1.96)); // 0.9750021048517795
+</script>
+```
+
+ビルド結果 (`dist/`) は main ブランチにはなく、リリースのタグにだけ入っています。npm を元にした CDN も
+使えます。たとえば
+`https://cdn.jsdelivr.net/npm/@numero-uno-jpn/rstats@0.5.0/dist/rstats.js` や
+`https://esm.sh/@numero-uno-jpn/rstats` です。
+
+ブラウザ向けのビルドは、headless Chromium でテストしています。バンドラでまとめた場合と、
+`dist/rstats.js` を ES モジュールとして読み込んだ場合の両方です (`npm run test:browser`)。
+
+**デモ。** [`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.md](CONTRIBUTING.md) (英語) にあります。速さと double-double 演算については
+[docs/performance.md](docs/performance.md) (英語) にあります。
+
+## ライセンス
+
+MIT です。数値計算の部品は、SciPy の xsf と scipy.stats (BSD-3)、Boost.Math (BSL-1.0)、
+statsmodels (BSD-3)、LAPACK の参照実装 (修正 BSD) から移植しています。パブリックドメインの
+LINPACK・EISPACK・Cephes のコードも使っています。詳しくは
+[THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) (英語) を見てください。

package/README.md

@@ -1,3 +1,173 @@
-# 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.
+
+- **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.5.0.** The goal is to cover the numerical core of R's
+`stats` package (distributions, hypothesis tests, special functions 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` |
+| 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`) |
+| Random numbers | `setSeed` (`set.seed`), `getRandomSeed`/`setRandomSeed` (`.Random.seed`), 20 `r*` functions, `sample`, `sampleInt` (`sample.int`) |
+| Hypothesis tests | `tTest`, `chisqTest`, `fisherTest`, `wilcoxTest`, `cor`, `corTest`, `pAdjust` (`p.adjust`) |
+| Linear algebra | `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`, `ginv` (MASS) |
+
+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` | 7.9 / 13.2 / 16.3 KB |
+| `qbeta` / `pt` and `qt` | 17.3 / 25.0 KB |
+| everything | 72.2 KB |
+
+(`npm run size` measures these.)
+
+Without a bundler, load the single-file build `dist/rstats.js` (one minified ES module with every
+function, 72 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.5.0/dist/rstats.js";
+  console.log(pnorm(1.96)); // 0.9750021048517795
+</script>
+```
+
+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.5.0/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.** [`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 and scipy.stats (BSD-3), Boost.Math
+(BSL-1.0), statsmodels (BSD-3) and the LAPACK reference implementation (modified BSD), plus
+public-domain LINPACK, EISPACK and Cephes code. See [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).