investing-algorithm-framework 1.5__py3-none-any.whl → 7.25.6__py3-none-any.whl

investing_algorithm_framework/services/metrics/price_efficiency.py

@@ -0,0 +1,57 @@
+import logging
+from pandas import DataFrame, DatetimeIndex
+from investing_algorithm_framework.domain.exceptions import \
+    OperationalException
+
+logger = logging.getLogger(__name__)
+
+
+def get_price_efficiency_ratio(data: DataFrame):
+    """
+    Calculate the price efficiency ratio (noise) for each symbol.
+
+    The price efficiency ratio is calculated as follows:
+
+    1. Calculate the net price change over the period
+    2. Calculate the sum of absolute daily price changes
+    3. Calculate Efficiency Ratio = Net Price Change / Sum of Absolute
+    Daily Price Changes
+
+    The price efficiency ratio is a measure of the efficiency of the
+    price movement over the period. A higher efficiency ratio indicates
+    a more efficient price movement.
+
+    Args:
+        data (dict): A pandas DataFrame containing a column with either a
+        'Close' or 'Price' label and a datetime index.
+
+    returns:
+        float: The price efficiency ratio
+    """
+
+    # Check if close value and index is a datetime object
+    if 'Close' not in data.columns:
+        raise OperationalException(
+            "Close column not found in data, "
+            "required for price efficiency ratio calculation"
+        )
+
+    if not isinstance(data.index, DatetimeIndex):
+        raise OperationalException(
+            "Index is not a datetime object,"
+            "required for price efficiency ratio calculation"
+        )
+
+    # Calculate daily price changes
+    data['Daily Change'] = data['Close'].diff()
+
+    # Calculate net price change over the period
+    net_price_change = abs(
+        data['Close'].iloc[-1] - data['Close'].iloc[0])
+
+    # Calculate the sum of absolute daily price changes
+    sum_absolute_changes = data['Daily Change'] \
+        .abs().sum()
+
+    # Calculate Efficiency Ratio
+    return net_price_change / sum_absolute_changes

investing_algorithm_framework/services/metrics/profit_factor.py

