API reference
Statistics
Order statistics, averages, correlations and histograms (NumPy numpy statistics routines). Results are NDArrays (0-d when everything is reduced); tuple results are JS arrays.
| Name | Summary |
|---|---|
np.quantile | The q-th quantile (q in [0, 1]; percentile takes [0, 100]). |
np.median | Median along the given axes: the mean of the middle values, so integer input gives float64 (float16/float32 are kept). |
np.cumulativeSum | Array-API cumulative_sum / cumulative_prod: like cumsum, but axis is required when x has more than one dimension, and includeInitial: true prepends the identity (0 or 1), so the axis grows by one. |
np.diff | The n-th discrete difference a[i+1] - a[i] along axis (bool input uses !=). |
np.ptp | Range of values (max - min) along the axes, in the input dtype (integer results can wrap, as in NumPy). |
np.nansum | Reductions that ignore NaN: NaN counts as 0 for nansum, 1 for nanprod, and is left out of the count for nanmean/nanvar/nanstd. |
np.nanargmin | Index of the minimum / maximum ignoring NaNs. |
np.average | Weighted mean. |
np.cov | Covariance matrix (rows are variables unless rowvar: false), normalised by N - 1 (N with bias, N - ddof with ddof), with optional frequency and observation weights. |
np.gradient | Central differences in the interior and one-sided (order 1 or 2) differences at the edges. |
np.trapezoid | Composite trapezoidal integral of y along axis (default -1), using sample points x or uniform spacing dx (default 1). |
np.correlate | 1-D cross-correlation: c[k] = Σ_j a[j+k]·conj(v[j]). |
np.convolve | Discrete linear convolution: c[k] = Σ_j a[j]·v[k-j]. |
np.histogram | histogram counts sample values into bins (integer count, estimator name, or explicit edges) and returns { hist, edges } where edges.length === hist.length + 1. |
np.histogram2d | 2-D histogram of two 1-D samples. |
np.histogramdd | Multi-dimensional histogram. |
np.bincount | Count occurrences of each non-negative integer in x. |
np.digitize | Return indices such that bins[i-1] <= x < bins[i] (right=false, default) or bins[i-1] < x <= bins[i] (right=true). |
np.interp | 1-D piecewise-linear interpolation. |
np.quantile
#np.quantile(a, q, { axis?, keepdims?, method?, weights? }) · np.percentile(a, q, ...) · np.nanquantile · np.nanpercentile
The q-th quantile (q in [0, 1]; percentile takes [0, 100]). All 13 NumPy methods are supported ("linear" default, "lower", "higher", "nearest", "midpoint", "inverted_cdf", "averaged_inverted_cdf", "closest_observation", "interpolated_inverted_cdf", "hazen", "weibull", "median_unbiased", "normal_unbiased"). The result shape is q.shape followed by the reduced shape. Discrete methods keep the input dtype; the others give float64 for integer input, and a JS-number q keeps float32 input as float32. A slice containing NaN gives NaN; the nan* variants ignore NaNs. weights (non-negative) need method: "inverted_cdf" and either a's shape or the shape of the reduced axes.
Parameters
aArrayLike- An
NDArray, nested JS array or scalar. qArrayLike- Quantile(s), scalar or up to 2-d.
[options.axis]number | number[] | null- Axis or axes to reduce; default all (flattened).
[options.keepdims]boolean- Keep reduced axes with length 1.
[options.method]QuantileMethod- Estimation method (default
"linear"). [options.weights]ArrayLike- Sample weights (
inverted_cdfonly).
Returns
NDArray
Example
const a = np.array([[10, 7, 4], [3, 2, 1]]);
np.quantile(a, 0.5); // => 3.5
np.percentile(a, [25, 75], { axis: 1 }); // => [[5.5, 1.5], [8.5, 2.5]]
np.quantile(a, 0.5, { method: "lower" }); // => 3
np.nanquantile([1, NaN, 3], 0.5); // => 2
np.quantile([1, 2, 3], 0.5, { weights: [1, 1, 4], method: "inverted_cdf" }); // => 3TypeScript declaration
np.quantile(a: ArrayLike, q: ArrayLike, opts?: QuantileOptions | undefined): NDArray
np.percentile(a: ArrayLike, q: ArrayLike, opts?: QuantileOptions | undefined): NDArray
np.nanquantile(a: ArrayLike, q: ArrayLike, opts?: QuantileOptions | undefined): NDArray
np.nanpercentile(a: ArrayLike, q: ArrayLike, opts?: QuantileOptions | undefined): NDArraynp.median
#np.median(a, { axis?, keepdims? }) · np.nanmedian(a, ...)
Median along the given axes: the mean of the middle values, so integer input gives float64 (float16/float32 are kept). Any NaN in a slice gives NaN; nanmedian ignores NaNs (an all-NaN slice gives NaN). An empty input gives NaN.
Parameters
aArrayLike- An
NDArray, nested JS array or scalar. [options.axis]number | number[] | null- Axis or axes to reduce; default all (flattened).
[options.keepdims]boolean- Keep reduced axes with length 1.
Returns
NDArray
Example
np.median([[10, 7, 4], [3, 2, 1]], { axis: 0 }); // => [6.5, 4.5, 2.5]
Number.isNaN(np.median([1, NaN, 3]).item()); // => true
np.nanmedian([1, NaN, 3]); // => 2TypeScript declaration
np.median(a: ArrayLike, opts?: MedianOptions | undefined): NDArray
np.nanmedian(a: ArrayLike, opts?: MedianOptions | undefined): NDArraynp.cumulativeSum
#np.cumulativeSum(x, { axis?, dtype?, includeInitial?, out? }) · np.cumulativeProd(x, ...)
Array-API cumulative_sum / cumulative_prod: like cumsum, but axis is required when x has more than one dimension, and includeInitial: true prepends the identity (0 or 1), so the axis grows by one.
Parameters
xArrayLike- An
NDArray, nested JS array or scalar. [options.axis]number- Axis (required for ndim > 1).
[options.includeInitial]boolean- Prepend the identity.
Returns
NDArray
Example
np.cumulativeSum([1, 2, 3], { includeInitial: true }); // => [0, 1, 3, 6]
np.cumulativeProd([[1, 2], [3, 4]], { axis: 1 }); // => [[1, 2], [3, 12]]TypeScript declaration
np.cumulativeSum(x: ArrayLike, opts?: CumulativeOptions | undefined): NDArray
np.cumulativeProd(x: ArrayLike, opts?: CumulativeOptions | undefined): NDArraynp.diff
#np.diff(a, n = 1, axis = -1) · np.diff(a, { n?, axis?, prepend?, append? })
The n-th discrete difference a[i+1] - a[i] along axis (bool input uses !=). prepend/append are joined to a along axis first; scalars are broadcast to length 1 along it. Integer differences wrap in the input dtype.
Parameters
aArrayLike- An
NDArray, nested JS array or scalar. [n]number- Number of differences (default 1).
[axis]number- Axis (default -1).
[options.prepend]ArrayLike- Values before
a. [options.append]ArrayLike- Values after
a.
Returns
NDArray
Example
np.diff([1, 4, 9, 16]); // => [3, 5, 7]
np.diff([1, 4, 9, 16], 2); // => [2, 2]
np.diff([1, 2], { prepend: 0 }); // => [1, 1]
np.diff([[1, 2], [4, 8]], { axis: 0 }); // => [[3, 6]]TypeScript declaration
np.diff(a: ArrayLike, n?: number | DiffOptions | undefined, axis?: number | undefined): NDArraynp.ptp
#np.ptp(a, { axis?, keepdims? }) · a.ptp(...)
Range of values (max - min) along the axes, in the input dtype (integer results can wrap, as in NumPy). Bool input raises DTypeError; empty input raises ValueError.
Parameters
aArrayLike- An
NDArray, nested JS array or scalar. [options.axis]number | number[] | null- Axis or axes to reduce; default all (flattened).
[options.keepdims]boolean- Keep reduced axes with length 1.
Returns
NDArray
Example
np.ptp([[1, 5], [2, 9]]); // => 8
np.ptp([[1, 5], [2, 9]], { axis: 0 }); // => [1, 4]np.nansum
#np.nansum · np.nanprod · np.nanmean · np.nanvar · np.nanstd · np.nanmin · np.nanmax (a, { axis?, keepdims?, dtype?, initial?, ddof? })
Reductions that ignore NaN: NaN counts as 0 for nansum, 1 for nanprod, and is left out of the count for nanmean/nanvar/nanstd. All-NaN slices give 0 (nansum), 1 (nanprod) or NaN (the others; NumPy also warns). Integer input behaves like the plain reduction. Options are those of sum/mean/var/min.
Parameters
aArrayLike- An
NDArray, nested JS array or scalar. [options.axis]number | number[] | null- Axis or axes to reduce; default all (flattened).
[options.keepdims]boolean- Keep reduced axes with length 1.
[options.ddof]numbernanvar/nanstd: divisor is count - ddof.
Returns
NDArray
Example
const x = np.array([[1, NaN, 3], [4, 5, NaN]]);
np.nansum(x); // => 13
np.nanmean(x, { axis: 1 }); // => [2, 4.5]
np.nanmax(x, { axis: 0 }); // => [4, 5, 3]
np.nanvar([1, NaN, 2], { ddof: 1 }); // => 0.5TypeScript declaration
np.nansum(a: ArrayLike, opts?: ReduceOptions | undefined): NDArray
np.nanprod(a: ArrayLike, opts?: ReduceOptions | undefined): NDArray
np.nanmean(a: ArrayLike, opts?: Omit<ReduceOptions, "initial"> | undefined): NDArray
np.nanvar(a: ArrayLike, opts?: VarOptions | undefined): NDArray
np.nanstd(a: ArrayLike, opts?: VarOptions | undefined): NDArray
np.nanmin(a: ArrayLike, opts?: Omit<ReduceOptions, "dtype"> | undefined): NDArray
np.nanmax(a: ArrayLike, opts?: Omit<ReduceOptions, "dtype"> | undefined): NDArraynp.nanargmin
#np.nanargmin(a, { axis?, keepdims? }) · np.nanargmax(a, ...)
Index of the minimum / maximum ignoring NaNs. An all-NaN slice raises ValueError("All-NaN slice encountered").
Parameters
aArrayLike- An
NDArray, nested JS array or scalar. [options.axis]number | null- Axis; default the flattened array.
[options.keepdims]boolean- Keep reduced axes with length 1.
Returns
NDArray (int64)
Example
np.nanargmax([NaN, 2, 5, NaN]); // => 2
np.nanargmin([[NaN, 1], [2, 3]], { axis: 0 }); // => [1, 0]TypeScript declaration
np.nanargmin(a: ArrayLike, opts?: ArgReduceOptions | undefined): NDArray
np.nanargmax(a: ArrayLike, opts?: ArgReduceOptions | undefined): NDArraynp.average
#np.average(a, { axis?, weights?, returned?, keepdims? })
Weighted mean. weights has a's shape or the shape of a along axis; integer input averages in float64. With returned: true the result is [avg, sumOfWeights]. Weights summing to zero raise ValueError (NumPy: ZeroDivisionError).
Parameters
aArrayLike- An
NDArray, nested JS array or scalar. [options.axis]number | number[] | null- Axis or axes to reduce; default all (flattened).
[options.weights]ArrayLike- Weights.
[options.returned]boolean- Also return the sum of weights.
[options.keepdims]boolean- Keep reduced axes with length 1.
Returns
NDArray | [NDArray, NDArray]
Example
np.average([1, 2, 3, 4]); // => 2.5
np.average([1, 2, 3], { weights: [3, 0, 1] }); // => 1.5
np.average([[1, 2], [3, 4]], { axis: 1, weights: [1, 3], returned: true }).map((r) => r.toArray()); // => [[1.75, 3.75], [4, 4]]TypeScript declaration
np.average(a: ArrayLike, opts: AverageOptions & { returned: true; }): [NDArray, NDArray]
np.average(a: ArrayLike, opts?: AverageOptions | undefined): NDArraynp.cov
#np.cov(m, { y?, rowvar?, bias?, ddof?, fweights?, aweights?, dtype? }) · np.corrcoef(x, { y?, rowvar?, dtype? })
Covariance matrix (rows are variables unless rowvar: false), normalised by N - 1 (N with bias, N - ddof with ddof), with optional frequency and observation weights. corrcoef divides by the standard deviations and clips to [-1, 1]. Results are squeezed (one variable gives a 0-d array).
Parameters
mArrayLike- An
NDArray, nested JS array or scalar. [options.y]ArrayLike- Extra variables.
[options.rowvar]boolean- Default true.
[options.ddof]number- Overrides
bias.
Returns
NDArray
Example
np.cov([1, 2, 3]); // => 1
np.cov([1, 2, 3], { y: [1, 5, 2] }); // => [[1, 0.5], [0.5, 4.333333333333334]]
np.corrcoef([[1, 2, 3], [3, 2, 1]]); // => [[1, -1], [-1, 1]]TypeScript declaration
np.cov(m: ArrayLike, opts?: CovOptions | undefined): NDArray
np.corrcoef(x: ArrayLike, opts?: CorrcoefOptions | undefined): NDArraynp.gradient
#np.gradient(f, ...spacing, { axis?, edgeOrder? })
Central differences in the interior and one-sided (order 1 or 2) differences at the edges. Spacing is a scalar, one scalar or coordinate array per axis, or nothing (unit spacing). Returns an NDArray for one axis, otherwise one array per axis. Integer input gives float64.
Parameters
fArrayLike- An
NDArray, nested JS array or scalar. ...spacingnumber | ArrayLike- Scalar distances or 1-d coordinates.
[options.edgeOrder]1 | 2- Edge accuracy (default 1).
Returns
NDArray | NDArray[]
Example
np.gradient([1, 2, 4, 7, 11]); // => [1, 1.5, 2.5, 3.5, 4]
np.gradient([1, 2, 4, 7, 11], 2); // => [0.5, 0.75, 1.25, 1.75, 2]
np.gradient([1, 2, 4, 7, 11], { edgeOrder: 2 }); // => [0.5, 1.5, 2.5, 3.5, 4.5]TypeScript declaration
np.gradient(f: ArrayLike, ...args: (Spacing | GradientOptions)[]): NDArray | NDArray[]np.trapezoid
#np.trapezoid(y, { x?, dx?, axis? })
Composite trapezoidal integral of y along axis (default -1), using sample points x or uniform spacing dx (default 1).
Parameters
yArrayLike- An
NDArray, nested JS array or scalar. [options.x]ArrayLike- Sample points.
[options.dx]number- Spacing when
xis absent. [options.axis]number- Default -1.
Returns
NDArray
Example
np.trapezoid([1, 2, 3]); // => 4
np.trapezoid([1, 2, 3], { x: [0, 1, 3] }); // => 6.5TypeScript declaration
np.trapezoid(y: ArrayLike, opts?: TrapezoidOptions | undefined): NDArraynp.correlate
#np.correlate(a, v, mode?)
1-D cross-correlation: c[k] = Σ_j a[j+k]·conj(v[j]). Default mode is 'valid'. When mode='valid' and len(v) > len(a), returns the NumPy-compatible reversed result. Output dtype is promote_types(a, v).
Parameters
aArrayLike- An
NDArray, nested JS array or scalar. vArrayLike- An
NDArray, nested JS array or scalar. [mode]'full' | 'same' | 'valid'- Default 'valid'.
Returns
NDArray
Example
np.correlate([1, 2, 3], [0, 1, 0.5]); // => [3.5]
np.correlate([1, 2, 3], [0, 1, 0.5], 'full'); // => [0.5, 2, 3.5, 3, 0]
np.correlate([1, 2, 3], [0, 1, 0.5], 'same'); // => [2, 3.5, 3]TypeScript declaration
np.correlate(a: ArrayLike, v: ArrayLike, mode?: ConvMode | undefined): NDArraynp.convolve
#np.convolve(a, v, mode?)
Discrete linear convolution: c[k] = Σ_j a[j]·v[k-j]. Equivalent to correlating a with the reversed (un-conjugated) v. Default mode is 'full'. Output dtype is promote_types(a, v).
Parameters
aArrayLike- An
NDArray, nested JS array or scalar. vArrayLike- An
NDArray, nested JS array or scalar. [mode]'full' | 'same' | 'valid'- Default 'full'.
Returns
NDArray
Example
np.convolve([1, 2, 3], [0, 1, 0.5]); // => [0, 1, 2.5, 4, 1.5]
np.convolve([1, 2, 3], [0, 1, 0.5], 'same'); // => [1, 2.5, 4]
np.convolve([1, 2, 3], [0, 1, 0.5], 'valid'); // => [2.5]TypeScript declaration
np.convolve(a: ArrayLike, v: ArrayLike, mode?: ConvMode | undefined): NDArraynp.histogram
#np.histogram(a, bins?, { range?, density?, weights? }) · np.histogramBinEdges(a, bins?, ...)
histogram counts sample values into bins (integer count, estimator name, or explicit edges) and returns { hist, edges } where edges.length === hist.length + 1. The rightmost bin is closed on both sides (NumPy behaviour). density: true normalises so that the integral over the histogram equals 1. histogramBinEdges returns only the edges.
Parameters
aArrayLike- An
NDArray, nested JS array or scalar. [bins]number | BinsArg- Default 10. Estimators: 'auto', 'fd', 'sturges', 'scott', 'rice', 'doane', 'sqrt'.
[options.range][number, number]- Data range [min, max].
[options.density]boolean- Normalise to density.
[options.weights]ArrayLike- Per-sample weights.
Returns
{ hist: NDArray; edges: NDArray }
Example
const { hist, edges } = np.histogram([1, 2, 1, 3], 3);
hist.toArray(); // => [2, 1, 1]
edges.toArray(); // => [1, 1.6666666666666667, 2.333333333333333, 3]
np.histogramBinEdges([1, 2, 3, 4], 2).toArray(); // => [1, 2.5, 4]TypeScript declaration
np.histogram(a: ArrayLike, bins?: BinsArg | undefined, opts?: HistogramOptions | undefined): HistogramResult
np.histogramBinEdges(a: ArrayLike, bins?: BinsArg | undefined, opts?: HistogramOptions | undefined): NDArraynp.histogram2d
#np.histogram2d(x, y, bins?, { range?, density?, weights? })
2-D histogram of two 1-D samples. Returns { hist, xedges, yedges } where hist.shape === [xbins, ybins]. bins may be a scalar (applied to both axes) or [xbins, ybins].
Parameters
xArrayLike- An
NDArray, nested JS array or scalar. yArrayLike- An
NDArray, nested JS array or scalar. [bins]number | [BinsArg, BinsArg]- Default 10.
Returns
{ hist: NDArray; xedges: NDArray; yedges: NDArray }
Example
const { hist, xedges, yedges } = np.histogram2d([0,1,2],[0,1,2], 3);
hist.shape; // => [3, 3]
xedges.size; // => 4TypeScript declaration
np.histogram2d(x: ArrayLike, y: ArrayLike, bins?: BinsArg | [BinsArg, BinsArg] | undefined, opts?: Omit<Histogram2dOptions, "bins"> | undefined): Histogram2dResultnp.histogramdd
#np.histogramdd(sample, bins?, { density?, weights? })
Multi-dimensional histogram. sample is an (N, D) array or a 1-D array (treated as 1 column). Returns { hist, edges } where edges is an array of D edge arrays.
Parameters
sampleArrayLike- An
NDArray, nested JS array or scalar. [bins]number | BinsArg[]- Per-axis bins (scalar broadcast to all axes).
Returns
{ hist: NDArray; edges: NDArray[] }
Example
const { hist, edges } = np.histogramdd([[0,0],[1,1],[2,2]], 2);
hist.shape; // => [2, 2]
edges.length; // => 2TypeScript declaration
np.histogramdd(sample: ArrayLike, bins?: BinsArg | BinsArg[] | undefined, opts?: HistogramddOptions | undefined): HistogramddResultnp.bincount
#np.bincount(x, { weights?, minlength? })
Count occurrences of each non-negative integer in x. Returns a 1-D array of length max(x) + 1 or minlength, whichever is larger. With weights, sums weights instead of counting.
Parameters
aArrayLike- An
NDArray, nested JS array or scalar. [options.weights]ArrayLike- Per-element weights.
[options.minlength]number- Minimum output length.
Returns
NDArray
Example
np.bincount([1, 0, 2, 0, 1]).toArray(); // => [2, 2, 1]
np.bincount([0, 1], { minlength: 5 }).toArray(); // => [1, 1, 0, 0, 0]TypeScript declaration
np.bincount(x: ArrayLike, opts?: BincountOptions | undefined): NDArraynp.digitize
#np.digitize(x, bins, right?)
Return indices such that bins[i-1] <= x < bins[i] (right=false, default) or bins[i-1] < x <= bins[i] (right=true). bins must be monotonic. Output shape matches x.
Parameters
aArrayLike- An
NDArray, nested JS array or scalar. binsArrayLike- Monotonic bin edges.
[right]boolean- Default false.
Returns
NDArray
Example
np.digitize([0.2, 6.4, 3.0, 1.6], [0, 1, 2.5, 4, 10]).toArray(); // => [1, 4, 3, 2]TypeScript declaration
np.digitize(x: ArrayLike, bins: ArrayLike, right?: boolean | undefined): NDArraynp.interp
#np.interp(x, xp, fp, { left?, right?, period? })
1-D piecewise-linear interpolation. xp must be increasing (or decreasing when period is given). Values outside the range clamp to fp[0] / fp[-1] unless left / right are given. Complex fp is supported.
Parameters
aArrayLike- An
NDArray, nested JS array or scalar. xpArrayLike- Sorted x-coordinates of the data.
fpArrayLike- y-coordinates (may be complex).
[options.left]number- Fill below xp[0].
[options.right]number- Fill above xp[-1].
[options.period]number- Wrap-around period.
Returns
NDArray
Example
np.interp([0, 1, 1.5, 2, 2.5, 3], [1, 2, 3], [3, 2, 0]).toArray(); // => [3, 3, 2.5, 2, 1, 0]
np.interp([-1, 5], [0, 1, 2], [0, 1, 2], { left: -99, right: 99 }).toArray(); // => [-99, 99]TypeScript declaration
np.interp(x: ArrayLike, xp: ArrayLike, fp: ArrayLike, opts?: InterpOptions | undefined): NDArray