11. HistoryPanel and the optional “FactorResearch” helper layer (evaluation conclusions)

This document answers the evaluation item in the roadmap: Do we need to add another lightweight API abstraction layer on top of HistoryPanel (working name FactorResearch), dedicated to computing IC/IR, quantile-portfolio returns, long-short curves, etc.?

11.1. 1. 当前能力边界（已满足的部分）

The following capabilities are already covered by HistoryPanel and related APIs—no need to reinvent the wheel:

  • Factor column generation: assign, __setitem__, returns, kline, apply_ta, etc.;

  • Cross-sectional transforms: rank, zscore(method='cs'|'ts');

  • Coarse portfolios and benchmarks: portfolio (equal-weight/weighted, groups, benchmark);

  • Research-oriented return display: cum_return, normalize, and mask=;

  • Visualization: plot and (M,L) mask highlighting;

  • Integration with measurement/analytics tools: to_df_dict, or manually reshape to long format and then use pandas / statsmodels (see Tutorial 2.5 §11).

For the goal of “lightweight factor research + rough validation,” the above already forms a complete foundation.

11.2. 2. 若增加 FactorResearch 层，能解决什么？

Typical wrappers may include:

  • Given a factor column and a return column (or label), output per-period IC, IC mean/IR;

  • A NAV or return series of a quantile portfolio (bucketed by cross-section);

  • A time series of a long-short portfolio (top minus bottom).

All of these can be implemented in a few dozen lines on the user side or in an independent module using existing rank / portfolio / values + pandas; the value of wrapping lies in stable APIs, unified parameter conventions, and fewer copy-paste errors.

11.3. 3. 结论（短期不引入类库级 FactorResearch）

Conclusion: at the current stage, we will not force the addition of a FactorResearch class/submodule to the qteasy kernel or on top of HistoryPanel.

Brief rationale:

  1. Clear responsibilities: HistoryPanel is already positioned as a 3D research container with explicit alignment/resampling; IC/IR, quantile portfolios, etc. are “analysis recipes” with much stronger research workflow conventions. They fit better in standalone tutorials, examples, or a future optional package, to avoid HP API bloat.

  2. Avoid wrong expectations: naming it as a standalone module can easily make users think the framework already includes “publication-grade factor testing” (e.g., multiple testing, sample splitting, HAC standard errors), while in reality users still need to do inference on the statsmodels side, etc.

  3. Relationship with the mid-term “built-in factor library”: If the built-in factor library (M2.1) in the top-level roadmap is implemented, a more natural approach would be factor definition + registration + integration with FactorSorter/backtesting; batch IC/stratification can be optional utility functions around the factor library, rather than HistoryPanel instance methods.

  4. Maintenance cost: IC needs conventions for the forward return window, trading halts, delistings, weights (value-weighted vs equal-weighted), etc. There are many parameter combinations; without a unified data contract, it can easily drive up support costs.

11.4. 4. 若未来引入，建议形态（备忘）

If community demand is clear, recommend an independent module (e.g., qteasy.research.factor_stats or an external qteasy-research project), rather than HistoryPanel methods:

  • Inputs: HistoryPanel or DataFrame + column name + forward-looking periods;

  • Outputs: DataFrame / Series (optionally re-plotted as a supplement);

  • Docs: clearly state that it is not a replacement for the Backtester, and that it does not have built-in Fama–MacBeth / Newey–West (still export to statsmodels).

At that point, it should come with TDD and English ValueError contracts, consistent with the existing HP test style.

11.5. 5. 与教程的关系

For the practical workflow, follow §9–§11 of Tutorial 2.5: Using HistoryPanel to operate on and analyze historical data; this design document only records architecture-level evaluation conclusions and does not add any must-read API surface for users.