Add linear regression stats of log-equity curve (#21)

* add linear regression stats of log-equity curve

Author: adrianhasse

examples/20241227_introduction.ipynb

@@ -2,6 +2,7 @@
 
 import numpy as np
 import pandas as pd
+from scipy.stats import linregress
 
 from kissbt.broker import Broker
 
@@ -68,6 +69,52 @@ def __init__(
                 self.analysis_df["benchmark"].cummax() - self.analysis_df["benchmark"]
             ) / self.analysis_df["benchmark"].cummax()
 
+    def _equity_curve_stats(
+        self,
+        value_series: pd.Series,
+        *,
+        prefix: str = "",
+    ) -> Dict[str, float]:
+        """
+        Calculate statistics of the equity curve based on the log-equity curve.
+        This method performs a linear regression on the log-equity curve to estimate
+        the slope, standard error, t-statistic, and R² value.
+
+        - slope: The slope of the log-equity curve, indicating the average return per
+            bar.
+        - slope_se: The standard error of the slope, indicating the variability of the
+            average return.
+        - slope_tstat: The t-statistic of the slope, indicating how strongly the data
+            supports the presence of a non-zero trend in the log-equity curve.
+        - r_squared: The R² value of the regression, indicating the proportion of
+            variance explained.
+
+        Parameters:
+            value_series (pd.Series): The series of values to analyze, typically the
+                total value of the portfolio or benchmark.
+            prefix (str): A prefix to add to the keys in the returned dictionary, useful
+                for distinguishing between portfolio and benchmark statistics.
+        """
+
+        if (value_series <= 0).any():
+            raise ValueError(
+                "Value series contains non-positive values, cannot compute log-based statistics"  # noqa: E501
+            )
+        y = np.log(value_series.to_numpy())
+        x = np.arange(y.size, dtype=float)
+
+        res = linregress(x, y)
+        slope, slope_se, r_squared = res.slope, res.stderr, res.rvalue**2
+
+        slope_tstat = slope / slope_se
+
+        return {
+            f"{prefix}slope": slope,
+            f"{prefix}slope_se": slope_se,
+            f"{prefix}slope_tstat": slope_tstat,
+            f"{prefix}r_squared": r_squared,
+        }
+
     def get_performance_metrics(self) -> Dict[str, float]:
         """
         Calculate and return key performance metrics of the trading strategy.
@@ -85,9 +132,26 @@ def get_performance_metrics(self) -> Dict[str, float]:
         - profit_factor: The profit factor of the trading strategy, a ratio of gross
             profits to gross losses.
 
-        If a benchmark is available in the data, the dictionary also includes:
-        - total_benchmark_return: The total return of the benchmark as a decimal.
-        - annual_benchmark_return: The annualized return of the benchmark as a decimal.
+        Additionally we compute the equity curve statistics for the portfolio's
+        total value, including:
+        - slope: The slope of the log-equity curve, indicating the average return per
+            bar.
+        - slope_se: The standard error of the slope, indicating the variability of the
+            average return.
+        - slope_tstat: The t-statistic of the slope (slope / slope_se), indicating how
+            strongly the data supports the presence of a non-zero trend in the
+            log-equity curve. A larger absolute value (positive or negative) provides
+            stronger evidence against H_0 (β = 0), suggesting that the observed trend is
+            unlikely to be due to random fluctuations. For typical backtests the
+            t-statistic approximately follows a standard normal distribution. Values
+            above +1.96 or below -1.96 are considered statistically significant at the
+            95% confidence level.
+        - r_squared: The R² value of the regression, indicating the proportion of
+            variance explained by the model.
+
+        If a benchmark is available in the data, the dictionary also includes the
+        total_return, annual_return, slope, slope_se, slope_tstat and r_squared for the
+        benchmark, prefixed with "benchmark_".
 
         Returns:
             Dict[str, float]: A dictionary containing the calculated performance
@@ -103,14 +167,21 @@ def get_performance_metrics(self) -> Dict[str, float]:
             "win_rate": self._calculate_win_rate(),
             "profit_factor": self._calculate_profit_factor(),
         }
+        metrics.update(self._equity_curve_stats(self.analysis_df["total_value"]))
 
         if "benchmark" in self.analysis_df.columns:
-            metrics["total_benchmark_return"] = self._calculate_total_return(
+            metrics["benchmark_total_return"] = self._calculate_total_return(
                 "benchmark"
             )
-            metrics["annual_benchmark_return"] = self._calculate_annual_return(
+            metrics["benchmark_annual_return"] = self._calculate_annual_return(
                 "benchmark"
             )
+            metrics.update(
+                self._equity_curve_stats(
+                    self.analysis_df["benchmark"],
+                    prefix="benchmark_",
+                )
+            )
 
         return metrics
 

kissbt/analyzer.py

@@ -22,6 +22,7 @@ classifiers = [
 dependencies = [
     "numpy",
     "pandas",
+    "scipy",
     "matplotlib"
 ]
 requires-python = ">=3.10"

pyproject.toml

@@ -0,0 +1,61 @@
+import numpy as np
+import pandas as pd
+import pytest
+from kissbt.analyzer import Analyzer
+from kissbt.broker import Broker
+
+
+def test_constant_growth_benchmark_stats():
+    daily_return = 0.0001
+    num_days = 252
+    start_value = 100000.0
+    values = [start_value * (1 + daily_return) ** i for i in range(num_days)]
+
+    broker = Broker(benchmark="constant_growth")
+    for i, val in enumerate(values):
+        ts = pd.Timestamp("2023-01-01") + pd.Timedelta(days=i)
+        broker.history["timestamp"].append(ts)
+        broker.history["total_value"].append(start_value)
+        broker.history["benchmark"].append(val)
+        broker.history["cash"].append(0)
+        broker.history["long_position_value"].append(0)
+        broker.history["short_position_value"].append(0)
+        broker.history["positions"].append({})
+
+    analyzer = Analyzer(broker)
+    metrics = analyzer.get_performance_metrics()
+
+    assert abs(metrics["benchmark_slope"] - np.log(1 + daily_return)) < 1e-10
+    assert metrics["benchmark_slope_se"] < 1e-10
+    assert metrics["benchmark_slope_tstat"] > 1e5
+    assert metrics["benchmark_r_squared"] > 0.9999
+
+
+def test_portfolio_equity_curve_stats_with_volatility():
+    np.random.seed(42)
+    num_days = 256 * 3
+    start_value = 100000.0
+
+    # Generate portfolio values with some volatility
+    daily_returns = np.random.normal(0.001, 0.02, num_days)
+    portfolio_values = [start_value]
+    for ret in daily_returns:
+        portfolio_values.append(portfolio_values[-1] * (1 + ret))
+
+    broker = Broker()
+    for i, val in enumerate(portfolio_values):
+        ts = pd.Timestamp("2023-01-01") + pd.Timedelta(days=i)
+        broker.history["timestamp"].append(ts)
+        broker.history["total_value"].append(val)
+        broker.history["cash"].append(0)
+        broker.history["long_position_value"].append(val)
+        broker.history["short_position_value"].append(0)
+        broker.history["positions"].append({})
+
+    analyzer = Analyzer(broker)
+    metrics = analyzer.get_performance_metrics()
+
+    assert metrics["slope"] == pytest.approx(0.001, abs=0.0005)
+    assert metrics["slope_se"] > 0
+    assert metrics["slope_tstat"] > 1.96
+    assert 0.5 < metrics["r_squared"] < 0.9

tests/test_analyzer.py

@@ -98,8 +98,8 @@ def test_analyzer_with_golden_cross(tech_stock_data):
     assert pytest.approx(metrics["volatility"], abs=0.01) == 0.24
     assert pytest.approx(metrics["win_rate"], abs=0.01) == 0.47
     assert pytest.approx(metrics["profit_factor"], abs=0.01) == 3.17
-    assert pytest.approx(metrics["total_benchmark_return"], abs=0.01) == 0.29
-    assert pytest.approx(metrics["annual_benchmark_return"], abs=0.01) == 0.09
+    assert pytest.approx(metrics["benchmark_total_return"], abs=0.01) == 0.29
+    assert pytest.approx(metrics["benchmark_annual_return"], abs=0.01) == 0.09
 
     # Ensure running the plot functions does not raise an exception
     analyzer.plot_equity_curve()