@@ -0,0 +1,165 @@
+"""
+Module for calculating profit factor metrics from backtest trades.
+
+| **Profit Factor** | **Interpretation**                                                                        |
+| ----------------- | ----------------------------------------------------------------------------------------- |
+| **< 1.0**         | **Losing strategy** — losses outweigh profits                                             |
+| **1.0 – 1.3**     | Weak or barely breakeven — needs improvement or may not be sustainable                    |
+| **1.3 – 1.6**     | Average — possibly profitable but sensitive to market regime changes                      |
+| **1.6 – 2.0**     | Good — generally indicates a solid, sustainable edge                                      |
+| **2.0 – 3.0**     | Very good — strong edge with lower drawdown risk                                          |
+| **> 3.0**         | Excellent — rare in real markets; often associated with low-frequency or niche strategies |
+
+"""
+
+from collections import deque
+from datetime import datetime
+from typing import List, Tuple
+
+from investing_algorithm_framework.domain.models import Trade
+
+
+def get_cumulative_profit_factor_series(
+    trades: List[Trade]
+) -> list[tuple[datetime, float]]:
+    """
+    Calculates the cumulative profit factor over time from a backtest report.
+
+    Args:
+        trades (List[Trade]): List of closed trades from the backtest report.
+
+    Returns:
+        List of (datetime, float) tuples: (timestamp, cumulative profit factor)
+    """
+    results = []
+    gross_profit = 0.0
+    gross_loss = 0.0
+
+    for trade in trades:
+        close_time = trade.closed_at
+        profit = trade.net_gain
+
+        if profit >= 0:
+            gross_profit += profit
+        else:
+            gross_loss += abs(profit)
+
+        # Calculate profit factor with division-by-zero protection
+        if gross_loss > 0:
+            profit_factor = gross_profit / gross_loss
+        else:
+            profit_factor = float('inf') if gross_profit > 0 else 0.0
+
+        results.append((close_time, profit_factor))
+
+    return results
+
+
+def get_rolling_profit_factor_series(
+    trades: List[Trade], window_size: int = 20
+) -> List[Tuple[datetime, float]]:
+    """
+    Calculates the rolling profit factor over time from a backtest report.
+
+    The rolling profit factor is computed using the most recent
+    `window_size` trades and updated after each closed trade.
+
+    Args:
+        backtest_report (BacktestReport): A instance of BacktestReport
+            containing closed trades.
+        window_size: The number of most recent trades to include in
+            each rolling calculation.
+
+    Returns:
+        A list of tuples, where each tuple contains:
+            - datetime: The close time of the trade (or aligned date).
+            - float: The rolling profit factor at that time.
+    """
+
+    results = []
+    trade_window = deque(maxlen=window_size)
+
+    for trade in trades:
+        close_time = trade.closed_at
+        profit = trade.net_gain
+
+        trade_window.append(profit)
+
+        gross_profit = sum(p for p in trade_window if p >= 0)
+        gross_loss = sum(abs(p) for p in trade_window if p < 0)
+
+        if gross_loss > 0:
+            profit_factor = gross_profit / gross_loss
+        else:
+            profit_factor = float('inf') if gross_profit > 0 else 0.0
+
+        results.append((close_time, profit_factor))
+
+    return results
+
+
+def get_profit_factor(trades: List[Trade]) -> float:
+    """
+    Calculates the total profit factor at the end of the backtest.
+
+    The profit factor is defined as:
+        Total Gross Profit / Total Gross Loss
+
+    Args:
+        trades (List[Trade]): List of closed trades from the backtest report.
+
+    Returns:
+        float: The profit factor at the end of the backtest.
+               Returns float('inf') if there are no losses,
+               and 0.0 if there are no profits and losses.
+    """
+    gross_profit = 0.0
+    gross_loss = 0.0
+
+    for trade in trades:
+        profit = trade.net_gain
+        if profit > 0:
+            gross_profit += profit
+        elif profit < 0:
+            gross_loss += abs(profit)
+
+    if gross_loss == 0:
+        return float('inf') if gross_profit > 0 else 0.0
+
+    return gross_profit / gross_loss
+
+
+def get_gross_profit(trades: List[Trade]) -> float:
+    """
+    Function to calculate the total gross profit from a list of trades.
+
+    Args:
+        trades (List[Trade]): List of closed trades from the backtest report.
+
+    Returns:
+        float: The total gross profit from the trades.
+    """
+
+    gross_profit = 0.0
+    for trade in trades:
+        if trade.net_gain > 0:
+            gross_profit += trade.net_gain
+    return gross_profit
+
+
+def get_gross_loss(trades: List[Trade]) -> float:
+    """
+    Function to calculate the total gross loss from a list of trades.
+
+    Args:
+        trades (List[Trade]): List of closed trades from the backtest report.
+
+    Returns:
+        float: The total gross loss from the trades.
+    """
+
+    gross_loss = 0.0
+    for trade in trades:
+        if trade.net_gain < 0:
+            gross_loss += abs(trade.net_gain)
+    return gross_loss

investing_algorithm_framework/services/metrics/recovery.py

