> ## Documentation Index
> Fetch the complete documentation index at: https://numpyts.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Distributions

> Continuous, discrete, and multivariate probability distributions for random sampling.

All functions on this page are accessed via the `np.random` namespace and use the global MT19937 generator. The same distributions are also available on `Generator` instances (see [Generator API](./generator)).

<Note>
  As of v1.2.0, all distribution functions now produce bit-for-bit identical output to NumPy given the same seed. This applies to every distribution on this page -- exponential, gamma, beta, chi-square, poisson, binomial, and all others -- thanks to the Zig/WASM rewrite of the random module.
</Note>

## Continuous Distributions

### uniform

Draw samples from a uniform distribution over `[low, high)`.

```typescript theme={null}
function uniform(low?: number, high?: number, size?: number | number[]): NDArray | number
```

| Name | Type | Default | Description |
| - | - | - | - |
| `low` | `number` | `0` | Lower boundary (inclusive). |
| `high` | `number` | `1` | Upper boundary (exclusive). |
| `size` | `number \| number[]` | `undefined` | Output shape. |

**Returns:** `NDArray | number` -- Samples from the uniform distribution.

```typescript theme={null}
import * as np from 'numpy-ts';

const a = np.random.uniform(-1, 1, [2, 3]);
```

***

### normal

Draw samples from a normal (Gaussian) distribution.

```typescript theme={null}
function normal(loc?: number, scale?: number, size?: number | number[]): NDArray | number
```

| Name | Type | Default | Description |
| - | - | - | - |
| `loc` | `number` | `0` | Mean of the distribution. |
| `scale` | `number` | `1` | Standard deviation (spread). |
| `size` | `number \| number[]` | `undefined` | Output shape. |

**Returns:** `NDArray | number` -- Samples from the normal distribution.

```typescript theme={null}
import * as np from 'numpy-ts';

const samples = np.random.normal(0, 1, [1000]);
```

***

### standard\_normal

Draw samples from the standard normal distribution (mean=0, std=1). Equivalent to `normal(0, 1, size)`.

```typescript theme={null}
function standard_normal(size?: number | number[]): NDArray | number
```

| Name | Type | Default | Description |
| - | - | - | - |
| `size` | `number \| number[]` | `undefined` | Output shape. |

**Returns:** `NDArray | number` -- Standard normal samples.

***

### exponential

Draw samples from an exponential distribution.

```typescript theme={null}
function exponential(scale?: number, size?: number | number[]): NDArray | number
```

| Name | Type | Default | Description |
| - | - | - | - |
| `scale` | `number` | `1` | Scale parameter (beta = 1/lambda). |
| `size` | `number \| number[]` | `undefined` | Output shape. |

**Returns:** `NDArray | number` -- Exponential samples.

```typescript theme={null}
import * as np from 'numpy-ts';

const a = np.random.exponential(2.0, [1000]);
```

***

### standard\_exponential

Draw samples from the standard exponential distribution (scale=1). Equivalent to `exponential(1, size)`.

```typescript theme={null}
function standard_exponential(size?: number | number[]): NDArray | number
```

| Name | Type | Default | Description |
| - | - | - | - |
| `size` | `number \| number[]` | `undefined` | Output shape. |

**Returns:** `NDArray | number` -- Standard exponential samples.

***

### gamma

Draw samples from a Gamma distribution. Uses Marsaglia and Tsang's method.

```typescript theme={null}
function gamma(shape: number, scale?: number, size?: number | number[]): NDArray | number
```

| Name | Type | Default | Description |
| - | - | - | - |
| `shape` | `number` | -- | Shape parameter (k, alpha). Must be > 0. |
| `scale` | `number` | `1` | Scale parameter (theta). Must be > 0. |
| `size` | `number \| number[]` | `undefined` | Output shape. |

**Returns:** `NDArray | number` -- Gamma-distributed samples.

```typescript theme={null}
import * as np from 'numpy-ts';

const a = np.random.gamma(2, 2, [1000]);
```

***

### standard\_gamma

Draw samples from the standard Gamma distribution (scale=1).

```typescript theme={null}
function standard_gamma(shape: number, size?: number | number[]): NDArray | number
```

