investing-algorithm-framework 6.7.1__tar.gz → 6.8.1__tar.gz

{investing_algorithm_framework-6.7.1 → investing_algorithm_framework-6.8.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: investing-algorithm-framework
-Version: 6.7.1
+Version: 6.8.1
 Summary: A framework for creating trading bots
 Author: MDUYN
 Requires-Python: >=3.10

{investing_algorithm_framework-6.7.1 → investing_algorithm_framework-6.8.1}/investing_algorithm_framework/__init__.py

@@ -31,7 +31,8 @@ from .metrics import get_volatility, get_sortino_ratio, get_profit_factor, \
     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, \
+    get_trade_frequency
 
 __all__ = [
     "Algorithm",
@@ -120,4 +121,8 @@ __all__ = [
     "get_exposure_time",
     "get_average_trade_duration",
     "get_net_profit",
+    "get_win_rate",
+    "get_win_loss_ratio",
+    "get_calmar_ratio",
+    "get_trade_frequency",
 ]

{investing_algorithm_framework-6.7.1 → investing_algorithm_framework-6.8.1}/investing_algorithm_framework/domain/models/trade/trade.py

@@ -148,6 +148,12 @@ class Trade(BaseModel):
 
     @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-6.7.1 → investing_algorithm_framework-6.8.1}/investing_algorithm_framework/infrastructure/repositories/order_repository.py

@@ -53,6 +53,7 @@ class SQLOrderRepository(Repository):
                 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-6.7.1 → investing_algorithm_framework-6.8.1}/investing_algorithm_framework/metrics/__init__.py

@@ -15,7 +15,10 @@ from .cagr import get_cagr
 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
 
 __all__ = [
     "get_volatility",
@@ -36,4 +39,8 @@ __all__ = [
     "get_net_profit",
     "get_exposure_time",
     "get_average_trade_duration",
+    "get_win_rate",
+    "get_win_loss_ratio",
+    "get_calmar_ratio",
+    "get_trade_frequency",
 ]

{investing_algorithm_framework-6.7.1 → investing_algorithm_framework-6.8.1}/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']
@@ -60,8 +60,5 @@ def get_cagr(report: BacktestReport) -> float:
     if num_days == 0 or start_value == 0:
         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
+    # Apply CAGR formula
+    return (end_value / start_value) ** (365 / num_days) - 1

investing_algorithm_framework-6.8.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-6.7.1 → investing_algorithm_framework-6.8.1}/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-6.7.1 → investing_algorithm_framework-6.8.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,7 +53,8 @@ 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
 
@@ -52,4 +62,24 @@ def get_average_trade_duration(report: BacktestReport):
             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):
+    """
+    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-6.8.1/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-6.8.1/investing_algorithm_framework/metrics/sharp_ratio.py

@@ -0,0 +1,87 @@
+"""
+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 .mean_daily_return import get_mean_daily_return
+from .risk_free_rate import get_risk_free_rate_us
+from .standard_deviation import get_daily_returns_std
+
+
+def get_sharpe_ratio(
+    backtest_report: BacktestReport, risk_free_rate: Optional[float] = None,
+) -> float:
+    """
+    Calculate the Sharpe Ratio from a backtest report using daily or
+    weekly returns.
+
+    The Sharpe Ratio is calculated as:
+        (Annualized Return - Risk-Free Rate) / Annualized Std Dev of Returns
+
+    Args:
+        backtest_report: Object with get_trades(trade_status=...) and
+            `number_of_days` attributes.
+        risk_free_rate (float, optional): Annual risk-free rate as a
+            decimal (e.g., 0.047 for 4.7%).
+
+    Returns:
+        float: The Sharpe Ratio.
+    """
+    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()
+
+    # 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-6.7.1 → investing_algorithm_framework-6.8.1}/investing_algorithm_framework/metrics/sortino_ratio.py

@@ -11,14 +11,21 @@ symmetrically distributed.
 | **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

investing_algorithm_framework-6.8.1/investing_algorithm_framework/metrics/standard_deviation.py

