refactor: fix portfolio analyzer biases and extract shared utils

- portfolio_analyzer: apply shift(1) lag to eliminate lookahead bias,
  rename 'size' factor to 'liquidity', unify alpha to arithmetic annualization
- Extract ensemble_utils.py, search_utils.py, fusion_engine.py, backtest_report.py
  from duplicated logic across ensemble/brute-force scripts
- Remove hacky cross-script imports in minentropy_ensemble.py
- Reduce ensemble_fusion.py from ~1515 to ~1145 lines
- Update all affected tests (525 passed)

Author: Tonny@Home

quantpits/scripts/analysis/portfolio_analyzer.py

@@ -304,9 +304,9 @@ def calculate_factor_exposure(self, market=None):
         X = sm.add_constant(aligned['Market'])
         model = sm.OLS(aligned['Portfolio'], X).fit()
 
-        # Use period-based years for consistency with metrics
-        years = len(aligned) / self.periods_per_year
-        alpha = (1.0 + model.params['const']) ** self.periods_per_year - 1.0
+        # OLS intercept is an arithmetic daily mean; annualize arithmetically
+        # to stay consistent with the multi-factor model.
+        alpha = model.params['const'] * self.periods_per_year
         beta = model.params['Market']
 
         return {
@@ -317,7 +317,10 @@ def calculate_factor_exposure(self, market=None):
 
     def calculate_style_exposures(self, market=None):
         """
-        Regress daily returns against proxy style factors (Size, Momentum, Volatility).
+        Regress daily returns against proxy style factors (Liquidity, Momentum, Volatility).
+        Factor values are lagged by 1 day (T-1) to avoid lookahead bias.
+        Note: 'Liquidity' uses log(close*volume) as a proxy; this is turnover/amount,
+        not market capitalization (which requires total_shares data).
         market 默认从 model_config.json 读取。
         """
         if market is None:
@@ -344,18 +347,23 @@ def calculate_style_exposures(self, market=None):
         features['datetime'] = pd.to_datetime(features['datetime'])
 
         features = features.sort_values(['instrument', 'datetime'])
-        features['size'] = np.log(features['close'] * features['volume'] + 1e-9)
-        features['momentum'] = features.groupby('instrument')['close'].pct_change(20)
 
+        # Calculate daily returns first (no lag needed, this is the dependent variable)
         features['prev_close'] = features.groupby('instrument')['close'].shift(1)
         features['ret'] = (features['close'] - features['prev_close']) / features['prev_close']
 
+        # Factor values use T-1 data (shift(1)) to avoid lookahead bias:
+        # We use yesterday's factor scores to explain today's returns.
+        features['liquidity'] = np.log(features['close'] * features['volume'] + 1e-9)
+        features['liquidity'] = features.groupby('instrument')['liquidity'].shift(1)
+        features['momentum'] = features.groupby('instrument')['close'].pct_change(20).shift(1)
         features['volatility'] = features.groupby('instrument')['ret'].rolling(20, min_periods=5).std().reset_index(0, drop=True)
+        features['volatility'] = features.groupby('instrument')['volatility'].shift(1)
 
-        features = features.dropna(subset=['ret', 'size', 'momentum', 'volatility'])
+        features = features.dropna(subset=['ret', 'liquidity', 'momentum', 'volatility'])
 
         factor_returns = {}
-        for factor in ['size', 'momentum', 'volatility']:
+        for factor in ['liquidity', 'momentum', 'volatility']:
             # top 20% minus bottom 20%
             def _factor_ret(df):
                 if len(df) < 5:
@@ -397,13 +405,13 @@ def _factor_ret(df):
         if len(aligned) < 2:
             return {}
 
-        X = sm.add_constant(aligned[['Market', 'size', 'momentum', 'volatility']])
+        X = sm.add_constant(aligned[['Market', 'liquidity', 'momentum', 'volatility']])
         model = sm.OLS(aligned.iloc[:, 0], X).fit()
 
         return {
             'Multi_Factor_Intercept': float(model.params.get('const', 0)) * self.periods_per_year,
             'Multi_Factor_Beta': float(model.params.get('Market', 0)),
-            'Barra_Size_Exp': float(model.params.get('size', 0)),
+            'Barra_Liquidity_Exp': float(model.params.get('liquidity', 0)),
             'Barra_Momentum_Exp': float(model.params.get('momentum', 0)),
             'Barra_Volatility_Exp': float(model.params.get('volatility', 0)),
             'Barra_Style_R_Squared': float(model.rsquared),

quantpits/scripts/analyze_ensembles.py

@@ -37,51 +37,12 @@ def run_single_backtest_oos(
     combo_models, norm_df, top_k, drop_n, benchmark, freq,
     trade_exchange, bt_start, bt_end, st_config=None, bt_config=None
 ):
-    """单独运行一次标准回测，用于 OOS 精确验证"""
-    if st_config is None:
-        st_config = strategy.load_strategy_config()
-    if bt_config is None:
-        bt_config = strategy.get_backtest_config(st_config)
-
-    # 1. 合成信号
-    combo_score = norm_df[list(combo_models)].dropna(how='any').mean(axis=1)
-
-    import copy
-    st_config = copy.deepcopy(st_config)
-    st_config["strategy"]["params"]["topk"] = top_k
-    st_config["strategy"]["params"]["n_drop"] = drop_n
-
-    strategy_inst = strategy.create_backtest_strategy(combo_score, st_config)
-
-    # 2. 回测
-    try:
-        report, _ = run_backtest_with_strategy(
-            strategy_inst=strategy_inst,
-            trade_exchange=trade_exchange,
-            freq=freq,
-            account_cash=bt_config["account"],
-            bt_start=bt_start,
-            bt_end=bt_end
-        )
-
-        st_config_inner = strategy.load_strategy_config()
-        benchmark_col = st_config_inner.get('benchmark', 'SH000300')
-        metrics = standard_evaluate_portfolio(report, benchmark_col, freq)
-
-        return {
-            "models": ",".join(combo_models),
-            "n_models": len(combo_models),
-            "Ann_Ret": metrics.get("CAGR", 0),
-            "Max_DD": metrics.get("Max_Drawdown", 0),
-            "Excess_Ret": metrics.get("Absolute_Return", 0) - metrics.get("Benchmark_Absolute_Return", 0),
-            "Ann_Excess": metrics.get("Excess_Return_CAGR", 0),
-            "Total_Ret": metrics.get("Absolute_Return", 0),
-            "Final_NAV": report.iloc[-1]["account"],
-            "Calmar": metrics.get("Calmar", 0) if pd.notna(metrics.get("Calmar")) else 0,
-        }
-    except Exception as e:
-        print(f"  [ERROR] Combo {combo_models} failed: {e}")
-        return None
+    """单独运行一次标准回测，用于 OOS 精确验证 (委托给 search_utils)"""
+    from quantpits.utils.search_utils import run_single_backtest
+    return run_single_backtest(
+        combo_models, norm_df, top_k, drop_n, benchmark, freq,
+        trade_exchange, bt_start, bt_end, st_config, bt_config
+    )