join_lagged_values: Join Lagged Variable Values over a Date Range
In tidyfinance: Tidy Finance Helper Functions

join_lagged_values

R Documentation

Join Lagged Variable Values over a Date Range

Description

Joins lagged values of selected variables from one dataset (new_data) into another (original_data), based on date ranges defined by min_lag and max_lag. Unlike add_lagged_columns(), this function supports joining across data frames with different date grids (e.g., monthly source data into quarterly target data).

Usage

join_lagged_values(
  original_data,
  new_data,
  id_keys,
  min_lag,
  max_lag,
  ff_adjustment = FALSE,
  data_options = NULL
)

Arguments

`original_data`	A data frame containing the target panel data.
`new_data`	A data frame containing the source variables to lag and merge. All columns besides `id_keys` and the date column will be lagged and joined.
`id_keys`	A character vector specifying the identifier column(s).
`min_lag`	A `lubridate::Period` specifying the lower lag bound (inclusive).
`max_lag`	A `lubridate::Period` specifying the upper lag bound (inclusive).
`ff_adjustment`	Logical; if `TRUE`, keeps only the last observation per identifier and year before lagging (Fama-French convention). Defaults to `FALSE`.
`data_options`	A list of class `tidyfinance_data_options` (created via `data_options()`) specifying column name mappings. The `date` element is used to identify the date column. Uses `data_options()` default if `NULL`: `"date" = "date"`.

Value

A data frame with all columns from original_data plus the lagged columns from new_data (keeping their original names).

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)
)

tidyfinance documentation built on June 1, 2026, 1:06 a.m.