| Name | Type | Default | Description |
| - | - | - | - |
| `shape` | `number` | -- | Shape parameter (alpha). Must be > 0. |
| `size` | `number \| number[]` | `undefined` | Output shape. |

**Returns:** `NDArray | number` -- Standard gamma samples.

***

### beta

Draw samples from a Beta distribution.

```typescript theme={null}
function beta(a: number, b: number, size?: number | number[]): NDArray | number
```

| Name | Type | Default | Description |
| - | - | - | - |
| `a` | `number` | -- | Alpha parameter. Must be > 0. |
| `b` | `number` | -- | Beta parameter. Must be > 0. |
| `size` | `number \| number[]` | `undefined` | Output shape. |

**Returns:** `NDArray | number` -- Beta-distributed samples in `[0, 1]`.

```typescript theme={null}
import * as np from 'numpy-ts';

const a = np.random.beta(2, 5, [1000]);
```

***

### chisquare

Draw samples from a chi-square distribution. Internally uses `gamma(df/2, 2)`.

```typescript theme={null}
function chisquare(df: number, size?: number | number[]): NDArray | number
```

| Name | Type | Default | Description |
| - | - | - | - |
| `df` | `number` | -- | Degrees of freedom. Must be > 0. |
| `size` | `number \| number[]` | `undefined` | Output shape. |

**Returns:** `NDArray | number` -- Chi-square samples.

***

### noncentral\_chisquare

Draw samples from a noncentral chi-square distribution.

```typescript theme={null}
function noncentral_chisquare(df: number, nonc: number, size?: number | number[]): NDArray | number
```

| Name | Type | Default | Description |
| - | - | - | - |
| `df` | `number` | -- | Degrees of freedom. Must be > 0. |
| `nonc` | `number` | -- | Non-centrality parameter. Must be >= 0. |
| `size` | `number \| number[]` | `undefined` | Output shape. |

**Returns:** `NDArray | number` -- Noncentral chi-square samples.

***

### f

Draw samples from an F distribution.

```typescript theme={null}
function f(dfnum: number, dfden: number, size?: number | number[]): NDArray | number
```

| Name | Type | Default | Description |
| - | - | - | - |
| `dfnum` | `number` | -- | Degrees of freedom in numerator. Must be > 0. |
| `dfden` | `number` | -- | Degrees of freedom in denominator. Must be > 0. |
| `size` | `number \| number[]` | `undefined` | Output shape. |

**Returns:** `NDArray | number` -- F-distributed samples.

***

### noncentral\_f

Draw samples from a noncentral F distribution.

```typescript theme={null}
function noncentral_f(
  dfnum: number,
  dfden: number,
  nonc: number,
  size?: number | number[]
): NDArray | number
```

| Name | Type | Default | Description |
| - | - | - | - |
| `dfnum` | `number` | -- | Degrees of freedom in numerator. Must be > 0. |
| `dfden` | `number` | -- | Degrees of freedom in denominator. Must be > 0. |
| `nonc` | `number` | -- | Non-centrality parameter. Must be >= 0. |
| `size` | `number \| number[]` | `undefined` | Output shape. |

**Returns:** `NDArray | number` -- Noncentral F samples.

***

### standard\_cauchy

Draw samples from a standard Cauchy distribution (location=0, scale=1).

```typescript theme={null}
function standard_cauchy(size?: number | number[]): NDArray | number
```

| Name | Type | Default | Description |
| - | - | - | - |
| `size` | `number \| number[]` | `undefined` | Output shape. |

**Returns:** `NDArray | number` -- Cauchy samples.

***

### standard\_t

Draw samples from a standard Student's t distribution.

```typescript theme={null}
function standard_t(df: number, size?: number | number[]): NDArray | number
```

| Name | Type | Default | Description |
| - | - | - | - |
| `df` | `number` | -- | Degrees of freedom. Must be > 0. |
| `size` | `number \| number[]` | `undefined` | Output shape. |

**Returns:** `NDArray | number` -- Student's t samples.

***

### laplace

Draw samples from a Laplace (double exponential) distribution.

```typescript theme={null}
function laplace(loc?: number, scale?: number, size?: number | number[]): NDArray | number
```

