ranjs
rán · 然 “so; correct” — robust random variates, distribution testing & statistics for JavaScript.
What is this?
A small library for robust generation of various random variates, testing data against distributions or calculating different statistical properties.
Install in node
npm install --save ranjsUse in browser
<script type="text/javascript" src="ran.min.js"></script>Demo
Continuous distributions · Discrete distributions
API
ran.core.char([string[, n]])
Samples some characters with replacement from a string with uniform distribution.
Parameters
| Name | Type | Description |
|---|---|---|
| string | string | String to sample characters from. |
| n | number | Number of characters to sample. |
Returns
stringstring[]undefinedRandom character if n is not given or less than 2, an array of random characters otherwise. If string is empty, undefined is returned.
Examples
ran.core.char('abcde')
// => 'd'
ran.core.char('abcde', 5)
// => [ 'd', 'c', 'a', 'a', 'd' ]ran.core.choice(values[, n])
Samples some elements with replacement from an array with uniform distribution.
Parameters
| Name | Type | Description |
|---|---|---|
| values | T[] | Array to sample from. |
| n | number | Number of elements to sample. |
Returns
TT[]undefinedSingle element or array of sampled elements. If the array is invalid (empty or not passed), undefined is returned.
Examples
ran.core.choice([1, 2, 3, 4, 5])
// => 2
ran.core.choice([1, 2, 3, 4, 5], 5)
// => [ 1, 5, 4, 4, 1 ]ran.core.coin(head, tail[, p[, n]])
Flips a biased coin several times and returns the associated head/tail value or array of values.
Parameters
| Name | Type | Description |
|---|---|---|
| head | H | Head value. |
| tail | T | Tail value. |
| p | number | Bias (probability of head). Default is 0.5. |
| n | number | Number of coins to flip. Default is 1. |
Returns
HTundefined[]Single head/tail value or an array of head/tail values.
Examples
ran.core.coin('a', {b: 2})
// => { b: 2 }
ran.core.coin('a', {b: 2}, 0.9)
// => 'a'
ran.core.coin('a', {b: 2}, 0.9, 9)
// => [ { b: 2 }, 'a', 'a', 'a', 'a', 'a', 'a', { b: 2 }, 'a' ]ran.core.float([min[, max[, n]]])
Generates some uniformly distributed random floats in (min, max). If min > max, a random float in (max, min) is generated. If no parameters are passed, generates a single random float between 0 and 1. If only min is specified, generates a single random float between 0 and min.
Parameters
| Name | Type | Description |
|---|---|---|
| min | number | Lower boundary, or upper if max is not given. |
| max | number | Upper boundary. |
| n | number | Number of floats to generate. |
Returns
numbernumber[]Single float or array of random floats.
Examples
ran.core.float()
// => 0.278014086611011
ran.core.float(2)
// => 1.7201255276155272
ran.core.float(2, 3)
// => 2.3693449236256185
ran.core.float(2, 3, 5)
// => [ 2.4310443387740093,
// 2.934333354639414,
// 2.7689523358767127,
// 2.291137165632517,
// 2.5040591952427906 ]ran.core.int(min[, max[, n]])
Generates some uniformly distributed random integers in (min, max). If min > max, a random integer in (max, min) is generated. If only min is specified, generates a single random integer between 0 and min.
Parameters
| Name | Type | Description |
|---|---|---|
| min | number | Lower boundary, or upper if max is not specified. |
| max | number | Upper boundary. |
| n | number | Number of integers to generate. |
Returns
numbernumber[]Single integer or array of random integers.
Examples
ran.core.int(10)
// => 2
ran.core.int(10, 20)
//=> 12
ran.core.int(10, 20, 5)
// => [ 12, 13, 10, 14, 14 ]ran.core.seed(value)
Sets the seed for the underlying pseudo random number generator used by the core generators. Under the hood, ranjs implements the xoshiro128+ algorithm as described in Blackman and Vigna: Scrambled Linear Pseudorandom Number Generators (2019).
Parameters
| Name | Type | Description |
|---|---|---|
| value | numberstring | The value of the seed, either a number or a string (for the ease of tracking seeds). |
Returns
voidran.core.shuffle(values)
Shuffles an array in-place using the Fisher‒Yates algorithm.
Parameters
| Name | Type | Description |
|---|---|---|
| values | T[] | Array to shuffle. |
Returns
T[]The shuffled array.
Examples
ran.core.shuffle([1, 2, 3])
// => [ 2, 3, 1 ]ran.dependence.covariance(x, y)
Calculates the sample covariance for paired arrays of values.
Parameters
| Name | Type | Description |
|---|---|---|
| x | number[] | First array of values. |
| y | number[] | Second array of values. |
Returns
numberThe sample covariance, or NaN if either array has fewer than 2 elements.
Throws
ErrorExamples
ran.dependence.covariance([], [])
// => NaN
ran.dependence.covariance([1], [2])
// => NaN
ran.dependence.covariance([1, 2, 3], [4, 5, 6])
// => 1
ran.dependence.covariance([1, 9, 10], [1, 2, 10])
// => 16.166666666666668ran.dependence.dCor(x, y)
Calculates the distance correlation for paired arrays of values.
Parameters
| Name | Type | Description |
|---|---|---|
| x | number[] | First array of values. |
| y | number[] | Second array of values. |
Returns
numberThe distance correlation, or NaN for empty or constant arrays.
Throws
ErrorExamples
ran.dependence.dCor([], [])
// => NaN
ran.dependence.dCor([1, 2, 3], [2, 1, 2])
// => 0.5623413251903491ran.dependence.dCov(x, y)
Calculates the distance covariance for paired arrays of values.
Parameters
| Name | Type | Description |
|---|---|---|
| x | number[] | First array of values. |
| y | number[] | Second array of values. |
Returns
numberThe distance covariance, or NaN for empty arrays.
Throws
ErrorExamples
ran.dependence.dCov([], [])
// => NaN
ran.dependence.dCov([1, 2, 3], [2, 1, 2])
// => 0.31426968052735443ran.dependence.kendall(x, y)
Calculates Kendall's rank correlation coefficient for paired arrays of values.
Parameters
| Name | Type | Description |
|---|---|---|
| x | number[] | First array of values. |
| y | number[] | Second array of values. |
Returns
numberKendall's correlation coefficient, or NaN for empty arrays.
Throws
ErrorExamples
ran.dependence.kendall([], [])
// => NaN
ran.dependence.kendall([1, 2, 3], [4, 5, 6])
// => 1
ran.dependence.kendall([1, 2, 3], [1, 4, 2])
// => 0.3333333333333333ran.dependence.kullbackLeibler(p, q)
Calculates the (discrete) Kullback-Leibler divergence for two probability distributions:
Parameters
| Name | Type | Description |
|---|---|---|
| p | number[] | Array representing the probabilities for the i-th value in the base distribution (P). |
| q | number[] | Array representing the probabilities for the i-th value in compared distribution (Q). |
Returns
numberThe Kullback-Leibler divergence, NaN for empty input, Infinity if Q(x) = 0 and P(x) > 0 for some x.
Throws
ErrorExamples
ran.dependence.kullbackLeibler([], [])
// => NaN
ran.dependence.kullbackLeibler([0.1, 0.2, 0.7], [0, 0.3, 0.7])
// => Infinity
ran.dependence.kullbackLeibler([0.1, 0.3, 0.6], [0.333, 0.333, 0.334])
// => 0.19986796234715937
ran.dependence.kullbackLeibler([0.333, 0.333, 0.334], [0.1, 0.3, 0.6])
// => 0.2396882491444514ran.dependence.oddsRatio(p00, p01, p10, p11)
Calculates the odds ratio for the joint probabilities of two binary variables:
Parameters
| Name | Type | Description |
|---|---|---|
| p00 | number | The probability of X = 0 and Y = 0. |
| p01 | number | The probability of X = 0 and Y = 1. |
| p10 | number | The probability of X = 1 and Y = 0. |
| p11 | number | The probability of X = 1 and Y = 1. |
Returns
numberThe odds ratio. Returns Infinity when p01 or p10 is zero and the numerator is non-zero.
Examples
ran.dependence.oddsRatio(0.3, 0, 0.3, 0.4)
// => Infinity
ran.dependence.oddsRatio(0.3, 0.3, 0, 0.4)
// => Infinity
ran.dependence.oddsRatio(0.1, 0.2, 0.3, 0.4)
// => 0.6666666666666669ran.dependence.pearson(x, y)
Calculates the Pearson correlation coefficient for paired arrays of values.
Parameters
| Name | Type | Description |
|---|---|---|
| x | number[] | First array of values. |
| y | number[] | Second array of values. |
Returns
numberThe Pearson correlation coefficient, or NaN if arrays have fewer than two elements or zero variance.
Throws
ErrorExamples
ran.dependence.pearson([], [])
// => NaN
ran.dependence.pearson([1, 2, 3], [1, 1, 1])
// => NaN
ran.dependence.pearson([1, 2, 3], [4, 5, 6])
// => 1
ran.dependence.pearson([1, 9, 10], [1, 2, 10])
// => 0.6643835616438358ran.dependence.pointBiserial(x, y)
Calculates the point-biserial correlation coefficient for paired arrays of values.
Parameters
| Name | Type | Description |
|---|---|---|
| x | number[] | First array of values. |
| y | number[] | Second array of values. Must contain 0s and 1s only. |
Returns
numberThe point-biserial correlation coefficient, or NaN if arrays have fewer than 2 elements or zero variance.
Throws
ErrorExamples
ran.dependence.pointBiserial([], [])
// => NaN
ran.dependence.pointBiserial([2, 2, 2], [0, 0, 1])
// => NaN
ran.dependence.pointBiserial([1, 2, 3], [4, 5, 6])
// => 0.8660254037844386ran.dependence.somersD(x, y)
Calculates Somers' D for paired arrays of values.
Parameters
| Name | Type | Description |
|---|---|---|
| x | number[] | First array of values. |
| y | number[] | Second array of values. |
Returns
numberSomers' D, or NaN for empty arrays.
Throws
ErrorExamples
ran.dependence.somersD([], [])
// => NaN
ran.dependence.somersD([1, 2, 3], [4, 6, 6])
// => 0.6666666666666666
ran.dependence.somersD([1, 1, 0], [4, 5, 6])
// => -1ran.dependence.spearman(x, y)
Calculates Spearman's rank correlation coefficient for two paired arrays of values.
Parameters
| Name | Type | Description |
|---|---|---|
| x | number[] | First array of values. |
| y | number[] | Second array of values. |
Returns
numberSpearman's rank correlation coefficient, or NaN for empty arrays.
Throws
ErrorExamples
ran.dependence.spearman([], [])
// => NaN
ran.dependence.spearman([1, 2, 3], [1, 4, 2])
// => 0.5
ran.dependence.spearman([1, 9, 10], [1, 2, 10])
// => 1ran.dependence.yuleQ(p00, p01, p10, p11)
Calculates Yule's Q for the joint probabilities of two binary variables:
Parameters
| Name | Type | Description |
|---|---|---|
| p00 | number | The probability of X = 0 and Y = 0. |
| p01 | number | The probability of X = 0 and Y = 1. |
| p10 | number | The probability of X = 1 and Y = 0. |
| p11 | number | The probability of X = 1 and Y = 1. |
Returns
numberYule's Q, or NaN when p01 or p10 is zero (the odds ratio diverges, making the formula indeterminate).
Examples
ran.dependence.yuleQ(0.3, 0, 0.3, 0.4)
// => NaN
ran.dependence.yuleQ(0.3, 0.3, 0, 0.4)
// => NaN
ran.dependence.yuleQ(0.1, 0.2, 0.3, 0.4)
// => -0.19999999999999984ran.dependence.yuleY(p00, p01, p10, p11)
Calculates Yule's Y for the joint probabilities of two binary variables:
Parameters
| Name | Type | Description |
|---|---|---|
| p00 | number | The probability of X = 0 and Y = 0. |
| p01 | number | The probability of X = 0 and Y = 1. |
| p10 | number | The probability of X = 1 and Y = 0. |
| p11 | number | The probability of X = 1 and Y = 1. |
Returns
numberYule's Y, or NaN when p01 or p10 is zero (the odds ratio diverges, making the formula indeterminate).
Examples
ran.dependence.yuleY(0.3, 0, 0.3, 0.4)
// => NaN
ran.dependence.yuleY(0.3, 0.3, 0, 0.4)
// => NaN
ran.dependence.yuleY(0.1, 0.2, 0.3, 0.4)
// => -0.10102051443364372ran.dispersion.cv(values)
Calculates the coefficient of variation of an array of values.
Parameters
| Name | Type | Description |
|---|---|---|
| values | number[] | Array of values to calculate coefficient of variation for. |
Returns
numberCoefficient of variation, or NaN for fewer than 2 elements, zero mean, or zero variance.
Examples
ran.dispersion.cv([])
// => NaN
ran.dispersion.cv([1])
// => NaN
ran.dispersion.cv([-1, 0, 1])
// => NaN
ran.dispersion.cv([1, 2, 3, 4, 5])
// => 0.5270462766947299ran.dispersion.dVar(x)
Calculates the distance variance for paired arrays of values.
Parameters
| Name | Type | Description |
|---|---|---|
| x | number[] | Array of values. |
Returns
numberThe distance variance, or NaN for an empty array.
Examples
ran.dispersion.dVar([])
// => NaN
ran.dispersion.dVar([1, 2, 3])
// => 0.7027283689263066ran.dispersion.entropy(probabilities[, base])
Calculates the Shannon entropy for a probability distribution.
Parameters
| Name | Type | Description |
|---|---|---|
| probabilities | number[] | Array representing the probabilities for the i-th value. |
| base | number | Base for the logarithm. If not specified, natural logarithm is used. |
Returns
numberEntropy of the probabilities, or NaN for empty input.
Examples
ran.dispersion.entropy([])
// => NaN
ran.dispersion.entropy([0.1, 0.1, 0.8])
// => 0.639031859650177
ran.dispersion.entropy([0.3, 0.3, 0.4])
// => 1.0888999753452238ran.dispersion.gini(values)
Calculates the Gini coefficient for a sample of values.
Parameters
| Name | Type | Description |
|---|---|---|
| values | number[] | Array of values to calculate the Gini coefficient for. |
Returns
numberThe Gini coefficient, or NaN for fewer than 2 elements or zero mean.
Examples
ran.dispersion.gini([])
// => NaN
ran.dispersion.gini([1])
// => NaN
ran.dispersion.gini([-1, 0, 1])
// => NaN
ran.dispersion.gini([1, 2, 3, 4])
// => 0.25
ran.dispersion.gini([1, 1, 1, 7])
// => 0.45ran.dispersion.iqr(values)
Calculates the interquartile range for a sample of values.
Parameters
| Name | Type | Description |
|---|---|---|
| values | number[] | Array of values to calculate the interquartile range for. |
Returns
numberThe interquartile range, or NaN for an empty array.
Examples
ran.dispersion.iqr([])
// => NaN
ran.dispersion.iqr([1, 1, 2, 3, 3])
// => 2ran.dispersion.md(values)
Calculates the mean absolute difference of an array of values.
Parameters
| Name | Type | Description |
|---|---|---|
| values | number[] | Array of values to calculate mean absolute difference for. |
Returns
numberMean absolute difference, or NaN for fewer than 2 elements.
Examples
ran.dispersion.md([])
// => NaN
ran.dispersion.md([1])
// => NaN
ran.dispersion.md([1, 2, 3, 4])
// => 1.25ran.dispersion.midhinge(values)
Calculates the midhinge for a sample of values.
Parameters
| Name | Type | Description |
|---|---|---|
| values | number[] | Array of values to calculate midhinge for. |
Returns
numberThe midhinge, or NaN for an empty array.
Examples
ran.dispersion.midhinge([])
// => NaN
ran.dispersion.midhinge([1, 1, 1, 2, 3])
// => 1.5ran.dispersion.qcd(values)
Calculates the quartile coefficient of dispersion for a sample of values.
Parameters
| Name | Type | Description |
|---|---|---|
| values | number[] | Array of values to calculate quartile coefficient of dispersion for. |
Returns
numberThe quartile coefficient of dispersion, or NaN for an empty array.
Examples
ran.dispersion.qcd([])
// => NaN
ran.dispersion.qcd([1, 2, 3])
// => 0.25ran.dispersion.range(values)
Calculates the range for a sample of values.
Parameters
| Name | Type | Description |
|---|---|---|
| values | number[] | Array of values to calculate range for. |
Returns
numberThe range of the values, or NaN for an empty array.
Examples
ran.dispersion.range([])
// => NaN
ran.dispersion.range([0, 1, 2, 2])
// => 2ran.dispersion.rmd(values)
Calculates the relative mean absolute difference of an array of values.
Parameters
| Name | Type | Description |
|---|---|---|
| values | number[] | Array of values to calculate relative mean absolute difference for. |
Returns
numberRelative mean absolute difference, or NaN for fewer than 2 elements or zero mean.
Examples
ran.dispersion.rmd([])
// => NaN
ran.dispersion.rmd([1])
// => NaN
ran.dispersion.rmd([-1, 0, 1])
// => NaN
ran.dispersion.rmd([1, 2, 3, 4])
// => 0.5ran.dispersion.stdev(values)
Calculates the unbiased standard deviation of an array of values.
Parameters
| Name | Type | Description |
|---|---|---|
| values | number[] | Array of values to calculate standard deviation for. |
Returns
numberStandard deviation of the values, NaN for fewer than 2 elements.
Examples
ran.dispersion.stdev([])
// => NaN
ran.dispersion.stdev([1])
// => NaN
ran.dispersion.stdev([1, 2, 3, 4, 5])
// => 1.5811388300841898ran.dispersion.variance(values)
Calculates the unbiased sample variance of an array of values using Welford's algorithm.
Parameters
| Name | Type | Description |
|---|---|---|
| values | number[] | Array of values to calculate variance for. |
Returns
numberVariance of the values, NaN for fewer than 2 elements.
Examples
ran.dispersion.variance([])
// => NaN
ran.dispersion.variance([1])
// => NaN
ran.dispersion.variance([1, 2, 3, 4, 5])
// => 2.5ran.dispersion.vmr(values)
Calculates the variance-to-mean ratio of an array of values.
Parameters
| Name | Type | Description |
|---|---|---|
| values | number[] | Array of values to calculate variance-to-mean ratio for. |
Returns
numberVariance-to-mean ratio, or NaN for fewer than 2 elements or zero mean.
Examples
ran.dispersion.vmr([])
// => NaN
ran.dispersion.vmr([1])
// => NaN
ran.dispersion.vmr([-1, 0, 1])
// => NaN
ran.dispersion.vmr([1, 2, 3, 4, 5])
// => 0.8333333333333334ran.dist.guess(data[, options])
Fits a set of candidate distributions to a dataset and ranks them by BIC weight — the probability that each candidate is the best-fitting model in the candidate set, given the data. "Guess" is intentional: this is a heuristic exploratory tool, not a verdict.
Candidates are pre-filtered before the expensive fit() call: hard filters (matching type and support against the data) are followed by soft, statistically-principled filters (skewness, coefficient of variation, dispersion index) that can, by design, silently exclude a candidate that would in fact have fit reasonably well. The soft filters' false-exclusion risk is not uniform, and has been empirically measured by Monte Carlo simulation (scripts/guess-filter-validation.js, 10 000 seeded draws per configuration, n = 50..1000; see issues #1054 and #1064). The skewness threshold used for a SYMMETRIC candidate is 2·√(c/n), where c is that family's own asymptotic skewness-estimator variance factor (Var(g1)·n ≈ μ6/μ2³ − 6·μ4/μ2² + 9, using population central moments — see _guess-meta.js's SYMMETRIC doc for the per-family derivation), not a single normal-only constant: the naive 6/n (roughly 2 standard errors of the sample-skewness estimator under normality) only holds for Normal(0, 1) (measured 4.2%-4.7% false exclusion across the tested n range, unaffected by this fix) and understates the true variance for heavier-tailed symmetric families — Laplace(0, 1)'s heavier tails (excess kurtosis 3 vs. Normal's 0) inflate it roughly tenfold (c ≈ 63 vs. Normal's c = 6), which the per-family threshold now accounts for directly instead of sharing Normal's bound: measured false exclusion dropped from 34.7%-51.1% under the old shared threshold to 1.4%-4.2% across the same n range. Uniform(-1, 1)'s c = 72/35 ≈ 2.06 is already lower than Normal's, so its measured 4.4%-5.6% rate was safe both before and after this fix. The positive-skew-only rule is deliberately asymmetric — it only excludes on strongly negative sample skewness, so ordinary sampling noise around zero or positive skew never triggers it; measured false-exclusion was ~0% for both Exponential(1) and Gamma(20, 1) (the latter's skewness, 2/√20 ≈ 0.45, is the family's lowest at that shape, making it the closest a POSITIVE_SKEW_ONLY member gets to the symmetric boundary). The coefficient-of-variation ([0.1, 10]) and dispersion-index (>3, <0.5) bounds were also measured at ~0% false exclusion for their respective representative distributions (Exponential(1), Poisson(5), NegativeBinomial(5, 0.5)) across the same n range — comfortably safe heuristics for those families, not merely unvalidated ones. A distribution excluded by a soft filter is never reported, with no diagnostic indicating it was screened out; callers with a specific hypothesis about their data should bypass all filtering via the candidates option rather than rely on the default pool. A candidate whose fit() throws is skipped rather than propagating the error. Throws if the data is too small for the surviving candidate set's largest parameter count (BIC's asymptotic approximation requires roughly 20 observations per parameter).
Parameters
| Name | Type | Description |
|---|---|---|
| data | number[] | Array of numbers to fit candidate distributions to. |
| options | Object | Options for the fitting procedure. |
| candidates | Function[] | Distribution constructors to try, overriding the default candidate pool (all distributions). |
Returns
Object[]Array of {name, params, bicWeight, pValue}, sorted by descending bicWeight (bicWeight values across the array sum to 1). For continuous candidates, pValue uses the Marsaglia & Marsaglia (2004) Anderson-Darling asymptotic approximation, which can occasionally report a value slightly above 1 for a very small, near-perfectly-fit sample — an artifact of the published approximation itself. Carries a warning string property when every surviving candidate fails goodness-of-fit at α=0.05.
Throws
Errorran.dist.Distribution()
The distribution generator base class, all distribution generators extend this class. The methods listed here are available for all distribution generators. Integer parameters of a distribution are rounded. The examples provided for this class are using a Pareto distribution.
ran.dist.Distribution.aic(data)
Returns the value of the Akaike information criterion for a specific data set. Note that this method does not optimize the likelihood, merely computes the AIC with the current parameter values.
Parameters
| Name | Type | Description |
|---|---|---|
| data | number[] | Array of values containing the data. |
Returns
numberThe AIC for the current parameters.
Examples
let pareto1 = new dist.Pareto(1, 2)
let pareto2 = new dist.Pareto(1, 5)
let sample = pareto1.sample(1000)
pareto1.aic(sample)
// => 1584.6619128383577
pareto2.aic(sample)
// => 2719.0367230482957ran.dist.Distribution.bic(data)
Returns the value of the Bayesian information criterion for a specific data set. Note that this method does not optimize the likelihood, merely computes the BIC with the current parameter values.
Parameters
| Name | Type | Description |
|---|---|---|
| data | number[] | Array of values containing the data. |
Returns
numberThe BIC for the current parameters.
Examples
let pareto1 = new dist.Pareto(1, 2)
let pareto2 = new dist.Pareto(1, 5)
let sample = pareto1.sample(1000)
pareto1.bic(sample)
// => 1825.3432698372499
pareto2.bic(sample)
// => 3190.5839264881165ran.dist.Distribution.bounded()
Returns the boundedness category of the distribution's support:
Returns
The boundedness category of the support.
ran.dist.Distribution.cdf(x)
The cumulative distribution function:
if the distribution is continuous and
if it is discrete. The functions and denote the probability density and mass functions.
Parameters
| Name | Type | Description |
|---|---|---|
| x | number | Value to evaluate CDF at. |
Returns
numberThe cumulative distribution value.
Examples
let pareto = new ran.dist.Pareto(1, 2)
pareto.cdf(3)
// => 0.8888888888888888ran.dist.Distribution.cHazard(x)
Parameters
| Name | Type | Description |
|---|---|---|
| x | number | Value to evaluate cumulative hazard at. |
Returns
numberThe cumulative hazard.
Examples
let pareto = new ran.dist.Pareto(1, 2)
pareto.cHazard(3)
// => 2.197224577336219ran.dist.Distribution.fit(data)
Estimates the distribution parameters from data using maximum likelihood estimation (MLE). Distributions with a closed-form MLE return it directly; all others maximise the log-likelihood lnL(data) with Powell's derivative-free conjugate-direction optimizer.
Parameters
| Name | Type | Description |
|---|---|---|
| data | number[] | Array of observations to fit. |
Returns
DistributionA new instance of the same distribution with MLE parameters.
ran.dist.Distribution.hazard(x)
The hazard function:
where and are the probability density (or mass) function and the survival function, respectively.
Parameters
| Name | Type | Description |
|---|---|---|
| x | number | Value to evaluate the hazard at. |
Returns
numberThe hazard value.
Examples
let pareto = new ran.dist.Pareto(1, 2)
pareto.hazard(3)
// => 0.6666666666666663ran.dist.Distribution.kurtosis()
The theoretical excess kurtosis of the distribution:
Returns NaN when undefined (zero variance, or moment does not exist). Distributions with non-finite moments must override this method.
Returns
numberThe theoretical excess kurtosis.
ran.dist.Distribution.lnL(data)
The log-likelihood of the current distribution based on some data. More precisely:
where is the set of observations (sample) and is the parameter vector of the distribution. The function denotes the probability density/mass function.
Parameters
| Name | Type | Description |
|---|---|---|
| data | number[] | Array of numbers to calculate log-likelihood for. |
Returns
numberThe log-likelihood of the data for the distribution.
Examples
let pareto = new ran.dist.Pareto(1, 2)
let uniform = new ran.dist.UniformContinuous(1, 10);
let sample1 = pareto.sample(100)
pareto.L(sample1)
// => -104.55926409382
let sample2 = uniform.sample(100)
pareto.L(sample2)
// => -393.1174868780569ran.dist.Distribution.load(state)
Reconstructs a distribution instance from a snapshot created by save(). The returned instance is still built without a constructor call; a throwaway probe instance is constructed only to validate that the restored state's shape matches what the current class definition expects.
Parameters
| Name | Type | Description |
|---|---|---|
| state | Object | The state to load, as returned by save(). |
Returns
DistributionNew distribution instance with the restored state.
Throws
ErrorExamples
let pareto1 = new ran.dist.Pareto(1, 2).seed('test')
let sample1 = pareto1.sample(2)
let state = pareto1.save()
let pareto2 = ran.dist.Pareto.load(state)
let sample2 = pareto2.sample(3)
// => [ 1.1315154468682591,
// 5.44269493220745,
// 1.2587482868229616 ]ran.dist.Distribution.logPdf(x)
The logarithmic probability density function. For discrete distributions, this is the logarithm of the probability mass function.
Parameters
| Name | Type | Description |
|---|---|---|
| x | number | Value to evaluate the log pdf at. |
Returns
numberThe logarithmic probability density (or mass).
Examples
let pareto = new ran.dist.Pareto(1, 2)
pareto.lnPdf(3)
// => -2.6026896854443837ran.dist.Distribution.mean()
The theoretical mean of the distribution:
Returns a finite number for well-behaved distributions, NaN when the moment is mathematically undefined, or Infinity / -Infinity when it diverges. Distributions with non-finite moments must override this method; the numerical fallback cannot detect divergence through truncated integration.
Returns
numberThe theoretical mean.
ran.dist.Distribution.params()
Returns the natural (user-facing) parameters of the distribution. Internal lookup state is not included.
Returns
ObjectThe natural parameters of the distribution.
ran.dist.Distribution.pdf(x)
Probability density function. In case of discrete distributions, it is the probability mass function.
Parameters
| Name | Type | Description |
|---|---|---|
| x | number | Value to evaluate distribution at. |
Returns
numberThe probability density or probability mass.
Examples
let pareto = new ran.dist.Pareto(1, 2)
pareto.pdf(3)
// => 0.07407407407407407ran.dist.Distribution.q(p)
The quantile function of the distribution. For continuous distributions, it is defined as the inverse of the distribution function:
whereas for discrete distributions it is the lower boundary of the interval that satisfies :
with denoting the support of the distribution. For distributions with an analytically invertible cumulative distribution function, the quantile is explicitly implemented. In other cases, two fallback estimations are used: for continuous distributions the equation is solved using Brent's method. For discrete distributions a look-up table is used with linear search.
Parameters
| Name | Type | Description |
|---|---|---|
| p | number | The probability at which the quantile should be evaluated. |
Returns
numberThe value of the quantile function at the specified probability.
Throws
Errorran.dist.Distribution.sample([n])
Generates some random variate.
Parameters
| Name | Type | Description |
|---|---|---|
| n | number | Number of variates to generate. If not specified, a single value is returned. |
Returns
numbernumber[]Single sample or an array of samples.
Examples
let pareto = new ran.dist.Pareto(1, 2)
pareto.sample(5)
// => [ 5.619011325146519,
// 1.3142187491180493,
// 1.0513159445581859,
// 1.8124951360943067,
// 1.1694087449301402 ]ran.dist.Distribution.save()
Returns the current state of the generator. The object returned by this method contains all information necessary to set up another generator of the same distribution (parameters, state of the pseudo random generator, etc).
Returns
Object representing the inner state of the current generator.
Examples
let pareto1 = new ran.dist.Pareto(1, 2).seed('test')
let sample1 = pareto1.sample(2)
let state = pareto1.save()
let pareto2 = ran.dist.Pareto.load(state)
let sample2 = pareto2.sample(3)
// => [ 1.1315154468682591,
// 5.44269493220745,
// 1.2587482868229616 ]ran.dist.Distribution.seed(value)
Sets the seed for the distribution generator. Distributions implement the same PRNG ( xoshiro128+) that is used in the core functions.
Parameters
| Name | Type | Description |
|---|---|---|
| value | numberstring | The value of the seed, either a number or a string (for the ease of tracking seeds). |
Returns
thisReference to the current distribution.
Examples
let pareto = new ran.dist.Pareto(1, 2).seed('test')
pareto.sample(5)
// => [ 1.571395735462202,
// 2.317583041477979,
// 1.1315154468682591,
// 5.44269493220745,
// 1.2587482868229616 ]ran.dist.Distribution.skewness()
The theoretical skewness of the distribution:
Returns NaN when undefined (zero variance, or moment does not exist). Distributions with non-finite moments must override this method.
Returns
numberThe theoretical skewness.
ran.dist.Distribution.support()
Returns the support of the probability distribution (based on the current parameters). Note that the support for the probability distribution is not necessarily the same as the support of the cumulative distribution.
Returns
undefined[]An array of objects describing the lower and upper boundary of the support. Each object contains a value: number and a closed: boolean property with the value of the boundary and whether it is closed, respectively. When value is (+/-)Infinity, closed is always false.
ran.dist.Distribution.survival(x)
Parameters
| Name | Type | Description |
|---|---|---|
| x | number | Value to evaluate survival function at. |
Returns
numberThe survival value.
Examples
let pareto = new ran.dist.Pareto(1, 2)
pareto.survival(3)
// => 0.11111111111111116ran.dist.Distribution.test(values)
Tests if an array of values is sampled from the specified distribution. For discrete distributions this method uses test, whereas for continuous distributions it uses the Anderson-Darling test. In both cases, the probability of Type I error (rejecting a correct null hypotheses) is 1%.
Parameters
| Name | Type | Description |
|---|---|---|
| values | number[] | Array of values to test. |
Returns
Object representing the result of the test:
Examples
let pareto = new ran.dist.Pareto(1, 2)
let uniform = new ran.dist.UniformContinuous(1, 10);
let sample1 = pareto.sample(100)
pareto.test(sample1)
// => { statistics: 0.312, passed: true }
let sample2 = uniform.sample(100)
pareto.test(sample2)
// => { statistics: 9.47, passed: false }ran.dist.Distribution.type()
Returns the type of the distribution (either discrete or continuous).
Returns
Distribution type.
ran.dist.Distribution.variance()
The theoretical variance of the distribution:
Returns a non-negative finite number for well-behaved distributions, NaN when the moment is mathematically undefined, or Infinity when it diverges. Distributions with non-finite moments must override this method.
Returns
numberThe theoretical variance.
ran.dist.Alpha(alpha, beta)
Probability density function for the alpha distribution:
where and denote the probability density and cumulative probability functions of the normal distribution. Support: .
Parameters
| Name | Type | Description |
|---|---|---|
| alpha | number | Shape parameter. |
| beta | number | Scale parameter. |
ran.dist.Anglit(mu, beta)
Parameters
| Name | Type | Description |
|---|---|---|
| mu | number | Location parameter. |
| beta | number | Scale parameter. |
ran.dist.Arcsine(a, b)
Probability density function for the arbitrarily bounded arcsine distribution:
where and . Support: .
Parameters
| Name | Type | Description |
|---|---|---|
| a | number | Lower boundary. |
| b | number | Upper boundary. |
ran.dist.AsymmetricLaplace(mu, sigma, kappa)
Probability density function for the asymmetric Laplace distribution:
where , , and . At it reduces to . Support: .
Parameters
| Name | Type | Description |
|---|---|---|
| mu | number | Location parameter. |
| sigma | number | Scale parameter. |
| kappa | number | Asymmetry parameter. |
ran.dist.BaldingNichols(F, p)
Probability density function for the Balding-Nichols distribution:
where , and . Support: . It is simply a re-parametrization of the beta distribution.
Parameters
| Name | Type | Description |
|---|---|---|
| F | number | Fixation index. |
| p | number | Allele frequency. |
ran.dist.Bates(n, a, b)
Parameters
| Name | Type | Description |
|---|---|---|
| n | number | Number of uniform variates to sum. If not an integer, it is rounded to the nearest one. |
| a | number | Lower boundary of the uniform variate. |
| b | number | Upper boundary of the uniform variate. |
ran.dist.Benini(alpha, beta, sigma)
Parameters
| Name | Type | Description |
|---|---|---|
| alpha | number | First shape parameter. |
| beta | number | Second shape parameter. |
| sigma | number | Scale parameter. |
ran.dist.BenktanderII(a, b)
Parameters
| Name | Type | Description |
|---|---|---|
| a | number | Scale parameter. |
| b | number | Shape parameter. |
ran.dist.Bernoulli(p)
Parameters
| Name | Type | Description |
|---|---|---|
| p | number | Probability of the outcome 1. |
ran.dist.Beta(alpha, beta)
Parameters
| Name | Type | Description |
|---|---|---|
| alpha | number | First shape parameter. |
| beta | number | Second shape parameter. |
ran.dist.BetaBinomial(n, alpha, beta)
Parameters
| Name | Type | Description |
|---|---|---|
| n | number | Number of trials. |
| alpha | number | First shape parameter. |
| beta | number | Second shape parameter. |
ran.dist.BetaGeometric(alpha, beta)
Parameters
| Name | Type | Description |
|---|---|---|
| alpha | number | First shape parameter. |
| beta | number | Second shape parameter. |
ran.dist.BetaNegativeBinomial(r, alpha, beta)
Parameters
| Name | Type | Description |
|---|---|---|
| r | number | Number of successes (rounded to nearest integer). |
| alpha | number | First shape parameter. |
| beta | number | Second shape parameter. |
ran.dist.BetaPrime(alpha, beta)
Probability density function for the beta prime distribution (also known as inverted beta):
with and is the beta function. Support: .
Parameters
| Name | Type | Description |
|---|---|---|
| alpha | number | First shape parameter. |
| beta | number | Second shape parameter. |
ran.dist.BetaRectangular(alpha, beta, theta, a, b)
Probability density function for the beta-rectangular distribution:
with , , , and is the beta function. Support: .
Parameters
| Name | Type | Description |
|---|---|---|
| alpha | number | First shape parameter. |
| beta | number | Second shape parameter. |
| theta | number | Mixture parameter. |
| a | number | Lower boundary of the support. |
| b | number | Upper boundary of the support. |
ran.dist.Binomial(n, p)
Parameters
| Name | Type | Description |
|---|---|---|
| n | number | Number of trials. |
| p | number | Probability of success. |
ran.dist.BirnbaumSaunders(mu, beta, gamma)
Probability density function for the Birnbaum-Saunders distribution (also known as fatigue life distribution):
with , , and is the probability density function of the standard normal distribution. Support: .
Parameters
| Name | Type | Description |
|---|---|---|
| mu | number | Location parameter. |
| beta | number | Scale parameter. |
| gamma | number | Shape parameter. |
ran.dist.Borel(mu)
Parameters
| Name | Type | Description |
|---|---|---|
| mu | number | Distribution parameter. |
ran.dist.BorelTanner(mu, n)
Parameters
| Name | Type | Description |
|---|---|---|
| mu | number | Distribution parameter. |
| n | number | Number of Borel distributed variates to add. If not an integer, it is rounded to the nearest one. |
ran.dist.BoundedPareto(L, H, alpha)
Parameters
| Name | Type | Description |
|---|---|---|
| L | number | Lower boundary. |
| H | number | Upper boundary. |
| alpha | number | Shape parameter. |
ran.dist.Bradford(c)
Parameters
| Name | Type | Description |
|---|---|---|
| c | number | Shape parameter. |
ran.dist.Burr(c, k)
Probability density function for the Burr (XII) distribution (also known as Singh-Maddala distribution):
with . Support: .
Parameters
| Name | Type | Description |
|---|---|---|
| c | number | First shape parameter. |
| k | number | Second shape parameter. |
ran.dist.Categorical(weights, min)
Parameters
| Name | Type | Description |
|---|---|---|
| weights | number[] | Weights for the distribution (doesn't need to be normalized). |
| min | number | Lowest value to sample (support starts at this value). |
ran.dist.Cauchy(x0, gamma)
Parameters
| Name | Type | Description |
|---|---|---|
| x0 | number | Location parameter. |
| gamma | number | Scale parameter. |
ran.dist.Champernowne(alpha, lambda, x0)
Probability density function for the Champernowne distribution:
with normalization constant , where , , and . Support: .
Parameters
| Name | Type | Description |
|---|---|---|
| alpha | number | Shape parameter. Must be positive. |
| lambda | number | Asymmetry parameter. Must satisfy 0 <= lambda < 1. |
| x0 | number | Location parameter. |
ran.dist.Chi(k)
Parameters
| Name | Type | Description |
|---|---|---|
| k | number | Degrees of freedom. If not an integer, is rounded to the nearest integer. |
ran.dist.Chi2(k)
Parameters
| Name | Type | Description |
|---|---|---|
| k | number | Degrees of freedom. If not an integer, is rounded to the nearest one. |
ran.dist.ConwayMaxwellPoisson(lambda, nu)
Parameters
| Name | Type | Description |
|---|---|---|
| lambda | number | Rate parameter (lambda > 0). |
| nu | number | Dispersion parameter (nu > 0). nu = 1 gives Poisson, nu > 1 gives underdispersion. |
ran.dist.Dagum(p, a, b)
Parameters
| Name | Type | Description |
|---|---|---|
| p | number | First shape parameter. |
| a | number | Second shape parameter. |
| b | number | Scale parameter. |
ran.dist.Davis(mu, b, n)
Parameters
| Name | Type | Description |
|---|---|---|
| mu | number | Location parameter. |
| b | number | Scale parameter. |
| n | number | Shape parameter. Must be greater than 1. |
ran.dist.Degenerate(x0)
Parameters
| Name | Type | Description |
|---|---|---|
| x0 | number | Location of the distribution. |
ran.dist.Delaporte(alpha, beta, lambda)
Parameters
| Name | Type | Description |
|---|---|---|
| alpha | number | Shape parameter of the gamma component. Default component is 1. |
| beta | number | Scale parameter of the gamma component. |
| lambda | number | Mean of the Poisson component. |
ran.dist.DiscreteLaplace(p, mu)
Probability mass function for the discrete Laplace distribution (also called the bilateral geometric distribution):
with and . Support: .
Parameters
| Name | Type | Description |
|---|---|---|
| p | number | Geometric decay parameter. |
| mu | number | Integer location parameter. If not an integer, it is rounded to the nearest one. |
ran.dist.DiscreteUniform(xmin, xmax)
Parameters
| Name | Type | Description |
|---|---|---|
| xmin | number | Lower boundary. If not an integer, it is rounded to the nearest one. |
| xmax | number | Upper boundary. If not an integer, it is rounded to the nearest one. |
ran.dist.DiscreteWeibull(q, beta)
Probability mass function for the discrete Weibull distribution (using the original parametrization):
with and . Support: .
Parameters
| Name | Type | Description |
|---|---|---|
| q | number | First shape parameter. |
| beta | number | Second shape parameter. |
ran.dist.DoubleGamma(alpha, beta)
Probability density function for the double gamma distribution (same shape/rate parametrization as used by the gamma distribution):
where . Support: .
Parameters
| Name | Type | Description |
|---|---|---|
| alpha | number | Shape parameter. |
| beta | number | Rate parameter. |
ran.dist.DoubleWeibull(lambda, k)
Parameters
| Name | Type | Description |
|---|---|---|
| lambda | number | Scale parameter. |
| k | number | Shape parameter. |
ran.dist.DoublyNoncentralBeta(alpha, beta, lambda1, lambda2)
Parameters
| Name | Type | Description |
|---|---|---|
| alpha | number | First shape parameter. |
| beta | number | Second shape parameter. |
| lambda1 | number | First non-centrality parameter. |
| lambda2 | number | Second non-centrality parameter. |
ran.dist.DoublyNoncentralBeta._powellOptions()
Bounds fit()'s Powell search budget. On data that genuinely mismatches this family (also inherited by DoublyNoncentralF, which delegates its _pdf/_cdf here), the nested double-Poisson-mixing log-likelihood carries a long, near-flat ridge between the shape and non-centrality parameters: a full-precision Powell search (the base class's default tol=1e-8, maxIter=200) chases negligible log-likelihood gains along this ridge almost indefinitely, at ever-increasing per-point cost since larger non-centrality parameters require more series terms to evaluate (#1063). Empirically, tol=1e-2/maxIter=15 recovers parameters within this class's existing fit tolerances on well-matched data (matching the default optimizer's result within ordinary finite-sample noise) while bounding worst-case cost to roughly 1-2s instead of 13-30s+ on mismatched data. See solutions/performance/2026-07-22-0702-doubly-noncentral-fit-powell-ridge-cost.md
maxIter also bounds each inner Brent line search powell() runs per outer sweep, not just the outer sweep count itself (#1078). Investigated across 35 well-matched fits (7 parameter sets x 5 seeds): a decoupled, much larger inner-Brent budget produced bit-identical results, confirming maxIter=15 is not starving convergence there. On the same family-mismatched ridge data this fix targets, a larger inner budget did recover a meaningfully better log-likelihood (~16-32%) — but at the cost of reintroducing multi-second-plus fit() runs on that same data, i.e. exactly the cost blowup this fix exists to bound. The coupled maxIter=15 is kept as-is: on mismatched data, looser convergence is the deliberate, already-documented tradeoff above, not an unrelated defect to fix separately. See solutions/performance/2026-07-22-1600-doubly-noncentral-fit-inner-line-search-budget.md
Returns
ObjectThe bounded Powell search options.
ran.dist.DoublyNoncentralChi2(k1, k2, lambda1, lambda2)
Probability density function for the doubly non-central distribution:
where is the central density with degrees of freedom, and . Support: .
Parameters
| Name | Type | Description |
|---|---|---|
| k1 | number | First degrees of freedom. If not an integer, it is rounded to the nearest one. |
| k2 | number | Second degrees of freedom. If not an integer, it is rounded to the nearest one. |
| lambda1 | number | First non-centrality parameter. |
| lambda2 | number | Second non-centrality parameter. |
ran.dist.DoublyNoncentralF(d1, d2, lambda1, lambda2)
Parameters
| Name | Type | Description |
|---|---|---|
| d1 | number | First degrees of freedom. If not an integer, it is rounded to the nearest one. |
| d2 | number | Second degrees of freedom. If not an integer, it is rounded to the nearest one. |
| lambda1 | number | First non-centrality parameter. |
| lambda2 | number | Second non-centrality parameter. |
ran.dist.DoublyNoncentralT(nu, mu, theta)
Parameters
| Name | Type | Description |
|---|---|---|
| nu | number | Degrees of freedom. If not an integer, it is rounded to the nearest one. |
| mu | number | Location parameter. |
| theta | number | Shape parameter. |
ran.dist.Erlang(k, lambda)
Parameters
| Name | Type | Description |
|---|---|---|
| k | number | Shape parameter. It is rounded to the nearest integer. |
| lambda | number | Rate parameter. |
ran.dist.Exponential(lambda)
Parameters
| Name | Type | Description |
|---|---|---|
| lambda | number | Rate parameter. |
ran.dist.ExponentialLogarithmic(p, beta)
Parameters
| Name | Type | Description |
|---|---|---|
| p | number | Shape parameter. |
| beta | number | Scale parameter. |
ran.dist.ExponentiallyModifiedGaussian(mu, sigma, lambda)
Probability density function for the exponentially modified Gaussian distribution:
with , and . Support: .
The distribution is the convolution of a and an random variable.
Parameters
| Name | Type | Description |
|---|---|---|
| mu | number | Location parameter of the Gaussian component. |
| sigma | number | Scale parameter of the Gaussian component. |
| lambda | number | Rate parameter of the exponential component. |
ran.dist.ExponentiatedWeibull(lambda, k, alpha)
Parameters
| Name | Type | Description |
|---|---|---|
| lambda | number | Scale parameter. |
| k | number | First shape parameter. |
| alpha | number | Second shape parameter. |
ran.dist.F(d1, d2)
Probability density function for the F distribution (or Fisher-Snedecor's F distribution):
with . Support: .
Parameters
| Name | Type | Description |
|---|---|---|
| d1 | number | First degree of freedom. If not an integer, it is rounded to the nearest one. |
| d2 | number | Second degree of freedom. If not an integer, it is rounded to the nearest one. |
ran.dist.FisherZ(d1, d2)
Parameters
| Name | Type | Description |
|---|---|---|
| d1 | number | First degree of freedom. |
| d2 | number | Second degree of freedom. |
ran.dist.FlorySchulz(a)
Parameters
| Name | Type | Description |
|---|---|---|
| a | number | Shape parameter. |
ran.dist.Frechet(alpha, s, m)
Parameters
| Name | Type | Description |
|---|---|---|
| alpha | number | Shape parameter. |
| s | number | Scale parameter. |
| m | number | Location parameter. |
ran.dist.Gamma(alpha, beta)
Probability density function for the gamma distribution using the shape/rate parametrization:
where . Support: .
Parameters
| Name | Type | Description |
|---|---|---|
| alpha | number | Shape parameter. |
| beta | number | Rate parameter. |
ran.dist.GammaGompertz(b, s, beta)
Parameters
| Name | Type | Description |
|---|---|---|
| b | number | Scale parameter. |
| s | number | First shape parameter. |
| beta | number | Second shape parameter. |
ran.dist.GeneralizedExponential(a, b, c)
Parameters
| Name | Type | Description |
|---|---|---|
| a | number | First shape parameter. |
| b | number | Second shape parameter. |
| c | number | Third shape parameter. |
ran.dist.GeneralizedExtremeValue(c)
Probability density function for the generalized extreme value distribution:
with . Support: if , otherwise.
Parameters
| Name | Type | Description |
|---|---|---|
| c | number | Shape parameter. |
ran.dist.GeneralizedGamma(a, d, p)
Parameters
| Name | Type | Description |
|---|---|---|
| a | number | Scale parameter. |
| d | number | Shape parameter. |
| p | number | Shape parameter. |
ran.dist.GeneralizedHermite(a1, a2, m)
Parameters
| Name | Type | Description |
|---|---|---|
| a1 | number | Mean of the first Poisson component. |
| a2 | number | Mean of the second Poisson component. |
| m | number | Multiplier of the second Poisson. If not an integer, it is rounded to the nearest one. |
ran.dist.GeneralizedLogistic(mu, s, c)
Parameters
| Name | Type | Description |
|---|---|---|
| mu | number | Location parameter. |
| s | number | Scale parameter. |
| c | number | Shape parameter. |
ran.dist.GeneralizedNormal(mu, alpha, beta)
Parameters
| Name | Type | Description |
|---|---|---|
| mu | number | Location paramameter. |
| alpha | number | Scale parameter. |
| beta | number | Shape parameter. |
ran.dist.GeneralizedPareto(mu, sigma, xi)
Probability density function for the generalized Pareto distribution:
with , and . Support: if , otherwise.
Parameters
| Name | Type | Description |
|---|---|---|
| mu | number | Location parameter. |
| sigma | number | Scale parameter. |
| xi | number | Shape parameter. |
ran.dist.Geometric(p)
Probability mass function for the geometric distribution (the number of failures before the first success definition):
with . Support: .
Parameters
| Name | Type | Description |
|---|---|---|
| p | number | Probability of success. |
ran.dist.Gilbrat()
ran.dist.Gompertz(eta, b)
Parameters
| Name | Type | Description |
|---|---|---|
| eta | number | Shape parameter. |
| b | number | Scale parameter. |
ran.dist.Gumbel(mu, beta)
Parameters
| Name | Type | Description |
|---|---|---|
| mu | number | Location parameter. |
| beta | number | Scale parameter. |
ran.dist.HalfGeneralizedNormal(alpha, beta)
Parameters
| Name | Type | Description |
|---|---|---|
| alpha | number | Scale parameter. |
| beta | number | Shape parameter. |
ran.dist.HalfLogistic()
ran.dist.HalfNormal(sigma)
Parameters
| Name | Type | Description |
|---|---|---|
| sigma | number | Scale parameter. |
ran.dist.HeadsMinusTails(n)
Probability mass function for the absolute-value (folded) heads-minus-tails distribution:
where . Support: .
Parameters
| Name | Type | Description |
|---|---|---|
| n | number | Half number of trials (n > 0). |
ran.dist.Hoyt(q, omega)
Probability density function for the Nakagami distribution (previously mis-labelled as the Hoyt distribution):
where and . Support: .
Parameters
| Name | Type | Description |
|---|---|---|
| q | number | Shape parameter (same as m in Nakagami). |
| omega | number | Spread parameter. |
References
- ran.dist.Nakagami
ran.dist.HyperbolicSecant()
ran.dist.Hypergeometric(N, K, n)
Parameters
| Name | Type | Description |
|---|---|---|
| N | number | Total number of elements to sample from. If not an integer, it is rounded to the nearest one. |
| K | number | Total number of successes. If not an integer, it is rounded to the nearest one. |
| n | number | Number of draws. If not an integer, it is rounded to the nearest one. |
ran.dist.InverseChi2(nu)
Parameters
| Name | Type | Description |
|---|---|---|
| nu | number | Degrees of freedom. |
ran.dist.InverseGamma(alpha, beta)
Parameters
| Name | Type | Description |
|---|---|---|
| alpha | number | Shape parameter. |
| beta | number | Scale parameter. |
ran.dist.InverseGaussian(mu, lambda)
Parameters
| Name | Type | Description |
|---|---|---|
| mu | number | Mean of the distribution. |
| lambda | number | Shape parameter. |
ran.dist.InvertedWeibull(c)
Parameters
| Name | Type | Description |
|---|---|---|
| c | number | Shape parameter. |
ran.dist.JohnsonSB(gamma, delta, lambda, xi)
Parameters
| Name | Type | Description |
|---|---|---|
| gamma | number | First location parameter. |
| delta | number | First scale parameter. |
| lambda | number | Second scale parameter. |
| xi | number | Second location parameter. |
ran.dist.JohnsonSU(gamma, delta, lambda, xi)
Parameters
| Name | Type | Description |
|---|---|---|
| gamma | number | First location parameter. |
| delta | number | First scale parameter. |
| lambda | number | Second scale parameter. |
| xi | number | Second location parameter. |
ran.dist.Kolmogorov()
ran.dist.Kumaraswamy(a, b)
Probability density function for the Kumaraswamy distribution (also known as Minimax distribution):
with . Support: .
Parameters
| Name | Type | Description |
|---|---|---|
| a | number | First shape parameter. |
| b | number | Second shape parameter. |
ran.dist.Laplace(mu, b)
Probability density function for the Laplace distribution (also known as double exponential distribution):
where and . Support: .
Parameters
| Name | Type | Description |
|---|---|---|
| mu | number | Location parameter. |
| b | number | Scale parameter. |
ran.dist.Levy(mu, c)
Parameters
| Name | Type | Description |
|---|---|---|
| mu | number | Location parameter. |
| c | number | Scale parameter. |
ran.dist.Lindley(theta)
Parameters
| Name | Type | Description |
|---|---|---|
| theta | number | Shape parameter. |
ran.dist.Logarithmic(a, b)
Parameters
| Name | Type | Description |
|---|---|---|
| a | number | Lower boundary of the distribution. |
| b | number | Upper boundary of the distribution. |
ran.dist.LogCauchy(mu, sigma)
Parameters
| Name | Type | Description |
|---|---|---|
| mu | number | Location parameter. |
| sigma | number | Scale parameter. |
ran.dist.LogGamma(alpha, beta, mu)
Probability density function for the log-gamma distribution using the shape/rate parametrization:
where and . Support: .
Parameters
| Name | Type | Description |
|---|---|---|
| alpha | number | Shape parameter. |
| beta | number | Rate parameter. |
| mu | number | Location parameter. |
ran.dist.Logistic(mu, s)
Parameters
| Name | Type | Description |
|---|---|---|
| mu | number | Location parameter. |
| s | number | Scale parameter. |
ran.dist.LogisticExponential(lambda, kappa)
Parameters
| Name | Type | Description |
|---|---|---|
| lambda | number | Scale parameter. |
| kappa | number | Shape parameter. |
ran.dist.LogitNormal(mu, sigma)
Parameters
| Name | Type | Description |
|---|---|---|
| mu | number | Location parameter. |
| sigma | number | Scale parameter. |
ran.dist.LogLaplace(mu, b)
Parameters
| Name | Type | Description |
|---|---|---|
| mu | number | Location parameter. |
| b | number | Scale parameter. |
ran.dist.LogLogistic(alpha, beta)
Probability density function for the log-logistic distribution (also known as Fisk distribution):
with . Support: .
Parameters
| Name | Type | Description |
|---|---|---|
| alpha | number | Scale parameter. |
| beta | number | Shape parameter. |
ran.dist.LogNormal(mu, sigma)
Parameters
| Name | Type | Description |
|---|---|---|
| mu | number | Location parameter. |
| sigma | number | Scale parameter. |
ran.dist.LogSeries(p)
Parameters
| Name | Type | Description |
|---|---|---|
| p | number | Distribution parameter. |
ran.dist.Lomax(lambda, alpha)
Parameters
| Name | Type | Description |
|---|---|---|
| lambda | number | Scale parameter. |
| alpha | number | Shape parameter. |
ran.dist.Makeham(alpha, beta, lambda)
Probability density function for the Makeham distribution (also known as Gompertz-Makeham distribution):
with . Support: .
Parameters
| Name | Type | Description |
|---|---|---|
| alpha | number | Shape parameter. |
| beta | number | Rate parameter. |
| lambda | number | Scale parameter. |
ran.dist.MaxwellBoltzmann(a)
Parameters
| Name | Type | Description |
|---|---|---|
| a | number | Scale parameter. |
ran.dist.Mielke(k, s)
Probability density function for the Mielke distribution:
with . Support: . It can be viewed as a re-parametrization of the Dagum distribution.
Parameters
| Name | Type | Description |
|---|---|---|
| k | number | First shape parameter. |
| s | number | Second shape parameter. |
ran.dist.Moyal(mu, sigma)
Parameters
| Name | Type | Description |
|---|---|---|
| mu | number | Location parameter. |
| sigma | number | Scale parameter. |
ran.dist.Muth(alpha)
Parameters
| Name | Type | Description |
|---|---|---|
| alpha | number | Shape parameter. |
ran.dist.Nakagami(m, omega)
Parameters
| Name | Type | Description |
|---|---|---|
| m | number | Shape parameter. |
| omega | number | Spread parameter. |
ran.dist.NegativeHypergeometric(N, K, r)
Parameters
| Name | Type | Description |
|---|---|---|
| N | number | Total number of elements to sample from. If not an integer, it is rounded to the nearest one. |
| K | number | Total number of successes. If not an integer, it is rounded to the nearest one. |
| r | number | Total number of failures to stop at. If not an integer, it is rounded to the nearest one. |
ran.dist.NeymanA(lambda, phi)
Probability mass function for the Neyman type A distribution:
where and denotes the Stirling number of the second kind. Support: .
Parameters
| Name | Type | Description |
|---|---|---|
| lambda | number | Mean of the number of clusters. |
| phi | number | Mean of the cluster size. |
ran.dist.NoncentralBeta(alpha, beta, lambda)
Parameters
| Name | Type | Description |
|---|---|---|
| alpha | number | First shape parameter. |
| beta | number | Second shape parameter. |
| lambda | number | Non-centrality parameter. |
ran.dist.NoncentralChi(k, lambda)
Probability density function for the non-central distribution:
with , and is the modified Bessel function of the first kind with order . Support: .
Parameters
| Name | Type | Description |
|---|---|---|
| k | number | Degrees of freedom. If not an integer, it is rounded to the nearest one. |
| lambda | number | Non-centrality parameter. |
ran.dist.NoncentralChi2(k, lambda)
Probability density function for the non-central distribution:
with , and is the modified Bessel function of the first kind with order . Support: . When the distribution degenerates to a central .
Parameters
| Name | Type | Description |
|---|---|---|
| k | number | Degrees of freedom. If not an integer, it is rounded to the nearest one. |
| lambda | number | Non-centrality parameter. |
ran.dist.NoncentralF(d1, d2, lambda)
Parameters
| Name | Type | Description |
|---|---|---|
| d1 | number | First degree of freedom. If not an integer, it is rounded to the nearest one. |
| d2 | number | Second degree of freedom. If not an integer, it is rounded to the nearest one. |
| lambda | number | Non-centrality parameter. |
ran.dist.NoncentralT(nu, mu)
Parameters
| Name | Type | Description |
|---|---|---|
| nu | number | Degrees of freedom. If not an integer, it is rounded to the nearest one. |
| mu | number | Non-centrality parameter. |
ran.dist.Normal(mu, sigma)
Parameters
| Name | Type | Description |
|---|---|---|
| mu | number | Location parameter (mean). |
| sigma | number | Scale parameter (standard deviation). |
ran.dist.Pareto(xmin, alpha)
Parameters
| Name | Type | Description |
|---|---|---|
| xmin | number | Scale parameter. |
| alpha | number | Shape parameter. |
ran.dist.PERT(a, b, c)
Probability density function for the PERT distribution:
where , , , and is the beta function. Support: .
Parameters
| Name | Type | Description |
|---|---|---|
| a | number | Lower boundary of the support. |
| b | number | Mode of the distribution. |
| c | number | Upper boundary of the support. |
ran.dist.Poisson(lambda)
Parameters
| Name | Type | Description |
|---|---|---|
| lambda | number | Mean of the distribution. |
ran.dist.PolyaAeppli(lambda, theta)
Probability mass function for the Pólya-Aeppli distribution (also known as geometric Poisson distribution):
where and . Support: .
Parameters
| Name | Type | Description |
|---|---|---|
| lambda | number | Mean of the Poisson component. |
| theta | number | Parameter of the shifted geometric component. |
ran.dist.PowerLaw(a)
Probability density function for the power-law distribution (also called power-law distribution):
with . Support: .
Parameters
| Name | Type | Description |
|---|---|---|
| a | number | One plus the exponent of the distribution. |
ran.dist.QExponential(q, lambda)
Probability density function for the q-exponential distribution:
where , and denotes the q-exponential function. Support: if , otherwise .
Parameters
| Name | Type | Description |
|---|---|---|
| q | number | Shape parameter. |
| lambda | number | Rate parameter. |
ran.dist.R(c)
Parameters
| Name | Type | Description |
|---|---|---|
| c | number | Shape parameter. |
ran.dist.Rademacher()
ran.dist.RaisedCosine(mu, s)
Parameters
| Name | Type | Description |
|---|---|---|
| mu | number | Location paramter. |
| s | number | Scale parameter. |
ran.dist.Rayleigh(sigma)
Parameters
| Name | Type | Description |
|---|---|---|
| sigma | number | Scale parameter. |
ran.dist.Reciprocal(a, b)
Parameters
| Name | Type | Description |
|---|---|---|
| a | number | Lower boundary of the support. |
| b | number | Upper boundary of the support. |
ran.dist.ReciprocalInverseGaussian(mu, lambda)
Probability density function for the reciprocal inverse Gaussian distribution (RIG):
with . Support: .
Parameters
| Name | Type | Description |
|---|---|---|
| mu | number | Mean of the inverse Gaussian distribution. |
| lambda | number | Shape parameter. |
ran.dist.Rice(nu, sigma)
Probability density function for the Rice distribution:
with and is the modified Bessel function of the first kind with order zero. Support: .
Parameters
| Name | Type | Description |
|---|---|---|
| nu | number | First shape parameter. |
| sigma | number | Second shape parameter. |
ran.dist.ShiftedLogLogistic(mu, sigma, xi)
Probability density function for the shifted log-logistic distribution:
with , and . Support: if , if , otherwise.
Parameters
| Name | Type | Description |
|---|---|---|
| mu | number | Location parameter. |
| sigma | number | Scale parameter. |
| xi | number | Shape parameter. |
ran.dist.Skellam(mu1, mu2)
Probability mass function for the Skellam distribution:
with and is the modified Bessel function of the first kind with order . Support: .
Parameters
| Name | Type | Description |
|---|---|---|
| mu1 | number | Mean of the first Poisson distribution. |
| mu2 | number | Mean of the second Poisson distribution. |
ran.dist.SkewNormal(xi, omega, alpha)
Probability density function for the skew normal distribution:
where , and , denote the probability density and cumulative distribution functions of the standard normal distribution. Support: .
Parameters
| Name | Type | Description |
|---|---|---|
| xi | number | Location parameter. |
| omega | number | Scale parameter. |
| alpha | number | Shape parameter. |
ran.dist.Slash()
Probability density function for the slash distribution:
where is the probability density function of the standard normal distribution. Support: .
ran.dist.Soliton(N)
Parameters
| Name | Type | Description |
|---|---|---|
| N | number | Number of blocks in the messaging model. If not an integer, it is rounded to the nearest one. |
ran.dist.StudentT(nu)
Parameters
| Name | Type | Description |
|---|---|---|
| nu | number | Degrees of freedom. |
ran.dist.StudentZ(n)
Parameters
| Name | Type | Description |
|---|---|---|
| n | number | Degrees of freedom. |
ran.dist.Trapezoidal(a, b, c, d)
Parameters
| Name | Type | Description |
|---|---|---|
| a | number | Lower bound of the support. |
| b | number | Start of the level part. |
| c | number | End of the level part. |
| d | number | Upper bound of the support. |
ran.dist.Triangular(a, b, c)
Parameters
| Name | Type | Description |
|---|---|---|
| a | number | Lower bound of the support. |
| b | number | Upper bound of the support. |
| c | number | Mode of the distribution. |
ran.dist.TruncatedExponential(lambda, a, b)
Parameters
| Name | Type | Description |
|---|---|---|
| lambda | number | Rate parameter. |
| a | number | Lower boundary of the support. |
| b | number | Upper boundary of the support. |
ran.dist.TruncatedNormal(mu, sigma, a, b)
Probability density function for the truncated normal distribution:
where and . The functions and denote the probability density and cumulative distribution functions of the normal distribution. Finally, , and . Support: .
Parameters
| Name | Type | Description |
|---|---|---|
| mu | number | Mean of the underlying normal distribution. |
| sigma | number | Variance of the underlying normal distribution. |
| a | number | Lower boundary of the support. |
| b | number | Upper boundary of the support. |
ran.dist.TukeyLambda(lambda)
Probability density function for the Tukey lambda distribution:
where and . Support: if , otherwise .
Parameters
| Name | Type | Description |
|---|---|---|
| lambda | number | Shape parameter. |
ran.dist.Uniform(xmin, xmax)
Parameters
| Name | Type | Description |
|---|---|---|
| xmin | number | Lower boundary. |
| xmax | number | Upper boundary. |
ran.dist.UniformProduct(n)
Parameters
| Name | Type | Description |
|---|---|---|
| n | number | Number of uniform factors. If not an integer, it is rounded to the nearest one. |
ran.dist.UniformRatio()
ran.dist.UQuadratic(a, b)
Parameters
| Name | Type | Description |
|---|---|---|
| a | number | Lower bound of the support. |
| b | number | Upper bound of the support. |
ran.dist.VonMises(kappa)
Probability density function for the von Mises distribution:
with . Support: . Note that originally this distribution is periodic and therefore it is defined over , but (without the loss of general usage) this implementation still does limit the support on the bounded interval .
Parameters
| Name | Type | Description |
|---|---|---|
| kappa | number | Shape parameter. |
ran.dist.Weibull(lambda, k)
Parameters
| Name | Type | Description |
|---|---|---|
| lambda | number | Scale parameter. |
| k | number | Shape parameter. |
ran.dist.Wigner(R)
Parameters
| Name | Type | Description |
|---|---|---|
| R | number | Radius of the distribution. |
ran.dist.YuleSimon(rho)
Parameters
| Name | Type | Description |
|---|---|---|
| rho | number | Shape parameter. |
ran.dist.Zeta(s)
Probability mass function for the zeta distribution:
with and is the Riemann zeta function. Support: .
Parameters
| Name | Type | Description |
|---|---|---|
| s | number | Exponent of the distribution. |
ran.dist.Zipf(s, N)
Probability mass function for the Zipf distribution:
with , and denotes the generalized harmonic number. Support: .
Parameters
| Name | Type | Description |
|---|---|---|
| s | number | Exponent of the distribution. |
| N | number | Number of words. If not an integer, it is rounded to the nearest integer. Default is 100. |
ran.dist.ZipfMandelbrot(N, s, q)
Parameters
| Name | Type | Description |
|---|---|---|
| N | number | Number of elements (support size). If not an integer, it is rounded to the nearest integer. |
| s | number | Exponent of the distribution. |
| q | number | Shift parameter. |
ran.location.geometricMean(values)
Calculates the geometric mean of an array of values.
Parameters
| Name | Type | Description |
|---|---|---|
| values | number[] | Array of values to calculate geometric mean for. |
Returns
numberGeometric mean of the values, NaN for empty input.
Examples
ran.location.geometricMean([])
// => NaN
ran.location.geometricMean([1, 2, 3])
// => 1.8171205928321394ran.location.harmonicMean(values)
Calculates the harmonic mean of an array of values.
Parameters
| Name | Type | Description |
|---|---|---|
| values | number[] | Array of values to calculate harmonic mean for. |
Returns
numberHarmonic mean of the values, NaN if any value is non-positive.
Examples
ran.location.harmonicMean([])
// => NaN
ran.location.harmonicMean([0, 1, 2])
// => NaN
ran.location.harmonicMean([-1, 2, 3])
// => NaN
ran.location.harmonicMean([1, 2, 3])
// => 1.6363636363636365ran.location.mean(values)
Calculates the arithmetic mean of an array of values.
Parameters
| Name | Type | Description |
|---|---|---|
| values | number[] | Array of values to calculate mean for. |
Returns
numberMean of the values, NaN for empty input.
Examples
ran.location.mean([])
// => NaN
ran.location.mean([1, 2, 3])
// => 2ran.location.median(values)
Calculates the median of a sample of values.
Parameters
| Name | Type | Description |
|---|---|---|
| values | number[] | Array of values to calculate median for. |
Returns
numberMedian of the values, NaN for empty input.
Examples
ran.location.median([])
// => NaN
ran.location.median([1, 2, 3, 4])
// => 2.5ran.location.midrange(values)
Calculates the mid-range for a sample of values.
Parameters
| Name | Type | Description |
|---|---|---|
| values | number[] | Array of values to calculate mid-range for. |
Returns
numberThe mid-range of the values, NaN for empty input.
Examples
ran.location.midrange([])
// => NaN
ran.location.midrange([0, 0, 0, 1, 2])
// => 1ran.location.mode(values)
Calculates the mode(s) of a sample. In case of discrete values (integers), it returns the values corresponding to the highest frequencies in ascending order. For continuous sample, the mode is estimated using the half-sample mode algorithm.
Parameters
| Name | Type | Description |
|---|---|---|
| values | number[] | Array of values to calculate mode for. |
Returns
numbernumber[]The estimated mode (continuous sample) or an array of modes (discrete sample). Returns an empty array for empty input.
Examples
ran.location.mode([])
// => []
ran.location.mode([1])
// => [1]
ran.location.mode([1, 1, 2, 2, 3])
// => [1, 2]
ran.location.mode([1, 2, 2, 2, 3])
// => [2]
ran.location.mode([1.2, 3.4, 5.6])
// => 4.5ran.location.trimean(values)
Calculates the trimean for a sample of values.
Parameters
| Name | Type | Description |
|---|---|---|
| values | number[] | Array of values to calculate trimean for. |
Returns
numberThe trimean of the values, NaN for empty input.
Examples
ran.location.trimean([])
// => NaN
ran.location.trimean([1, 1, 1, 2, 3])
// => 1.25ran.mc.gelmanRubin(samples[, maxLength])
Calculates the Gelman-Rubin convergence diagnostic for a set of independent chains. Returns the R-hat statistic as a function of iteration count for each state dimension, starting from the minimum of 2 samples.
Parameters
| Name | Type | Description |
|---|---|---|
| samples | Array | Array of chains, where each chain is an array of states returned by RWM#sample. At least two chains are required. |
| maxLength | number | Maximum number of diagnostic values to return per dimension. Defaults to the full chain length. |
Throws
Errorran.mc.runChains(Sampler[, samplerOptions[, runOptions]])
Runs multiple independently-seeded MCMC chains from the same target and computes the Gelman-Rubin convergence diagnostic across them — the recommended workflow for gating MCMC convergence (decisions/0024-mcmc-warmup-convergence-strategy.md), since no signal computable from a single chain can distinguish "converged" from "stuck". samplerOptions is forwarded to new Sampler(samplerOptions) without inspecting its keys, so any MCMC subclass — including Gibbs, whose options object has no logDensity at all — can drive the diagnostic the same way (decisions/0033-generalized-runchains-sampler-driver.md).
Do not pass an explicit initialState.x. The same samplerOptions object is forwarded to every chain, and MCMC.seed() only redraws the starting position when x was not supplied. If you provide initialState.x, all chains start from the identical point, which defeats the over-dispersed-initialization that makes the Gelman-Rubin diagnostic meaningful — a chain family stuck in one mode then reports R-hat ≈ 1 ("converged") because every chain is stuck in the same place. Omit initialState.x so each seed draws its own random start.
Parameters
| Name | Type | Description |
|---|---|---|
| Sampler | Function | An MCMC subclass (e.g. RWM, AdaptiveMetropolis, Slice, Gibbs, HMC, MALA, or NUTS) to drive each chain. |
| samplerOptions | Object | Options object forwarded verbatim to new Sampler(samplerOptions) for every chain — the same shape that sampler's own options-object constructor accepts (e.g. {logDensity, config, initialState} for RWM/AdaptiveMetropolis/Slice, {logDensity, gradLogDensity, config, initialState} for HMC/MALA/NUTS, {conditionals, config, initialState} for Gibbs). |
| runOptions | Object | Run configuration. Supported properties: |
Returns
ObjectObject with properties: samples (number[][][], one sample array per chain) and rhat (number[][], the gelmanRubin() diagnostic across the chains).
Throws
Errorran.mc.MCMC(logDensity[, config[, initialState]])
Base class implementing a general Markov chain Monte Carlo sampler. All MCMC samplers extend this class. MCMC samplers approximate integrals by efficiently sampling a density that cannot be normalized or sampled directly. Every public subclass (RWM, AdaptiveMetropolis, Slice, HMC, Gibbs, MALA, NUTS) exposes an options-object-only constructor; this base constructor's positional (logDensity, config, initialState) signature is an internal contract those subclasses forward to, not part of the public API.
Parameters
| Name | Type | Description |
|---|---|---|
| logDensity | Function | The logarithm of the (unnormalized) target density. |
| config | Object | Sampler configuration. Supported properties: |
| initialState | Object | Initial state of the sampler. Supported properties: {x} (starting position), {samplingRate} (thinning interval), and {internal} for subclass-specific state. |
Throws
ErrorErrorErrorErrorran.mc.MCMC.ac()
Computes the autocorrelation function for each dimension at lags 0 to maxLag-1. Uses an online estimator: O(dim * maxLag) memory, O(dim * maxLag) per update, O(1) per query.
ran.mc.MCMC.ar()
Computes the acceptance rate over the most recent arWindow iterations (a sliding window, default 1000). During the partial-fill phase, before arWindow iterations have occurred since the last reset, this equals the exact cumulative rate.
Returns
numberFraction of proposals accepted in the current window.
ran.mc.MCMC.ess()
Computes the effective sample size for each dimension using Geyer's initial positive monotone sequence estimator (IPSM; Geyer 1992, Vehtari et al. 2021 — the estimator used by Stan and ArviZ): pairs consecutive lags starting at lag 0 (so the first pair always includes ), clamped to be no larger than (the true autocovariance sequence is convex, so a non-increasing sequence of pair sums has strictly lower variance than summing raw lags). The sum stops at the first pair whose clamped value is not positive; or () if even the first pair is non-positive (sum = 0) -- that would otherwise give a nonsensical negative . Anchoring the pairing at lag 0 means alone can never prematurely truncate the sum: is non-positive only when , an extreme case, unlike the old single-lag rule which underestimated (overestimated ESS) whenever an otherwise well-mixing chain had one merely-negative early lag. Built directly on the same accumulators as ac() and statistics() — no additional accumulator state. If the first pair itself is already non-positive (, an extreme case), exactly: a legitimate output of this truncation rule when the sampler genuinely produces that strong an anti-correlation, not necessarily a sign of a broken sampler. A milder resonance -- e.g. HMC's fixed pathLength resonating with the target's geometry, see hmc.js -- typically lands well short of that boundary and instead inflates or deflates ESS relative to the raw sample count without saturating to exactly. See #974: verified against a brute-force autocorrelation over the raw iterate() sequence, which confirmed the online accumulator is exact and the anti-correlation is genuine.
A fully stuck (zero-variance) chain is a distinct case from the above: ac()'s divisor is the population variance, so a chain that never moves produces at every lag including lag 0. That NaN is not a signal of non-positive autocorrelation to saturate on — it means the chain contributed zero effectively-independent samples, so ess() reports 1 rather than (the case, no observations at all yet, is unaffected and still reports 0).
solutions/testing/2026-07-18-1641-ess-geyer-ipsm-pairing-offset-self-consistent-wrong-tests.md — the pairing must start at lag 0 (anchored by rho[0] = 1), not lag 1; an off-by-one-lag version of this method passed every hand-derived test because the tests were derived by hand using the same wrong pairing.
Returns
number[]Array of effective sample sizes, one per dimension.
ran.mc.MCMC.iterate([callback[, warmUp]])
Performs a single iteration, updates accumulators, and optionally calls a callback.
Advanced/low-level: most callers should use warmUp and sample instead, which drive iterate() internally. Calling it manually is for cases that need per-step control (e.g. live progress plotting, custom stopping rules). sample() resets the accumulators before it starts collecting, but interleaving manual iterate() calls with warmUp()/sample() otherwise does not — mixing manual draws in can blend adaptation-phase and equilibrium-phase observations into statistics(), ar(), and ac().
Parameters
| Name | Type | Description |
|---|---|---|
| callback | Function | Called with (x, accepted) after each iteration. |
| warmUp | boolean | Whether the iteration is part of warm-up. Default is false. |
ran.mc.MCMC.sample([progress[, size]])
Samples from the target density. Resets accumulators so that statistics() reflects the sampling phase only, and ar() reflects at most its last arWindow draws (see ADR-0021). Thins the chain by samplingRate (set during warm-up).
Parameters
| Name | Type | Description |
|---|---|---|
| progress | Function | Called with the integer percentage complete (0–99), once per percent. |
| size | number | Number of samples to collect. Default is 1000. |
ran.mc.MCMC.seed(value)
Sets the seed for the sampler's pseudo random number generator. If the initial position was not explicitly provided at construction, it is redrawn from the newly seeded generator so that sampling is fully reproducible.
Parameters
| Name | Type | Description |
|---|---|---|
| value | numberstring | The value of the seed, either a number or a string (for the ease of tracking seeds). |
Returns
thisReference to the current sampler.
ran.mc.MCMC.state()
Returns the current state of the sampler. The return value can be passed to a sampler of the same type to resume from this position.
Returns
ObjectObject with properties: x (current position), samplingRate (thinning interval), internal (subclass state), and prng (the PRNG's exact stream position, restored on reconstruction so a resumed sampler's subsequent draws are bit-for-bit identical to an uninterrupted run — decisions/0035-mcmc-exact-stream-reproducible-resume.md).
ran.mc.MCMC.statistics()
Computes mean, standard deviation, and coefficient of variation for each dimension based on observations seen since the last reset (start of sampling or construction).
Returns
Object[]Array of {mean, std, cv} objects, one per dimension.
ran.mc.MCMC.warmUp([progress[, maxBatches]])
Carries out the warm-up phase. Runs batches of 10K iterations, adapts internal parameters via _adjust(), and tunes the thinning interval using the online autocorrelation estimate.
decisions/0024-mcmc-warmup-convergence-strategy.md — deliberately fixed-length, no convergence-triggered early stop: no signal computable from a single chain can distinguish "converged" from "stuck". Gate convergence on gelmanRubin() across multiple independently-seeded chains instead.
Parameters
| Name | Type | Description |
|---|---|---|
| progress | Function | Called with the percentage complete (0–100) after each batch. |
| maxBatches | number | Number of warm-up batches. Default is 100. |
ran.mc.AdaptiveMetropolis(options)
Class implementing the full-covariance adaptive Metropolis algorithm (Haario, Saksman & Tamminen, 2001). Unlike RWM, which adapts only the per-component (diagonal) proposal scale, this sampler learns the full joint proposal covariance from the chain's own history during warm-up: Sigma_proposal = (2.38^2 / dim) * (Cov(x) + epsilon * I). The covariance is refactorized via Matrix.ldl() after every warm-up iteration and frozen once sample() is called, since _adjust is only ever invoked from warmUp().
Parameters
| Name | Type | Description |
|---|---|---|
| options | Object | Sampler options, as a single object. |
| logDensity | Function | The logarithm of the (unnormalized) target density. |
| config | Object | AdaptiveMetropolis configuration (see MCMC base class for shared options). |
| initialState | Object | Initial state of the sampler (see MCMC base class). |
Throws
Errorran.mc.ARS(logDensity, support[, derivative])
Class implementing Adaptive Rejection Sampling (Gilks & Wild, 1992) for a univariate log-concave target density on a finite support bracket. A piecewise-linear upper hull, built from tangent lines to the log-density at a growing set of abscissae, gives a piecewise-exponential sampling envelope; a piecewise-linear lower hull built from the secant lines between the same abscissae gives a cheap "squeeze" test that avoids evaluating the true log-density whenever possible. Every time the true log-density does have to be evaluated, the tested point is added to the abscissa set, tightening both hulls so the acceptance probability increases monotonically as sampling proceeds. Unlike MCMC and its subclasses, ARS is not a Markov chain: every draw is an exact, independent sample from the target (up to the target being genuinely log-concave), with no warm-up or burn-in.
Parameters
| Name | Type | Description |
|---|---|---|
| logDensity | Function | The logarithm of the (unnormalized) target density. |
| support | number[] | The two-element [lo, hi] support bracket. Must be finite with lo < hi. |
| derivative | Function | The derivative of logDensity. Estimated via finite differences when omitted. |
Throws
Errorran.mc.Gibbs(options)
Class implementing a component-wise (systematic-scan) Gibbs sampler. Cycles through the dimensions in a fixed order and replaces each in turn with a draw from its full conditional distribution, given the current values of every other dimension. Because each draw comes directly from the exact conditional, there is no accept/reject step: every iteration is accepted and ar is always 1.
Parameters
| Name | Type | Description |
|---|---|---|
| options | Object | Sampler options, as a single object. |
| conditionals | Function[] | Array of samplers, one per dimension. The d-th conditional function is called as conditionals[d](x, rng) with the current full state (an array where index d is about to be replaced) and the sampler's own PRNG (exposing rng.next(): number, a uniform variate in [0, 1)), and must return a single draw from the full conditional distribution of dimension d given the rest of the state. seed() only reproduces a conditional's draws if the conditional actually consumes rng for its own randomness (e.g. rng.next()); a conditional that ignores rng and constructs its own independent generator remains non-reproducible regardless of seed() — see decisions/0026-gibbs-seed-rng-threading.md. |
| config | Object | Sampler configuration (see MCMC base class for shared options). dim defaults to conditionals.length; if provided explicitly it must match conditionals.length. |
| initialState | Object | Initial state of the sampler (see MCMC base class). |
Throws
Errorran.mc.HMC(options)
Class implementing the Hamiltonian Monte Carlo (HMC) sampler. Uses gradient information and a leapfrog integrator to simulate Hamiltonian dynamics, proposing distant moves along the resulting trajectory and accepting/rejecting via the Metropolis criterion on the augmented (position, momentum) system. Momenta are resampled from a standard multivariate Normal at the start of every iteration. During warm-up, the step size is adapted via Robbins-Monro dual averaging (Hoffman & Gelman 2014, S3.2) toward a target acceptance probability, and jittered multiplicatively each iteration to avoid periodicity artifacts.
Known limitation: only stepSize is jittered — pathLength (the number of leapfrog steps) stays fixed for the sampler's entire lifetime. A fixed trajectory length (pathLength * stepSize) can still land near a half-period of the target's natural oscillation at certain target correlations, producing genuine negative low-lag autocorrelation that ess() and ac() faithfully report — this is a legitimate property of the chain, not a bug in those estimators. If you observe this (e.g. ac() reporting negative autocorrelation at low lags, or ess() reporting an effective sample size well above or below the raw sample count), try a different pathLength, or switch to NUTS, which adapts trajectory length automatically each iteration (Hoffman & Gelman 2014) and removes the need to hand-tune pathLength.
Parameters
| Name | Type | Description |
|---|---|---|
| options | Object | Sampler options, as a single object. |
| logDensity | Function | The logarithm of the (unnormalized) target density. |
| gradLogDensity | Function | The gradient of logDensity: maps a state (number[]) to its gradient (number[]) of the same dimension. The array passed in may be reused and mutated across subsequent leapfrog steps; read it synchronously and do not retain the reference. |
| config | Object | HMC configuration (see MCMC base class for shared options), plus stepSize (ε, the leapfrog step size, default 0.1), pathLength (L, the number of leapfrog steps per iteration, default 10 — fixed for the sampler's lifetime and not jittered like stepSize; see the class JSDoc's "Known limitation" note for the resonance risk this can produce), and metric (the mass matrix structure adapted during warm-up: 'diag' (default) estimates a per-dimension variance; 'dense' estimates the full covariance matrix, refactored through Matrix's LDL decomposition). |
| initialState | Object | Initial state of the sampler (see MCMC base class). |
Throws
Errorran.mc.MALA(options)
Class implementing the Metropolis-adjusted Langevin algorithm (MALA) sampler. Proposes a single gradient-informed Langevin step per iteration (x' = x + (stepSize^2 / 2) * gradLogDensity(x) + stepSize * z, z ~ N(0, I)), then applies a Metropolis-Hastings correction for the proposal's asymmetry (the transition density's mean is state-dependent, so q(x'|x) != q(x|x')) to make the chain exact. During warm-up, the step size is adapted via batch Robbins-Monro (Roberts & Rosenthal 2009), the same scheme RWM uses, toward the MALA-optimal acceptance rate of ~0.574 (Roberts & Rosenthal 1998).
Parameters
| Name | Type | Description |
|---|---|---|
| options | Object | MALA options, as a single object. |
| logDensity | Function | The logarithm of the (unnormalized) target density. |
| gradLogDensity | Function | The gradient of logDensity: maps a state (number[]) to its gradient (number[]) of the same dimension. |
| config | Object | MALA configuration (see MCMC base class for shared options), plus stepSize (ε, default 0.1). |
| initialState | Object | Initial state of the sampler (see MCMC base class). |
Throws
Errorran.mc.NUTS(options)
Class implementing the No-U-Turn Sampler (NUTS). Extends Hamiltonian Monte Carlo by replacing a fixed-length leapfrog trajectory with a recursive doubling-tree procedure that extends forward or backward in a randomly chosen direction until the trajectory's outer endpoints start turning back toward each other (the "U-turn" stopping criterion) or a maximum tree depth is reached. The transition is selected via slice sampling over the tree's valid states, eliminating the need to hand-tune a trajectory length. Momenta are resampled from N(0, M) at the start of every iteration, where M is the Euclidean mass matrix adapted during warm-up (config.metric); the no-U-turn criterion is evaluated on the velocity M⁻¹r. During warm-up, the step size is adapted via Robbins-Monro dual averaging (Hoffman & Gelman 2014, S3.2) toward a target acceptance probability, driven by the tree-averaged acceptance statistic accumulated across every leapfrog evaluation in that iteration's tree.
Sampler-health diagnostics are exposed both per-transition and in aggregate: every iterate result carries divergent and maxDepthHit booleans, and divergenceCount / maxDepthCount report the per-sampling-phase totals (reset like ar). A well-behaved run reports both counts as 0; nonzero divergences flag a step size that is too large or a target too extreme, nonzero max-depth hits a step size that is too small. See decisions/0035-nuts-sampler-health-diagnostics.md.
Parameters
| Name | Type | Description |
|---|---|---|
| options | Object | Sampler options, as a single object. |
| logDensity | Function | The logarithm of the (unnormalized) target density. |
| gradLogDensity | Function | The gradient of logDensity: maps a state (number[]) to its gradient (number[]) of the same dimension. |
| config | Object | NUTS configuration (see MCMC base class for shared options), plus stepSize (ε, the leapfrog step size, default 0.1) and metric (the mass matrix structure adapted during warm-up: 'diag' (default) estimates a per-dimension variance; 'dense' estimates the full covariance matrix, refactored through Matrix's LDL decomposition). |
| initialState | Object | Initial state of the sampler (see MCMC base class). |
Throws
Errorran.mc.NUTS.divergenceCount()
Returns the number of divergent transitions recorded during the current sampling phase. A divergent transition is one whose leapfrog trajectory contained a leaf whose Hamiltonian drifted more than the energy-divergence threshold from the trajectory's start, indicating the step size is too large or the target geometry too extreme (biased exploration). Reset at construction and at the start of each sample call, so a read afterwards reflects the sampling phase only — the same lifecycle as ar. A well-behaved run reports 0.
Returns
numberCount of divergent transitions since the last reset.
ran.mc.NUTS.maxDepthCount()
Returns the number of transitions that reached the maximum tree depth during the current sampling phase. A max-depth hit is a doubling that exhausted the tree-depth cap without the trajectory U-turning, indicating the step size is too small (inefficient sampling). Reset at construction and at the start of each sample call, so a read afterwards reflects the sampling phase only — the same lifecycle as ar. A well-behaved run reports 0.
Returns
numberCount of max-tree-depth-saturated transitions since the last reset.
ran.mc.ParallelTempering(options[, legacyOptions])
Class implementing Parallel Tempering (Replica Exchange MCMC, Geyer 1991) to sample multimodal targets. Runs N independent MCMC replicas at inverse temperatures beta_1 = 1 > beta_2 > ... > beta_n, replica i targeting beta_i * logDensity(x). Hot replicas (small beta) have a flattened target and cross low-probability barriers between modes easily; the cold replica (beta = 1) samples the true target. After each thinned step, a swap between one alternating-parity set of adjacent replica pairs is proposed and accepted with probability min(1, exp((beta_i - beta_j) * (logDensity(x_j) - logDensity(x_i)))) (the direction that follows from detailed balance on the joint replica distribution; see the _proposeSwap implementation comment), letting the cold chain inherit the hot chains' mode-crossing moves.
Unlike every other class in ran.mc, this is not an MCMC subclass: it has no single position or target density of its own, only an array of independent replicas and the swap logic that couples them (see decisions/0028-parallel-tempering-standalone-coordinator.md). Each replica keeps its own proposal tuning pinned to its temperature slot; an accepted swap exchanges only the replicas' positions (and, where present, their cached scaled log-density), not their adaptation state.
Parameters
| Name | Type | Description |
|---|---|---|
| options | Object | Coordinator options, as a single object. Supported properties: |
| legacyOptions | Object | Deprecated positional-form options object, read only when the deprecated new ParallelTempering(logDensity, options) form is used. Do not use in new code. |
Throws
ErrorErrorran.mc.RWM(options)
Class implementing the (random walk) Metropolis algorithm as a diagonal adaptive Metropolis sampler. Proposals are joint (every component perturbed at once) in both warm-up and sampling; during warm-up a single global step scale is adapted via batch Robbins-Monro toward the optimal acceptance rate (0.44 in one dimension, 0.234 for higher dimensions) and the per-component scales track the running marginal standard deviations.
Parameters
| Name | Type | Description |
|---|---|---|
| options | Object | Sampler options, as a single object. |
| logDensity | Function | The logarithm of the (unnormalized) target density. |
| config | Object | RWM configuration (see MCMC base class for shared options). |
| initialState | Object | Initial state of the sampler (see MCMC base class). |
Throws
Errorran.mc.Slice(options)
Class implementing coordinate-wise slice sampling (Neal, R.M. (2003) "Slice Sampling", Annals of Statistics 31(3):705-767) via the stepping-out and shrinkage procedure. Each sweep updates every dimension in turn: a vertical level is drawn below the current point's density, an interval bracketing the resulting horizontal slice is found by stepping outward in increments of w, and a point within that interval is accepted once shrinkage finds one whose density exceeds the vertical level. No proposal distribution or gradient is required, and every sweep produces an accepted draw, so ar is always 1.
A prior, non-functional slice.js (100% commented out, 1D only, never wired into the base class) was deleted as dead code in PR #615; this is a fresh implementation, not a restoration.
Parameters
| Name | Type | Description |
|---|---|---|
| options | Object | Sampler options, as a single object. |
| logDensity | Function | The logarithm of the (unnormalized) target density. |
| config | Object | Sampler configuration (see MCMC base class for shared options). |
| initialState | Object | Initial state of the sampler (see MCMC base class). The interval width w (default 1.0) may be seeded via initialState.internal.w, either as a single number (broadcast to every dimension) or as a per-dimension array. |
Throws
Errorran.process.Process()
The stochastic process generator base class, all process generators extend this class. The methods listed here are available for all process generators.
ran.process.Process.covariogram(s, t)
Returns the analytical covariogram (covariance function) of the process evaluated at times s and t. Must be implemented by subclasses.
Parameters
| Name | Type | Description |
|---|---|---|
| s | number | First time point. |
| t | number | Second time point. |
Returns
numberCovariance between the process values at times s and t.
ran.process.Process.ensemble(m, n)
Generates m independent paths of n steps each by calling path(n) m times.
Parameters
| Name | Type | Description |
|---|---|---|
| m | number | Number of paths. |
| n | number | Number of steps per path. |
Returns
ArrayArray of m arrays, each of length n+1 (initial state followed by n states).
ran.process.Process.marginal(t)
Returns the marginal distribution of the process at time t as a fully-functional Distribution instance, unlocking the entire Distribution API (quantile, hazard, survival, likelihood, aic, bic, test) on the marginal without additional numerical machinery. Must be implemented by subclasses.
decisions/0040-process-marginal-distribution-instance.md — returns an existing Distribution instance built from already-derived mean()/variance()/pdf() parameters, instead of duplicating Distribution's numerical machinery on Process.
Parameters
| Name | Type | Description |
|---|---|---|
| t | number | Time. |
Throws
Errorran.process.Process.mean(t)
Returns the analytical mean of the process at time t. Must be implemented by subclasses.
Parameters
| Name | Type | Description |
|---|---|---|
| t | number | Time. |
Returns
numberExpected value at time t, or NaN for t < 0.
ran.process.Process.next()
Advances the process by one step, updates the current state, and returns the new state.
Returns
numberThe new state after the step.
ran.process.Process.path(n)
Generates a path of n steps starting from the initial state. Advances the PRNG stream by n steps (like sample()), so consecutive calls return independent realizations. The process state is restored to its pre-call value after generation.
Parameters
| Name | Type | Description |
|---|---|---|
| n | number | Number of steps. |
Returns
ArrayArray of n+1 states (initial state followed by n successive states).
ran.process.Process.pdf(x, t)
Returns the marginal probability density or mass at state x and time t. For continuous processes this is a probability density; for discrete processes (e.g. Poisson) this is a probability mass. Must be implemented by subclasses.
Parameters
| Name | Type | Description |
|---|---|---|
| x | number | State value. |
| t | number | Time. |
Returns
numberMarginal density or mass at (x, t), or NaN when t is out of domain.
ran.process.Process.reset()
Resets the process to its initial state.
ran.process.Process.seed(value)
Seeds the internal PRNG for reproducible paths.
Parameters
| Name | Type | Description |
|---|---|---|
| value | numberstring | Seed value passed to the underlying Xoshiro128p PRNG. |
Returns
thisReference to the current process.
ran.process.Process.state()
Returns the current state of the process.
Returns
numberCurrent state.
ran.process.Process.variance(t)
Returns the analytical variance of the process at time t. Must be implemented by subclasses.
Parameters
| Name | Type | Description |
|---|---|---|
| t | number | Time. |
Returns
numberVariance at time t, or NaN for t < 0.
ran.process.AR1(phi, sigma)
First-order autoregressive (AR(1)) process, the discrete-time analogue of the Ornstein-Uhlenbeck process.
The update rule per step is
where . For the process is stationary with marginal distribution . For the process is non-stationary and grows without bound; a warning is emitted but no error is thrown.
Parameters
| Name | Type | Description |
|---|---|---|
| phi | number | Autoregressive coefficient. |
| sigma | number | Innovation standard deviation (must be > 0). |
ran.process.BrownianBridge(sigma, T[, dt])
Brownian bridge process conditioned to return to 0 at time T, using an exact discrete-time sampler.
The underlying SDE is
Because the SDE is linear, the conditional distribution is Gaussian, derived from the covariance structure of the Wiener process. The sampler draws from that distribution directly
where . There is no step-size discretization error. The process pins to 0 at step .
Parameters
| Name | Type | Description |
|---|---|---|
| sigma | number | Volatility (must be > 0). |
| T | number | Terminal time (must be > 0). |
| dt | number | Time step (must be > 0; T/dt must be a positive integer). |
ran.process.BrownianMotion(mu, sigma[, dt])
Brownian motion (Wiener process) with drift, using an exact discrete-time sampler.
The underlying SDE is
Because the coefficients are constant (state-independent), the Euler–Maruyama step coincides with the exact transition: each increment is an independent draw from , giving the update rule
where . There is no step-size discretization error.
Parameters
| Name | Type | Description |
|---|---|---|
| mu | number | Drift coefficient. |
| sigma | number | Diffusion coefficient (must be > 0). |
| dt | number | Time step (must be > 0). |
ran.process.CompoundPoisson(jumpDist, lambda[, dt])
Compound Poisson process: cumulative random-magnitude jumps arriving at a Poisson rate.
At each time step of width the state advances by the sum of independent jumps drawn from the supplied distribution:
where and .
Parameters
| Name | Type | Description |
|---|---|---|
| jumpDist | Object | A ran.dist Distribution instance whose .sample() method supplies jump sizes. |
| lambda | number | Arrival rate (must be > 0). |
| dt | number | Time step (must be > 0). |
ran.process.CompoundPoissonProcess(jumpDist, lambda[, dt])
Deprecated alias for ran.process.CompoundPoisson. Process must not appear in Process subclass names (decisions/0041-process-subclass-naming-no-process-suffix.md).
Parameters
| Name | Type | Description |
|---|---|---|
| jumpDist | Object | A ran.dist Distribution instance whose .sample() method supplies jump sizes. |
| lambda | number | Arrival rate (must be > 0). |
| dt | number | Time step (must be > 0). |
References
- ran.process.CompoundPoisson
ran.process.CoxIngersollRoss(kappa, theta, sigma[, dt])
Cox-Ingersoll-Ross (CIR) mean-reverting process, using an Euler-Maruyama discretization with reflection to keep paths non-negative.
The underlying SDE is
The Euler-Maruyama step uses reflection to prevent the noise term from amplifying negative states:
where . When the Feller condition holds, the continuous-time process is strictly positive; below the Feller threshold, paths may occasionally become negative under Euler-Maruyama despite the reflection.
Parameters
| Name | Type | Description |
|---|---|---|
| kappa | number | Mean-reversion speed (must be > 0). |
| theta | number | Long-run mean (must be > 0). |
| sigma | number | Volatility (must be > 0). |
| dt | number | Time step (must be > 0). |
ran.process.GeometricBrownianMotion(mu, sigma[, dt])
Geometric Brownian Motion with drift, using an exact discrete-time sampler.
The underlying SDE is
By Itô's formula, follows Brownian motion with drift, yielding the closed-form solution . Each step is therefore an independent lognormal draw
where . There is no step-size discretization error.
Parameters
| Name | Type | Description |
|---|---|---|
| mu | number | Drift rate. |
| sigma | number | Volatility (must be > 0). |
| dt | number | Time step (must be > 0). |
ran.process.OrnsteinUhlenbeck(theta, mu, sigma[, dt])
Ornstein-Uhlenbeck mean-reverting process, using an exact discrete-time sampler.
The underlying SDE is
Because the SDE is linear, is Gaussian with closed-form mean and variance. The sampler draws from that distribution directly
where . There is no step-size discretization error regardless of .
Parameters
| Name | Type | Description |
|---|---|---|
| theta | number | Mean-reversion speed (must be > 0). |
| mu | number | Long-run mean. |
| sigma | number | Diffusion coefficient (must be > 0). |
| dt | number | Time step (must be > 0). |
ran.process.Poisson(lambda[, dt])
Poisson process: a counting process of independent arrivals at rate , using an exact discrete-time sampler.
By the independent-increments property, the number of arrivals in any interval of length is exactly , independent of all other intervals. The sampler draws that count directly
with no step-size discretization error.
Parameters
| Name | Type | Description |
|---|---|---|
| lambda | number | Event rate (must be > 0). |
| dt | number | Time step (must be > 0). |
ran.process.PoissonProcess(lambda[, dt])
Deprecated alias for ran.process.Poisson. Process must not appear in Process subclass names (decisions/0041-process-subclass-naming-no-process-suffix.md).
Parameters
| Name | Type | Description |
|---|---|---|
| lambda | number | Event rate (must be > 0). |
| dt | number | Time step (must be > 0). |
References
- ran.process.Poisson
ran.process.RandomWalk(p)
Discrete-time random walk on the integers: at each step the state moves by +1 with probability p and by −1 with probability 1 − p. For p = 0.5 the walk is symmetric (unbiased); for p ≠ 0.5 it has drift 2p − 1 per step.
The update rule is
where .
Parameters
| Name | Type | Description |
|---|---|---|
| p | number | Probability of a +1 step (must satisfy 0 < p < 1). |
ran.shape.kurtosis(values)
Calculates the sample excess kurtosis which is unbiased for the normal distribution.
Parameters
| Name | Type | Description |
|---|---|---|
| values | number[] | Array of values to calculate kurtosis for. |
Returns
numberThe sample excess kurtosis, or NaN for fewer than 3 elements or zero variance.
Examples
ran.shape.kurtosis([])
// => NaN
ran.shape.kurtosis([1, 2])
// => NaN
ran.shape.kurtosis([1, 1, 1])
// => NaN
ran.shape.kurtosis([1, 1, 3, 1, 1])
// => 5.000000000000003
ran.shape.kurtosis([1, 2, 2, 2, 1])
// => -3.3333333333333326ran.shape.max(values)
Returns the maximum of an array of values.
Parameters
| Name | Type | Description |
|---|---|---|
| values | number[] | Array of values to find the maximum for. |
Returns
numberThe maximum of the values, or NaN for an empty array.
Examples
ran.shape.max([])
// => NaN
ran.shape.max([3, 1, 4, 1, 5, 9])
// => 9ran.shape.min(values)
Returns the minimum of an array of values.
Parameters
| Name | Type | Description |
|---|---|---|
| values | number[] | Array of values to find the minimum for. |
Returns
numberThe minimum of the values, or NaN for an empty array.
Examples
ran.shape.min([])
// => NaN
ran.shape.min([3, 1, 4, 1, 5, 9])
// => 1ran.shape.moment(values, k[, c])
Calculates the k-th raw moment for a sample of values.
Parameters
| Name | Type | Description |
|---|---|---|
| values | number[] | Array of values to calculate moment for. |
| k | number | Order of the moment. |
| c | number | Value to shift the distribution by before calculating the moment. |
Returns
numberThe k-th moment, or NaN for an empty array.
Examples
ran.shape.moment([], 2)
// => NaN
ran.shape.moment([1, 2, 3], 0)
// => 1
ran.shape.moment([1, 2, 3], 2)
// => 4.666666666666667ran.shape.quantile(values, p)
Calculates the quantile at 0 < p < 1 using the R-7 algorithm.
Parameters
| Name | Type | Description |
|---|---|---|
| values | number[] | Array of values to calculate quantile for. |
| p | number | Value to calculate quantile at. |
Returns
numberThe quantile of the sample, or NaN for an empty array.
ran.shape.rank(values)
Calculates the fractional rank for an array of values.
Parameters
| Name | Type | Description |
|---|---|---|
| values | number[] | Array of values to calculate ranks for. |
Returns
number[]The ranks of the values, or an empty array for empty input.
Examples
ran.shape.rank([])
// => []
ran.shape.rank([1, 2, 2, 3])
// => [1, 2.5, 2.5, 4]ran.shape.skewness(values)
Calculates the Fisher-Pearson standardized sample skewness for a sample of values.
Parameters
| Name | Type | Description |
|---|---|---|
| values | number[] | Array of values to calculate skewness for. |
Returns
numberThe sample skewness, or NaN for fewer than 3 elements or zero variance.
Examples
ran.shape.skewness([])
// => NaN
ran.shape.skewness([1, 2])
// => NaN
ran.shape.skewness([1, 1, 1])
// => NaN
ran.shape.skewness([1, 1, 1, 2])
// => 2
ran.shape.skewness([1, 2, 2, 2])
// => -2ran.shape.yule(values)
Calculates Yule's coefficient which is a measure of skewness based on quantiles.
Parameters
| Name | Type | Description |
|---|---|---|
| values | number[] | Array of values to calculate Yule's coefficient for. |
Returns
numberYule's coefficient, or NaN for an empty array or when the lower and upper quartiles are equal.
Examples
ran.shape.yule([])
// => NaN
ran.shape.yule([1, 1, 1])
// => NaN
ran.shape.yule([1, 1, 1, 2])
// => 1
ran.shape.yule([1, 2, 2, 2])
// => -1ran.test.bartlett(dataSets[, alpha])
Calculates the Bartlett statistics for multiple data sets.
Parameters
| Name | Type | Description |
|---|---|---|
| dataSets | Array[] | Array containing the data sets. |
| alpha | number | Confidence level. |
Returns
Object containing the test statistics (chi2) and whether the data sets passed the null hypothesis that their variances are the same.
Throws
ErrorErrorExamples
let normal1 = new ran.dist.Normal(1, 2)
let normal2 = new ran.dist.Normal(1, 3)
let normal3 = new ran.dist.Normal(1, 5)
ran.test.bartlett([normal1.sample(100), normal1.sample(100), normal1.sample(100)], 0.1)
// => { stat: 0.09827551592930094, passed: true }
ran.test.bartlett([normal1.sample(100), normal2.sample(100), normal3.sample(100)], 0.1)
// => { stat: 104.31185521417476, passed: false }ran.test.brownForsythe(dataSets[, alpha])
Calculates the Brown-Forsythe test statistic for multiple data sets.
Parameters
| Name | Type | Description |
|---|---|---|
| dataSets | Array[] | Array containing the data sets. |
| alpha | number | Confidence level. |
Returns
Object containing the test statistics (W) and whether the data sets passed the null hypothesis that their variances are the same.
Throws
ErrorErrorExamples
let normal1 = new ran.dist.Normal(1, 2)
let normal2 = new ran.dist.Normal(1, 3)
let normal3 = new ran.dist.Normal(1, 5)
ran.test.brownForsythe([normal1.sample(100), normal1.sample(100), normal1.sample(100)], 0.1)
// => { stat: 1.0664885130451343, passed: true }
ran.test.brownForsythe([normal1.sample(100), normal2.sample(100), normal3.sample(100)], 0.1)
// => { stat: 27.495614343570345, passed: false }ran.test.cramerVonMises(values, cdf[, alpha])
Calculates the Cramér-von Mises statistic for an array of values against a cumulative distribution function, testing the null hypothesis that the sample is drawn from the distribution the CDF represents. The asymptotic p-value uses the Csörgő & Faraway (1996) convergent series for the limiting distribution's CDF.
Parameters
| Name | Type | Description |
|---|---|---|
| values | number[] | Array of values to perform the test for. |
| cdf | Function | Cumulative distribution function to test against. |
| alpha | number | Confidence level. |
Returns
Object containing the test statistic (T = n omega^2), the asymptotic goodness-of-fit p-value, and whether the sample passed the null hypothesis that it is drawn from the tested distribution.
Throws
ErrorExamples
let normal = new ran.dist.Normal(0, 1)
ran.test.cramerVonMises(normal.sample(100), x => normal.cdf(x))
// => { stat: 0.043, pValue: 0.802, passed: true }ran.test.hsic(dataSets[, alpha])
Calculates the Hilbert-Schmidt independence criterion (HSIC) for paired arrays of values. HSIC tests if two data sets are statistically independent. Source: A. Gretton et al. A Kernel Statistical Test of Independence in Advances in Neural Information Processing Systems (2008).
Parameters
| Name | Type | Description |
|---|---|---|
| dataSets | Array[] | Array containing the two data sets. |
| alpha | number | Confidence level. |
Returns
Object containing the test statistics and whether the data sets passed the null hypothesis that they are statistically independent.
Throws
ErrorErrorErrorExamples
let sample1 = Array.from({length: 50}, (d, i) => i)
let sample2 = sample1.map(d => d + Math.random() - 0.5)
ran.test.hsic([sample1, sample2])
// => { stat: 6.197628059960943, passed: false }
sample1 = ran.core.float(0, 10, 50)
sample2 = ran.core.float(0, 10, 50)
ran.test.hsic([sample1, sample2])
// => { stat: 0.3876607680368274, passed: true }ran.test.levene(dataSets, alpha)
Calculates the Levene's test statistic for multiple data sets.
Parameters
| Name | Type | Description |
|---|---|---|
| dataSets | Array[] | Array containing the data sets. |
| alpha | number | Confidence level. |
Returns
Object containing the test statistics (W) and whether the data sets passed the null hypothesis that their variances are the same.
Throws
ErrorErrorExamples
let normal1 = new ran.dist.Normal(1, 2)
let normal2 = new ran.dist.Normal(1, 3)
let normal3 = new ran.dist.Normal(1, 5)
ran.test.levene([normal1.sample(100), normal1.sample(100), normal1.sample(100)], 0.1)
// => { stat: 0.019917137672045088, passed: true }
ran.test.levene([normal1.sample(100), normal2.sample(100), normal3.sample(100)], 0.1)
// => { stat: 29.06345994086687, passed: false }ran.test.mannWhitney(dataSets[, alpha])
Calculates the Mann-Whitney statistics for two data sets.
Parameters
| Name | Type | Description |
|---|---|---|
| dataSets | Array[] | Array containing the two data sets. |
| alpha | number | Confidence level. |
Returns
Object containing the (non-standardized) test statistics (U) and whether the data sets passed the null hypothesis that the samples come from the same distribution.
Throws
ErrorExamples
let pareto = new ran.dist.Pareto(1, 2)
let uniform = new ran.dist.Uniform(1, 10)
ran.test.mannWhitney([pareto.sample(100), pareto.sample(100)], 0.1)
// => { stat: 4941, passed: true }
ran.test.mannWhitney([pareto.sample(100), uniform.sample(100)], 0.1)
// => { stat: 132, passed: false }ran.test.welch(x, y[, alpha])
Calculates Welch's two-sample t-test for two data sets.
Parameters
| Name | Type | Description |
|---|---|---|
| x | number[] | First sample. |
| y | number[] | Second sample. |
| alpha | number | Confidence level. |
Returns
Object containing the test statistic (t) and whether the data sets passed the null hypothesis that their means are equal.
Throws
ErrorExamples
let normal1 = new ran.dist.Normal(0, 1)
let normal2 = new ran.dist.Normal(5, 1)
ran.test.welch(normal1.sample(100), normal1.sample(100))
// => { stat: -0.43, passed: true }
ran.test.welch(normal1.sample(100), normal2.sample(100))
// => { stat: -49.3, passed: false }