% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/lag_data.R
\name{lag_data}
\alias{lag_data}
\title{Construct lagged regressors and aligned response}
\usage{
lag_data(
  formula = NULL,
  data = NULL,
  y = NULL,
  x = NULL,
  lags = 0,
  include_intercept = TRUE,
  preserve_ts = FALSE
)
}
\arguments{
\item{formula}{An optional model formula. The left-hand side is
taken as the response and the right-hand side as the regressor(s).
Only one non-intercept regressor is currently allowed when
lagging is used.}

\item{data}{Optional data frame in which to evaluate \code{formula}.}

\item{y}{Optional numeric or time series object with the response.
Ignored if \code{formula} is supplied.}

\item{x}{Optional numeric vector with the regressor to be lagged.
Ignored if \code{formula} is supplied. If \code{x} is not \code{NULL}, it must
have the same length as \code{y} (when \code{y} is supplied).}

\item{lags}{Integer vector of lags to include. The default \code{lags = 0}
means that only the contemporaneous regressor is used. For example,
\code{lags = 0:2} gives columns corresponding to (x(t), x(t-1), x(t-2)).}

\item{include_intercept}{Logical; if \code{TRUE} (default) an intercept
column named \code{"Intercept"} is prepended to the design matrix.}

\item{preserve_ts}{Logical; if \code{TRUE} and \code{y} is a \code{ts} object, the
returned \code{y} will also be a \code{ts} object obtained via
\code{\link[stats]{window}} starting at the first retained time
point. Otherwise, \code{y} is returned as a numeric vector.}
}
\value{
A list with components
\describe{
\item{y}{The aligned response vector. If \code{preserve_ts = TRUE}
and \code{y} was a \code{ts} object, then this is a \code{ts} object; otherwise
a numeric vector.}
\item{X}{The design matrix of lagged regressors, including an
intercept column if \code{include_intercept = TRUE}. If \code{x} is \code{NULL},
then \code{X} is \code{NULL}.}
\item{rows}{Integer vector of row indices from the original data
that are retained after lagging.}
\item{max_lag}{The maximum lag used, i.e. \code{max(lags)}.}
}
}
\description{
Helper for building lagged design matrices for time series or
longitudinal data. The function aligns a response vector \code{y}
and a single regressor \code{x} (possibly with several lags) and
returns a list with the cleaned response, the design matrix and
the row indices used.

You can either:
\itemize{
\item supply \code{y} and \code{x} directly, or
\item use a formula of the form \code{y ~ x} together with \code{data}.
}
}
\details{
When using the formula interface, the function creates a model frame
internally. The first column is taken as the response. All remaining
columns are considered regressors. If the right-hand side contains
only an intercept, \code{x} is set to \code{NULL} and no lagged regressors are
constructed.

If multiple regressors are present on the right-hand side, they are
combined into a matrix, but in the current implementation this is
only allowed when no lagging is requested (i.e., \code{lags} is \code{0}).
Attempting to lag multiple regressors will result in an error.

For a given vector of lags, a lag matrix is built with one column
per lag. The column names are \code{"lag0"}, \code{"lag1"}, etc., corresponding
to the entries in \code{lags}. Rows which involve undefined values (due to
lagging) are dropped from both \code{y} and \code{X}. The indices of the rows
kept from the original series are returned in the \code{rows} component.
}
\examples{
## ------------------------------------------------------------
## 1. Basic usage with y/x interface
## ------------------------------------------------------------
set.seed(123)
n  <- 10
y  <- rnorm(n)
x  <- rnorm(n)

## Use current and one lag of x
ld1 <- lag_data(y = y, x = x, lags = 0:1)
ld1$y                # aligned response
ld1$X                # design matrix (Intercept, lag0, lag1)
ld1$rows             # indices retained


## ------------------------------------------------------------
## 2. Formula interface with a data frame
## ------------------------------------------------------------
dat <- data.frame(
  y = rnorm(20),
  x = rnorm(20)
)

## Use y ~ x with one lag
ld2 <- lag_data(y ~ x, data = dat, lags = 0:2)
head(ld2$X)
length(ld2$y)


## ------------------------------------------------------------
## 3. Using the result in a regression / ARX setting
## ------------------------------------------------------------
## Here we regress y_t on an intercept and lagged x's
ld3 <- lag_data(y = y, x = x, lags = 0:2)

## Remove intercept column when passing to lm()
fit_lm <- lm(ld3$y ~ ld3$X[, -1])
coef(fit_lm)


## ------------------------------------------------------------
## 4. Time series example with preserve_ts = TRUE
## ------------------------------------------------------------
y_ts <- Nile

## Regress Nile flow on its own lag-1 (simple ARX-like setup)
ld4 <- lag_data(y = y_ts, x = y_ts, lags = 1, preserve_ts = TRUE)

## y is now a ts object starting at the appropriate time
start(y_ts)
start(ld4$y)

## Fit an AR(1) model with lagged Nile as xreg
## (intercept in X, lag in the second column)
fit_arx <- stats::arima(ld4$y,
                        order = c(1, 0, 0),
                        xreg  = ld4$X[, -1, drop = FALSE])
fit_arx

}
\seealso{
\code{\link[stats]{lag}}, \code{\link[stats]{embed}},
and \code{\link[stats]{ts}} for related time series utilities.
}
