investing-algorithm-framework 7.12.0__tar.gz → 7.14.0__tar.gz

{investing_algorithm_framework-7.12.0 → investing_algorithm_framework-7.14.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: investing-algorithm-framework
-Version: 7.12.0
+Version: 7.14.0
 Summary: A framework for creating trading bots
 Author: MDUYN
 Requires-Python: >=3.10
@@ -212,13 +212,6 @@ class RSIEMACrossoverStrategy(TradingStrategy):
             data_sources=data_sources, time_unit=time_unit, interval=interval
         )
 
-        self.buy_signal_dates = {}
-        self.sell_signal_dates = {}
-
-        for symbol in self.symbols:
-            self.buy_signal_dates[symbol] = []
-            self.sell_signal_dates[symbol] = []
-
     def _prepare_indicators(
         self,
         rsi_data,
@@ -299,13 +292,6 @@ class RSIEMACrossoverStrategy(TradingStrategy):
             buy_signal = rsi_oversold & ema_crossover_lookback
             buy_signals = buy_signal.fillna(False).astype(bool)
             signals[symbol] = buy_signals
-
-            # Get all dates where there is a sell signal
-            buy_signal_dates = buy_signals[buy_signals].index.tolist()
-
-            if buy_signal_dates:
-                self.buy_signal_dates[symbol] += buy_signal_dates
-
         return signals
 
     def generate_sell_signals(self, data: Dict[str, Any]) -> Dict[str, pd.Series]:
@@ -345,13 +331,6 @@ class RSIEMACrossoverStrategy(TradingStrategy):
             sell_signal = rsi_overbought & ema_crossunder_lookback
             sell_signal = sell_signal.fillna(False).astype(bool)
             signals[symbol] = sell_signal
-
-            # Get all dates where there is a sell signal
-            sell_signal_dates = sell_signal[sell_signal].index.tolist()
-
-            if sell_signal_dates:
-                self.sell_signal_dates[symbol] += sell_signal_dates
-
         return signals
 
 

{investing_algorithm_framework-7.12.0 → investing_algorithm_framework-7.14.0}/README.md

@@ -176,13 +176,6 @@ class RSIEMACrossoverStrategy(TradingStrategy):
             data_sources=data_sources, time_unit=time_unit, interval=interval
         )
 
