% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/02_algo_hp.R
\name{hp_filter}
\alias{hp_filter}
\title{Hodrick-Prescott Filter (Sparse Matrix Implementation)}
\usage{
hp_filter(x, lambda = NULL, freq = NULL)
}
\arguments{
\item{x}{Numeric vector, \code{ts}, \code{xts}, or \code{zoo} object.}

\item{lambda}{Smoothing parameter.
If \code{NULL} (default), it is auto-detected using the Ravn-Uhlig rule
(\code{6.25 * freq^4}).}

\item{freq}{Numeric frequency override (1 = annual, 4 = quarterly,
12 = monthly). Used only when \code{lambda} is \code{NULL} and the frequency cannot
be inferred from \code{x}.}
}
\value{
A \code{macrofilter} object with \code{trend}, \code{cycle}, \code{data}, and \code{meta}
components.
}
\description{
Decomposes a time series into trend and cycle components by solving the
HP penalized least-squares problem using a sparse Cholesky factorization.
This avoids the dense O(n^3) inversion used by other implementations and
scales linearly in the number of observations.
}
\details{
The HP filter minimises
\deqn{\sum (y_t - \tau_t)^2 + \lambda \sum (\Delta^2 \tau_t)^2}
which admits the closed-form solution
\deqn{(I + \lambda D'D)\,\tau = y}
where \eqn{D} is the second-difference operator.

The implementation builds \eqn{D} as a banded sparse matrix
(\code{\link[Matrix:bandSparse]{Matrix::bandSparse()}}) and solves the symmetric positive-definite system
with a sparse Cholesky decomposition (\code{\link[Matrix:solve-methods]{Matrix::solve()}}).

When \code{lambda} is not supplied the Ravn-Uhlig (2002) rule is applied:
\code{lambda = 6.25 * freq^4}, yielding 6.25 (annual), 1600 (quarterly), and
129 600 (monthly).
}
\examples{
# Quarterly GDP-like series
y <- ts(cumsum(rnorm(200)), start = c(2000, 1), frequency = 4)
result <- hp_filter(y)
print(result)
}
\references{
Hodrick, R.J. and Prescott, E.C. (1997). Postwar U.S. Business Cycles: An
Empirical Investigation. \emph{Journal of Money, Credit and Banking}, 29(1),
1--16.

Ravn, M.O. and Uhlig, H. (2002). On Adjusting the Hodrick-Prescott Filter
for the Frequency of Observations. \emph{Review of Economics and Statistics},
84(2), 371--376.
}
