% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/join_lagged_values.R
\name{join_lagged_values}
\alias{join_lagged_values}
\title{Join Lagged Variable Values over a Date Range}
\usage{
join_lagged_values(
  original_data,
  new_data,
  id_keys,
  min_lag,
  max_lag,
  ff_adjustment = FALSE,
  data_options = NULL
)
}
\arguments{
\item{original_data}{A data frame containing the target panel data.}

\item{new_data}{A data frame containing the source variables to lag and
merge. All columns besides \code{id_keys} and the date column will be lagged
and joined.}

\item{id_keys}{A character vector specifying the identifier column(s).}

\item{min_lag}{A \code{lubridate::Period} specifying the lower lag bound
(inclusive).}

\item{max_lag}{A \code{lubridate::Period} specifying the upper lag bound
(inclusive).}

\item{ff_adjustment}{Logical; if \code{TRUE}, keeps only the last observation
per identifier and year before lagging (Fama-French convention). Defaults
to \code{FALSE}.}

\item{data_options}{A list of class \code{tidyfinance_data_options} (created via
\code{\link[=data_options]{data_options()}}) specifying column name mappings. The \code{date} element is
used to identify the date column. Uses \code{\link[=data_options]{data_options()}} default if
\code{NULL}: \code{"date" = "date"}.}
}
\value{
A data frame with all columns from \code{original_data} plus the
lagged columns from \code{new_data} (keeping their original names).
}
\description{
\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#experimental}{\figure{lifecycle-experimental.svg}{options: alt='[Experimental]'}}}{\strong{[Experimental]}}

Joins lagged values of selected variables from one dataset (\code{new_data})
into another (\code{original_data}), based on date ranges defined by \code{min_lag}
and \code{max_lag}. Unlike \code{\link[=add_lagged_columns]{add_lagged_columns()}}, this function supports
joining across data frames with different date grids (e.g., monthly source
data into quarterly target data).
}
\examples{
set.seed(42)
library(dplyr)
library(lubridate)

df1 <- tibble(
  id = rep(1:2, each = 6),
  date = rep(seq(as.Date("2020-01-01"), by = "month", length.out = 6), 2)
)

df2 <- df1 |>
  mutate(x = rnorm(n()))

join_lagged_values(
  original_data = df1,
  new_data = df2,
  id_keys = "id",
  min_lag = months(1),
  max_lag = months(3)
)
}
\seealso{
Other rolling and lagging functions: 
\code{\link{add_lagged_columns}()},
\code{\link{compute_rolling_value}()}
}
\concept{rolling and lagging functions}
