Add metrics

Author: MDUYN

investing_algorithm_framework/__init__.py

@@ -31,7 +31,7 @@
     get_drawdown_series, get_max_drawdown, get_cagr, \
     get_standard_deviation_returns, get_standard_deviation_downside_returns, \
     get_max_drawdown_absolute, get_exposure_time, get_average_trade_duration, \
-    get_net_profit
+    get_net_profit, get_win_rate, get_win_loss_ratio, get_calmar_ratio
 
 __all__ = [
     "Algorithm",
@@ -120,4 +120,7 @@
     "get_exposure_time",
     "get_average_trade_duration",
     "get_net_profit",
+    "get_win_rate",
+    "get_win_loss_ratio",
+    "get_calmar_ratio",
 ]

investing_algorithm_framework/metrics/__init__.py

@@ -16,6 +16,8 @@
     get_standard_deviation_returns
 from .net_profit import get_net_profit
 from .exposure import get_exposure_time, get_average_trade_duration
+from .win_rate import get_win_rate, get_win_loss_ratio
+from .calmar_ratio import get_calmar_ratio
 
 __all__ = [
     "get_volatility",
@@ -36,4 +38,7 @@
     "get_net_profit",
     "get_exposure_time",
     "get_average_trade_duration",
+    "get_win_rate",
+    "get_win_loss_ratio",
+    "get_calmar_ratio",
 ]

investing_algorithm_framework/metrics/cagr.py

@@ -45,12 +45,12 @@ def get_cagr(report: BacktestReport) -> float:
 
     # Convert snapshots to DataFrame
     data = [(s.total_value, s.created_at) for s in snapshots]
-    df = pd.DataFrame(data, columns=["net_size", "created_at"])
+    df = pd.DataFrame(data, columns=["total_value", "created_at"])
     df['created_at'] = pd.to_datetime(df['created_at'])
     df = df.sort_values('created_at')
 
-    start_value = df.iloc[0]['net_size']
-    end_value = df.iloc[-1]['net_size']
+    start_value = df.iloc[0]['total_value']
+    end_value = df.iloc[-1]['total_value']
 
     start_date = df.iloc[0]['created_at']
     end_date = df.iloc[-1]['created_at']
@@ -61,7 +61,4 @@ def get_cagr(report: BacktestReport) -> float:
         return 0.0
 
     # CAGR formula
-    cagr = (end_value / start_value) ** (365 / num_days) - 1
-    # Return as percentage
-    cagr = round(cagr * 100, 2)  # Convert to percentage and 2 decimal places
-    return cagr
+    return (end_value / start_value) ** (365 / num_days) - 1

investing_algorithm_framework/metrics/calmar_ratio.py

@@ -0,0 +1,39 @@
+"""
+| **Calmar Ratio** | **Interpretation**                                          |
+| ---------------- | ----------------------------------------------------------- |
+| **> 3.0**        | **Excellent** – strong return vs. drawdown                  |
+| **2.0 – 3.0**    | **Very Good** – solid risk-adjusted performance             |
+| **1.0 – 2.0**    | **Acceptable** – decent, especially for volatile strategies |
+| **< 1.0**        | **Poor** – high drawdowns relative to return                |
+"""
+
+
+from investing_algorithm_framework.domain import BacktestReport
+from .cagr import get_cagr
+from .drawdown import get_max_drawdown
+
+
+def get_calmar_ratio(report: BacktestReport):
+    """
+    Calculate the Calmar Ratio, which is the ratio of the annualized
+    return to the maximum drawdown.
+
+    Formula:
+        Calmar Ratio = CAGR / |Maximum Drawdown|
+
+    The Calmar Ratio is a measure of risk-adjusted return,
+    where a higher ratio indicates a more favorable risk-return profile.
+
+    Args:
+        report: An object that provides methods to get trades and equity curve.
+
+    Returns:
+        float: The Calmar Ratio.
+    """
+    cagr = get_cagr(report)
+    max_drawdown = get_max_drawdown(report)
+
+    if max_drawdown == 0 or max_drawdown is None:
+        return 0.0
+
+    return cagr / max_drawdown