@@ -0,0 +1,159 @@
+import numpy as np
+import pandas as pd
+from investing_algorithm_framework.domain import BacktestReport
+
+def get_standard_deviation_downside_returns(report: BacktestReport):
+    """
+    Calculate the standard deviation of downside returns from the net size
+    of the reports.
+
+    Args:
+        report (BacktestReport): The report containing the equity curve.
+
+    Returns:
+        float: The standard deviation of downside returns.
+    """
+    snapshots = report.get_snapshots()
+
+    if len(snapshots) < 2:
+        return 0.0  # Not enough data
+
+    # Create DataFrame of net_size over time
+    data = [(s.total_value, s.created_at) for s in snapshots]
+    df = pd.DataFrame(data, columns=["total_value", "created_at"])
+    df['created_at'] = pd.to_datetime(df['created_at'])
+    df = df.sort_values('created_at').drop_duplicates('created_at').copy()
+
+    # Compute percentage returns
+    df['return'] = df['total_value'].pct_change()
+    df = df.dropna()
+
+    if df.empty:
+        return 0.0
+
+    # Filter downside returns
+    downside_returns = df['return'][df['return'] < 0]
+
+    if downside_returns.empty:
+        return 0.0
+
+    # Compute standard deviation of downside returns
+    downside_std = downside_returns.std(ddof=1)  # ddof=1 for sample std dev
+
+    # Handle edge cases
+    if np.isnan(downside_std):
+        return 0.0
+
+    return downside_std
+
+
+def get_standard_deviation_returns(report: BacktestReport):
+    """
+    Calculate the standard deviation of returns from the net size
+    of the reports.
+
+    Args:
+        report (BacktestReport): The report containing the equity curve.
+
+    Returns:
+        float: The standard deviation of downside returns.
+    """
+    snapshots = report.get_snapshots()
+
+    if len(snapshots) < 2:
+        return 0.0  # Not enough data
+
+    # Create DataFrame of net_size over time
+    data = [(s.total_value, s.created_at) for s in snapshots]
+    df = pd.DataFrame(data, columns=["total_value", "created_at"])
+    df['created_at'] = pd.to_datetime(df['created_at'])
+    df = df.sort_values('created_at').drop_duplicates('created_at').copy()
+
+    # Compute percentage returns
+    df['return'] = df['total_value'].pct_change()
+    df = df.dropna()
+
+    if df.empty:
+        return 0.0
+
+    # Filter downside returns
+    df_returns = df['return']
+
+    if df_returns.empty:
+        return 0.0
+
+    std = df_returns.std(ddof=1)  # ddof=1 for sample std dev
+
+    # Handle edge cases
+    if np.isnan(std):
+        return 0.0
+
+    return std
+
+def get_daily_returns_std(snapshots):
+    """
+    Calculate the standard deviation of daily returns from a list of snapshots.
+    Resamples data to daily frequency using end-of-day values.
+
+    Args:
+        snapshots (List[PortfolioSnapshot]): Snapshots with total_value and created_at.
+
+    Returns:
+        float: Standard deviation of daily returns.
+    """
+    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.drop_duplicates("created_at").set_index("created_at")
+    df = df.sort_index()
+
+    # Resample to daily frequency (end of day)
+    daily_df = df.resample("D").last().dropna()
+
+    # Calculate daily returns
+    daily_df["return"] = daily_df["total_value"].pct_change().dropna()
+
+    if daily_df["return"].empty:
+        return 0.0
+
+    return daily_df["return"].std()
+
+
+def get_downside_std_of_daily_returns(snapshots):
+    """
+    Calculate the downside standard deviation of daily returns from a list of snapshots.
+    Resamples data to daily frequency using end-of-day values.
+
+    Args:
+        snapshots (List[PortfolioSnapshot]): Snapshots with total_value and created_at.
+
+    Returns:
+        float: Downside standard deviation of daily returns.
+    """
+    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.drop_duplicates("created_at").set_index("created_at")
+    df = df.sort_index()
+
+    # Resample to daily frequency (end of day)
+    daily_df = df.resample("D").last().dropna()
+
+    # Calculate daily returns
+    daily_df["return"] = daily_df["total_value"].pct_change().dropna()
+
+    # Filter only negative returns for downside deviation
+    negative_returns = daily_df["return"][daily_df["return"] < 0]
+
+    if negative_returns.empty:
+        return 0.0
+
+    return negative_returns.std()