My First Commit

lib/pt_trading/results.py

@@ -427,14 +427,16 @@ class BacktestResult:
                         trd["open_scaled_disequilibrium"] is not None
                         and trd["open_scaled_disequilibrium"] is not None
                     ):
-                        disequil_info = f" | Open Dis-eq: {trd['open_scaled_disequilibrium']:.2f},"
-                        f" Close Dis-eq: {trd['open_scaled_disequilibrium']:.2f}"
+                        disequil_info = (
+                            f' | Open Dis-eq: {trd["open_scaled_disequilibrium"]:.2f},'
+                            f' Close Dis-eq: {trd["close_scaled_disequilibrium"]:.2f}'
+                        )
 
                     print(
-                        f" {trd['open_time'].time()}-{trd['close_time'].time()}  {trd['symbol']}: "
-                        f" {trd['open_side']} @ ${trd['open_price']:.2f},"
-                        f" {trd["close_side"]} @ ${trd["close_price"]:.2f},"
-                        f" Return: {trd['symbol_return']:.2f}%{disequil_info}"
+                        f' {trd["open_time"].time()}-{trd["close_time"].time()}  {trd["symbol"]}: '
+                        f' {trd["open_side"]} @ ${trd["open_price"]:.2f},'
+                        f' {trd["close_side"]} @ ${trd["close_price"]:.2f},'
+                        f' Return: {trd["symbol_return"]:.2f}%{disequil_info}'
                     )
                     pair_return += trd["symbol_return"]
 

lib/pt_trading/rolling_window_fit.py

@@ -188,7 +188,8 @@ class RollingFit(PairsTradingFitMethod):
         open_px_b = open_row[f"{colname_b}"]
 
         # creating the trades
-        print(f"OPEN_TRADES: {row["tstamp"]} {open_scaled_disequilibrium=}")
+        # use outer single quotes so we can reference DataFrame keys with double quotes inside
+        print(f'OPEN_TRADES: {open_tstamp} open_scaled_disequilibrium={open_scaled_disequilibrium}')
         if open_disequilibrium > 0:
             open_side_a = "SELL"
             open_side_b = "BUY"
@@ -237,10 +238,7 @@ class RollingFit(PairsTradingFitMethod):
             ),
         ]
         # Create DataFrame with explicit dtypes to avoid concatenation warnings
