help mata mm_linbin()-------------------------------------------------------------------------------

Title

mm_linbin() -- Linear binning

Syntax

real colvectormm_linbin(x,w,g)

real colvectormm_fastlinbin(x,w,g)

real colvectormm_exactbin(x,w,g[,dir,include])

real colvectormm_makegrid(x[,m,e,min,max])

where

x:real colvectorcontaining data points

w:real colvectorcontaining weights

g:real colvectorcontaining grid points

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

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

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

e:real scalar eextending the grid range

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

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

Description

mm_linbin()returns linearly binned counts ofxat the grid pointsg(gmust be sorted).

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

mm_exactbin()returns counts ofxwithin the intervals defined by the grid pointsg(gmust 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 allowxto contain data outside the grid range, unlessinclude!=0 is specified, in which case such data is included in the first and last bin, respectively.

winmm_linbin(),mm_fastlinbin(), andmm_exactbin()specifies weights associated with the observations inx. Specifywas 1 to obtain unweighted results. The sum of returned counts is equal to the sum of weights.

mm_makegrid()returns a grid ofmequally spaced points overx. The default range of the grid is [min(x),max(x)]. Ifeis specified, the range is set to [min(x)-e,max(x)+e]. Alternatively, specifyminand/ormaxto determine the limits of the grid range.

RemarksLinear 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.

Conformability

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

mm_exactbin(x,w,g,dir,include)x:n x1w:n x1 or 1x1g:m x1,m>=2dir: 1x1include: 1x1result:m-1x1.

mm_makegrid(x,m,e,min,max):x:n x1m: 1x1e: 1x1min: 1x1max: 1x1result:m x1.

Diagnostics

mm_exactbin()aborts with error ifmin(x)<g[1]ormax(x)>g[rows(g)](unlessinclude!=0 is specified).

mm_linbin(),mm_fastlinbin(), andmm_exactbin()produce erroneous results ifgis not sorted or ifx,w, orgcontain missing.

mm_fastlinbin()produces erroneous results if the values ingare not equidistant.

Source codemm_linbin.mata, mm_fastlinbin.mata, mm_exactbin.mata, mm_makegrid.mata

AuthorBen Jann, ETH Zurich, jann@soz.gess.ethz.ch

Also seeOnline: help for

[M-5] range(),[M-4] utility,moremata