investing_algorithm_framework/metrics/drawdown.py

@@ -79,7 +79,7 @@ def get_max_drawdown(backtest_report: BacktestReport) -> float:
         drawdown_pct = (equity - peak) / peak  # Will be 0 or negative
         max_drawdown_pct = min(max_drawdown_pct, drawdown_pct)
 
-    return max_drawdown_pct * 100.0  # Return as percentage (e.g., -10.0)
+    return abs(max_drawdown_pct)
 
 
 def get_max_drawdown_absolute(backtest_report: BacktestReport) -> float:
@@ -110,4 +110,4 @@ def get_max_drawdown_absolute(backtest_report: BacktestReport) -> float:
         drawdown = peak - equity  # Drop from peak
         max_drawdown = max(max_drawdown, drawdown)
 
-    return max_drawdown
+    return abs(max_drawdown)  # Return as positive number (e.g., €10,000)

investing_algorithm_framework/metrics/exposure.py

@@ -53,3 +53,23 @@ def get_average_trade_duration(report: BacktestReport):
 
     average_trade_duration = total_duration / len(trades)
     return average_trade_duration.total_seconds() / 3600.0  # Convert to hours
+
+
+def get_trade_frequency(report: BacktestReport):
+    """
+    Calculates the trade frequency as the number of trades per day
+    during the backtest period.
+
+    Returns:
+        A float representing the average number of trades per day.
+    """
+    trades = report.get_trades()
+
+    if not trades:
+        return 0.0
+
+    total_days = (report.backtest_end_date - report.backtest_start_date).days + 1
+    if total_days <= 0:
+        return 0.0
+
+    return len(trades) / total_days

investing_algorithm_framework/metrics/win_rate.py

@@ -0,0 +1,81 @@
+"""
+| Metric             | High Value Means...         | Weakness if Used Alone              |
+| ------------------ | --------------------------- | ----------------------------------- |
+| **Win Rate**       | Many trades are profitable  | Doesn't say how big wins/losses are |
+| **Win/Loss Ratio** | Big wins relative to losses | Doesn’t say how *often* you win     |
+
+
+Example of Non-Overlap:
+Strategy A: 90% win rate, but average win is $1, average loss is $10 → not profitable.
+
+Strategy B: 30% win rate, but average win is $300, average loss is $50 → highly profitable.
+"""
+
+from investing_algorithm_framework import BacktestReport, TradeStatus
+
+
+def get_win_rate(backtest_report: BacktestReport) -> float:
+    """
+    Calculate the win rate of the portfolio based on the backtest report.
+
+    Win Rate is defined as the percentage of trades that were profitable.
+    The percentage of trades that are profitable.
+
+    Formula:
+        Win Rate = (Number of Profitable Trades / Total Number of Trades) * 100
+
+    Example: If 60 out of 100 trades are profitable, the win rate is 60%.
+
+    Args:
+        backtest_report (BacktestReport): The backtest report containing
+                                          trade history.
+
+    Returns:
+        float: The win rate as a percentage (e.g., 75.0 for 75% win rate).
+    """
+    return backtest_report.percentage_positive_trades
+
+
+def get_win_loss_ratio(backtest_report: BacktestReport) -> float:
+    """
+    Calculate the win/loss ratio of the portfolio based on the backtest report.
+
+    Win/Loss Ratio is defined as the average profit of winning trades divided by
+    the average loss of losing trades.
+
+    Formula:
+        Win/Loss Ratio = Average Profit of Winning Trades
+            / Average Loss of Losing Trades
+
+    Example: If the average profit of winning trades is $200 and the
+            average loss of losing trades is $100, the win/loss ratio is 2.0.
+
+    Args:
+        backtest_report (BacktestReport): The backtest report containing
+                                          trade history.
+
+    Returns:
+        float: The win/loss ratio.
+    """
+    trades = backtest_report.get_trades(trade_status=TradeStatus.CLOSED)
+
+    if not trades:
+        return 0.0
+
+    # Separate winning and losing trades
+    winning_trades = [t for t in trades if t.net_gain > 0]
+    losing_trades = [t for t in trades if t.net_gain < 0]
+
+    if not winning_trades or not losing_trades:
+        return 0.0
+
+    # Compute averages
+    avg_win = sum(t.net_gain for t in winning_trades) / len(winning_trades)
+    avg_loss = abs(
+        sum(t.net_gain for t in losing_trades) / len(losing_trades))
+
+    # Avoid division by zero
+    if avg_loss == 0:
+        return float('inf')
+
+    return avg_win / avg_loss

