```-------------------------------------------------------------------------------
help for invcdf
-------------------------------------------------------------------------------

Invert the cumulative distribution function (quantile function)

incdf varname [if exp] [in range] [weight] , generate(newvar)
reference(refvar [if exp] [in range]) [ cdf(cdfvar) ]

by ... : may be used with invcdf; see help by.

fweights and aweights are allowed; see help weights.

Description

invcdf applies the inverse cumulative distribution function (the so
called quantile function) of refvar to the values of varname.
Technically, invcdf first computes the empirical cumulative distribution
function of refvar (see cumul) and then applies the inverse of this CDF
to the values of varname. Note that varname must lie between 0 and 1
(inclusive).

The values computed by invcdf are equivalent to those obtained by
_pctile, percentiles() (apart from possible precision problems). Also see
the relrank command (available from the SSC Archive). An application of
invcdf can be found in the jmp package (also available from the SSC
Archive).

Options

generate(newvar) it not optional. It specifies the name of the new
variable to be created.

reference(refvar [if exp] [in range]) is not optional. It specifies the
variable representing the reference distribution. Use if and in
within reference() to restrict the sample for refvar (the if and in
restrictions outside reference() do not apply to refvar). Note that
the indicated samples for refvar and varname may overlap.

cdf(cdfvar) may be used to specify a variable representing the empirical
cumulative distribution function (e.c.d.f.) of refvar. In this case,
relrank skips the computation of the e.c.d.f. and uses cdfvar
instead. Note that cdfvar should lie in [0,1] and must be defined for
all values of refvar in the specified sample.

Examples

Compute the hypothetical wages for women that would result if women had
the male wage distribution:

. cumul wage if female==1, generate(cum)
. invcdf cum, ref(wage if female==0) g(hypwage)
. summarize hypwage

Methods and Formulas

invcdf inverts the empirical distribution function using averages where
the function is flat. The formula can be found in [R] pctile (standard
formula).

Author

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

Also see

Online:  help for pctile, cumul, relrank (if installed), jmp (if
```