Troubleshooting¶
Start with the error message: input problems are raised as ValueError or TypeError before
anything is computed and say what to change. When a statistic is missing, inspect its sample status
and, for intervals, its inference status.
Errors when you call evaluate¶
| Message | Meaning and action |
|---|---|
prices must be indexed by timestamps |
The index is not a DatetimeIndex. Convert it with pd.to_datetime. |
prices must be sorted by time / duplicate timestamps |
Call sort_index(); keep one row per bar. |
prices must be positive |
Returns are ratios. Mask zero or negative values with NaN. |
prices must be finite |
Replace infinities with NaN. |
a factor Series needs a two-level (timestamp, asset) MultiIndex |
Pass a wide DataFrame, or a Series with exactly one timestamp level and one asset level. |
the factor has scores at N timestamps that are not in prices |
The tables disagree on which bars exist. Reindex one to the other, or narrow start and end. |
no factor asset has prices |
The asset labels of the two tables do not match at all (for example integers against ticker strings). The message shows a few labels from each. |
factor assets have no prices and are ignored (warning) |
Some factor columns are absent from the price table. A matching column full of NaN is kept and yields missing pairs. |
the factor has no finite scores |
Every score is NaN for the priced assets, usually a label mismatch. |
the window is empty / prices have no rows in the window |
start and end exclude every bar. |
pass either a config or keyword options, not both |
Use evaluate(f, p, EvaluationConfig(...)) or evaluate(f, p, horizons=...). |
Unavailable cross-sectional IC¶
result.periods has one row per timestamp and horizon. The first applicable reason is stored as
status:
| Status | Meaning and next check |
|---|---|
valid |
An IC was computed. |
insufficient_assets |
Fewer than min_assets finite score/return pairs. Inspect missing scores, warmup, the unlabelled last bars, gaps and universe size. |
constant_signal |
All scores among the valid pairs are equal (often a rounded or capped factor). |
constant_returns |
All returns are equal (often stale or filled prices). |
The last delay + horizon bars have no label, and an interior price gap removes every label whose
path crosses it.
Unavailable time-series IC¶
result.time_series.assets, monthly and rolling carry a status for each asset and window:
| Status | Meaning and next check |
|---|---|
valid |
The IC was computed. |
partial_window |
The UTC month or rolling window is not fully inside the evaluation period. |
short_window |
The window holds fewer than min_horizons × horizon bars. Lower min_horizons or use longer windows. |
insufficient_pairs |
Fewer than min_pairs finite pairs after boundary exclusions. The default of 100 is high for daily bars and for monthly windows; see configure an evaluation. |
low_coverage |
Fewer than min_coverage of the window's bars have a finite pair. |
constant_signal / constant_returns |
No variation in that asset's sample (Spearman and Pearson). The cosine accepts a constant score. |
zero_signal / zero_returns |
Every score, or every target, is zero (cosine). |
With the default vol-scaled time-series target, a bar has a target only once its asset has
vol_min_bars one-bar returns. If prices begin at the window's start, the first windows lose those
bars and can turn low_coverage or insufficient_pairs; pass prices from before start (they are
read only to estimate volatility), lower vol_min_bars, or set time_series={"target": "return"}.
A vol_scaled cross-sectional target loses the same bars, which shows as insufficient_assets at
the start.
Missing ratios and intervals¶
- ICIR is undefined for a constant IC series. HAC inference also needs more observations than its lag count permits. A valid IC can exist without either.
- Monthly TS ICIR needs
min_monthscomplete valid months and variation across them. Its status isinsufficient_months,constant_ic,preliminary(fewer than twelve) oravailable. - Bootstrap intervals report
bootstrap_status:disabled(bootstrap_samples=0),too_few_blocks(less than five blocks of history; shortenblock_barsor lengthen the sample),no_eligible_assets,insufficient_draws, orvalid. - Time-series t-tests (
hac_t,hac_p_value) are missing where the IC is, and when the sample has fewer than two horizons of bars;hac_dofis then 0. - In
result.metrics()missing statistics are omitted; in CSVs they are blank. They are never zeros.
Surprising results¶
- An IC of exactly 0.0 is real: tiny samples have discrete rank correlations, and values within 1e-12 of zero are reported as zero so rounding error cannot decide whether a period counts as positive.
- Wider intervals than an independence-based estimate can result from positive temporal dependence. The Newey–West standard error accounts for this; see dependence and uncertainty.
- A suspiciously high IC warrants a timing and data check. Run the truncation check in
prepare factor and prices, and confirm
delaymatches when the score is really known.
Speed¶
The time-series bootstrap is usually the largest cost. To reduce it, reduce
time_series.bootstrap_samples (or set it to 0) or widen time_series.rolling_step. Both
analyses always run; disabling the bootstrap keeps their point estimates. See the cost note in
configure an evaluation.