% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/extract_eigenvalues.R
\name{.extract_eigenvalues}
\alias{.extract_eigenvalues}
\title{Extract Leading Eigenvalues from a Panel Data Matrix}
\usage{
.extract_eigenvalues(X, kmax)
}
\arguments{
\item{X}{Numeric matrix of dimensions T x N.}

\item{kmax}{Integer. Number of leading eigenvalues to compute. Should be
set generously (e.g., 8-15) to allow estimators to evaluate the full
candidate range.}
}
\value{
A named list with the following elements:
\describe{
\item{values}{Numeric vector of length \code{kmax + 1} containing the
leading eigenvalues in descending order. The extra eigenvalue is
required by ratio-based estimators.}
\item{vectors}{Numeric matrix of corresponding eigenvectors.}
\item{orientation}{Character string, either \code{"N"} or \code{"T"},
indicating which covariance matrix was decomposed.}
}
}
\description{
Computes the leading eigenvalues of the sample covariance matrix using
a truncated eigendecomposition. Automatically selects the smaller of the
N x N or T x T covariance matrix for efficiency. Uses RSpectra when
available for large matrices, falling back to base R otherwise.
}
\details{
When N <= T, the function decomposes the N x N matrix \eqn{X'X / T}.
When N > T, it decomposes the T x T matrix \eqn{XX' / N}.
This ensures the cheaper decomposition is always used.

RSpectra's \code{eigs_sym()} is used when available and when
\code{min(N, T) > 100}, as truncated decomposition only provides
meaningful speedup at larger scales.
}
\references{
Ahn, S.C. and Horenstein, A.R. (2013). Eigenvalue Ratio Test for the
Number of Factors. \emph{Econometrica}, 81(3), 1203-1227.
}
