`discretize`

Groups numeric data into bins.

Category: Language Fundamentals > Data Types

Syntax

Y = discretize(X, edges)

Returns the bin number of each element, using the bin edges edges.

Y = discretize(X, n)

Uses n equal-width bins covering the data.

Y = discretize(X, edges, values)

Returns the corresponding entry of values instead of the bin number.

[Y, E] = discretize(___)

Also returns the bin edges.

Y = discretize(___, 'IncludedEdge', 'right')

Makes bins closed on the right.

Description

Bin k covers edges(k) <= x < edges(k+1), so a value equal to an inner edge falls in the bin to its right. Only the last bin includes its upper edge by default. With 'IncludedEdge', 'right', bins are (edges(k), edges(k+1)] and the first bin includes its lower edge.

Data outside the range of the edges gives NaN. Use accumarray or histcounts to count how many fall into each bin.

Input arguments

X: Numeric array.
edges: Increasing vector of bin edges.
values: One value per bin.

Output arguments

Y: Bin numbers (or values), with NaN for data outside all bins.
E: Bin edges.

Example

Bin numbers and labels

x = [1 5 9 10];
discretize(x, [0 5 10])
discretize(x, [0 5 10], 'IncludedEdge', 'right')
discretize([0 1 2 3], [0 2 4], [10 20])
discretize([0.5 20], [0 2 4])

Output

ans = 1×4

     1     2     2     2
ans = 1×4

     1     1     2     2
ans = 1×4

    10    10    20    20
ans = 1×2

     1   NaN

Notes

The 'categorical' option and datetime input are not available in MatLivre; use the numeric bin numbers with categorical(Y, 1:n, names).

discretize