{smcl}
{* *! version 1.0.0 24jul2010}{...}
{hline}
{cmd:help rpec}{right:Michal Brzezinski (July 2010)}
{hline}

{title:Title}

{p2colset 5 16 20 2}{...}
{p2col: {hi:rpec} {hline 2}}Estimate robustly the number ({it:k}) of extreme order statistics used for fitting the Pareto model to upper tails of distributions{p_end}
{p2colreset}{...}


{title:Syntax}

{p 4 4 2}
{cmd:rpec} [{varname}] [{cmd:,}  {it:options}]


{synoptset 20 tabbed}{...}
{synopthdr}
{synoptline}
{synopt:{bf:k({it:scalar})}}the maximum number of extreme order statistics used in estimation{p_end}
{synopt:{bf:x0({it:scalar})}}the minimum value of {it:varname} used in estimation{p_end}
{synopt:{bf:c({it:scalar})}}robustness constant{p_end}
{synopt:{bf:ns({it:scalar})}}number of Monte Carlo simulations{p_end}

{p 4 4 2}
If neither {it:k} nor {it:x0} options are used, {cmd:nrpec} searches for optimal {it:k} over the whole range of {it:varname}.

{title:Description}

{p 4 4 2}
{cmd:rpec} estimates the number {it:k} of extreme ordered statistics 
(e.g. highest incomes) for fitting the Pareto model to the upper tail of the distribution.
It uses the robust Pareto error criterion (RC-criterion) introduced 
in Dupuis and Victoria-Feser (2006).
Estimating {it:k} is equivalent to estimating the scale parameter {it:x0} of the Pareto distribution:
k = SUM I({it:varname} >= {it:x0}), where I is the indicator function. The estimated {it:x0} can be then used in fitting Pareto model by, e.g., ML method, see {help paretofit}.

{p 4 4 2}
For an implementation of non-robust Pareto error criterion for choosing {it:k}, also introduced in Dupuis and Victoria-Feser (2006), see {help nrpec}, if installed. 


{title:Dependencies}

{pstd} {cmd:rpec} requires {cmd:paretowml} by Michal Brzezinski
 and {cmd:moremata} by Ben Jann. First package is used to compute weighted 
maximum likelihood estimator of Pareto distribution shape parameter. 
It can be installed by typing {it:net install paretowml,}
{it:from(http://coin.wne.uw.edu.pl/mbrzezinski/software/)}. The second package can 
be installed by typing {it: ssc install moremata}.{p_end}


{title:Examples}

{pstd}To search for optimal {it:k} over the whole range of {it:varname}:{p_end}

{phang2}{cmd:. rpec {it:varname} }{p_end}

{pstd}To search for optimal {it:k} among the 50 largest values of {it:varname}{p_end}

{phang2}{cmd:. rpec {it:varname}, k(50)}{p_end}

{pstd}To search for optimal {it:k} among the values of {it:varname} >= 10000{p_end}

{phang2}{cmd:. rpec {it:varname}, x0(10000)}{p_end}


{title:References}


{phang}
Dupuis, Debbie J. and Victoria-Feser, Maria-Pia (2006). A Robust Prediction Error Criterion for Pareto Modelling of Upper Tails. {it:The Canadian Journal of Statistics}, {cmd: 34} (4), 639-658.


{title:Also see}

{p 4 13 2}
Online: help for {help nrpec}, {help paretofit}, {help paretowml}, {help paretoobre}, {help hillp} if installed. 


{title:Author}

{p 4 4 2}
Michal Brzezinski <mbrzezinski@wne.uw.edu.pl>, Faculty of Economic Sciences, University of Warsaw, Poland.