tests/metrics/test_cagr.py

@@ -42,7 +42,7 @@ def test_cagr_for_return_less_then_a_year(self):
         report_x = self.create_report(prices, start_date)
 
         cagr = get_cagr(report_x)
-        self.assertAlmostEqual(cagr, 12, delta=1)
+        self.assertAlmostEqual(cagr, 0.12034875793587707, delta=1)
 
     def test_cagr_for_return_exactly_a_year(self):
         """
@@ -63,7 +63,7 @@ def test_cagr_for_return_exactly_a_year(self):
         report_x = self.create_report(prices, start_date)
 
         cagr = get_cagr(report_x)
-        self.assertAlmostEqual(cagr, 12, delta=1)
+        self.assertAlmostEqual(cagr, 0.12034875793587663, delta=1)
 
     def test_cagr_for_return_more_then_a_year(self):
         """
@@ -84,4 +84,4 @@ def test_cagr_for_return_more_then_a_year(self):
         report_x = self.create_report(prices, start_date)
 
         cagr = get_cagr(report_x)
-        self.assertAlmostEqual(cagr, 12, delta=1)
+        self.assertAlmostEqual(cagr, 0.1203487579358764, delta=1)

tests/metrics/test_calmer_ratio.py

@@ -0,0 +1,68 @@
+import unittest
+from datetime import datetime
+from unittest.mock import patch, MagicMock
+from investing_algorithm_framework.domain import BacktestReport
+
+from investing_algorithm_framework import get_calmar_ratio
+
+
+class TestGetCalmarRatio(unittest.TestCase):
+
+    def setUp(self):
+        # Generate mocked equity curve: net_size over time
+        self.timestamps = [
+            datetime(2024, 1, 1),
+            datetime(2024, 1, 2),
+            datetime(2024, 1, 3),
+            datetime(2024, 1, 4),
+            datetime(2024, 1, 5),
+        ]
+
+        self.net_sizes = [1000, 1200, 900, 1100, 1300]  # Simulates rise, fall, recovery, new high
+
+        # Create mock snapshot objects
+        self.snapshots = []
+        for ts, net_size in zip(self.timestamps, self.net_sizes):
+            snapshot = MagicMock()
+            snapshot.created_at = ts
+            snapshot.total_value = net_size
+            self.snapshots.append(snapshot)
+
+        # Create a mocked BacktestReport
+        self.backtest_report = MagicMock()
+        self.backtest_report.get_snapshots.return_value = self.snapshots
+
+    def _create_report(self, total_size_series, timestamps):
+        report = MagicMock(spec=BacktestReport)
+        report.get_snapshots.return_value = [
+            MagicMock(created_at=ts, total_value=size)
+            for ts, size in zip(timestamps, total_size_series)
+        ]
+        return report
+
+    def test_typical_case(self):
+        # Create a report with total sizes for a whole year, with intervals of 31 days.
+        report = self._create_report(
+            [1000, 1200, 900, 1100, 1300],
+            [datetime(2024, i, 1) for i in range(1, 6)]
+        )
+        ratio = get_calmar_ratio(report)
+        self.assertEqual(ratio, 4.8261927891975365)  # Expected ratio based on the mock data
+
+    def test_calmar_ratio_zero_drawdown(self):
+        # Create a report with total sizes for a whole year, with intervals of 31 days, and no drawdowns.
+        report = self._create_report(
+            [1000, 1200, 1300, 1400, 1500, 1600, 1700, 1800, 1900, 2000],
+            [datetime(2024, 1, i) for i in range(1, 11)]
+        )
+        ratio = get_calmar_ratio(report)
+        self.assertEqual(ratio, 0.0)
+
+    def test_calmar_ratio_with_only_drawdown(self):
+        # Create a report with total sizes for a whole year, with intervals of 31 days, and no drawdowns.
+        report = self._create_report(
+            [1000, 900, 800, 700, 600, 500, 400, 300, 200, 100],
+            [datetime(2024, 1, i) for i in range(1, 11)]
+        )
+        ratio = get_calmar_ratio(report)
+        self.assertEqual(ratio, -1.1111111111111112)

