lagging.join_lagged_values()

Join lagged values of variables over a date range.

Usage

Source

lagging.join_lagged_values(
    original_data,
    new_data,
    id_keys,
    min_lag=None,
    max_lag=None,
    ff_adjustment=False,
    data_options=None
)

Joins lagged values of selected variables from one data frame (‘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). All columns in ‘new_data’ besides ‘id_keys’ and the date column are lagged and joined under their original names.

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 ‘pl.col(“date”).dt.truncate(“1mo”)’ beforehand. This does not apply to ‘ff_adjustment=True’, which works on calendar years.

Parameters

original_data: pl.DataFrame

Target panel data. The date column must be of dtype ‘pl.Date’ or ‘pl.Datetime’.

new_data: pl.DataFrame

Source variables to lag and merge. All columns besides ‘id_keys’ and the date column will be lagged and joined.

id_keys: list of str or str

Identifier column(s) shared by both frames.

min_lag: int, str, datetime.timedelta, or pd.DateOffset = None

Lower lag bound (inclusive). Required unless ‘ff_adjustment=True’.

max_lag: int, str, datetime.timedelta, or pd.DateOffset = None

Upper lag bound (inclusive). Required unless ‘ff_adjustment=True’.

ff_adjustment: bool = False

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: dict = None
Column-name mapping (see ‘data_options’). The ‘date’ element is used to identify the date column. Uses the ‘data_options’ default when None: ‘date’ -> ‘date’.

Returns

pl.DataFrame
‘original_data’ with all columns from ‘new_data’ appended as lagged values (keeping their original names).

Examples

import numpy as np
import polars as pl
import datetime as dt
from tidyfinance import join_lagged_values
rng = np.random.default_rng(42)
dates = pl.date_range(
    dt.date(2020, 1, 1), dt.date(2020, 6, 1), "1mo", eager=True
)
df1 = pl.DataFrame({
    'id': [1] * 6 + [2] * 6,
    'date': dates.to_list() * 2,
})
df2 = df1.with_columns(
    x=pl.Series(rng.standard_normal(len(df1)))
)
join_lagged_values(
    original_data=df1,
    new_data=df2,
    id_keys='id',
    min_lag='1mo',
    max_lag='3mo',
)
# Fama-French timing: annual values are used from July to June
annual = pl.DataFrame({
    'id': [1, 2],
    'date': [dt.date(2019, 12, 1), dt.date(2019, 6, 1)],
    'x': [10.0, 20.0],
})
monthly = pl.DataFrame({
    'id': [1] * 3 + [2] * 3,
    'date': [
        dt.date(2020, 6, 1), dt.date(2020, 7, 1), dt.date(2021, 6, 1)
    ] * 2,
})
join_lagged_values(monthly, annual, id_keys='id', ff_adjustment=True)