Fix metrics

Author: MDUYN

investing_algorithm_framework/__init__.py

@@ -31,7 +31,8 @@
     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_win_rate, get_win_loss_ratio, get_calmar_ratio
+    get_net_profit, get_win_rate, get_win_loss_ratio, get_calmar_ratio, \
+    get_trade_frequency
 
 __all__ = [
     "Algorithm",
@@ -123,4 +124,5 @@
     "get_win_rate",
     "get_win_loss_ratio",
     "get_calmar_ratio",
+    "get_trade_frequency",
 ]

investing_algorithm_framework/domain/models/trade/trade.py

@@ -148,6 +148,12 @@ def symbol(self):
 
     @property
     def duration(self):
+        """
+        Calculate the duration of the trade in hours.
+
+        Returns:
+            float: The duration of the trade in hours.
+        """
         if TradeStatus.CLOSED.equals(self.status):
             # Get the total hours between the closed and opened datetime
             diff = self.closed_at - self.opened_at

investing_algorithm_framework/infrastructure/repositories/order_repository.py

@@ -53,6 +53,7 @@ def _apply_query_params(self, db, query, query_params):
                 query = query.filter_by(id=None)
 
         if external_id_query_param:
+            print("Filtering by external_id:", external_id_query_param)
             query = query.filter_by(external_id=external_id_query_param)
 
         if side_query_param:

investing_algorithm_framework/metrics/__init__.py

@@ -15,7 +15,8 @@
 from .standard_deviation import get_standard_deviation_downside_returns, \
     get_standard_deviation_returns
 from .net_profit import get_net_profit
-from .exposure import get_exposure_time, get_average_trade_duration
+from .exposure import get_exposure_time, get_average_trade_duration, \
+    get_trade_frequency
 from .win_rate import get_win_rate, get_win_loss_ratio
 from .calmar_ratio import get_calmar_ratio
 
@@ -41,4 +42,5 @@
     "get_win_rate",
     "get_win_loss_ratio",
     "get_calmar_ratio",
+    "get_trade_frequency",
 ]

investing_algorithm_framework/metrics/cagr.py

@@ -60,5 +60,5 @@ def get_cagr(report: BacktestReport) -> float:
     if num_days == 0 or start_value == 0:
         return 0.0
 
-    # CAGR formula
+    # Apply CAGR formula
     return (end_value / start_value) ** (365 / num_days) - 1

investing_algorithm_framework/metrics/exposure.py

@@ -1,3 +1,11 @@
+"""
+High exposure (>1) means you’re deploying capital aggressively, possibly with many simultaneous positions.
+
+Exposure around 1 means capital is nearly fully invested most of the time, but not overlapping.
+
+Low exposure (<1) means capital is mostly idle or only partially invested.
+"""
+
 from datetime import timedelta
 from investing_algorithm_framework.domain import BacktestReport
 
@@ -18,13 +26,14 @@ def get_exposure_time(report: BacktestReport):
 
     total_trade_duration = timedelta(0)
     for trade in trades:
-        entry = trade.created_at
+        entry = trade.opened_at
         exit = trade.closed_at or report.backtest_end_date  # open trades counted up to end
 
         if exit > entry:
             total_trade_duration += exit - entry
 
     backtest_duration = report.backtest_end_date - report.backtest_start_date
+
     if backtest_duration.total_seconds() == 0:
         return 0.0
 
@@ -44,15 +53,16 @@ def get_average_trade_duration(report: BacktestReport):
     if not trades:
         return 0.0
 
-    total_duration = timedelta(0)
+    total_duration = 0
+
     for trade in trades:
         trade_duration = trade.duration
 
         if trade_duration is not None:
             total_duration += trade_duration
 
     average_trade_duration = total_duration / len(trades)
-    return average_trade_duration.total_seconds() / 3600.0  # Convert to hours
+    return average_trade_duration
 
 
 def get_trade_frequency(report: BacktestReport):

investing_algorithm_framework/metrics/mean_daily_return.py