| Name | Type | Default | Description |
| - | - | - | - |
| `loc` | `number` | `0` | Location parameter (mean). |
| `scale` | `number` | `1` | Scale parameter. Must be > 0. |
| `size` | `number \| number[]` | `undefined` | Output shape. |

**Returns:** `NDArray | number` -- Laplace samples.

***

### logistic

Draw samples from a logistic distribution.

```typescript theme={null}
function logistic(loc?: number, scale?: number, size?: number | number[]): NDArray | number
```

| Name | Type | Default | Description |
| - | - | - | - |
| `loc` | `number` | `0` | Location parameter. |
| `scale` | `number` | `1` | Scale parameter. Must be > 0. |
| `size` | `number \| number[]` | `undefined` | Output shape. |

**Returns:** `NDArray | number` -- Logistic samples.

***

### lognormal

Draw samples from a log-normal distribution. If `X ~ Normal(mean, sigma)`, then `exp(X) ~ LogNormal`.

```typescript theme={null}
function lognormal(mean?: number, sigma?: number, size?: number | number[]): NDArray | number
```

| Name | Type | Default | Description |
| - | - | - | - |
| `mean` | `number` | `0` | Mean of the underlying normal distribution. |
| `sigma` | `number` | `1` | Standard deviation of the underlying normal. Must be > 0. |
| `size` | `number \| number[]` | `undefined` | Output shape. |

**Returns:** `NDArray | number` -- Log-normal samples.

***

### gumbel

Draw samples from a Gumbel distribution.

```typescript theme={null}
function gumbel(loc?: number, scale?: number, size?: number | number[]): NDArray | number
```

| Name | Type | Default | Description |
| - | - | - | - |
| `loc` | `number` | `0` | Location parameter. |
| `scale` | `number` | `1` | Scale parameter. Must be > 0. |
| `size` | `number \| number[]` | `undefined` | Output shape. |

**Returns:** `NDArray | number` -- Gumbel samples.

***

### pareto

Draw samples from a Pareto II (Lomax) distribution.

```typescript theme={null}
function pareto(a: number, size?: number | number[]): NDArray | number
```

| Name | Type | Default | Description |
| - | - | - | - |
| `a` | `number` | -- | Shape parameter. Must be > 0. |
| `size` | `number \| number[]` | `undefined` | Output shape. |

**Returns:** `NDArray | number` -- Pareto samples.

***

### power

Draw samples from a power distribution with positive exponent `a - 1` over `[0, 1]`.

```typescript theme={null}
function power(a: number, size?: number | number[]): NDArray | number
```

| Name | Type | Default | Description |
| - | - | - | - |
| `a` | `number` | -- | Shape parameter. Must be > 0. |
| `size` | `number \| number[]` | `undefined` | Output shape. |

**Returns:** `NDArray | number` -- Power-distributed samples in `[0, 1]`.

***

### rayleigh

Draw samples from a Rayleigh distribution.

```typescript theme={null}
function rayleigh(scale?: number, size?: number | number[]): NDArray | number
```

| Name | Type | Default | Description |
| - | - | - | - |
| `scale` | `number` | `1` | Scale parameter. Must be > 0. |
| `size` | `number \| number[]` | `undefined` | Output shape. |

**Returns:** `NDArray | number` -- Rayleigh samples.

***

### triangular

Draw samples from a triangular distribution over `[left, right]` with the given mode.

```typescript theme={null}
function triangular(
  left: number,
  mode: number,
  right: number,
  size?: number | number[]
): NDArray | number
```

| Name | Type | Default | Description |
| - | - | - | - |
| `left` | `number` | -- | Lower limit. |
| `mode` | `number` | -- | Peak of the distribution. Must satisfy `left <= mode <= right`. |
| `right` | `number` | -- | Upper limit. Must satisfy `left < right`. |
| `size` | `number \| number[]` | `undefined` | Output shape. |

**Returns:** `NDArray | number` -- Triangular samples.

```typescript theme={null}
import * as np from 'numpy-ts';

const a = np.random.triangular(0, 5, 10, [1000]);
```

***

### wald

Draw samples from a Wald (inverse Gaussian) distribution.

