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