@@ -0,0 +1,84 @@
+import pandas as pd
+import numpy as np
+
+from .cagr import get_cagr
+
+
+def get_mean_daily_return(report):
+    """
+    Calculate the mean daily return from the total value of the snapshots.
+
+    This function computes the mean daily return based on the list of
+    snapshots in the report. If the snapshots have a granularity of less
+    than a day, the function will resample to daily frequency and compute
+    average daily returns.
+
+    If there is less data then for a year, it will use cagr to
+    calculate the mean daily return.
+
+    Args:
+        report (BacktestReport): The report containing the equity curve.
+
+    Returns:
+        float: The mean daily return.
+    """
+    snapshots = report.get_snapshots()
+
+    if len(snapshots) < 2:
+        return 0.0  # Not enough data
+
+    # Create DataFrame from snapshots
+    data = [(s.created_at, s.total_value) for s in snapshots]
+    df = pd.DataFrame(data, columns=["created_at", "total_value"])
+    df['created_at'] = pd.to_datetime(df['created_at'])
+    df = df.sort_values('created_at').drop_duplicates('created_at')\
+        .set_index('created_at')
+
+    start_date = df.iloc[0].name
+    end_date = df.iloc[-1].name
+
+    # Check if the period is less than a year
+    if (end_date - start_date).days < 365:
+        # Use CAGR to calculate mean daily return
+        cagr = get_cagr(report)
+        if cagr == 0.0:
+            return 0.0
+        return (1 + cagr) ** (1 / 365) - 1
+
+    # Resample to daily frequency using last value of the day
+    daily_df = df.resample('1D').last().dropna()
+
+    # Calculate daily returns
+    daily_df['return'] = daily_df['total_value'].pct_change()
+    daily_df = daily_df.dropna()
+
+    if daily_df.empty:
+        return 0.0
+
+    mean_return = daily_df['return'].mean()
+
+    if np.isnan(mean_return):
+        return 0.0
+
+    return mean_return
+
+
+def get_mean_yearly_return(report, periods_per_year=365):
+    """
+    Calculate the mean yearly return from a backtest report by
+    annualizing the mean daily return.
+
+    Args:
+        report (BacktestReport): The report containing the snapshots.
+        periods_per_year (int): Number of periods in a year (e.g., 365 for daily data).
+
+    Returns:
+        float: The mean yearly return (annualized).
+    """
+    mean_daily_return = get_mean_daily_return(report)
+
+    if mean_daily_return == 0.0:
+        return 0.0
+
+    return (1 + mean_daily_return) ** periods_per_year - 1
+

investing_algorithm_framework/metrics/sharp_ratio.py

@@ -1,9 +1,57 @@
+"""
+The Sharpe Ratio is a widely used risk-adjusted performance metric. It
+measures the excess return per unit of risk (volatility), where risk is
+represented by the standard deviation of returns.
+
+| Sharpe Ratio   | Interpretation                              |
+| -------------- | ------------------------------------------- |
+| **< 0**        | Bad: Underperforms risk-free asset          |
+| **0.0 – 1.0**  | Suboptimal: Returns do not justify risk     |
+| **1.0 – 1.99** | Acceptable: Reasonable risk-adjusted return |
+| **2.0 – 2.99** | Good: Strong risk-adjusted performance      |
+| **3.0+**       | Excellent: Exceptional risk-adjusted return |
+
+Sharpe Ratio is highly sensitive to the volatility estimate: Inconsistent sampling frequency, short backtests, or low trade frequency can distort it.
+
+Different strategies have different risk profiles:
+
+High-frequency strategies may have high Sharpe Ratios (>3).
+
+Trend-following strategies might have lower Sharpe (1–2) but strong CAGR and Calmar.
+
+Use risk-free rate (~4–5% annual currently) if your backtest spans long periods.
+
+### 📌 Practical Notes about the implementation:
+
+- Use **daily returns** for consistent Sharpe Ratio calculation and **annualize** the result using this formula:
+
+
+Sharpe Ratio Formula:
+    Sharpe Ratio = (Mean Daily Return × Periods Per Year - Risk-Free Rate) /
+                   (Standard Deviation of Daily Returns × sqrt(Periods Per Year))
+
+- You can also calculate a **rolling Sharpe Ratio** (e.g., over a 90-day window) to detect changes in performance stability over time.
+
+Mean daily return is either based on the real returns from the backtest or the CAGR, depending on the data duration.
+
+When do we use actual returns vs CAGR?
+
+| Data Duration | Use This Approach                                               | Reason                                                            |
+| ------------- | --------------------------------------------------------------- | ----------------------------------------------------------------- |
+| **< 1 year**  | Use **CAGR** directly and avoid Sharpe Ratio                    | Not enough data to estimate volatility robustly                   |
+| **1–2 years** | Use **CAGR + conservative vol estimate** OR Sharpe with caution | Sharpe may be unstable, consider adding error bars or disclaimers |
+| **> 2 years** | Use **Sharpe Ratio** based on periodic returns                  | Adequate data to reliably estimate risk-adjusted return           |
+
+"""
+
 from typing import Optional
 
