Factor research framework with IC/IR analysis, quantile backtesting, and factor combination. Suitable for cross-sectional factor evaluation across multiple instruments.
69%
Does it follow best practices?
Run evals on this skill
Adds up to 20 points to the overall score
Passed
No findings from the security scan
Fix and improve this skill with Tessl
tessl review fix ./agent/src/skills/factor-research/SKILL.mdSystematically evaluates the predictive power of single or multiple factors. Uses IC/IR statistical tests and quantile backtests to determine whether a factor has stock-selection power, and to guide factor screening and combination.
Applicable scenarios:
index=date, columns=codes)factor_analysis tool: pass in the factor CSV, return CSV, and output directoryKey point: the rows (dates) and columns (instrument codes) of the factor CSV and return CSV must align exactly. Returns must be forward returns after the factor-observation date (to avoid look-ahead bias).
factor_analysis Tool Parameters| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| factor_csv | string | Yes | - | Path to the factor-value CSV |
| return_csv | string | Yes | - | Path to the return CSV |
| output_dir | string | Yes | - | Output directory for results |
| n_groups | integer | No | 5 | Number of quantile groups |
| File | Contents |
|---|---|
| ic_series.csv | Daily IC series |
| ic_summary.json | IC mean, IC standard deviation, IR, proportion of IC > 0 |
| group_equity.csv | Cumulative equity curves for each quantile group |
| Metric | Threshold | Interpretation |
|---|---|---|
| IC mean | > 0.03 | Factor has basic predictive power |
| IC mean | > 0.05 | Factor has strong predictive power |
| IC mean | > 0.10 | Unusually high; check for look-ahead bias |
| IR (IC mean / IC std) | > 0.5 | Factor is stably effective |
| IR | > 1.0 | Extremely strong, very rare |
| Proportion of IC > 0 | > 55% | Factor direction is stable |
| Proportion of IC > 0 | < 50% | Factor direction is unstable and unusable |
Note: negative IC can also be useful (reverse factors). Judge by absolute value, and reverse the signal direction in actual use.
Quantile backtesting sorts instruments into N groups by factor value from low to high (default 5 groups), with equal-weight holding inside each group.
Criteria:
Group_1 to Group_N should show a monotonic rising (or falling) pattern. Better monotonicity means stronger factor discriminationlong_short_spread). A larger spread means stronger selection powerWarning signs:
When multiple single factors pass validity tests, they should be combined into a composite factor:
The simplest method: standardize each factor and sum them with equal weights. Suitable when the factor count is small and IC differences are minor.
Composite factor = Z(factor1) + Z(factor2) + ... + Z(factorN)
where Z() is cross-sectional Z-score standardizationAssign weights according to historical IC mean. Factors with higher IC receive larger weights.
weight_i = |IC_mean_i| / sum(|IC_mean_j|)
Composite factor = sum(weight_i * Z(factor_i))First orthogonalize the factors with the Schmidt process to remove collinearity, then combine them with equal weights. Suitable when factors are highly correlated with one another.
1. Sort factors by IC from high to low
2. Keep the first factor unchanged
3. Regress each later factor on all previous factors and use the residual as the orthogonalized factor
4. Combine the orthogonalized factors with equal weightsThe methods above are unrolled by hand only when you want to inspect every step.
The optional combination quantlib module performs the equal-weight and IC
variants as one reproducible call and returns the weights it used:
from src.quantlib.combination import combine_factors
result = combine_factors(
{"momentum": momentum_panel, "value": value_panel},
forward_returns, # row t is the return earned after observing t
method="ic", # "equal", "ic" or "icir"
window=252, # trailing IC observations per weight
rebalance=20,
)
result.composite, result.weights, result.diagnostics["correlation"]Weights are estimated from rows strictly before the row they apply to, so a
weight never sees its own forward return. There is no complete list of
combination methods: for decayed IC, maximum IC, regression or trained weights,
compute the weight table yourself and pass method="explicit", weights=table
(a time x factor DataFrame). The module enforces the timing contract and
reports the diagnostics; it does not choose a method for you, and nothing in the
backtest path requires it. See
references/combination.md for the pre-flight
checklist, the failure modes and the JSON envelope.
Use quantlib_call with module="neutralization" (or import
src.quantlib.neutralization) for tested transforms rather than retyping a
regression. neutralize_factor removes named numeric/classification exposures
with OLS or WLS. pca_factors compresses correlated factor columns into
uncorrelated components; PCA alone does not make a factor industry/style neutral.
Panels use observation-time rows and asset columns. Minute, hourly, daily, weekly, monthly and irregular observations all use the same contract: each row is fitted independently, with no resampling, forward filling or full-period fit. Single-asset time-series residualization is a different model and is not provided. Align controls, weights, classifications and the tradable mask to information available at that observation time; the library cannot verify publication dates.
control_selection="explicit" is the default. Optional "auto" filters the
supplied controls in insertion order by current coverage, rank and remaining
degrees of freedom. It reports every selection/drop and never uses IC, returns
or test-period performance. Supply economically justified controls: automatic
quality filtering cannot decide which economic exposures should be removed.
Missing/nonpositive WLS weights are excluded, not replaced. Missing exposures
remain missing; rank-deficient explicit fits and empty auto selections skip the
observation with diagnostics rather than silently changing the requested model.
Inspect coverage and Pearson exposure before/after on the same sample. WLS
reports weighted exposure; unweighted or rank correlations need not be zero.
Residual standardization is linear (no post-fit clipping/ranking), preserving
the fitted orthogonality. Exact zero residuals are reported as such, not as an
effective new factor. Compare raw/residual IC and group backtests separately
with factor_analysis, using identical universes, masks and holding horizons.
The transform itself does not calculate Sharpe, trading costs or turnover.
PCA reports per-time loadings, centering/scales, retained variance and component counts. Its loading-sign convention does not guarantee stable component identity across time; near-equal eigenvalues can rotate. Choose component counts/variance thresholds using research/training data rather than test-period performance.
See the neutralization workflow for Python and JSON-envelope examples, diagnostics and limits.
For a shared stage, mode and lineage envelope across alpha bench entry points, see the factor-research run contract. The v1 modes are declarative; they do not replace the availability contract or enforce locked evaluation by themselves.
n_groups instrumentspip install pandas numpy scipyRather than recompute factors from raw OHLCV every research iteration, prefer reusing the 450+ pre-built alphas in the Alpha Zoo registry. Each alpha is metadata-validated (AlphaMeta schema with theme, universe, columns_required, decay_horizon, min_warmup_bars), shape-checked against panel["close"], and rejected if it emits +/- inf or >95% NaN — so the factor CSV you feed to factor_analysis is already sanity-checked.
from src.factors.registry import Registry
registry = Registry()
ids = registry.list(theme="momentum", universe="equity_cn") # filter the catalogue
factor_panel = registry.compute("alpha101_001", panel) # wide DataFrame, same shape as panel["close"]
factor_panel.to_csv("factor_alpha101_001.csv") # ready for factor_analysis toolFor combining several validated alphas into one composite signal, see the multi-factor skill's ZooSignalEngine (it z-scores, weights, and ranks alphas for you, with per-alpha skip isolation). For browsing the catalogue and inspecting individual __alpha_meta__ records, see the alpha-zoo skill.
When factor_analysis runs inside a backtest or swarm run, set output_dir to <run_dir>/artifacts/factor/<factor_name>/ so the Run Detail Factor tab can render the results. Use one subdirectory per factor (for example artifacts/factor/momentum_20d/), and keep the three standard output files (ic_series.csv, ic_summary.json, group_equity.csv) together inside it. Artifacts written elsewhere under artifacts/ are still discovered by the recursive scan, but the canonical layout keeps runs comparable.
HKUDS/Vibe-Trading
1dbe5d5
If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.