investing-algorithm-framework 7.0.3__tar.gz → 7.2.0__tar.gz

{investing_algorithm_framework-7.0.3 → investing_algorithm_framework-7.2.0}/PKG-INFO

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

{investing_algorithm_framework-7.0.3 → investing_algorithm_framework-7.2.0}/investing_algorithm_framework/__init__.py

@@ -5,7 +5,7 @@ from .app import App, Algorithm, \
     pretty_print_orders, pretty_print_backtest, select_backtest_date_ranges, \
     get_equity_curve_with_drawdown_chart, \
     get_rolling_sharpe_ratio_chart, rank_results, \
-    get_monthly_returns_heatmap_chart, defaults_ranking_weights, \
+    get_monthly_returns_heatmap_chart, create_weights, \
     get_yearly_returns_bar_chart, get_entry_and_exit_signals, \
     get_ohlcv_data_completeness_chart
 from .domain import ApiException, \
@@ -159,7 +159,7 @@ __all__ = [
     "get_yearly_returns_bar_chart",
     "get_ohlcv_data_completeness_chart",
     "rank_results",
-    "defaults_ranking_weights",
+    "create_weights",
     "get_entry_and_exit_signals",
     "get_growth",
     "get_growth_percentage"

{investing_algorithm_framework-7.0.3 → investing_algorithm_framework-7.2.0}/investing_algorithm_framework/app/__init__.py

@@ -14,7 +14,7 @@ from .reporting import add_html_report, \
     get_yearly_returns_bar_chart, \
     get_ohlcv_data_completeness_chart, get_entry_and_exit_signals
 from .analysis import select_backtest_date_ranges, rank_results, \
-    defaults_ranking_weights
+    create_weights
 
 
 __all__ = [
@@ -39,6 +39,6 @@ __all__ = [
     "get_yearly_returns_bar_chart",
     "get_ohlcv_data_completeness_chart",
     "rank_results",
-    "defaults_ranking_weights",
+    "create_weights",
     "get_entry_and_exit_signals"
 ]

{investing_algorithm_framework-7.0.3 → investing_algorithm_framework-7.2.0}/investing_algorithm_framework/app/algorithm/algorithm.py

@@ -33,7 +33,8 @@ class Algorithm:
         strategies=None,
         tasks: List = None,
         data_sources: List[DataSource] = None,
-        on_strategy_run_hooks=None
+        on_strategy_run_hooks=None,
+        metadata=None
     ):
         self._name = name
         self._context = {}
@@ -46,6 +47,7 @@ class Algorithm:
         self._tasks = []
         self._data_sources = []
         self._on_strategy_run_hooks = []
+        self.metadata = metadata
 
         if data_sources is not None:
             self._data_sources = data_sources

{investing_algorithm_framework-7.0.3 → investing_algorithm_framework-7.2.0}/investing_algorithm_framework/app/analysis/__init__.py

@@ -1,8 +1,8 @@
 from .backtest_data_ranges import select_backtest_date_ranges
-from .ranking import rank_results, defaults_ranking_weights
+from .ranking import rank_results, create_weights
 
 __all__ = [
     "select_backtest_date_ranges",
     "rank_results",
-    "defaults_ranking_weights"
+    "create_weights"
 ]

investing_algorithm_framework-7.2.0/investing_algorithm_framework/app/analysis/ranking.py

@@ -0,0 +1,178 @@
+default_weights = {
+    # Profitability
+    "total_net_gain": 3.0,
+    "total_net_loss": 0.0,
+    "total_return": 0.0,
+    "avg_return_per_trade": 0.0,
+
+    # Risk-adjusted returns
+    "sharpe_ratio": 1.0,
+    "sortino_ratio": 1.0,
+    "profit_factor": 1.0,
+
+    # Risk
+    "max_drawdown": -2.0,
+    "max_drawdown_duration": -0.5,
+
+    # Trading activity
+    "number_of_trades": 2.0,
+    "win_rate": 3.0,
+
+    # Exposure
+    "exposure_factor": 0.5,
+    "exposure_ratio": 0.0,
+    "exposure_time": 0.0,
+}
+
+
+def normalize(value, min_val, max_val):
+    """
+    Normalize a value to a range [0, 1].
+
+    Args:
+        value (float): The value to normalize.
+        min_val (float): The minimum value of the range.
+        max_val (float): The maximum value of the range.
+
+    Returns:
+        float: The normalized value.
+    """
+    if max_val == min_val:
+        return 0
+    return (value - min_val) / (max_val - min_val)
+
+
+def compute_score(metrics, weights, ranges):
+    """
+    Compute a weighted score for the given metrics.
+
+    Args:
+        metrics: The metrics to evaluate.
+        weights: The weights to apply to each metric.
+        ranges: The min/max ranges for each metric.
+
+    Returns:
+        float: The computed score.
+    """
+    score = 0
+    for key, weight in weights.items():
+
+        if not hasattr(metrics, key):
+            continue
+        value = getattr(metrics, key)
+
+        if key in ranges:
+            value = normalize(value, ranges[key][0], ranges[key][1])
+        score += weight * value
+    return score
+
+
+def create_weights(
+    focus: str = "balanced",
+    gain: float = 3.0,
+    win_rate: float = 3.0,
+    trades: float = 2.0,
+    custom_weights: dict | None = None,
+) -> dict:
+    """
+    Utility to generate weights dicts for ranking backtests.
+
+    This function does not assign weights to every possible performance
+    metric. Instead, it focuses on a curated subset of commonly relevant
+    ones (profitability, win rate, trade frequency, and risk-adjusted returns).
+    The rationale is to avoid overfitting ranking logic to noisy or redundant
+    statistics (e.g., monthly return breakdowns, best/worst trade), while
+    keeping the weighting system simple and interpretable.
+    Users who need fine-grained control can pass `custom_weights` to fully
+    override defaults.
+
+    Args:
+        focus (str): One of [
+            "balanced", "profit", "frequency", "risk_adjusted"
+        ].
+        gain (float): Weight for total_net_gain (default only).
+        win_rate (float): Weight for win_rate (default only).
+        trades (float): Weight for number_of_trades (default only).
+        custom_weights (dict): Full override for weights (all metrics).
+                               If provided, it takes precedence over presets.
+
+    Returns:
+        dict: A dictionary of weights for ranking backtests.
+    """
+
+    # default / balanced
+    base = {
+        "total_net_gain": gain,
+        "win_rate": win_rate,
+        "number_of_trades": trades,
+        "sharpe_ratio": 1.0,
+        "sortino_ratio": 1.0,
+        "profit_factor": 1.0,
+        "max_drawdown": -2.0,
+        "max_drawdown_duration": -0.5,
+        "total_net_loss": 0.0,
+        "total_return": 0.0,
+        "avg_return_per_trade": 0.0,
+        "exposure_factor": 0.5,
+        "exposure_ratio": 0.0,
+        "exposure_time": 0.0,
+    }
+
+    # apply presets
+    if focus == "profit":
+        base.update({
+            "total_net_gain": 5.0,
+            "win_rate": 2.0,
+            "number_of_trades": 1.0,
+        })
+    elif focus == "frequency":
+        base.update({
+            "number_of_trades": 4.0,
+            "win_rate": 2.0,
+            "total_net_gain": 2.0,
+        })
+    elif focus == "risk_adjusted":
+        base.update({
+            "sharpe_ratio": 3.0,
+            "sortino_ratio": 3.0,
+            "max_drawdown": -3.0,
+        })
+
+    # if full custom dict is given → override everything
+    if custom_weights is not None:
+        base = {**base, **custom_weights}
+
+    return base
+
+
+def rank_results(backtests, focus=None, weights=None):
+    """
+    Rank backtest results based on specified focus and weights.
+    Args:
+        backtests (list): List of backtest results to rank.
+        focus (str, optional): Focus for ranking. If None,
+            uses default weights. Options: "balanced", "profit",
+            "frequency", "risk_adjusted".
+        weights (dict, optional): Custom weights for ranking metrics.
+            If None, uses default weights based on focus.
+
+    Returns:
+        list: Sorted list of backtests based on computed scores.
+    """
+
+    if weights is None:
+        weights = create_weights(focus=focus)
+
+    # First compute metric ranges for normalization
+    ranges = {}
+    for key in weights:
+        values = [getattr(bt.backtest_metrics, key, None) for bt in backtests]
+        values = [v for v in values if isinstance(v, (int, float))]
+        if values:
+            ranges[key] = (min(values), max(values))
+
+    return sorted(
+        backtests,
+        key=lambda bt: compute_score(bt.backtest_metrics, weights, ranges),
+        reverse=True
+    )

{investing_algorithm_framework-7.0.3 → investing_algorithm_framework-7.2.0}/investing_algorithm_framework/app/app.py

@@ -381,6 +381,10 @@ class App:
             None
         """
         logger.info("Initializing data sources")
+
+        if data_sources is None or len(data_sources) == 0:
+            return
+
         data_provider_service = self.container.data_provider_service()
         data_provider_service.reset()
 
@@ -415,6 +419,10 @@ class App:
             None
         """
         logger.info("Initializing data sources for backtest")
+
+        if data_sources is None or len(data_sources) == 0:
+            return
+
         data_provider_service = self.container.data_provider_service()
         data_provider_service.reset()
 
@@ -890,7 +898,16 @@ class App:
             risk_free_rate=risk_free_rate,
         )
 