@@ -0,0 +1,113 @@
+"""
+🔍 What is Recovery Factor:
+Recovery Factor =
+🔹 Total Net Profit (how much you made overall)
+➗
+🔹 Max Drawdown (worst capital drop at any point)
+
+This metric answers:
+
+💡 "How much return did I get per unit of worst-case risk?"
+
+🎯 Why this matters:
+Even if a strategy has many small drawdowns, only the worst one is used.
+
+A strategy that earns €100k total, but once dropped €50k from peak, has a
+recovery factor of 2.0 — suggesting that it made 2x the worst pain it endured.
+
+✅ Pros:
+Simple and interpretable.
+
+Useful when comparing strategies with very different drawdown profiles.
+
+⚠️ Limitations:
+It ignores the frequency or duration of drawdowns.
+
+It can be misleading if net profit is inflated due to one lucky trend or
+max drawdown happened early and was never tested again.
+
+| **Recovery Factor** | **Interpretation**                                   | **Comments**                                                     |
+| ------------------- | ---------------------------------------------------- | ---------------------------------------------------------------- |
+| **< 1.0**           | ❌ *Poor* – Risk outweighs reward                     | Losing more in drawdowns than you're making overall              |
+| **1.0 – 1.5**       | ⚠️ *Weak* – Barely recovering from drawdowns         | Net profit is only slightly higher than worst drawdown           |
+| **1.5 – 2.0**       | 🤔 *Moderate* – Acceptable, but not robust           | Strategy is viable but may lack strong risk-adjusted performance |
+| **2.0 – 3.0**       | ✅ *Good* – Solid recovery from worst drawdowns       | Indicates decent resilience and profitability                    |
+| **3.0 – 5.0**       | 🚀 *Very Good* – Strong risk-adjusted performance    | Shows good ability to recover and generate consistent profit     |
+| **> 5.0**           | 🏆 *Excellent* – Exceptional recovery vs. risk taken | Often seen in highly optimized or low-volatility strategies      |
+| **∞ (Infinity)**    | 💡 *No drawdown* – Unrealistic or incomplete data    | Can happen if drawdown is zero — investigate carefully           |
+"""
+from typing import List
+
+from investing_algorithm_framework.domain import PortfolioSnapshot
+from .drawdown import get_max_drawdown_absolute
+from .returns import get_total_return
+
+
+def get_recovery_factor(snapshots: List[PortfolioSnapshot]) -> float:
+    """
+    Calculate the recovery factor of a backtest report.
+
+    The recovery factor is defined as:
+        Recovery Factor = Total Net Profit / Maximum Drawdown
+
+    This metric indicates how efficiently a trading strategy recovers
+    from drawdowns. A higher recovery factor implies better
+    risk-adjusted performance.
+
+    Args:
+        snapshots (List[PortfolioSnapshot]): List of portfolio snapshots
+            from the backtest report.
+
+    Returns:
+        float: The recovery factor. Returns 0.0 if max drawdown is
+            zero or undefined.
+    """
+
+    if not snapshots:
+        return 0.0
+
+    max_drawdown_absolute = get_max_drawdown_absolute(snapshots)
+    net_profit, _ = get_total_return(snapshots)
+
+    if max_drawdown_absolute == 0:
+        return float('inf') if net_profit > 0 else 0.0
+
+    return net_profit / max_drawdown_absolute
+
+
+def get_recovery_time(snapshots: List[PortfolioSnapshot]) -> float:
+    """
+    Calculate the recovery time of a backtest report.
+
+    The recovery time is defined as the number of days it takes to recover
+    from the maximum drawdown.
+
+    Args:
+        snapshots (List[PortfolioSnapshot]): List of portfolio snapshots
+            from the backtest report.
+
+    Returns:
+        float: The recovery time in days. Returns 0.0 if no drawdown
+            occurred.
+    """
+
+    if not snapshots:
+        return 0.0
+
+    max_drawdown_absolute = get_max_drawdown_absolute(snapshots)
+
+    if max_drawdown_absolute == 0:
+        return 0.0
+
+    # Find the first snapshot after the maximum drawdown
+    first_snapshot_after_drawdown = next(
+        (s for s in snapshots if s.net_size >= max_drawdown_absolute), None)
+
+    if not first_snapshot_after_drawdown:
+        return 0.0
+
+    # Calculate recovery time in days
+    recovery_time = (first_snapshot_after_drawdown.created_at -
+                     snapshots[0].created_at).days
+
+    return recovery_time if recovery_time > 0 else 1.0