# @lazy-random/df-algorithm

> 各種統計分佈 (Statistical Distribution) 的亂數取樣函式 (Random Sampling Function) 集合，屬 @lazy-random 系列的分佈函式 (Distribution Function) 套件

Latest version **2.0.1** (published 2026-10-05) · ISC license · 0 weekly downloads

## Install

```sh
npm install @lazy-random/df-algorithm
pnpm add @lazy-random/df-algorithm
yarn add @lazy-random/df-algorithm
bun add @lazy-random/df-algorithm
```

## Health

**Score 70/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; recently updated; high maintenance score; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 2.0.1 |
| Published | 2026-10-05 |
| First published | 2021-12-12 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 2 |
| Unpacked size | 166.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 2 |
| Author | bluelovers |
| Maintainers | bluelovers |
| Keywords | df-algorithm, distribution, random-sampling, normal, lognormal, bates, bernoulli, binomial, exponential, geometric, irwinhall, pareto, rng, random, lazy-random, create-by-yarn-tool, create-by-tsdx |

## Links

- npm: https://www.npmjs.com/package/@lazy-random/df-algorithm
- Repository: https://github.com/bluelovers/ws-random
- Homepage: https://github.com/bluelovers/ws-random/tree/master/packages/@lazy-random/df-algorithm#readme
- Issues: https://github.com/bluelovers/ws-random/issues
- npm.io page: https://npm.io/package/@lazy-random/df-algorithm

## Dependencies (2)