tests/metrics/test_drawdowns.py

@@ -49,8 +49,7 @@ def test_drawdown_series(self):
 
     def test_max_drawdown(self):
         max_drawdown = get_max_drawdown(self.backtest_report)
-        print(max_drawdown)
-        expected_max = ((900 - 1200) / 1200) * 100# -0.25
+        expected_max = abs((900 - 1200) / 1200) # 0.25
         self.assertAlmostEqual(max_drawdown, expected_max, places=6)
 
     def test_max_drawdown_absolute(self):

tests/metrics/test_win_rate.py

@@ -0,0 +1,57 @@
+import unittest
+from unittest.mock import MagicMock
+from types import SimpleNamespace
+
+# Assuming your function is defined in a module called strategy_metrics
+from investing_algorithm_framework import get_win_loss_ratio
+
+
+class TestGetWinLossRatio(unittest.TestCase):
+
+    def create_mock_trade(self, net_gain):
+        return SimpleNamespace(net_gain=net_gain)
+
+    def test_mixed_winning_and_losing_trades(self):
+        report = MagicMock()
+        report.get_trades.return_value = [
+            self.create_mock_trade(100),
+            self.create_mock_trade(200),
+            self.create_mock_trade(-50),
+            self.create_mock_trade(-150),
+        ]
+        ratio = get_win_loss_ratio(report)
+        expected_avg_win = (100 + 200) / 2  # 150
+        expected_avg_loss = abs((-50 + -150) / 2)  # 100
+        expected_ratio = expected_avg_win / expected_avg_loss  # 1.5
+        self.assertAlmostEqual(ratio, expected_ratio)
+
+    def test_all_winning_trades(self):
+        report = MagicMock()
+        report.get_trades.return_value = [
+            self.create_mock_trade(100),
+            self.create_mock_trade(300),
+        ]
+        self.assertEqual(get_win_loss_ratio(report), 0.0)
+
+    def test_all_losing_trades(self):
+        report = MagicMock()
+        report.get_trades.return_value = [
+            self.create_mock_trade(-100),
+            self.create_mock_trade(-200),
+        ]
+        self.assertEqual(get_win_loss_ratio(report), 0.0)
+
+    def test_empty_trade_list(self):
+        report = MagicMock()
+        report.get_trades.return_value = []
+        self.assertEqual(get_win_loss_ratio(report), 0.0)
+
+    def test_division_by_zero_loss(self):
+        # Should not happen with realistic data, but test edge case
+        report = MagicMock()
+        report.get_trades.return_value = [
+            self.create_mock_trade(100),
+            self.create_mock_trade(200),
+            self.create_mock_trade(0),  # zero gain/loss
+        ]
+        self.assertEqual(get_win_loss_ratio(report), 0.0)