+import math
+
 from investing_algorithm_framework.domain.models import BacktestReport
-from .cagr import get_cagr
+from .mean_daily_return import get_mean_daily_return
 from .risk_free_rate import get_risk_free_rate_us
-from .standard_deviation import get_standard_deviation_returns
+from .standard_deviation import get_daily_returns_std
 
 
 def get_sharpe_ratio(
@@ -25,14 +73,15 @@ def get_sharpe_ratio(
     Returns:
         float: The Sharpe Ratio.
     """
-    annualized_return = get_cagr(backtest_report)
-    # Convert annualized return to decimal
-    annualized_return = annualized_return / 100.0
-    standard_deviation_downside = \
-        get_standard_deviation_returns(backtest_report)
+    snapshots = backtest_report.get_snapshots()
+    snapshots = sorted(snapshots, key=lambda s: s.created_at)
+    mean_daily_return = get_mean_daily_return(backtest_report)
+    std_daily_return = get_daily_returns_std(snapshots)
 
     if risk_free_rate is None:
         risk_free_rate = get_risk_free_rate_us()
 
-    # Calculate sharp ratio
-    return (annualized_return - risk_free_rate) / standard_deviation_downside
+    # Formula: Sharpe Ratio = (Mean Daily Return × Periods Per Year - Risk-Free Rate) /
+    # (Standard Deviation of Daily Returns × sqrt(Periods Per Year))
+    return (mean_daily_return * 365 - risk_free_rate) / \
+              (std_daily_return * math.sqrt(365))

investing_algorithm_framework/metrics/sortino_ratio.py

@@ -11,14 +11,21 @@
 | **1 to 2**        | ✅ Acceptable/Good — Reasonable performance for most portfolios       |
 | **2 to 3**        | 💪 Strong — Very good risk-adjusted returns                          |
 | **> 3**           | 🌟 Excellent — Rare, may indicate exceptional strategy or overfitting |
+
+Formula:
+Sortino Ratio = (Mean Daily Return × Periods Per Year - Risk-Free Rate) /
+               (Downside Standard Deviation of Daily Returns × sqrt(Periods Per Year))
+
 """
 
 from typing import Optional
 
+import math
+import numpy as np
 from investing_algorithm_framework.domain import BacktestReport
-from .cagr import get_cagr
+from .mean_daily_return import get_mean_daily_return
 from .risk_free_rate import get_risk_free_rate_us
-from .standard_deviation import get_standard_deviation_downside_returns
+from .standard_deviation import get_downside_std_of_daily_returns
 
 
 def get_sortino_ratio(
@@ -44,22 +51,24 @@ def get_sortino_ratio(
     Returns:
         float: The Sortino Ratio.
     """
-    annualized_return = get_cagr(report)
+    snapshots = report.get_snapshots()
+
+    if not snapshots:
+        return float('inf')
 
-    # Convert annualized return to decimal
-    annualized_return = annualized_return / 100.0
-    standard_deviation_downside = \
-        get_standard_deviation_downside_returns(report)
+    snapshots = sorted(snapshots, key=lambda s: s.created_at)
+    mean_daily_return = get_mean_daily_return(report)
+    std_downside_daily_return = get_downside_std_of_daily_returns(snapshots)
 
     if risk_free_rate is None:
         risk_free_rate = get_risk_free_rate_us()
 
-    if standard_deviation_downside == 0.0:
-        print("returning inf because standard deviation downside is 0")
-        return float("inf")
+    # Formula: Sharpe Ratio = (Mean Daily Return × Periods Per Year - Risk-Free Rate) /
+    # (Standard Deviation of Daily Returns × sqrt(Periods Per Year))
+    ratio = (mean_daily_return * 365 - risk_free_rate) / \
+              (std_downside_daily_return * math.sqrt(365))
 
-    if annualized_return == 0:
-        return 0
+    if np.float64("inf") == ratio or np.float64("-inf") == ratio:
+        return float('inf')
 
-    # Calculate sortino ratio
-    return (annualized_return - risk_free_rate) / standard_deviation_downside
+    return ratio if not np.isnan(ratio) else 0.0