{smcl}
{* *! version 1.1.5  11feb2011}{...}
{viewerdialog pctile "dialog pctile"}{...}
{viewerdialog xtile "dialog xtile"}{...}
{vieweralsosee "[D] pctile" "mansection D pctile"}{...}
{vieweralsosee "" "--"}{...}
{vieweralsosee "[R] centile" "help centile"}{...}
{vieweralsosee "[R] summarize" "help summarize"}{...}
{viewerjumpto "Syntax" "pctile##syntax"}{...}
{viewerjumpto "Description" "pctile##description"}{...}
{viewerjumpto "Options" "pctile##options"}{...}
{viewerjumpto "Examples" "pctile##examples"}{...}
{viewerjumpto "Saved results" "pctile##saved_results"}{...}
{title:Title}

{p2colset 5 19 21 2}{...}
{p2col :{manlink D pctile} {hline 2}}Create variable containing percentiles{p_end}
{p2colreset}{...}


{marker syntax}{...}
{title:Syntax}

{phang}
Create variable containing percentiles

{p 8 15 2}
{cmd:pctile}
{dtype}
{newvar}
{cmd:=} {it:{help exp}}
{ifin}
{weight}
[{cmd:,}
{it:{help pctile##pctile_options:pctile_options}}]


{phang}
Create variable containing quantile categories

{p 8 15 2}
{cmd:xtile}
{newvar} {cmd:=} {it:{help exp}}
{ifin}
{weight}
[{cmd:,} {it:{help pctile##xtile_options:xtile_options}}]


{phang}
Compute percentiles and store them in r()

{p 8 15 2}
{cmd:_pctile}
{varname}
{ifin}
{weight}
[{cmd:,} {it:{help pctile##_pctile_options:_pctile_options}}]


{synoptset 22 tabbed}{...}
{marker pctile_options}{...}
{synopthdr :pctile_options}
{synoptline}
{syntab :Main}
{synopt :{opt n:quantiles(#)}}number of quantiles; default is
{cmd:nquantiles(2)}{p_end}
{synopt :{opth g:enp(newvar:newvarp)}}generate
{it:newvarp} variable containing percentages{p_end}
{synopt :{opt alt:def}}use alternative formula for calculating
percentiles{p_end}
{synoptline}

{synoptset 22 tabbed}{...}
{marker xtile_options}{...}
{synopthdr :xtile_options}
{synoptline}
{syntab :Main}
{synopt :{opt n:quantiles(#)}}number of quantiles; default is
{cmd:nquantiles(2)}{p_end}
{synopt :{opth c:utpoints(varname)}}use values of {it:varname} as cutpoints
{p_end}
{synopt :{opt alt:def}}use alternative formula for calculating
percentiles{p_end}
{synoptline}

{synoptset 22}{...}
{marker _pctile_options}{...}
{synopthdr :_pctile_options}
{synoptline}
{synopt :{opt n:quantiles(#)}}number of quantiles; default is
{cmd:nquantiles(2)}{p_end}
{synopt :{opth p:ercentiles(numlist)}}calculate percentiles corresponding to
the specified percentages{p_end}
{synopt :{opt alt:def}}use alternative formula for calculating
percentiles{p_end}
{synoptline}

{p 4 6 2}
{opt aweight}s, {opt fweight}s, and {opt pweight}s are allowed
(see {manhelp weight U:11.1.6 weight}), except when
the {opt altdef} option is specified, in which case no weights are allowed.
{p_end}


{title:Menu}

    {title:pctile} 

{phang2}
{bf:Statistics > Summaries, tables, and tests >}
    {bf:Summary and descriptive statistics > Create variable of percentiles}

    {title:xtile}

{phang2}
{bf:Statistics > Summaries, tables, and tests >}
     {bf:Summary and descriptive statistics > Create variable of quantiles}


{marker description}{...}
{title:Description}

{pstd}
{opt pctile} creates a new variable containing the percentiles of 
{it:{help exp}}, where the expression {it:exp} is typically just another
variable.

{pstd}
{opt xtile} creates a new variable that categorizes {it:exp} by its
quantiles.  If the {opth cutpoints(varname)} option is specified, it
categorizes {it:exp} using the values of {it:varname} as category cutpoints.
For example, {it:varname} might contain percentiles of another variable,
generated by {opt pctile}.

{pstd}
{opt _pctile} is a programmer's command that computes up to 1,000 percentiles
and places results in {hi:r()}; see {findalias frresult}.
{opt summarize, detail} computes some percentiles
(1, 5, 10, 25, 50, 75, 90, 95, and 99th); see {manhelp summarize R}.


{marker options}{...}
{title:Options}

{dlgtab:Main}

{phang}{opt nquantiles(#)} specifies the number of quantiles.
It computes percentiles corresponding to percentages 100*k/m
for k=1, 2, ..., m-1, where m={it:#}.  For example, {cmd:nquantiles(10)}
requests that the 10th, 20th, ..., 90th percentiles be computed.  The default
is {cmd:nquantiles(2)}; that is, the median is computed.

{phang}{opth "genp(newvar:newvarp)"} ({cmd:pctile} only)
specifies a new variable to be generated
containing the percentages corresponding to the percentiles.

{phang}{opt altdef} uses an alternative formula for calculating percentiles.
The default method is to invert the empirical distribution function by using
averages, where the function is flat (the default is the same method used by
{cmd:summarize}; see {manhelp summarize R}).
The alternative formula uses an interpolation method.  See
{mansection D pctileMethodsandformulas:{it:Methods and formulas}} in
{bf:[D] pctile}.  Weights cannot be used when {opt altdef} is specified.

{phang}{opth cutpoints(varname)} ({cmd:xtile} only) requests that {opt xtile}
use the values of {it:varname}, rather than quantiles, as cutpoints for the
categories.  All values of {it:varname} are used, regardless of any {opt if}
or {opt in} restriction; see the
{mansection D pctileRemarkstechnote:technical note} in 
{bf:[D] pctile}.

{phang}{opth percentiles(numlist)} ({cmd:_pctile} only) requests
percentiles corresponding to the specified percentages.
Percentiles are placed in {cmd:r(r1)}, {cmd:r(r2)}, ..., etc.
For example, {cmd:percentiles(10(20)90)} requests that the 10th, 30th, 50th,
70th, and 90th percentiles be computed and placed into
{cmd:r(r1)}, {cmd:r(r2)}, {cmd:r(r3)}, {cmd:r(r4)}, and {cmd:r(r5)}.
Up to 1,000 (inclusive) percentiles can be requested.
See {help nlist} for the syntax of a numlist.  


{marker examples}{...}
{title:Examples}

    {hline}
    Setup
{phang2}{cmd:. sysuse auto}

{pstd}Create variable {cmd:pct} containing the deciles of {cmd:mpg}{p_end}
{phang2}{cmd:. pctile pct = mpg, nq(10)}{p_end}

{pstd}List the resulting data{p_end}
{phang2}{cmd:. list pct in 1/10}

{pstd}Setup{p_end}
{phang2}{cmd:. drop pct}

{pstd}Create variable {cmd:pct} containing the deciles of {cmd:mpg}, and
create variable {cmd:percent} containing the percentages{p_end}
{phang2}{cmd:. pctile pct = mpg, nq(10) genp(percent)}{p_end}

{pstd}List the resulting data{p_end}
{phang2}{cmd:. list percent pct in 1/10}

{pstd}Setup{p_end}
{phang2}{cmd:. drop pct percent}

{pstd}Create {cmd:pct} containing the deciles of {cmd:mpg} weighted by
{cmd:weight}, and create variable {cmd:percent} containing the
percentages{p_end}
{phang2}{cmd:. pctile pct = mpg [w=weight], nq(10) genp(percent)}

{pstd}List the resulting data{p_end}
{phang2}{cmd:. list percent pct in 1/10}

    {hline}
    Setup
{phang2}{cmd:. webuse bp1, clear}

{pstd}List variable {cmd:bp}{p_end}
{phang2}{cmd:. list bp, sep(4)}

{pstd}Create variable {cmd:quart} containing the quartiles of {cmd:bp}{p_end}
{phang2}{cmd:. xtile quart = bp, nq(4)}{p_end}

{pstd}List variables {cmd:bp} and {cmd:quart}{p_end}
{phang2}{cmd:. list bp quart, sep(4)}

{pstd}Setup{p_end}
        {cmd:. input class}

                   class
          1.  {cmd:100}
          2.  {cmd:110}
          3.  {cmd:120}
          4.  {cmd:130}
          5.  {cmd:end}

{pstd}Create variable {cmd:category} categorizing {cmd:bp} using the values of
{cmd:class} as category cutpoints{p_end}
{phang2}{cmd:. xtile category = bp, cut(class)}{p_end}

{pstd}List variables {cmd:bp}, {cmd:class}, and {cmd:category}{p_end}
{phang2}{cmd:. list bp class category, sep(4)}

    {hline}
    Setup
{phang2}{cmd:. sysuse auto, clear}

{pstd}Compute the deciles for {cmd:weight} and store then in
{cmd:r(r}{it:#}{cmd:)}{p_end}
{phang2}{cmd:. _pctile weight, nq(10)}

{pstd}List the saved results{p_end}
{phang2}{cmd:. return list}

{pstd}Compute the specified percentiles for {cmd:weight} and store them in 
{cmd:r(r}{it:#}{cmd:)}{p_end}
{phang2}{cmd:. _pctile weight, p(10, 33.333, 45 50, 55, 66.667, 90)}

{pstd}List the saved results{p_end}
{phang2}{cmd:. return list}{p_end}
    {hline}


{marker saved_results}{...}
{title:Saved results}

{pstd}
{cmd:pctile} and {cmd:_pctile} saves the following in {cmd:r()}:

{synoptset 10 tabbed}{...}
{p2col 5 10 14 2:Scalars}{p_end}
{synopt:{cmd:r(r}{it:#}{cmd:)}}value of {it:#}-requested percentile{p_end}
{p2colreset}{...}
