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

investing_algorithm_framework/domain/backtesting/backtest_summary_metrics.py

@@ -0,0 +1,162 @@
+import json
+import os
+from dataclasses import dataclass
+from logging import getLogger
+from pathlib import Path
+
+logger = getLogger(__name__)
+
+
+@dataclass
+class BacktestSummaryMetrics:
+    """
+    Represents the summarized results of a backtest,
+    focusing on key headline performance and risk metrics.
+
+    Attributes:
+        total_net_gain (float): Total net gain from the backtest.
+        total_net_gain_percentage (float): Total net gain percentage
+            from the backtest.
+        total_loss (float): Total gross loss from all trades.
+        total_loss_percentage (float): Total gross loss percentage.
+        total_growth (float): Total growth from the backtest.
+        total_growth_percentage (float): Total growth percentage
+            from the backtest.
+        average_net_gain (float): Average returns across multiple backtests.
+        average_net_gain_percentage (float): Average return percentage across
+            multiple backtests.
+        average_growth (float): Average growth across multiple backtests.
+        average_growth_percentage (float): Average growth percentage across
+            multiple backtests.
+        average_loss (float): Average loss across multiple backtests.
+        average_loss_percentage (float): Average loss percentage across
+            multiple backtests.
+        average_trade_return (float): Average return per trade.
+        average_trade_return_percentage (float): Average return percentage
+            per trade.
+        average_trade_loss (float): Total gross loss from all trades.
+        average_trade_loss_percentage (float): Average trade loss percentage.
+        average_trade_gain (float): Average gain from winning trades.
+        average_trade_gain_percentage (float): Average gain percentage
+        cagr (float): Compound annual growth rate of the backtest.
+        sharpe_ratio (float): Sharpe ratio, risk-adjusted return.
+        sortino_ratio (float): Sortino ratio, downside-risk adjusted return.
+        calmar_ratio (float): CAGR relative to max drawdown.
+        profit_factor (float): Total profit / total loss.
+        annual_volatility (float): Annualized volatility of returns.
+        max_drawdown (float): Maximum drawdown observed.
+        max_drawdown_duration (int): Duration of the maximum drawdown.
+        trades_per_year (float): Average trades executed per year.
+        win_rate (float): Percentage of winning trades.
+        current_win_rate (float): Win rate over recent trades.
+        win_loss_ratio (float): Ratio of average win to average loss.
+        current_win_loss_ratio (float): Win/loss ratio over recent trades.
+        number_of_trades (int): Total number of trades executed.
+        cumulative_exposure (float): Total exposure over the backtest period.
+        exposure_ratio (float): Ratio of exposure to available capital.
+    """
+    total_net_gain: float = None
+    total_net_gain_percentage: float = None
+    total_growth: float = None
+    total_growth_percentage: float = None
+    total_loss: float = None
+    total_loss_percentage: float = None
+    average_net_gain: float = None
+    average_net_gain_percentage: float = None
+    average_growth: float = None
+    average_growth_percentage: float = None
+    average_loss: float = None
+    average_loss_percentage: float = None
+    average_trade_return: float = None
+    average_trade_return_percentage: float = None
+    average_trade_loss: float = None
+    average_trade_loss_percentage: float = None
+    average_trade_gain: float = None
+    average_trade_gain_percentage: float = None
+    cagr: float = None
+    sharpe_ratio: float = None
+    sortino_ratio: float = None
+    calmar_ratio: float = None
+    profit_factor: float = None
+    annual_volatility: float = None
+    max_drawdown: float = None
+    max_drawdown_duration: int = None
+    trades_per_year: float = None
+    win_rate: float = None
+    current_win_rate: float = None
+    win_loss_ratio: float = None
+    current_win_loss_ratio: float = None
+    number_of_trades: int = None
+    number_of_trades_closed: int = None
+    cumulative_exposure: float = None
+    exposure_ratio: float = None
+
+    def to_dict(self) -> dict:
+        """
+        Convert the BacktestSummaryMetrics instance to a dictionary.
+        """
+        return {
+            "total_net_gain": self.total_net_gain,
+            "total_net_gain_percentage": self.total_net_gain_percentage,
+            "total_growth": self.total_growth,
+            "total_growth_percentage": self.total_growth_percentage,
+            "total_loss": self.total_loss,
+            "total_loss_percentage": self.total_loss_percentage,
+            "average_loss": self.average_loss,
+            "average_loss_percentage": self.average_loss_percentage,
+            "average_net_gain": self.average_net_gain,
+            "average_net_gain_percentage": self.average_net_gain_percentage,
+            "average_growth": self.average_growth,
+            "average_growth_percentage": self.average_growth_percentage,
+            "average_trade_return": self.average_trade_return,
+            "average_trade_return_percentage":
+                self.average_trade_return_percentage,
+            "average_trade_loss": self.average_trade_loss,
+            "average_trade_loss_percentage":
+                self.average_trade_loss_percentage,
+            "average_trade_gain": self.average_trade_gain,
+            "average_trade_gain_percentage":
+                self.average_trade_gain_percentage,
+            "cagr": self.cagr,
+            "sharpe_ratio": self.sharpe_ratio,
+            "sortino_ratio": self.sortino_ratio,
+            "calmar_ratio": self.calmar_ratio,
+            "profit_factor": self.profit_factor,
+            "annual_volatility": self.annual_volatility,
+            "max_drawdown": self.max_drawdown,
+            "max_drawdown_duration": self.max_drawdown_duration,
+            "trades_per_year": self.trades_per_year,
+            "win_rate": self.win_rate,
+            "current_win_rate": self.current_win_rate,
+            "win_loss_ratio": self.win_loss_ratio,
+            "current_win_loss_ratio": self.current_win_loss_ratio,
+            "number_of_trades": self.number_of_trades,
+            "number_of_trades_closed": self.number_of_trades_closed,
+            "cumulative_exposure": self.cumulative_exposure,
+            "exposure_ratio": self.exposure_ratio,
+        }
+
+    def save(self, file_path: str | Path) -> None:
+        """
+        Save the summary metrics to a JSON file.
+        """
+        with open(file_path, 'w') as file:
+            json.dump(self.to_dict(), file, indent=4, default=str)
+
+    @staticmethod
+    def open(file_path: str | Path) -> 'BacktestSummaryMetrics':
+        """
+        Load summary metrics from a JSON file.
+        """
+        if not os.path.exists(file_path):
+            raise FileNotFoundError(f"Metrics file not found at {file_path}")
+
+        with open(file_path, 'r') as file:
+            data = json.load(file)
+
+        return BacktestSummaryMetrics(**data)
+
+    def __repr__(self):
+        return json.dumps(
+            self.to_dict(), indent=4, sort_keys=True, default=str
+        )