- [num-is-zero](https://npm.io/package/num-is-zero.md) ^2.0.1
- [@lazy-random/expect](https://npm.io/package/@lazy-random/expect.md) ^2.0.1

## Alternatives

- [cli-color](https://npm.io/package/cli-color.md) — 3.4M weekly downloads
- [log](https://npm.io/package/log.md) — 1.3M weekly downloads
- [logstash-client](https://npm.io/package/logstash-client.md) — 4.5K weekly downloads
- [@nocobase/plugin-logger](https://npm.io/package/@nocobase/plugin-logger.md) — 2.0K weekly downloads
- [child-process-debug](https://npm.io/package/child-process-debug.md) — 695 weekly downloads

## Recent versions

- 2.0.1 (latest) — 2026-10-05
- 1.0.13 — 2023-11-19
- 1.0.11 — 2022-10-29
- 1.0.10 — 2022-01-04
- 1.0.9 — 2022-01-03
- 1.0.8 — 2021-12-21
- 1.0.4 — 2021-12-12

## README

# @lazy-random/df-algorithm

各種統計分佈 (Statistical Distribution) 的亂數取樣函式 (Random Sampling Function) 集合，屬於 `@lazy-random` 系列的分佈函式 (Distribution Function) 套件。

每個 `df*` 函式都是工廠 (Factory)：傳入一個亂數來源 (RNG) 與分佈參數，回傳可反覆呼叫的取樣函式 (Sampler)。參數會在建立時一次驗證完畢，呼叫取樣函式時不再重複檢查，兼顧安全與效能。

## 特色 (Features)

- 涵蓋 9 種常見分佈：貝茲 (Bates)、伯努利 (Bernoulli)、二項 (Binomial)、指數 (Exponential)、幾何 (Geometric)、Irwin–Hall、對數常態 (Log-Normal)、常態 (Normal)、帕累托 (Pareto)
- 統一的 `df` 前綴 (Prefix) 命名，參數順序一致：先亂數來源，再分佈參數
- 建立時以 `@lazy-random/expect` 驗證參數範圍，錯誤參數會立即拋出 (Throw)
- 常態分佈採 Marsaglia 極座標法 (Polar Method)，對數常態直接複用常態分佈實作

## 安裝 (Installation)

```bash
yarn add @lazy-random/df-algorithm
yarn-tool add @lazy-random/df-algorithm
yt add @lazy-random/df-algorithm
```

## 使用方式 (Usage)

```ts
import { dfNormal, dfBernoulli } from '@lazy-random/df-algorithm'

// 亂數來源需提供 next()，回傳 [0, 1) 的均勻亂數
const random = {
	next: () => Math.random(),
}

// 建立常態分佈 (μ = 0, σ = 1) 取樣函式
const normal = dfNormal(random, 0, 1)
console.log(normal())

// 建立 p = 0.3 的伯努利取樣函式
const bernoulli = dfBernoulli(random, 0.3)
console.log(bernoulli())
```

一次建立、重複取樣：

```ts
import { dfBinomial } from '@lazy-random/df-algorithm'

const binomial = dfBinomial(random, 10, 0.5)

// 每次呼叫都回傳新的取樣結果（0 ～ 10 的整數）
const samples = Array.from({ length: 5 }, () => binomial())
```

## API 文件

所有函式皆遵循下列慣例：

- 回傳值 (Returns)：無參數的函式，每次呼叫回傳一個取樣結果
- 例外 (Throws)：參數不符合範圍時，於**建立時**拋出驗證錯誤 (Validation Error)

### dfBates(random, n = 1)

貝茲分佈 (Bates Distribution)：回傳 `n` 個均勻亂數的平均值，結果落在 `[0, 1)`；`n = 1` 時等同均勻分佈 (Uniform Distribution)。

| 參數 (Parameter) | 型別 (Type) | 說明 |
| --- | --- | --- |
| `random` | `IRNGLike` | 亂數來源，需提供 `next()` |
| `n` | `number` | 均勻樣本數，需為正整數 (`> 0`) |

### dfBernoulli(random, p = 0.5)

伯努利分佈 (Bernoulli Distribution)：以機率 `p` 回傳 `1`，否則回傳 `0`。

| 參數 (Parameter) | 型別 (Type) | 說明 |
| --- | --- | --- |
| `random` | `IRNGLike` | 亂數來源 |
| `p` | `number` | 成功機率，範圍 `0 ≤ p ≤ 1` |

### dfBinomial(random, n = 1, p = 0.5)

二項分佈 (Binomial Distribution)：回傳 `n` 次獨立伯努利試驗 (Bernoulli Trial) 的成功次數，結果為 `0 ～ n` 的整數。

| 參數 (Parameter) | 型別 (Type) | 說明 |
| --- | --- | --- |
| `random` | `IRNGLike` | 亂數來源 |
| `n` | `number` | 試驗次數，需為正整數 (`> 0`) |
| `p` | `number` | 單次試驗的成功機率，範圍 `0 ≤ p ≤ 1` |

### dfExponential(random, lambda = 1)

指數分佈 (Exponential Distribution)：以反函數法 (Inverse Transform Sampling) 產生數值。

| 參數 (Parameter) | 型別 (Type) | 說明 |
| --- | --- | --- |
| `random` | `IRNGLike` | 亂數來源 |
| `lambda` | `number` | 率參數 (Rate Parameter) λ，需 `> 0` |

### dfGeometric(random, p = 0.5)

幾何分佈 (Geometric Distribution)：回傳首次成功所需的試驗次數（含成功那次），結果為 `≥ 1` 的整數。

| 參數 (Parameter) | 型別 (Type) | 說明 |
| --- | --- | --- |
| `random` | `IRNGLike` | 亂數來源 |
| `p` | `number` | 成功機率，範圍 `0 < p ≤ 1` |

### dfIrwinHall(random, n = 1)

Irwin–Hall 分佈：回傳 `n` 個均勻亂數的總和，結果落在 `[0, n)`；`n = 0` 時固定回傳 `0`。Bates 分佈即由此函式除以 `n` 而得。

| 參數 (Parameter) | 型別 (Type) | 說明 |
| --- | --- | --- |
| `random` | `IRNGLike` | 亂數來源 |
| `n` | `number` | 均勻樣本數，需為非負整數 (`≥ 0`) |

參考資料：

- <https://zh.wikipedia.org/wiki/%E6%AD%90%E6%96%87%E2%80%93%E8%B3%80%E7%88%BE%E5%88%86%E4%BD%88>
- <https://en.wikipedia.org/wiki/Irwin%E2%80%93Hall_distribution>

### dfLogNormal(...args)

對數常態分佈 (Log-Normal Distribution)：建立常態取樣函式後取指數 `exp()`，參數與 `dfNormal` 完全相同。

| 參數 (Parameter) | 型別 (Type) | 說明 |
| --- | --- | --- |
| `...args` | `Parameters<typeof dfNormal>` | 與 `dfNormal(random, mu, sigma)` 相同 |

### dfNormal(random, mu = 0, sigma = 1)

常態分佈 (Normal Distribution / 高斯分佈 Gaussian)：以 Marsaglia 極座標法 (Polar Method) 產生標準常態值，再平移、縮放到 `mu` 與 `sigma`。

| 參數 (Parameter) | 型別 (Type) | 說明 |
| --- | --- | --- |
| `random` | `IRNGLike` | 亂數來源 |
| `mu` | `number` | 平均值 (Mean)，需為數字 |
| `sigma` | `number` | 標準差 (Standard Deviation)，需為數字 |

### dfPareto(random, alpha = 1)

帕累托分佈 (Pareto Distribution)：以反函數法產生數值。

| 參數 (Parameter) | 型別 (Type) | 說明 |
| --- | --- | --- |
| `random` | `IRNGLike` | 亂數來源 |
| `alpha` | `number` | 形狀參數 (Shape Parameter) α，需 `> 0` |

## 開發 (Development)

```bash
pnpm run build
pnpm run lint
pnpm run test
```

## 變更日誌 (Changelog)

請見 [CHANGELOG.md](./CHANGELOG.md)。

## 常見問題 (FAQ)

### 取樣函式可以共用嗎？

可以。建立時就把參數固定下來，同一個取樣函式可反覆呼叫；若需要不同的參數組合，請另外建立一個取樣函式。

### 為什麼參數錯誤要等到建立時才拋出？

參數範圍（例如機率 `p`、樣本數 `n`）在建立後就不會改變，提前驗證可避免每次取樣都重複檢查，也能在程式早期攔下錯誤。

## 相關資源 (Resources)

- [Repository](https://github.com/bluelovers/ws-random/tree/master/packages/@lazy-random/df-algorithm#readme)
- [Issues](https://github.com/bluelovers/ws-random/issues)

---
_Source: https://npm.io/package/@lazy-random/df-algorithm · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._