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

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

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

{investing_algorithm_framework-7.1.0 → 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.1.0 → 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.1.0 → 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.1.0 → 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.1.0 → investing_algorithm_framework-7.2.0}/investing_algorithm_framework/app/app.py

@@ -898,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:
@@ -965,6 +974,18 @@ class App:
                 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(
@@ -1063,7 +1084,7 @@ class App:
         # Add the metadata to the backtest
         if metadata is None:
 
-            if strategy.metadata is not None:
+            if strategy.metadata is None:
                 backtest.metadata = {}
             else:
                 backtest.metadata = strategy.metadata

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

@@ -71,7 +71,7 @@ class TradingStrategy:
         if data_sources is not None:
             self.data_sources = data_sources
 
-        self.metadata = metadata if metadata is not None else {}
+        self.metadata = metadata
 
         if decorated is not None:
             self.decorated = decorated

{investing_algorithm_framework-7.1.0 → 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.1.0 → investing_algorithm_framework-7.2.0}/pyproject.toml

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

investing_algorithm_framework-7.1.0/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
-    )