investing_algorithm_framework/domain/backtesting/backtest_utils.py

@@ -0,0 +1,198 @@
+import os
+from logging import getLogger
+from pathlib import Path
+from random import Random
+from typing import List, Union, Callable
+
+from investing_algorithm_framework.domain.exceptions import \
+    OperationalException
+from investing_algorithm_framework.domain.utils.custom_tqdm import tqdm
+
+from .backtest import Backtest
+
+logger = getLogger("investing_algorithm_framework")
+
+
+def save_backtests_to_directory(
+    backtests: List[Backtest],
+    directory_path: Union[str, Path],
+    backtest_date_range=None,
+    dir_name_generation_function: Callable[[Backtest], str] = None,
+    number_of_backtests_to_save: int = None,
+    filter_function: Callable[[Backtest], bool] = None,
+    show_progress: bool = False
+) -> None:
+    """
+    Saves a list of Backtest objects to the specified directory.
+
+    Args:
+        backtests (List[Backtest]): List of Backtest objects to save.
+        directory_path (str): Path to the directory where backtests
+            will be saved.
+        backtest_date_range (BacktestDateRange, optional): Date range
+            to filter backtests before saving. If provided, only backtest runs
+            with this date range will be saved. Defaults to None.
+        dir_name_generation_function (Callable[[Backtest], str], optional):
+            A function that takes a Backtest object as input and returns
+            a string to be used as the directory name for that backtest.
+            If not provided, the backtest's algorithm_id will be used.
+            Defaults to None.
+        number_of_backtests_to_save (int, optional): Maximum number of
+            backtests to save. If None, all backtests will be saved.
+        filter_function (Callable[[Backtest], bool], optional): A function
+            that takes a Backtest object as input and returns True if the
+            backtest should be saved. Defaults to None.
+        show_progress (bool, optional): Whether to display a progress bar
+            while saving backtests. Defaults to False.
+
+    Returns:
+        None
+    """
+
+    if not os.path.exists(directory_path):
+        os.makedirs(directory_path)
+
+    if show_progress:
+        backtests = tqdm(backtests, desc="Saving backtests")
+
+    for backtest in backtests:
+
+        # Check if we have reached the limit of backtests to save
+        if number_of_backtests_to_save is not None:
+            if number_of_backtests_to_save <= 0:
+                break
+
+            number_of_backtests_to_save -= 1
+
+        if filter_function is not None:
+            if not filter_function(backtest):
+                continue
+
+        if dir_name_generation_function is not None:
+            dir_name = dir_name_generation_function(backtest)
+        else:
+
+            if not hasattr(backtest, "algorithm_id"):
+                raise OperationalException(
+                    "algorithm_id is not set in backtest instance,"
+                    "cannot generate directory name automatically, "
+                    "please make sure to set the algorithm_id field "
+                    "in your strategies or provide "
+                    "a dir_name_generation_function."
+                )
+
+            # Check if there is an ID in the backtest metadata
+            dir_name = backtest.algorithm_id
+
+        if dir_name is None:
+            logger.warning(
+                "Backtest algorithm_id is None. "
+                "Generating a random directory name."
+            )
+            dir_name = str(Random().randint(100000, 999999))
+
+        backtest.save(
+            os.path.join(directory_path, dir_name),
+            backtest_date_ranges=[backtest_date_range]
+            if backtest_date_range else None
+        )
+
+
+def load_backtests_from_directory(
+    directory_path: Union[str, Path],
+    filter_function: Callable[[Backtest], bool] = None,
+    number_of_backtests_to_load: int = None,
+    show_progress: bool = False
+) -> List[Backtest]:
+    """
+    Loads Backtest objects from the specified directory.
+
+    Args:
+        directory_path (str): Path to the directory from which backtests
+            will be loaded.
+        filter_function (Callable[[Backtest], bool], optional): A function
+            that takes a Backtest object as input and returns True if the
+            backtest should be included in the result. Defaults to None.
+        number_of_backtests_to_load (int, optional): Maximum number of
+            backtests to load. If None, all backtests will be loaded.
+        show_progress (bool, optional): Whether to display a progress bar
+            while loading backtests. Defaults to False.
+
+    Returns:
+        List[Backtest]: List of loaded Backtest objects.
+    """
+
+    backtests = []
+
+    if not os.path.exists(directory_path):
+        logger.warning(
+            f"Directory {directory_path} does not exist. "
+            "No backtests loaded."
+        )
+        return backtests
+
+    dirs = os.listdir(directory_path)
+
+    if show_progress:
+        dirs = tqdm(dirs, desc="Loading backtests")
+
+    for file_name in dirs:
+
+        # Check if the filename is not the checkpoints.json file or
+        # a python file
+        if file_name == "checkpoints.json" or file_name.endswith(".py"):
+            continue
+
+        # Check if we have reached the limit of backtests to load
+        if number_of_backtests_to_load is not None:
+            if number_of_backtests_to_load <= 0:
+                break
+            number_of_backtests_to_load -= 1
+
+        file_path = os.path.join(directory_path, file_name)
+
+        try:
+
+            # Add step-by-step debugging
+            try:
+                backtest = Backtest.open(file_path)
+            except KeyError as ke:
+                logger.error(
+                    f"KeyError during Backtest.open for {file_path}: {ke}"
+                )
+                import traceback
+                logger.error(
+                    f"Backtest.open KeyError "
+                    f"traceback: {traceback.format_exc()}"
+                )
+                continue  # Skip this backtest and continue with the next one
+            except Exception as be:
+                logger.error(
+                    f"Other error during Backtest.open for {file_path}: {be}"
+                )
+                import traceback
+                logger.error(
+                    f"Backtest.open error traceback: {traceback.format_exc()}"
+                )
+                continue  # Skip this backtest and continue with the next one
+
+            if filter_function is not None:
+                try:
+                    if not filter_function(backtest):
+                        continue
+                except Exception as fe:
+                    logger.error(
+                        f"Error in filter_function for {file_path}: {fe}"
+                    )
+                    continue
+
+            backtests.append(backtest)
+
+        except Exception as e:
+            logger.error(
+                f"Unexpected top-level error loading "
+                f"backtest from {file_path}: {e}"
+            )
+            import traceback
+
+    return backtests