help mata mm_quantile()-------------------------------------------------------------------------------

Title

mm_quantile() -- Empirical quantile function

Syntax

real matrixmm_quantile(X[,w,P,altdef])

real rowvectormm_median(X[,w])

real rowvectormm_iqrange(X[,w,altdef])

where

X:real matrixcontaining data (rows are observations, columns variables)

w:real colvectorcontaining weights

P:real matrixcontaining probabilities (default isP= (0, .25, .5, .75, 1)')

altdef:real scalarcausing interpolation formula to be used

Description

mm_quantile()applies toPthe inverse empirical cumulative distribution function ofX(the so called quantile function). That is,mm_quantile()returns the quantilesXcorresponding to the probabilities provided byP. For example,

mm_quantile(x, 1, 0.25)returns the first quartile (i.e. the 0.25-quantile) of

x.Note that

mm_quantile()works column by column. IfPhas one column andXhas several columns, then the quantiles corresponding toPare computed for each column ofX. IfXhas one column andPhas several columns, then the quantile function ofXis applied to each column ofP. IfXandPboth have several columns, then the number of columns is required to be the same and quantiles are computed column by column.

mm_median()andmm_iqrange()are wrappers formm_quantile()and return the median (the 0.5-quantile) and the inter-quartile range (IQR = 0.75-quantile - 0.25-quantile).

wspecifies weights associated with the observations (rows) inX. Omitw, or specifywas 1 to obtain unweighted results. Note that the arguments in the above functions must not contain missing values.

altdef!=0 inmm_quantile()andmm_iqrange()uses an interpolation formula for calculating the quantiles (see remarks below).

RemarksExample:

: x = invnormal(uniform(10000,1)) : mm_quantile(x, 1, (0.25 \ 0.5 \ 0.75)) 1 +----------------+ 1 | -.6673752219 | 2 | -.0021958246 | 3 | .6880046299 | +----------------+

: mm_median(x, 1), mm_iqrange(x, 1) 1 2 +-------------------------------+ 1 | -.0021958246 1.355379852 | +-------------------------------+

The default for

mm_quantile()is to apply a discontinuous quantile function using averages where the empirical distribution function is flat (this corresponds to Definition 2 in Hyndman and Fan 1996). The same method is used bysummarizeand is the default method in_pctile. However, ifaltdef!=0 is specified, a piecewise linear continuous function according to Definition 6 in Hyndman and Fan (1996) is applied. This is also used bycentileand by_pctilewith thealtdefoption.Unlike

centileand_pctile,mm_quantile()allows using weights with the interpolation method (altdef!=0). This functionality, however, is only intended to be used with (integer) frequency weights.

Conformability

mm_quantile(X,w,P,altdef):X: nx1 or nxkw: nx1 or 1x1P: rx1 or rxkaltdef: 1x1result: rx1 or rxk

mm_median(X,w):X: nxkw: nx1 or 1x1result: 1xk

mm_iqrange(X,w,altdef):X: nxkw: nx1 or 1x1altdef: 1x1result: 1xk

Diagnostics

mm_quantile():p< 0 is treated asp= 0,p> 1 asp= 1.Weights should not be negative.

Results may be misleading if

altdef!=0 is used with non-integer weights.

Source codemm_quantile.mata, mm_median.mata, mm_iqrange.mata

ReferencesHyndman, R. J., Fan, Y. (1996). Sample Quantiles in Statistical Packages. The American Statistician 50:361-365.

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

Also seeOnline: help for

mm_ecdf(),summarize,pctile,centile,invcdf(if installed),moremata