-        self.buy_signal_dates = {}
-        self.sell_signal_dates = {}
-
-        for symbol in self.symbols:
-            self.buy_signal_dates[symbol] = []
-            self.sell_signal_dates[symbol] = []
-
     def _prepare_indicators(
         self,
         rsi_data,
@@ -263,13 +256,6 @@ class RSIEMACrossoverStrategy(TradingStrategy):
             buy_signal = rsi_oversold & ema_crossover_lookback
             buy_signals = buy_signal.fillna(False).astype(bool)
             signals[symbol] = buy_signals
-
-            # Get all dates where there is a sell signal
-            buy_signal_dates = buy_signals[buy_signals].index.tolist()
-
-            if buy_signal_dates:
-                self.buy_signal_dates[symbol] += buy_signal_dates
-
         return signals
 
     def generate_sell_signals(self, data: Dict[str, Any]) -> Dict[str, pd.Series]:
@@ -309,13 +295,6 @@ class RSIEMACrossoverStrategy(TradingStrategy):
             sell_signal = rsi_overbought & ema_crossunder_lookback
             sell_signal = sell_signal.fillna(False).astype(bool)
             signals[symbol] = sell_signal
-
-            # Get all dates where there is a sell signal
-            sell_signal_dates = sell_signal[sell_signal].index.tolist()
-
-            if sell_signal_dates:
-                self.sell_signal_dates[symbol] += sell_signal_dates
-
         return signals
 
 

{investing_algorithm_framework-7.12.0 → investing_algorithm_framework-7.14.0}/investing_algorithm_framework/__init__.py

@@ -16,7 +16,7 @@ from .domain import ApiException, combine_backtests, PositionSize, \
     Trade, SYMBOLS, RESERVED_BALANCES, APP_MODE, AppMode, DATETIME_FORMAT, \
     BacktestDateRange, convert_polars_to_pandas, \
     DEFAULT_LOGGING_CONFIG, DataType, DataProvider, \
-    TradeStatus, TradeRiskType, \
+    TradeStatus, TradeRiskType, generate_backtest_summary_metrics, \
     APPLICATION_DIRECTORY, DataSource, OrderExecutor, PortfolioProvider, \
     SnapshotInterval, AWS_S3_STATE_BUCKET_NAME, BacktestEvaluationFocus
 from .infrastructure import AzureBlobStorageStateHandler, \
@@ -35,14 +35,15 @@ from .services import get_annual_volatility, get_sortino_ratio, \
     get_calmar_ratio, get_trade_frequency, get_yearly_returns, \
     get_monthly_returns, get_best_year, get_best_month, get_worst_year, \
     get_worst_month, get_best_trade, get_worst_trade, \
-    get_average_yearly_return, get_average_gain, get_average_loss, \
-    get_average_monthly_return, get_percentage_winning_months, \
-    get_max_drawdown_duration, get_max_daily_drawdown, get_trades_per_day, \
+    get_average_yearly_return, get_average_trade_gain, \
+    get_average_trade_loss, get_average_monthly_return, \
+    get_percentage_winning_months, get_max_drawdown_duration, \
+    get_max_daily_drawdown, get_trades_per_day, \
     get_trades_per_year, get_average_monthly_return_losing_months, \
     get_average_monthly_return_winning_months, get_percentage_winning_years, \
-    get_rolling_sharpe_ratio, create_backtest_metrics, get_growth, \
-    get_growth_percentage, get_cumulative_exposure, get_median_return, \
-    get_average_return, get_risk_free_rate_us, get_cumulative_return, \
+    get_rolling_sharpe_ratio, create_backtest_metrics, get_total_growth, \
+    get_total_loss, get_cumulative_exposure, get_median_trade_return, \
+    get_average_trade_return, get_risk_free_rate_us, get_cumulative_return, \
     get_cumulative_return_series
 
 
@@ -135,8 +136,8 @@ __all__ = [
     "get_best_trade",
     "get_worst_trade",
     "get_average_yearly_return",
-    "get_average_gain",
-    "get_average_loss",
+    "get_average_trade_gain",
+    "get_average_trade_loss",
     "get_average_monthly_return",
     "get_percentage_winning_months",
     "get_average_trade_duration",
@@ -163,14 +164,15 @@ __all__ = [
     "rank_results",
     "create_weights",
     "get_entry_and_exit_signals",
-    "get_growth",
-    "get_growth_percentage",
     "BacktestEvaluationFocus",
     "combine_backtests",
     "PositionSize",
-    "get_median_return",
-    "get_average_return",
+    "get_median_trade_return",
+    "get_average_trade_return",
     "get_risk_free_rate_us",
     "get_cumulative_return",
     "get_cumulative_return_series",
+    "get_total_loss",
+    "get_total_growth",
+    "generate_backtest_summary_metrics"
 ]

{investing_algorithm_framework-7.12.0 → investing_algorithm_framework-7.14.0}/investing_algorithm_framework/app/analysis/ranking.py

@@ -195,9 +195,9 @@ def combine_backtest_metrics(
         backtest_start_date=start_date,
         backtest_end_date=end_date,
         equity_curve=[],  # leave empty to avoid misleading curves
-        growth=safe_mean([m.growth for m in backtest_metrics]),
-        growth_percentage=safe_mean(
-            [m.growth_percentage for m in backtest_metrics]),
+        total_growth=safe_mean([m.total_growth for m in backtest_metrics]),
+        total_growth_percentage=safe_mean(
+            [m.total_growth_percentage for m in backtest_metrics]),
         total_net_gain=safe_mean([m.total_net_gain for m in backtest_metrics]),
         total_net_gain_percentage=safe_mean(
             [m.total_net_gain_percentage for m in backtest_metrics]),
@@ -228,10 +228,27 @@ def combine_backtest_metrics(
         exposure_ratio=safe_mean(
             [m.exposure_ratio for m in backtest_metrics]
         ),
-        trades_average_gain=safe_mean(
-            [m.trades_average_gain for m in backtest_metrics]),
-        trades_average_loss=safe_mean(
-            [m.trades_average_loss for m in backtest_metrics]),
+        average_trade_gain=safe_mean(
+            [m.average_trade_gain for m in backtest_metrics]),
+        average_trade_gain_percentage=(
+            safe_mean(
+                [m.average_trade_gain_percentage for m in backtest_metrics]
+            )
+        ),
+        average_trade_loss=safe_mean(
+            [m.average_trade_loss for m in backtest_metrics]),
+        average_trade_loss_percentage=(
+            safe_mean(
+                [m.average_trade_loss_percentage for m in backtest_metrics]
+            )
+        ),
+        median_trade_return=safe_mean(
+            [m.median_trade_return for m in backtest_metrics]),
+        median_trade_return_percentage=(
+            safe_mean(
+                [m.median_trade_return_percentage for m in backtest_metrics]
+            )
+        ),
         best_trade=max((
             m.best_trade for m in backtest_metrics if m.best_trade),
             key=lambda t: t.net_gain if t else float('-inf'),

{investing_algorithm_framework-7.12.0 → investing_algorithm_framework-7.14.0}/investing_algorithm_framework/app/app.py

@@ -20,7 +20,7 @@ from investing_algorithm_framework.domain import DATABASE_NAME, TimeUnit, \
     PortfolioConfiguration, SnapshotInterval, DataType, combine_backtests, \
     PortfolioProvider, OrderExecutor, ImproperlyConfigured, \
     DataProvider, INDEX_DATETIME, tqdm, BacktestPermutationTest, \
-    LAST_SNAPSHOT_DATETIME, BACKTESTING_FLAG
+    LAST_SNAPSHOT_DATETIME, BACKTESTING_FLAG, generate_backtest_summary_metrics
 from investing_algorithm_framework.infrastructure import setup_sqlalchemy, \
     create_all_tables, CCXTOrderExecutor, CCXTPortfolioProvider, \
     BacktestOrderExecutor, CCXTOHLCVDataProvider, clear_db, \
@@ -1022,7 +1022,10 @@ class App:
         )
         backtest = Backtest(
             backtest_runs=[run],
-            risk_free_rate=risk_free_rate
+            risk_free_rate=risk_free_rate,
+            backtest_summary=generate_backtest_summary_metrics(
+                [run.backtest_metrics]
+            )
         )
 
         # Add the metadata to the backtest
@@ -1323,9 +1326,7 @@ class App:
         original_datasets_ordered_by_symbol = {}
 
         for data_source in data_sources:
-            print(data_source)
             if DataType.OHLCV.equals(data_source.data_type):
-                print(data_source.symbol)
                 data_provider = data_provider_service.get(data_source)
                 data = data_provider_service.get_data(
                     data_source=data_source,

{investing_algorithm_framework-7.12.0 → investing_algorithm_framework-7.14.0}/investing_algorithm_framework/app/reporting/tables/trade_metrics_table.py

@@ -88,8 +88,8 @@ def create_html_trade_metrics_table(results, report):
         copy_results['Worst Trade'] = f"{worst_trade['net_gain']:.2f} {report.trading_symbol}"
         copy_results['Worst Trade Date'] = safe_format_date(worst_trade['opened_at'], format_str=DEFAULT_DATETIME_FORMAT)
 
-    copy_results['Trades Average Gain'] = f"{safe_format(copy_results['trades_average_gain'], string_format)} {report.trading_symbol} {copy_results['trades_average_gain_percentage']:.2f}%"
-    copy_results['Trades Average Loss'] = f"{safe_format(copy_results['trades_average_loss'], string_format)} {report.trading_symbol} {copy_results['trades_average_loss_percentage']:.2f}%"
+    copy_results['Trades Average Gain'] = f"{safe_format(copy_results['average_trade_gain'], string_format)} {report.trading_symbol} {copy_results['trades_average_gain_percentage']:.2f}%"
+    copy_results['Trades Average Loss'] = f"{safe_format(copy_results['average_trade_loss'], string_format)} {report.trading_symbol} {copy_results['trades_average_loss_percentage']:.2f}%"
     copy_results['Average Trade Duration'] = f"{copy_results['average_trade_duration']:.2f} hours"
     copy_results['Number of Trades'] = f"{copy_results['number_of_trades']}"
     copy_results['Win Rate'] = f"{copy_results['win_rate']:.2f}%"

{investing_algorithm_framework-7.12.0 → investing_algorithm_framework-7.14.0}/investing_algorithm_framework/domain/__init__.py

@@ -35,7 +35,8 @@ from .utils import random_string, append_dict_as_row_to_csv, \
     is_timezone_aware, sync_timezones, get_timezone
 from .backtesting import BacktestRun, BacktestSummaryMetrics, \
     BacktestDateRange, Backtest, BacktestMetrics, combine_backtests, \
-    BacktestPermutationTest, BacktestEvaluationFocus
+    BacktestPermutationTest, BacktestEvaluationFocus, \
+    generate_backtest_summary_metrics
 from .positions import PositionSize
 
 __all__ = [
@@ -141,5 +142,6 @@ __all__ = [
     "DEFAULT_DATETIME_FORMAT",
     "BacktestEvaluationFocus",
     'combine_backtests',
-    'PositionSize'
+    'PositionSize',
+    'generate_backtest_summary_metrics'
 ]

{investing_algorithm_framework-7.12.0 → investing_algorithm_framework-7.14.0}/investing_algorithm_framework/domain/backtesting/__init__.py

@@ -5,7 +5,8 @@ from .backtest_run import BacktestRun
 from .backtest import Backtest
 from .backtest_permutation_test import BacktestPermutationTest
 from .backtest_evaluation_focuss import BacktestEvaluationFocus
-from .combine_backtests import combine_backtests
+from .combine_backtests import combine_backtests, \
+    generate_backtest_summary_metrics
 
 __all__ = [
     "Backtest",
@@ -15,5 +16,6 @@ __all__ = [
     "BacktestRun",
     "BacktestPermutationTest",
     "BacktestEvaluationFocus",
-    "combine_backtests"
+    "combine_backtests",
+    "generate_backtest_summary_metrics"
 ]

{investing_algorithm_framework-7.12.0 → investing_algorithm_framework-7.14.0}/investing_algorithm_framework/domain/backtesting/backtest.py

@@ -57,14 +57,6 @@ class Backtest:
     strategy_ids: List[int] = field(default_factory=list)
     algorithm_id: int = None
 
-    def __post_init__(self):
-        # Create the BacktestSummaryMetrics instance if it doesn't exist
-        if self.backtest_summary is None:
-            self.backtest_summary = BacktestSummaryMetrics()
-
-        for backtest_metrics in self.get_all_backtest_metrics():
-            self.backtest_summary.add(backtest_metrics)
-
     def get_all_backtest_runs(self) -> List[BacktestRun]:
         """
         Retrieve all BacktestRun instances from the backtest.

{investing_algorithm_framework-7.12.0 → investing_algorithm_framework-7.14.0}/investing_algorithm_framework/domain/backtesting/backtest_metrics.py

@@ -23,17 +23,19 @@ class BacktestMetrics:
     Attributes:
         backtest_start_date (datetime): The start date of the backtest.
         backtest_end_date (datetime): The end date of the backtest.
+        final_value (float): The final value of the portfolio at the end
+            of the backtest.
         equity_curve (List[Tuple[datetime, float]]): A list of
             tuples representing  the equity curve, where each tuple
             contains a date and the  corresponding portfolio value.
-        growth (float): The growth of the portfolio over the backtest period.
-        growth_percentage (float): The percentage growth of the portfolio
+        total_growth (float): The growth of the portfolio over the
+            backtest period.
+        total_growth_percentage (float): The percentage growth of the portfolio
             over the backtest period.
-        final_value (float): The final value of the portfolio at the end
-            of the backtest.
         total_net_gain (float): The total return of the backtest.
         total_net_gain_percentage (float): The total return percentage
         total_loss (float): The total loss of the backtest.
+        total_loss_percentage (float): The total loss percentage
         cagr (float): The compound annual growth rate of the backtest.
         sharpe_ratio (float): The Sharpe ratio of the backtest, indicating
             risk-adjusted return.
@@ -68,15 +70,24 @@ class BacktestMetrics:
             average exposure of the portfolio.
         cumulative_exposure (float): The cumulative exposure, indicating the
             total exposure of the portfolio over the backtest period.
-        trades_average_gain (float): The average gain from winning trades.
-        trades_average_gain_percentage (float): The average gain percentage
-            from winning trades.
-        trades_average_loss (float): The average loss from losing trades.
-        trades_average_loss_percentage (float): The average loss percentage
+        average_trade_size (float): The average size of trades executed
+            during the backtest.
+        average_trade_loss (float): The average loss from losing trades.
+        average_trade_loss_percentage (float): The average loss percentage
             from losing trades.
-        trades_average_return (float): The average return from all trades.
-        trades_average_return_percentage (float): The average return
-            percentage from all trades.
+        average_trade_gain (float): The average gain from winning trades.
+        average_trade_gain_percentage (float): The average gain percentage
+            from winning trades.
+        average_trade_return (float): The average return from all trades.
+        average_trade_return_percentage (float): The average return percentage
+            from all trades.
+        median_trade_return (float): The median return from all trades.
+        median_trade_return_percentage (float): The median return percentage
+            from all trades.
+        number_of_positive_trades (int): The total number of profitable trades
+            executed during the backtest.
+        number_of_negative_trades (int): The total number of unprofitable
+            trades executed during the backtest.
         best_trade (float): A string representation of the best trade,
             including net gain and percentage.
         worst_trade (float): A string representation of the worst trade,
@@ -123,10 +134,12 @@ class BacktestMetrics:
     backtest_start_date: datetime
     backtest_end_date: datetime
     equity_curve: List[Tuple[float, datetime]] = field(default_factory=list)
-    growth: float = 0.0
-    growth_percentage: float = 0.0
+    total_growth: float = 0.0
+    total_growth_percentage: float = 0.0
     total_net_gain: float = 0.0
     total_net_gain_percentage: float = 0.0
+    total_loss: float = 0.0
+    total_loss_percentage: float = 0.0
     final_value: float = 0.0
     cumulative_return: float = 0.0
     cumulative_return_series: List[Tuple[float, datetime]] = \
@@ -152,24 +165,28 @@ class BacktestMetrics:
     trade_per_day: float = 0.0
     exposure_ratio: float = 0.0
     cumulative_exposure: float = 0.0
-    trades_average_gain: float = 0.0
-    trades_average_gain_percentage: float = 0.0
-    trades_average_loss: float = 0.0
-    trades_average_loss_percentage: float = 0.0
-    trades_average_return: float = 0.0
-    trades_average_return_percentage: float = 0.0
     best_trade: Trade = None
     worst_trade: Trade = None
+    number_of_positive_trades: int = 0
+    percentage_positive_trades: float = 0.0
+    number_of_negative_trades: int = 0
+    percentage_negative_trades: float = 0.0
     average_trade_duration: float = 0.0
     average_trade_size: float = 0.0
+    average_trade_loss: float = 0.0
+    average_trade_loss_percentage: float = 0.0
+    average_trade_gain: float = 0.0
+    average_trade_gain_percentage: float = 0.0
+    average_trade_return: float = 0.0
+    average_trade_return_percentage: float = 0.0
+    median_trade_return: float = 0.0
+    median_trade_return_percentage: float = 0.0
     number_of_trades: int = 0
     number_of_trades_closed: int = 0
     number_of_trades_opened: int = 0
     number_of_trades_open_at_end: int = 0
     win_rate: float = 0.0
     win_loss_ratio: float = 0.0
-    percentage_positive_trades: float = 0.0
-    percentage_negative_trades: float = 0.0
     percentage_winning_months: float = 0.0
     percentage_winning_years: float = 0.0
     average_monthly_return: float = 0.0
@@ -198,11 +215,13 @@ class BacktestMetrics:
             "backtest_end_date": self.backtest_end_date.isoformat(),
             "equity_curve": [(value, date.isoformat())
                              for value, date in self.equity_curve],
+            "final_value": self.final_value,
             "total_net_gain": self.total_net_gain,
             "total_net_gain_percentage": self.total_net_gain_percentage,
-            "final_value": self.final_value,
-            "growth": self.growth,
-            "growth_percentage": self.growth_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,
             "cumulative_return": self.cumulative_return,
             "cumulative_return_series": [(value, date.isoformat())
                                          for value, date in
@@ -216,8 +235,6 @@ class BacktestMetrics:
             "sortino_ratio": self.sortino_ratio,
             "calmar_ratio": self.calmar_ratio,
             "profit_factor": self.profit_factor,
-            "gross_profit": self.gross_profit,
-            "gross_loss": self.gross_loss,
             "annual_volatility": self.annual_volatility,
             "monthly_returns": [(value, date.isoformat())
                                 for value, date in self.monthly_returns],
@@ -233,15 +250,22 @@ class BacktestMetrics:
             "trade_per_day": self.trade_per_day,
             "exposure_ratio": self.exposure_ratio,
             "cumulative_exposure": self.cumulative_exposure,
-            "trades_average_gain": self.trades_average_gain,
-            "trades_average_gain_percentage":
-                self.trades_average_gain_percentage,
-            "trades_average_loss": self.trades_average_loss,
-            "trades_average_loss_percentage":
-                self.trades_average_loss_percentage,
-            "trades_average_return": self.trades_average_return,
-            "trades_average_return_percentage":
-                self.trades_average_return_percentage,
+            "average_trade_gain": self.average_trade_gain,
+            "average_trade_gain_percentage":
+                self.average_trade_gain_percentage,
+            "average_trade_loss": self.average_trade_loss,
+            "average_trade_loss_percentage":
+                self.average_trade_loss_percentage,
+            "average_trade_return": self.average_trade_return,
+            "average_trade_return_percentage":
+                self.average_trade_return_percentage,
+            "median_trade_return": self.median_trade_return,
+            "median_trade_return_percentage":
+                self.median_trade_return_percentage,
+            "number_of_positive_trades": self.number_of_positive_trades,
+            "percentage_positive_trades": self.percentage_positive_trades,
+            "number_of_negative_trades": self.number_of_negative_trades,
+            "percentage_negative_trades": self.percentage_negative_trades,
             "best_trade": self.best_trade.to_dict()
             if self.best_trade else None,
             "worst_trade": self.worst_trade.to_dict()
@@ -253,8 +277,6 @@ class BacktestMetrics:
             "win_loss_ratio": self.win_loss_ratio,
             "percentage_winning_months": self.percentage_winning_months,
             "percentage_winning_years": self.percentage_winning_years,
-            "percentage_positive_trades": self.percentage_positive_trades,
-            "percentage_negative_trades": self.percentage_negative_trades,
             "average_monthly_return": self.average_monthly_return,
             "average_monthly_return_losing_months":
                 self.average_monthly_return_losing_months,

{investing_algorithm_framework-7.12.0 → investing_algorithm_framework-7.14.0}/investing_algorithm_framework/domain/backtesting/backtest_run.py

@@ -66,13 +66,13 @@ class BacktestRun:
     backtest_start_date: datetime
     backtest_end_date: datetime
     trading_symbol: str
-    initial_unallocated: float
-    number_of_runs: int
-    portfolio_snapshots: List[PortfolioSnapshot]
-    trades: List[Trade]
-    orders: List[Order]
-    positions: List[Position]
-    created_at: datetime
+    initial_unallocated: float = 0.0
+    number_of_runs: int = 0
+    portfolio_snapshots: List[PortfolioSnapshot] = field(default_factory=list)
+    trades: List[Trade] = field(default_factory=list)
+    orders: List[Order] = field(default_factory=list)
+    positions: List[Position] = field(default_factory=list)
+    created_at: datetime = None,
     symbols: List[str] = field(default_factory=list)
     number_of_days: int = 0
     number_of_trades: int = 0

investing_algorithm_framework-7.14.0/investing_algorithm_framework/domain/backtesting/backtest_summary_metrics.py

@@ -0,0 +1,154 @@
+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.
+        win_loss_ratio (float): Ratio of average win to average loss.
+        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
+    win_loss_ratio: float = None
+    number_of_trades: 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,
+            "win_loss_ratio": self.win_loss_ratio,
+            "number_of_trades": self.number_of_trades,
+            "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
+        )