```typescript theme={null}
function wald(mean: number, scale: number, size?: number | number[]): NDArray | number
```

| Name | Type | Default | Description |
| - | - | - | - |
| `mean` | `number` | -- | Mean of the distribution. Must be > 0. |
| `scale` | `number` | -- | Scale parameter. Must be > 0. |
| `size` | `number \| number[]` | `undefined` | Output shape. |

**Returns:** `NDArray | number` -- Wald samples.

***

### weibull

Draw samples from a Weibull distribution.

```typescript theme={null}
function weibull(a: number, size?: number | number[]): NDArray | number
```

| Name | Type | Default | Description |
| - | - | - | - |
| `a` | `number` | -- | Shape parameter. Must be > 0. |
| `size` | `number \| number[]` | `undefined` | Output shape. |

**Returns:** `NDArray | number` -- Weibull samples.

***

### vonmises

Draw samples from a von Mises distribution (circular normal) on the interval `[-pi, pi]`.

```typescript theme={null}
function vonmises(mu: number, kappa: number, size?: number | number[]): NDArray | number
```

| Name | Type | Default | Description |
| - | - | - | - |
| `mu` | `number` | -- | Mode (center) of the distribution, in radians. |
| `kappa` | `number` | -- | Concentration parameter. Must be >= 0. When `kappa = 0`, the distribution is uniform on the circle. |
| `size` | `number \| number[]` | `undefined` | Output shape. |

**Returns:** `NDArray | number` -- Von Mises samples in `[-pi, pi]`.

***

## Discrete Distributions

### poisson

Draw samples from a Poisson distribution.

```typescript theme={null}
function poisson(lam?: number, size?: number | number[]): NDArray | number
```

| Name | Type | Default | Description |
| - | - | - | - |
| `lam` | `number` | `1` | Expected number of events (lambda). |
| `size` | `number \| number[]` | `undefined` | Output shape. |

**Returns:** `NDArray | number` -- Poisson samples (non-negative integers).

```typescript theme={null}
import * as np from 'numpy-ts';

const a = np.random.poisson(5, [1000]);
```

***

### binomial

Draw samples from a binomial distribution.

```typescript theme={null}
function binomial(n: number, p: number, size?: number | number[]): NDArray | number
```

| Name | Type | Default | Description |
| - | - | - | - |
| `n` | `number` | -- | Number of trials. |
| `p` | `number` | -- | Probability of success on each trial. |
| `size` | `number \| number[]` | `undefined` | Output shape. |

**Returns:** `NDArray | number` -- Binomial samples.

```typescript theme={null}
import * as np from 'numpy-ts';

// 10 coin flips with p=0.5, repeated 1000 times
const a = np.random.binomial(10, 0.5, [1000]);
```

***

### geometric

Draw samples from a geometric distribution. Returns the number of trials needed to get the first success.

```typescript theme={null}
function geometric(p: number, size?: number | number[]): NDArray | number
```

| Name | Type | Default | Description |
| - | - | - | - |
| `p` | `number` | -- | Probability of success. Must be in `(0, 1]`. |
| `size` | `number \| number[]` | `undefined` | Output shape. |

**Returns:** `NDArray | number` -- Geometric samples (positive integers).

***

### hypergeometric

Draw samples from a hypergeometric distribution. Models drawing `nsample` items without replacement from a population containing `ngood` successes and `nbad` failures.

```typescript theme={null}
function hypergeometric(
  ngood: number,
  nbad: number,
  nsample: number,
  size?: number | number[]
): NDArray | number
```

| Name | Type | Default | Description |
| - | - | - | - |
| `ngood` | `number` | -- | Number of good (success) items in the population. |
| `nbad` | `number` | -- | Number of bad (failure) items in the population. |
| `nsample` | `number` | -- | Number of items sampled. Must be `<= ngood + nbad`. |
| `size` | `number \| number[]` | `undefined` | Output shape. |

**Returns:** `NDArray | number` -- Number of good items in each sample.

***

### logseries

Draw samples from a logarithmic series distribution.

```typescript theme={null}
function logseries(p: number, size?: number | number[]): NDArray | number
```

