help mata mm_linbin()


mm_linbin() -- Linear binning


real colvector mm_linbin(x, w, g)

real colvector mm_fastlinbin(x, w, g)

real colvector mm_exactbin(x, w, g [, dir, include])

real colvector mm_makegrid(x [, m, e, min, max])


x: real colvector containing data points

w: real colvector containing weights

g: real colvector containing grid points

dir: real scalar idicating the direction of the intervals (default: right open)

include: real scalar idicating that data outside the grid be included in the first and last bins

m: real scalar specifying the number of equally spaced grid points (default is 512)

e: real scalar e extending the grid range

min: real scalar specifying the minimum grid value (default: min(x) - e)

max: real scalar specifying the maximum grid value (default: max(x) + e)


mm_linbin() returns linearly binned counts of x at the grid points g (g must be sorted).

mm_fastlinbin() also performs linear binning but assumes g to be a (sorted) regular grid containing equidistant grid points.

mm_exactbin() returns counts of x within the intervals defined by the grid points g (g must be sorted). The default is to use right open intervals (with the last interval closed). However, dir!=0 specifies that left open intervals be used (with the first interval closed). mm_exactbin() does not allow x to contain data outside the grid range, unless include!=0 is specified, in which case such data is included in the first and last bin, respectively.

w in mm_linbin(), mm_fastlinbin(), and mm_exactbin() specifies weights associated with the observations in x. Specify w as 1 to obtain unweighted results. The sum of returned counts is equal to the sum of weights.

mm_makegrid() returns a grid of m equally spaced points over x. The default range of the grid is [min(x),max(x)]. If e is specified, the range is set to [min(x)-e,max(x)+e]. Alternatively, specify min and/or max to determine the limits of the grid range.


Linear binning: Let g(j) and g(j+1) be the two nearest grid points below and above observation x. Then w*(g(j+1)-x)/(g(j+1)-g(j)) is added to the count at g(j) and w*(x-g(j))/(g(j+1)-g(j)) is added to the count at g(j+1), where w is the weight associated with x. Data below (above) the grid range is added to the count of the first (last) grid point.


mm_linbin(x, w, g) mm_fastlinbin(x, w, g) x: n x 1 w: n x 1 or 1 x 1 g: m x 1, m>=1 result: m x 1.

mm_exactbin(x, w, g, dir, include) x: n x 1 w: n x 1 or 1 x 1 g: m x 1, m>=2 dir: 1 x 1 include: 1 x 1 result: m-1 x 1.

mm_makegrid(x, m, e, min, max): x: n x 1 m: 1 x 1 e: 1 x 1 min: 1 x 1 max: 1 x 1 result: m x 1.


mm_exactbin() aborts with error if min(x) < g[1] or max(x) > g[rows(g)] (unless include!=0 is specified).

mm_linbin(), mm_fastlinbin(), and mm_exactbin() produce erroneous results if g is not sorted or if x, w, or g contain missing.

mm_fastlinbin() produces erroneous results if the values in g are not equidistant.

Source code

mm_linbin.mata, mm_fastlinbin.mata, mm_exactbin.mata, mm_makegrid.mata


Ben Jann, ETH Zurich,

Also see

Online: help for [M-5] range(), [M-4] utility, moremata