% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/onatski_2009.R
\name{.onatski_2009}
\alias{.onatski_2009}
\title{Onatski (2009) Test for the Number of Factors}
\usage{
.onatski_2009(X, kmax, alpha = 0.05)
}
\arguments{
\item{X}{Numeric matrix of dimensions T x N, typically preprocessed by
\code{.prepare_matrix()}. Must have an even number of rows.}

\item{kmax}{Integer. Maximum number of factors to consider. Defines the
upper bound k1 in the sequential testing procedure.}

\item{alpha}{Numeric. Significance level for the sequential test.
Defaults to \code{0.05}. Must be one of \code{0.01, 0.02, 0.03, 0.04,
  0.05, 0.06, 0.07, 0.08, 0.09, 0.10, 0.15}.}
}
\value{
A named list with the following elements:
\describe{
\item{k}{Integer. Estimated number of factors from the sequential
testing procedure.}
\item{ratios}{Numeric vector of length kmax. The ratio statistic
\eqn{(\tilde{\gamma}_i - \tilde{\gamma}_{i+1}) /
      (\tilde{\gamma}_{i+1} - \tilde{\gamma}_{i+2})} for each i.}
\item{eigenvalues}{Numeric vector of length kmax + 2. Leading
eigenvalues of the complex covariance matrix in descending order.}
\item{critical_value}{Numeric. Critical value used for the test
at the specified significance level.}
\item{alpha}{Numeric. The significance level used.}
}
}
\description{
Estimates the number of factors using the sequential hypothesis testing
procedure of Onatski (2009), applied to the static approximate factor
model version described in Section 4 of that paper. The test statistic
is based on ratios of differences of adjacent eigenvalues of a
complex-valued transformation of the data.
}
\details{
The static approximate factor model version of the Onatski (2009) test
(Section 4) proceeds as follows:

\enumerate{
\item Split the T x N data matrix into two halves of length T/2.
\item Form complex-valued vectors
\eqn{\tilde{X}_j = X_j + i X_{j + T/2}} for \eqn{j = 1, \ldots, T/2}.
\item Compute eigenvalues \eqn{\tilde{\gamma}_i} of
\eqn{\frac{2}{T} \sum_{j=1}^{T/2} \tilde{X}_j \tilde{X}_j^*}.
\item Sequentially test \eqn{H_0: r = k_0} versus
\eqn{H_1: k_0 < r \leq k_{max}} for \eqn{k_0 = 0, 1, \ldots}
using the statistic
\eqn{\tilde{R} = \max_{k_0 < i \leq k_{max}}
      (\tilde{\gamma}_i - \tilde{\gamma}_{i+1}) /
      (\tilde{\gamma}_{i+1} - \tilde{\gamma}_{i+2})}.
\item Stop when \eqn{H_0} is not rejected. The estimate is the
current \eqn{k_0}.
}

Critical values are taken from Table I of Onatski (2009) and depend
on the significance level \code{alpha} and the number of factors
tested under the alternative \eqn{k_1 - k_0 = k_{max} - k_0}.

If T is odd, the last observation is dropped to ensure equal-length
halves.
}
\references{
Onatski, A. (2009). Testing Hypotheses About the Number of Factors
in Large Factor Models. \emph{Econometrica}, 77(5), 1447-1479.
}
\seealso{
\code{.ahn_horenstein()}, \code{\link{select_factors}}
}