-        backtest.metadata = metadata if metadata is not None else {}
+        # Add the metadata to the backtest
+        if metadata is None:
+
+            if algorithm.metadata is not None:
+                backtest.metadata = algorithm.metadata
+            else:
+                backtest.metadata = {}
+        else:
+            backtest.metadata = metadata
+
         self.cleanup_backtest_resources()
 
         if save and directory:
@@ -900,18 +917,102 @@ class App:
 
         return backtest
 
+    def run_vector_backtests(
+        self,
+        backtest_date_range: BacktestDateRange,
+        initial_amount,
+        strategies: List[TradingStrategy],
+        snapshot_interval: SnapshotInterval = SnapshotInterval.DAILY,
+        risk_free_rate: Optional[float] = None,
+        skip_data_sources_initialization: bool = False
+    ):
+        """
+        Run vectorized backtests for a set of strategies. The provided
+        set of strategies need to have their 'buy_signal_vectorized' and
+        'sell_signal_vectorized' methods implemented to support vectorized
+        backtesting.
+
+        Args:
+            backtest_date_range: The date range to run the backtest for
+                (instance of BacktestDateRange)
+            initial_amount: The initial amount to start the backtest with.
+                This will be the amount of trading currency that the backtest
+                portfolio will start with.
+            strategies (List[TradingStrategy]): List of strategy objects
+                that need to be backtested. Each strategy should implement
+                the 'buy_signal_vectorized' and 'sell_signal_vectorized'
+                methods to support vectorized backtesting.
+            snapshot_interval (SnapshotInterval): The snapshot
+                interval to use for the backtest. This is used to determine
+                how often the portfolio snapshot should be taken during the
+                backtest. The default is TRADE_CLOSE, which means that the
+                portfolio snapshot will be taken at the end of each trade.
+            risk_free_rate (Optional[float]): The risk-free rate to use for
+                the backtest. This is used to calculate the Sharpe ratio
+                and other performance metrics. If not provided, the default
+                risk-free rate will be tried to be fetched from the
+                US Treasury website.
+            skip_data_sources_initialization (bool): Whether to skip the
+                initialization of data sources. This is useful when the data
+                sources are already initialized, and you want to skip the
+                initialization step. This will speed up the backtesting
+                process, but make sure that the data sources are already
+                initialized before calling this method.
+
+        Returns:
+            List[Backtest]: List of Backtest instances for each strategy
+                that was backtested.
+        """
+        backtests = []
+        data_sources = []
+
+        for strategy in strategies:
+            data_sources.extend(strategy.data_sources)
+
+        if not skip_data_sources_initialization:
+            self.initialize_data_sources_backtest(
+                data_sources, backtest_date_range
+            )
+
+        if risk_free_rate is None:
+            logger.info("No risk free rate provided, retrieving it...")
+            risk_free_rate = get_risk_free_rate_us()
+
+            if risk_free_rate is None:
+                raise OperationalException(
+                    "Could not retrieve risk free rate for backtest metrics."
+                    "Please provide a risk free as an argument when running "
+                    "your backtest or make sure you have an internet "
+                    "connection"
+                )
+
+        for strategy in tqdm(strategies):
+            backtests.append(
+                self.run_vector_backtest(
+                    backtest_date_range=backtest_date_range,
+                    initial_amount=initial_amount,
+                    strategy=strategy,
+                    snapshot_interval=snapshot_interval,
+                    risk_free_rate=risk_free_rate,
+                    skip_data_sources_initialization=True
+                )
+            )
+
+        return backtests
+
     def run_vector_backtest(
         self,
         backtest_date_range: BacktestDateRange,
         initial_amount,
-        strategy,
+        strategy: TradingStrategy,
         snapshot_interval: SnapshotInterval = SnapshotInterval.DAILY,
         metadata: Optional[Dict[str, str]] = None,
         risk_free_rate: Optional[float] = None,
+        skip_data_sources_initialization: bool = False
     ) -> Backtest:
         """
-        Run a vectorized backtest for an algorithm. The provided algorithm
-        or set of strategies need to have their 'buy_signal_vectorized' and
+        Run vectorized backtests for a strategy. The provided
+        strategy needs to have its 'buy_signal_vectorized' and
         'sell_signal_vectorized' methods implemented to support vectorized
         backtesting.
 
@@ -937,6 +1038,12 @@ class App:
                 backtest report. This can be used to store additional
                 information about the backtest, such as the author, version,
                 parameters or any other relevant information.
+            skip_data_sources_initialization (bool): Whether to skip the
+                initialization of data sources. This is useful when the data
+                sources are already initialized, and you want to skip the
+                initialization step. This will speed up the backtesting
+                process, but make sure that the data sources are already
+                initialized before calling this method.
 
         Returns:
             Backtest: Instance of Backtest
@@ -947,9 +1054,11 @@ class App:
             snapshot_interval=snapshot_interval,
             initial_amount=initial_amount
         )
-        self.initialize_data_sources_backtest(
-            strategy.data_sources, backtest_date_range
-        )
+
+        if not skip_data_sources_initialization:
+            self.initialize_data_sources_backtest(
+                strategy.data_sources, backtest_date_range
+            )
 
         if risk_free_rate is None:
             logger.info("No risk free rate provided, retrieving it...")
@@ -971,7 +1080,17 @@ class App:
             initial_amount=initial_amount,
             risk_free_rate=risk_free_rate
         )
-        backtest.metadata = metadata if metadata is not None else {}
+
+        # Add the metadata to the backtest
+        if metadata is None:
+
+            if strategy.metadata is None:
+                backtest.metadata = {}
+            else:
+                backtest.metadata = strategy.metadata
+        else:
+            backtest.metadata = metadata
+
         return backtest
 
     def run_backtests(

{investing_algorithm_framework-7.0.3 → investing_algorithm_framework-7.2.0}/investing_algorithm_framework/app/strategy.py

@@ -27,8 +27,12 @@ class TradingStrategy:
             sources to use for the strategy. The data sources will be used
             to indentify data providers that will be called to gather data
             and pass to the strategy before its run.
+        metadata (optional): Dict[str, Any] - a dictionary
+            containing metadata about the strategy. This can be used to
+            store additional information about the strategy, such as its
+            author, version, description, params etc.
     """
