Join Lagged Variable Values over a Date Range

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 = NULL,
  max_lag = NULL,
  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). Required unless ff_adjustment = TRUE.
max_lag: A lubridate::Period specifying the upper lag bound (inclusive). Required unless ff_adjustment = TRUE.
ff_adjustment: Logical; if TRUE, applies the Fama and French (1993) timing convention: the last observation per identifier and calendar year (the fiscal year-end) is used from July of the following year through June of the year after that, whatever the month of the fiscal year-end. A value for a fiscal year ending in December 2020 or in June 2020 is thus used from July 2021 to June 2022. min_lag and max_lag are ignored. 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).

Details

For min_lag/max_lag expressed in whole months or years, the dates in both data frames should be the first of the month, as returned by the download_data() functions. On other days of the month the monthly offset can miss the intended match (for example, a source dated 30 April never matches a target dated 31 May); floor the dates with lubridate::floor_date(date, "month") beforehand. This does not apply to ff_adjustment = TRUE, which works on calendar years.

Examples

set.seed(42)
library(dplyr)
library(lubridate)
#> 
#> Attaching package: ‘lubridate’
#> The following objects are masked from ‘package:base’:
#> 
#>     date, intersect, setdiff, union

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)
)
#> # A tibble: 12 × 3
#>       id date             x
#>    <int> <date>       <dbl>
#>  1     1 2020-01-01 NA     
#>  2     1 2020-02-01  1.37  
#>  3     1 2020-03-01 -0.565 
#>  4     1 2020-04-01  0.363 
#>  5     1 2020-05-01  0.633 
#>  6     1 2020-06-01  0.404 
#>  7     2 2020-01-01 NA     
#>  8     2 2020-02-01  1.51  
#>  9     2 2020-03-01 -0.0947
#> 10     2 2020-04-01  2.02  
#> 11     2 2020-05-01 -0.0627
#> 12     2 2020-06-01  1.30  

# Fama-French timing: annual values are used from July to June
annual <- tibble(
  id = 1:2,
  date = as.Date(c("2019-12-01", "2019-06-01")),
  x = c(10, 20)
)
monthly <- tibble(
  id = rep(1:2, each = 3),
  date = rep(as.Date(c("2020-06-01", "2020-07-01", "2021-06-01")), 2)
)
join_lagged_values(monthly, annual, id_keys = "id", ff_adjustment = TRUE)
#> # A tibble: 6 × 3
#>      id date           x
#>   <int> <date>     <dbl>
#> 1     1 2020-06-01    NA
#> 2     1 2020-07-01    10
#> 3     1 2021-06-01    10
#> 4     2 2020-06-01    NA
#> 5     2 2020-07-01    20
#> 6     2 2021-06-01    20

Usage

Arguments

Value

Details

See also

Examples