attach_latest_before

attach_latest_before(
    rows,
    observations,
    *,
    value_name,
    reading_column,
    key_columns,
    value_column=VALUE_COLUMN,
    known_at_column=KNOWN_AT_COLUMN,
    maximum_age=None,
)

Attach to each row the latest observation known strictly before its own moment.

latest_before reads a whole panel at one moment. An event study needs one moment per row: each report, each formation day, each horizon before a print. Every row gets the value knowable at its own reading moment, so rows sharing a key never share a reading by accident.

Parameters

Name	Type	Description	Default
rows	pd.DataFrame	Rows to enrich; carry the key columns and the reading column.	required
observations	pd.DataFrame	Point-in-time rows carrying the keys, a value and a known_at.	required
value_name	str	Name of the attached value. Its known_at is attached as this name suffixed with _known_at.	required
reading_column	str	Column of rows holding each row’s UTC reading moment.	required
key_columns	Sequence[str]	Columns that decide which observations belong to a row.	required
value_column	str	Column of observations holding the value.	VALUE_COLUMN
known_at_column	str	Column of observations holding its UTC known_at.	KNOWN_AT_COLUMN
maximum_age	pd.Timedelta | None	Discard an observation older than this at the row’s reading moment, rather than carry it forward. None keeps any age.	None

Returns

Name	Type	Description
	pd.DataFrame	A copy of rows, in their original order, with the value and its known_at attached. Missing where nothing qualifies or the reading moment is missing.

Raises

Name	Type	Description
	PanelError	A column is absent or a timestamp column is naive or outside UTC, every such problem reported at once; or maximum_age is not a positive duration.