-    time_unit: str = None
+    time_unit: TimeUnit = None
     interval: int = None
     worker_id: str = None
     strategy_id: str = None
@@ -36,6 +40,7 @@ class TradingStrategy:
     data_sources: List[DataSource] = None
     traces = None
     context: Context = None
+    metadata: Dict[str, Any] = None
 
     def __init__(
         self,
@@ -43,6 +48,7 @@ class TradingStrategy:
         time_unit=None,
         interval=None,
         data_sources=None,
+        metadata=None,
         worker_id=None,
         decorated=None
     ):
@@ -65,6 +71,8 @@ class TradingStrategy:
         if data_sources is not None:
             self.data_sources = data_sources
 
+        self.metadata = metadata
+
         if decorated is not None:
             self.decorated = decorated
 

{investing_algorithm_framework-7.0.3 → investing_algorithm_framework-7.2.0}/investing_algorithm_framework/services/metrics/win_rate.py

@@ -42,7 +42,7 @@ def get_win_rate(trades: List[Trade]) -> float:
     The percentage of trades that are profitable.
 
     Formula:
-        Win Rate = (Number of Profitable Trades / Total Number of Trades) * 100
+        Win Rate = Number of Profitable Trades / Total Number of Trades
 
     Example: If 60 out of 100 trades are profitable, the win rate is 60%.
 