| Name | Type | Default | Description |
| - | - | - | - |
| `p` | `number` | -- | Shape parameter. Must be in `(0, 1)`. |
| `size` | `number \| number[]` | `undefined` | Output shape. |

**Returns:** `NDArray | number` -- Log-series samples (positive integers).

***

### negative\_binomial

Draw samples from a negative binomial distribution. Models the number of failures before `n` successes.

```typescript theme={null}
function negative_binomial(n: number, p: number, size?: number | number[]): NDArray | number
```

| Name | Type | Default | Description |
| - | - | - | - |
| `n` | `number` | -- | Number of successes. Must be > 0. |
| `p` | `number` | -- | Probability of success. Must be in `(0, 1]`. |
| `size` | `number \| number[]` | `undefined` | Output shape. |

**Returns:** `NDArray | number` -- Negative binomial samples (non-negative integers).

***

### zipf

Draw samples from a Zipf distribution.

```typescript theme={null}
function zipf(a: number, size?: number | number[]): NDArray | number
```

| Name | Type | Default | Description |
| - | - | - | - |
| `a` | `number` | -- | Distribution parameter. Must be > 1. |
| `size` | `number \| number[]` | `undefined` | Output shape. |

**Returns:** `NDArray | number` -- Zipf samples (positive integers).

***

## Multivariate Distributions

### multinomial

Draw samples from a multinomial distribution.

```typescript theme={null}
function multinomial(n: number, pvals: ArrayLike, size?: number | number[]): NDArray
```

| Name | Type | Default | Description |
| - | - | - | - |
| `n` | `number` | -- | Number of experiments (total count per sample). |
| `pvals` | `ArrayLike` | -- | Probabilities of each category. Must sum to 1 (normalized automatically). |
| `size` | `number \| number[]` | `undefined` | Number of multinomial experiments to run. |

**Returns:** `NDArray` -- Array of shape `[...size, len(pvals)]` with integer counts.

```typescript theme={null}
import * as np from 'numpy-ts';

// 20 rolls of a fair 6-sided die
const a = np.random.multinomial(20, [1/6, 1/6, 1/6, 1/6, 1/6, 1/6]);
// array([3, 4, 2, 5, 3, 3])  (example, sums to 20)
```

***

### multivariate\_normal

Draw samples from a multivariate normal distribution.

```typescript theme={null}
function multivariate_normal(
  mean: ArrayLike,
  cov: ArrayLike | number[][],
  size?: number | number[],
  check_valid?: 'warn' | 'raise' | 'ignore',
  tol?: number
): NDArray
```

| Name | Type | Default | Description |
| - | - | - | - |
| `mean` | `ArrayLike` | -- | Mean of the distribution (1-D array of length N). |
| `cov` | `ArrayLike \| number[][]` | -- | Covariance matrix (N x N, symmetric positive semi-definite). |
| `size` | `number \| number[]` | `undefined` | Number of samples to draw. |
| `check_valid` | `'warn' \| 'raise' \| 'ignore'` | `undefined` | Behavior when covariance is not PSD. |
| `tol` | `number` | `undefined` | Tolerance for covariance validity checks. |

**Returns:** `NDArray` -- Array of shape `[...size, N]`.

```typescript theme={null}
import * as np from 'numpy-ts';

const mean = [0, 0];
const cov = [[1, 0.5], [0.5, 1]];
const samples = np.random.multivariate_normal(mean, cov, 1000);
// shape [1000, 2]
```

***

### dirichlet

Draw samples from a Dirichlet distribution. Each sample is a probability vector that sums to 1.

```typescript theme={null}
function dirichlet(alpha: ArrayLike, size?: number | number[]): NDArray
```

| Name | Type | Default | Description |
| - | - | - | - |
| `alpha` | `ArrayLike` | -- | Concentration parameters. Must all be > 0 and have at least 2 elements. |
| `size` | `number \| number[]` | `undefined` | Number of samples to draw. |

**Returns:** `NDArray` -- Array of shape `[...size, len(alpha)]`, where each row sums to 1.

```typescript theme={null}
import * as np from 'numpy-ts';

const samples = np.random.dirichlet([1, 1, 1], 5);
// shape [5, 3], each row sums to 1.0
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.