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

Title

mm_quantile() -- Empirical quantile function

Syntax

real matrix    mm_quantile(X [, w, P, altdef])

real rowvector mm_median(X [, w])

real rowvector mm_iqrange(X [, w, altdef])

where

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

w:  real colvector containing weights

P:  real matrix containing probabilities (default is P = (0,
.25, .5, .75, 1)')

altdef:  real scalar causing interpolation formula to be used

Description

mm_quantile() applies to P the inverse empirical cumulative distribution
function of X (the so called quantile function). That is, mm_quantile()
returns the quantiles X corresponding to the probabilities provided by P.
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. If P has one column and X
has several columns, then the quantiles corresponding to P are computed
for each column of X. If X has one column and P has several columns, then
the quantile function of X is applied to each column of P. If X and P
both have several columns, then the number of columns is required to be
the same and quantiles are computed column by column.

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

w specifies weights associated with the observations (rows) in X. Omit w,
or specify w as 1 to obtain unweighted results. Note that the arguments
in the above functions must not contain missing values.

altdef!=0 in mm_quantile() and mm_iqrange() uses an interpolation formula
for calculating the quantiles (see remarks below).

Remarks

Example:

: 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 by summarize and is the default method in _pctile.
However, if altdef!=0 is specified, a piecewise linear continuous
function according to Definition 6 in Hyndman and Fan (1996) is applied.
This is also used by centile and by _pctile with the altdef option.

Unlike centile and _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:  n x 1 or n x k
w:  n x 1 or 1 x 1
P:  r x 1 or r x k
altdef:  1 x 1
result:  r x 1 or r x k

mm_median(X, w):
X:  n x k
w:  n x 1 or 1 x 1
result:  1 x k

mm_iqrange(X, w, altdef):
X:  n x k
w:  n x 1 or 1 x 1
altdef:  1 x 1
result:  1 x k

Diagnostics

mm_quantile(): p < 0 is treated as p = 0, p > 1 as p = 1.

Weights should not be negative.

Results may be misleading if altdef!=0 is used with non-integer weights.

Source code

mm_quantile.mata, mm_median.mata, mm_iqrange.mata

References

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

Author

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

Also see

Online:  help for mm_ecdf(), summarize, pctile, centile, invcdf (if
installed), moremata
```