% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/03_algo_hamilton.R
\name{hamilton_filter}
\alias{hamilton_filter}
\title{Hamilton Filter}
\usage{
hamilton_filter(x, h = NULL, p = 4L)
}
\arguments{
\item{x}{Numeric vector, \code{ts}, \code{xts}, or \code{zoo} object.}

\item{h}{Integer horizon (number of periods ahead). If \code{NULL} (default),
auto-detected from the series frequency using Hamilton's rule:
annual = 2, quarterly = 8, monthly = 24.}

\item{p}{Integer number of lags in the regression (default 4).}
}
\value{
A \code{macrofilter} object with \code{trend}, \code{cycle}, \code{data}, and \code{meta}
components. \code{meta} includes \code{h}, \code{p}, \code{coefficients}, and \code{compute_time}.
}
\description{
Decomposes a time series into trend and cycle components using the
regression-based filter proposed by Hamilton (2018). The trend is the
fitted value from an OLS regression of \eqn{y_{t+h}} on
\eqn{(1, y_t, y_{t-1}, \ldots, y_{t-p+1})}, and the cycle is the residual.
}
\details{
Hamilton (2018) proposes replacing the HP filter with a simple regression:
\deqn{y_{t+h} = \beta_0 + \beta_1 y_t + \beta_2 y_{t-1} + \cdots +
  \beta_p y_{t-p+1} + v_{t+h}}
The fitted values \eqn{\hat{y}_{t+h}} define the trend and the residuals
\eqn{\hat{v}_{t+h}} define the cycle.

The first \eqn{h + p - 1} observations have no computable trend or cycle
and are filled with \code{NA}.

The lag matrix is constructed vectorized via \code{embed()} and the
regression is solved with \code{\link[stats:lmfit]{stats::lm.fit()}} for speed.
}
\examples{
# Quarterly GDP-like series
y <- ts(cumsum(rnorm(200)), start = c(2000, 1), frequency = 4)
result <- hamilton_filter(y)
print(result)
}
\references{
Hamilton, J.D. (2018). Why You Should Never Use the Hodrick-Prescott
Filter. \emph{Review of Economics and Statistics}, 100(5), 831--843.
}