@@ -50,7 +50,7 @@ def get_win_rate(trades: List[Trade]) -> float:
         trades (List[Trade]): List of trades from the backtest report.
 
     Returns:
-        float: The win rate as a percentage (e.g., 75.0 for 75% win rate).
+        float: The win rate as a percentage (e.g., o.75 for 75% win rate).
     """
     trades = [
         trade for trade in trades if TradeStatus.CLOSED.equals(trade.status)
@@ -61,7 +61,7 @@ def get_win_rate(trades: List[Trade]) -> float:
     if total_trades == 0:
         return 0.0
 
-    return (positive_trades / total_trades) * 100.0
+    return positive_trades / total_trades
 
 
 def get_win_loss_ratio(trades: List[Trade]) -> float:

{investing_algorithm_framework-7.0.3 → investing_algorithm_framework-7.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "investing-algorithm-framework"
-version = "v7.0.3"
+version = "v7.2.0"
 description = "A framework for creating trading bots"
 authors = ["MDUYN"]
 readme = "README.md"

investing_algorithm_framework-7.0.3/investing_algorithm_framework/app/analysis/ranking.py

@@ -1,58 +0,0 @@
-from investing_algorithm_framework.domain import Backtest
-
-defaults_ranking_weights = {
-    "total_net_gain": 2.0,
-    "sharpe_ratio": 1.0,
-    "sortino_ratio": 1.0,
-    "win_rate": 1.0,
-    "profit_factor": 1.0,
-    "max_drawdown": -1.0,  # negative weight to penalize high drawdown
-    "max_drawdown_duration": -0.5,  # penalize long drawdown periods
-    "number_of_trades": 0.5,
-    "exposure_factor": 0.5,
-}
-
-
-def compute_score(metrics: dict, weights: dict) -> float:
-    score = 0
-    for key, weight in weights.items():
-
-        # Metrics are attributes to the backtest
-        if not hasattr(metrics, key):
-            continue
-
-        # Get the value of the metric
-        value = getattr(metrics, key)
-
-        try:
-            score += weight * value
-        except TypeError:
-            continue  # skip if value is not a number
-    return score
-
-
-def rank_results(
-    backtests: list[Backtest], weights=defaults_ranking_weights
-) -> list[Backtest]:
-    """
-    Rank backtests based on their metrics and the provided weights.
-
-    The default weights are defined in `defaults_ranking_weights`.
-    Please note that the weights should be adjusted based on the
-    specific analysis needs. You can modify the `weights` parameter
-    to include or exclude metrics as needed and reuse
-    the `defaults_ranking_weights` as a starting point.
-
-    Args:
-        backtests (list[Backtest]): List of Backtest objects to rank.
-        weights (dict): Weights for each metric to compute the score.
-
-    Returns:
-        list[Backtest]: List of Backtest objects sorted by
-            their computed score.
-    """
-    return sorted(
-        backtests,
-        key=lambda bt: compute_score(bt.backtest_metrics, weights),
-        reverse=True
-    )