-        df = pd.DataFrame(
-            trd_signal_tuples,
-            columns=self.TRADES_COLUMNS,
-        )
+        df = pd.DataFrame(trd_signal_tuples, columns=self.TRADES_COLUMNS)
         # Ensure consistent dtypes
         return df.astype(
             {

lib/pt_trading/vecm_rolling_fit.py

@@ -1,14 +1,47 @@
+# original script moved to vecm_rolling_fit_01.py
+
+# 09.09.25  Added GARCH model - predicting volatility
+
+# Rule of thumb:
+# alpha + beta ≈ 1 → strong volatility clustering, persistence.
+# If much lower → volatility mean reverts quickly.
+# If > 1 → model is unstable / non-stationary (bad).
+
+# the VECM disequilibrium (mean reversion signal) and 
+# the GARCH volatility forecast (risk measure).
+# combine them → e.g., only enter trades when:
+
+# high_volatility = 1 → persistence > 0.95 or volatility > 2 (rule of thumb: unstable / risky regime).
+# high_volatility = 0 → stable regime.
+
+
+# VECM disequilibrium z-score > threshold and
+# GARCH-forecasted volatility is not too high (avoid noise-driven signals).
+# This creates a volatility-adjusted pairs trading strategy, more robust than plain VECM
+
+# now pair_predict_result_ DataFrame includes:
+# disequilibrium, scaled_disequilibrium, z-scores, garch_alpha, garch_beta, garch_persistence (α+β rule-of-thumb)
+# garch_vol_forecast (1-step volatility forecast)
+
+# Would you like me to also add a warning flag column 
+# (e.g., "high_volatility" = 1 if persistence > 0.95 or vol_forecast > threshold) 
+# so you can easily detect unstable regimes?
+
+# VECM/GARCH 
+# vecm_rolling_fit.py:
 from typing import Any, Dict, Optional, cast
 
+import numpy as np
 import pandas as pd
+from typing import Any, Dict, Optional
 from pt_trading.results import BacktestResult
 from pt_trading.rolling_window_fit import RollingFit
 from pt_trading.trading_pair import TradingPair
 from statsmodels.tsa.vector_ar.vecm import VECM, VECMResults
+from arch import arch_model
 
 NanoPerMin = 1e9
 
-
 class VECMTradingPair(TradingPair):
     vecm_fit_: Optional[VECMResults]
     pair_predict_result_: Optional[pd.DataFrame]
@@ -23,20 +56,23 @@ class VECMTradingPair(TradingPair):
         super().__init__(config, market_data, symbol_a, symbol_b)
         self.vecm_fit_ = None
         self.pair_predict_result_ = None
+        self.garch_fit_ = None
+        self.sigma_spread_forecast_ = None
+        self.garch_alpha_ = None
+        self.garch_beta_ = None
+        self.garch_persistence_ = None
+        self.high_volatility_flag_ = None
 
     def _train_pair(self) -> None:
         self._fit_VECM()
         assert self.vecm_fit_ is not None
+
         diseq_series = self.training_df_[self.colnames()] @ self.vecm_fit_.beta
-        # print(diseq_series.shape)
         self.training_mu_ = float(diseq_series[0].mean())
         self.training_std_ = float(diseq_series[0].std())
 
-        self.training_df_["dis-equilibrium"] = (
-            self.training_df_[self.colnames()] @ self.vecm_fit_.beta
-        )
-        # Normalize the dis-equilibrium
-        self.training_df_["scaled_dis-equilibrium"] = (
+        self.training_df_["disequilibrium"] = diseq_series
+        self.training_df_["scaled_disequilibrium"] = (
             diseq_series - self.training_mu_
         ) / self.training_std_
 
@@ -45,61 +81,96 @@ class VECMTradingPair(TradingPair):
         vecm_df = self.training_df_[self.colnames()].reset_index(drop=True)
         vecm_model = VECM(vecm_df, coint_rank=1)
         vecm_fit = vecm_model.fit()
-
-        assert vecm_fit is not None
-
-        # URGENT check beta and alpha
-
-        # Check if the model converged properly
-        if not hasattr(vecm_fit, "beta") or vecm_fit.beta is None:
-            print(f"{self}: VECM model failed to converge properly")
-
         self.vecm_fit_ = vecm_fit
-        pass
+
+        # Error Correction Term (spread)
+        ect_series = (vecm_df @ vecm_fit.beta).iloc[:, 0]
+
+        # Difference the spread for stationarity
+        dz = ect_series.diff().dropna()
+
+        if len(dz) < 30:
+            print("Not enough data for GARCH fitting.")
+            return
+
+        # Rescale if variance too small
+        if dz.std() < 0.1:
+            dz = dz * 1000
+        # print("Scale check:", dz.std())
+
+        try:
+            garch = arch_model(dz, vol="GARCH", p=1, q=1, mean="Zero", dist="normal")
+            garch_fit = garch.fit(disp="off")
+            self.garch_fit_ = garch_fit
+
+            # Extract parameters
+            params = garch_fit.params
+            self.garch_alpha_ = params.get("alpha[1]", np.nan)
+            self.garch_beta_ = params.get("beta[1]", np.nan)
+            self.garch_persistence_ = self.garch_alpha_ + self.garch_beta_
+
+            # print (f"GARCH α: {self.garch_alpha_:.4f}, β: {self.garch_beta_:.4f}, "
+            #       f"α+β (persistence): {self.garch_persistence_:.4f}")
+
+            # One-step-ahead volatility forecast
+            forecast = garch_fit.forecast(horizon=1)
+            sigma_next = np.sqrt(forecast.variance.iloc[-1, 0])
+            self.sigma_spread_forecast_ = float(sigma_next)
+            # print("GARCH sigma forecast:", self.sigma_spread_forecast_)
+
+            # Rule of thumb: persistence close to 1 or large volatility forecast
+            self.high_volatility_flag_ = int(
+                (self.garch_persistence_ is not None and self.garch_persistence_ > 0.95)
+                or (self.sigma_spread_forecast_ is not None and self.sigma_spread_forecast_ > 2)
+            )
+
+        except Exception as e:
+            print(f"GARCH fit failed: {e}")
+            self.garch_fit_ = None
+            self.sigma_spread_forecast_ = None
+            self.high_volatility_flag_ = None
 
     def predict(self) -> pd.DataFrame:
         self._train_pair()
-
         assert self.testing_df_ is not None
         assert self.vecm_fit_ is not None
+
+        # VECM predictions
         predicted_prices = self.vecm_fit_.predict(steps=len(self.testing_df_))
-
-        # Convert prediction to a DataFrame for readability
-        predicted_df = pd.DataFrame(
-            predicted_prices, columns=pd.Index(self.colnames()), dtype=float
-        )
-
         predicted_df = pd.merge(
             self.testing_df_.reset_index(drop=True),
-            pd.DataFrame(
-                predicted_prices, columns=pd.Index(self.colnames()), dtype=float
-            ),
+            pd.DataFrame(predicted_prices, columns=pd.Index(self.colnames()), dtype=float),
             left_index=True,
             right_index=True,
             suffixes=("", "_pred"),
         ).dropna()
 
+        # Disequilibrium and z-scores
         predicted_df["disequilibrium"] = (
             predicted_df[self.colnames()] @ self.vecm_fit_.beta
         )
-
         predicted_df["signed_scaled_disequilibrium"] = (
             predicted_df["disequilibrium"] - self.training_mu_
         ) / self.training_std_
-
         predicted_df["scaled_disequilibrium"] = abs(
             predicted_df["signed_scaled_disequilibrium"]
         )
 
-        predicted_df = predicted_df.reset_index(drop=True)
+        # Add GARCH parameters + volatility forecast
+        predicted_df["garch_alpha"] = self.garch_alpha_
+        predicted_df["garch_beta"] = self.garch_beta_
+        predicted_df["garch_persistence"] = self.garch_persistence_
+        predicted_df["garch_vol_forecast"] = self.sigma_spread_forecast_
+        predicted_df["high_volatility"] = self.high_volatility_flag_
+
+        # Save results
         if self.pair_predict_result_ is None:
             self.pair_predict_result_ = predicted_df
         else:
             self.pair_predict_result_ = pd.concat(
                 [self.pair_predict_result_, predicted_df], ignore_index=True
             )
-        # Reset index to ensure proper indexing
-        self.pair_predict_result_ = self.pair_predict_result_.reset_index(drop=True)
+
         return self.pair_predict_result_
 
 
@@ -117,6 +188,6 @@ class VECMRollingFit(RollingFit):
         return VECMTradingPair(
             config=config,
             market_data=market_data,
-            symbol_a=symbol_a,
-            symbol_b=symbol_b,
-        )
+            symbol_a = symbol_a,
+            symbol_b = symbol_b,
+        )

lib/pt_trading/z-score_rolling_fit.py

@@ -1,18 +1,28 @@
-from typing import Any, Dict, Optional, cast
+from typing import Any, Dict, Optional
 
 import pandas as pd
-from pt_trading.results import BacktestResult
+import statsmodels.api as sm
+
 from pt_trading.rolling_window_fit import RollingFit
 from pt_trading.trading_pair import TradingPair
-import statsmodels.api as sm
 
 NanoPerMin = 1e9
 
 
 class ZScoreTradingPair(TradingPair):
+    """TradingPair implementation that fits a hedge ratio with OLS and
+    computes a standardized spread (z-score).
+
+    The class stores training spread mean/std and hedge ratio so the model
+    can be applied to testing data consistently.
+    """
+
     zscore_model_: Optional[sm.regression.linear_model.RegressionResultsWrapper]
     pair_predict_result_: Optional[pd.DataFrame]
-    zscore_df_: Optional[pd.DataFrame]
+    zscore_df_: Optional[pd.Series]
+    hedge_ratio_: Optional[float]
+    spread_mean_: Optional[float]
+    spread_std_: Optional[float]
 
     def __init__(
         self,
@@ -25,47 +35,79 @@ class ZScoreTradingPair(TradingPair):
         self.zscore_model_ = None
         self.pair_predict_result_ = None
         self.zscore_df_ = None
+        self.hedge_ratio_ = None
+        self.spread_mean_ = None
+        self.spread_std_ = None
 
     def _fit_zscore(self) -> None:
+        """Fit OLS on the training window and compute training z-score."""
         assert self.training_df_ is not None
-        symbol_a_px_series = self.training_df_[self.colnames()].iloc[:, 0]
-        symbol_b_px_series = self.training_df_[self.colnames()].iloc[:, 1]
 
-        symbol_a_px_series, symbol_b_px_series = symbol_a_px_series.align(
-            symbol_b_px_series, axis=0
-        )
+        # Extract price series for the two symbols from the training frame.
+        px_df = self.training_df_[self.colnames()]
+        symbol_a_px = px_df.iloc[:, 0]
+        symbol_b_px = px_df.iloc[:, 1]
 
-        X = sm.add_constant(symbol_b_px_series)
-        self.zscore_model_ = sm.OLS(symbol_a_px_series, X).fit()
-        assert self.zscore_model_ is not None
-        hedge_ratio = self.zscore_model_.params.iloc[1]
+        # Align indexes and fit OLS: symbol_a ~ const + symbol_b
+        symbol_a_px, symbol_b_px = symbol_a_px.align(symbol_b_px, join="inner")
+        X = sm.add_constant(symbol_b_px)
+        self.zscore_model_ = sm.OLS(symbol_a_px, X).fit()
 
-        # Calculate spread and Z-score
-        spread = symbol_a_px_series - hedge_ratio * symbol_b_px_series
-        self.zscore_df_ = (spread - spread.mean()) / spread.std()
+        # Hedge ratio is the slope on symbol_b
+        params = self.zscore_model_.params
+        self.hedge_ratio_ = float(params.iloc[1]) if len(params) > 1 else 0.0
+
+        # Training spread and its standardized z-score
+        spread = symbol_a_px - self.hedge_ratio_ * symbol_b_px
+        self.spread_mean_ = float(spread.mean())
+        self.spread_std_ = float(spread.std(ddof=0)) if spread.std(ddof=0) != 0 else 1.0
+        self.zscore_df_ = (spread - self.spread_mean_) / self.spread_std_
 
     def predict(self) -> pd.DataFrame:
+        """Apply fitted hedge ratio to the testing frame and return a
+        dataframe with canonical columns:
+          - disequilibrium: signed z-score
+          - scaled_disequilibrium: absolute z-score
+          - signed_scaled_disequilibrium: same as disequilibrium (keeps sign)
+        """
+        # Fit on training window
         self._fit_zscore()
         assert self.zscore_df_ is not None
-        self.training_df_["dis-equilibrium"] = self.zscore_df_
-        self.training_df_["scaled_dis-equilibrium"] = abs(self.zscore_df_)
+        assert self.hedge_ratio_ is not None
+        assert self.spread_mean_ is not None and self.spread_std_ is not None
 
+        # Keep training columns for inspection
+        self.training_df_["disequilibrium"] = self.zscore_df_
+        self.training_df_["scaled_disequilibrium"] = self.zscore_df_.abs()
+
+        # Apply model to testing frame
         assert self.testing_df_ is not None
-        assert self.zscore_df_ is not None
-        predicted_df = self.testing_df_
+        test_df = self.testing_df_.copy()
+        px_test = test_df[self.colnames()]
+        a_test = px_test.iloc[:, 0]
+        b_test = px_test.iloc[:, 1]
+        a_test, b_test = a_test.align(b_test, join="inner")
 
-        predicted_df["disequilibrium"] = self.zscore_df_
-        predicted_df["signed_scaled_disequilibrium"] = self.zscore_df_
-        predicted_df["scaled_disequilibrium"] = abs(self.zscore_df_)
+        # Compute test spread and standardize using training mean/std
+        test_spread = a_test - self.hedge_ratio_ * b_test
+        test_zscore = (test_spread - self.spread_mean_) / self.spread_std_
 
-        predicted_df = predicted_df.reset_index(drop=True)
+        # Attach canonical columns
+        # Align back to test_df index if needed
+        test_zscore = test_zscore.reindex(test_df.index)
+        test_df["disequilibrium"] = test_zscore
+        test_df["signed_scaled_disequilibrium"] = test_zscore
+        test_df["scaled_disequilibrium"] = test_zscore.abs()
+
+        # Reset index and accumulate results across windows
+        test_df = test_df.reset_index(drop=True)
         if self.pair_predict_result_ is None:
-            self.pair_predict_result_ = predicted_df
+            self.pair_predict_result_ = test_df
         else:
             self.pair_predict_result_ = pd.concat(
-                [self.pair_predict_result_, predicted_df], ignore_index=True
+                [self.pair_predict_result_, test_df], ignore_index=True
             )
-        # Reset index to ensure proper indexing
+
         self.pair_predict_result_ = self.pair_predict_result_.reset_index(drop=True)
         return self.pair_predict_result_.dropna()
 
@@ -78,8 +120,5 @@ class ZScoreRollingFit(RollingFit):
         self, config: Dict, market_data: pd.DataFrame, symbol_a: str, symbol_b: str
     ) -> TradingPair:
         return ZScoreTradingPair(
-            config=config,
-            market_data=market_data,
-            symbol_a=symbol_a,
-            symbol_b=symbol_b,
+            config=config, market_data=market_data, symbol_a=symbol_a, symbol_b=symbol_b
         )