numeraire_dataset.zones.clean.crsp_monthly_clean

numeraire_dataset.zones.clean.crsp_monthly_clean(msf: DataFrame, msenames: DataFrame, msedelist: DataFrame, *, share_codes: tuple[int, ...] = (10, 11), exchanges: tuple[int, ...] | None = (1, 2, 3), performance_delist_fill: float | None = -0.3) → DataFrame

Tidy monthly CRSP: common-stock filter, delisting-adjusted returns, month-end mktcap.

msf = monthly stock file (permno, date, ret, prc, shrout); msenames = the name history (permno, namedt, nameendt, shrcd, exchcd); msedelist = delisting returns (permno, date, dlret, dlstcd). Keeps shrcd in share_codes and, unless exchanges=None, exchcd in exchanges (default NYSE/AMEX/NASDAQ), adjusts returns for delisting (missing perf-delist returns filled at performance_delist_fill, -30% by default), and computes mktcap = |prc| * shrout (thousands -> $millions). Pass performance_delist_fill=None to preserve an unreported performance-delisting return as missing; the choice is explicit recipe input for reproductions whose paper does not state an imputation convention.

Merge cardinality is validated so a duplicated name/delist record raises instead of silently duplicating a firm-month’s return: the name-window join must resolve to at most one name record per firm-month (overlapping msenames windows raise), and the stock and delisting inputs must each contain at most one row per normalized (permno, month). Those two files are outer-joined so a terminal month present only in msedelist is retained. Such a row has is_terminal=True; its market capitalization remains missing because no price or shares are fabricated.

A genuinely missing monthly ret (no usable delisting return that month) is kept as NaN rather than fabricated as a flat 0.0. Only a terminal month with an observed (or performance-code-imputed) dlret treats a missing price return as zero so that the delisting return still enters the combined return. source_ret, dlret, and dlstcd are retained alongside adjusted ret so the combination identity and any -30% convention remain inspectable. When present in the raw frames, permco and siccd are retained as method-neutral firm and industry identifiers.