qis.estimate_signal_diagnostics

qis.estimate_signal_diagnostics(asset_returns_dict, signal, group_data=None, horizons=(1, 3, 6), fit_intercept=False, is_log_returns=True, is_vol_normalised=True, min_obs_per_date=5, min_obs_per_group=10, group_order=None)[source]

Cross-sectional predictive regression of forward returns on lagged signal.

For each horizon h, builds non-overlapping (signal, return) pairs (z_{i,t-1}, ỹ_{i,t,t+h}) and fits

ỹ_{i,t,t+h} = β · z_{i,t-1} + ε (default: no intercept)

The forward window length h is in native cadence units of each asset — h=1 means 1 month for a monthly asset and 1 quarter for a quarterly asset. This avoids the zero-then-jump return artefacts that arise when quarterly NAVs are forced onto a monthly grid.

String horizons (e.g. ‘YE’) override per-asset cadence — all assets are resampled to that frequency. Use for headline annual tests.

Parameters:

  • asset_returns_dict (Dict[str, DataFrame]) – Per-frequency returns dict from a pipeline that already handles FX adjustment and unsmoothing. Keys are pandas frequency strings (e.g. ‘ME’, ‘QE’, ‘YE’); values are return DataFrames indexed at that frequency’s period-ends with asset tickers as columns. Each asset must appear in exactly one frame (its native cadence).

  • signal (DataFrame) – T x N signal panel (e.g. AlphasData.alpha_scores). Columns must include every asset in asset_returns_dict. Signal panel is typically at the finest frequency present in the dict (e.g. monthly); the function resamples it to each asset’s native cadence.

  • group_data (Series | None) – Optional Series mapping asset name → group label. When None, only the pooled regression is run.

  • horizons (Sequence[int | str]) – Forward-return horizons. Integers are in native-cadence units (1, 3, 6 → 1, 3, 6 native periods per asset). Strings like ‘YE’ override per-asset cadence and resample uniformly.

  • fit_intercept (bool) – Include α in the regression. Default False — cross-sectional demeaning of the LHS makes α = 0 by construction.

  • is_log_returns (bool) – Set True when asset_returns_dict contains log returns (default), False for arithmetic. Affects cumulation across horizons.

  • is_vol_normalised (bool) – Divide cross-sectional return by cross- sectional std at each date (default True).

  • min_obs_per_date (int) – Minimum cross-sectional sample at a date.

  • min_obs_per_group (int) – Minimum sample size for a group’s regression to be reported.

  • group_order (Sequence[str] | None) – Explicit ordering for the groups in per_group.

Returns:

SignalDiagnosticsResult with .pooled_universe, .per_group, and .pairs populated.

Return type:

SignalDiagnosticsResult