{smcl}
{* *! version 1 28aug2017}
{cmd:help kssur}
{hline}

{title:Title}

{p2colset 5 18 20 2}{...}

{p2col :{hi:kssur} {hline 2}} Calculate Kapetanios, Shin & Snell unit root test statistic along with 1, 5 and 10% finite-sample critical values, and associated p-values{p_end}
{p2colreset}{...}


{title:Syntax}
{p 8 17 2}
{cmd:kssur} {varname} {ifin} [{cmd:,} {cmd:noprint}
{cmdab:maxlag(}{it:integer}{cmd:)}
{cmdab:noconstant} {cmdab:trend}]

{p 4 6 2}
{cmd:by} is not allowed. The routine can be applied to a single unit of a panel.{p_end}
{p 4 6 2}
Before using {opt kssur} you must {opt tsset} your data; see {manhelp tsset TS}.{p_end}
{p 4 6 2}
{it:varname} may contain time series operators; see {manhelp tsvarlist U}.{p_end}
{p 4 6 2}
Sample may not contain gaps.{p_end}

{title:Description}

{pstd}{cmd:kssur} computes Kapetanios, Shin & Snell KSS (2003) OLS-detrending based unit root tests against the alternative of a globally stationary exponential smooth transition autoregressive (ESTAR) process.
The command accommodates {it:varname} with nonzero mean and nonzero trend. Allowance is also made for the lag length to be either fixed (FIXED)
or determined endogenously using information criteria such as Akaike and Schwarz, denoted AIC and SIC, respectively. A data-dependent procedure often known as the general-to-specific (GTS)
algorithm is also permitted, using significance levels of 5 and 10%, denoted GTS05 and GTS10, respectively; see e.g. Hall (1994). Approximate p-values are also calculated.

{pstd}Both the finite-sample critical values and the p-value are estimated based on an extensive set of Monte Carlo simulations, summarised by means of response surface regressions; for more details see Otero and Smith (2017).

{title:Options}

{phang}{opt noprint} specifies that the results are to be returned but not printed.

{phang}{opt maxlag} sets the number of lags to be included in the test regression to account for residual serial correlation.
If not specified, {hi:kssur} sets the number of lags following Schwert (1989) with the formula maxlag=int(12*(T/100)^0.25), where T is the total number of observations.

{phang} {opt noconstant} specifies that the test will be applied to the raw data. Use {hi:noconstant} when {it:varname} is a zero mean stochastic process.

{phang} {opt trend} specifies that OLS detrending is to be applied. Use {hi:trend} when {it:varname} is a nonzero trend stochastic process, in which case KSS recommend detrending the data using OLS.

{phang} By default, {it:varname} is assumed to be a nonzero mean stochastic process.

{title:Examples}

{pstd} We test whether coffee price differentials contain a unit root. For this, we use monthly price series of the four best known types of coffee, namely unwashed Arabicas (mainly coffee from Brazil), Colombian mild Arabicas (mainly coffee
from Colombia), other mild Arabicas (mainly coffee from other Latin American countries), and Robusta coffee (mainly coffee grown in African countries and south-east Asia). The coffee prices, denoted br, co, om and ro, respectively,
are considered after applying the logarithmic transformation. The sample period runs from 1990m1 to 2004m1, that is a total of 169 time observations for each series, and the data were downloaded from the website
of the International Coffee Organisation (ICO) at www.ico.org.

{pstd} We begin by downloading the data and verifying that it has a time-series format:

{phang2}{inp:.} {stata "use http://www2.warwick.ac.uk/fac/soc/economics/staff/jsmith/research/coffeedata.dta, clear":use http://www2.warwick.ac.uk/fac/soc/economics/staff/jsmith/research/coffeedata.dta, clear}{p_end}

{phang2}{inp:.} {stata "tsset date":tsset date}{p_end}

{pstd}Then, let us say that we would like to test whether the price differential between Brazilian coffee (br) and Colombia coffee (co), that is brco, contains a unit root, against the alternative that it is a globally stationary ESTAR process.
Given that brco has a nonzero mean, the relevant KSS statistic is that based on OLS demeaned data, which is implemented by default.
Initially, the number of lags is set by the user as p=3:

{phang2}{inp:.} {stata "kssur brco, maxlag(3)":kssur brco, maxlag(3)}{p_end}

{pstd}This second illustration is the same as above, but using a subsample of the data that starts in January 1992:

{phang2}{inp:.} {stata "kssur brco if tin(1992m1,), maxlag(3)":kssur brco if tin(1992m1,), maxlag(3)}{p_end}
 
{pstd}Lastly, we perform the KS test using all the available observations, but with the number of lags determined based on Schwert's formula:

{phang2}{inp:.} {stata "kssur brco":kssur brco}{p_end}


{title:Stored results}

{synopt:{cmd:r(varname)}}Variable name{p_end}
{synopt:{cmd:r(treat)}}Raw, demeaned or detrended data, depending on the {cmd:noconstant} and {cmd:trend} option{p_end}
{synopt:{cmd:r(minp)}}First period used in the test regression{p_end}
{synopt:{cmd:r(maxp)}}Last period used in the test regression{p_end}
{synopt:{cmd:r(tsfmt)}}Time series format of the time variable{p_end}
{synopt:{cmd:r(N)}}Number of observations{p_end}
{synopt:{cmd:r(results)}}Results matrix, 5x6{p_end}

{p}The rows of the results matrix indicate which method of lag length was used: 
FIX (lag selected by user, or using Schwert's formula); AIC; SIC;  GTS05; or GTS10.{p_end}

{p}The columns of the results matrix contain, for each method: the number of lags used;
the KSS statistic; its p-value; and the critical values at 1%, 5%, and 10%, respectively.{p_end}

{title:Authors}

{phang} Jesus Otero, Universidad del Rosario, Colombia{break} jesus.otero@urosario.edu.co{p_end}
{phang} Jeremy Smith, Warwick University, United Kingdom{break} jeremy.smith@warwick.ac.uk{p_end}


{title:References}

{phang}Hall, A. (1994). Testing for a unit root in time series with pretest data-based model selection. Journal of Business and Economic Statistics 12, 461-470.

{phang}Kapetanios, G., Y. Shin, and A. Snell (2003). Testing for a unit root in the nonlinear STAR framework. Journal of Econometrics 112, 359-379.

{phang}Otero, J., and J. Smith (2017). Response surface models for OLS and GLS detrending-based unit root tests in nonlinear ESTAR models. The Stata Journal, forthcoming.

{phang}Schwert, G. W. (1989). Tests for unit roots: A Monte Carlo investigation. Journal of Business and Economic Statistics 7, 147-159.