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

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

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

{investing_algorithm_framework-7.1.0 → investing_algorithm_framework-7.3.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, \
@@ -18,7 +18,7 @@ from .domain import ApiException, \
     DEFAULT_LOGGING_CONFIG, DataType, DataProvider, \
     BacktestResult, TradeStatus, TradeRiskType, \
     APPLICATION_DIRECTORY, DataSource, OrderExecutor, PortfolioProvider, \
-    SnapshotInterval, AWS_S3_STATE_BUCKET_NAME
+    SnapshotInterval, AWS_S3_STATE_BUCKET_NAME, BacktestEvaluationFocus
 from .infrastructure import AzureBlobStorageStateHandler, \
     CSVOHLCVDataProvider, CCXTOHLCVDataProvider, PandasOHLCVDataProvider, \
     AWSS3StorageStateHandler
@@ -159,8 +159,9 @@ __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"
+    "get_growth_percentage",
+    "BacktestEvaluationFocus"
 ]

{investing_algorithm_framework-7.1.0 → investing_algorithm_framework-7.3.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.3.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.3.0/investing_algorithm_framework/app/analysis/__init__.py

@@ -0,0 +1,10 @@
+from .backtest_data_ranges import select_backtest_date_ranges
+from .ranking import rank_results, create_weights
+from .permutation import create_ohlcv_permutation
+
+__all__ = [
+    "select_backtest_date_ranges",
+    "rank_results",
+    "create_weights",
+    "create_ohlcv_permutation"
+]

investing_algorithm_framework-7.3.0/investing_algorithm_framework/app/analysis/permutation.py

@@ -0,0 +1,116 @@
+from typing import Union
+
+import numpy as np
+import pandas as pd
+import polars as pl
+
+from investing_algorithm_framework.domain import OperationalException
+
+
+def create_ohlcv_permutation(
+    data: Union[pd.DataFrame, pl.DataFrame],
+    start_index: int = 0,
+    seed: int | None = None,
+) -> Union[pd.DataFrame, pl.DataFrame]:
+    """
+    Create a permuted OHLCV dataset by shuffling relative price moves.
+
+    Args:
+        data: A single OHLCV DataFrame (pandas or polars)
+            with columns ['Open', 'High', 'Low', 'Close', 'Volume'].
+            For pandas: Datetime can be either
+            index or a 'Datetime' column. For polars: Datetime
+            must be a 'Datetime' column.
+        start_index: Index at which the permutation should begin
+            (bars before remain unchanged).
+        seed: Random seed for reproducibility.
+
+    Returns:
+        DataFrame of the same type (pandas or polars) with
+            permuted OHLCV values, preserving the datetime
+            structure (index vs column) of the input.
+    """
+
+    if start_index < 0:
+        raise OperationalException("start_index must be >= 0")
+
+    if seed is None:
+        seed = np.random.randint(0, 1_000_000)
+
+    np.random.seed(seed)
+    is_polars = isinstance(data, pl.DataFrame)
+
+    # Normalize input to pandas
+    if is_polars:
+        has_datetime_col = "Datetime" in data.columns
+        ohlcv_pd = data.to_pandas().copy()
+        if has_datetime_col:
+            time_index = pd.to_datetime(ohlcv_pd["Datetime"])
+        else:
+            time_index = np.arange(len(ohlcv_pd))
+    else:
+        has_datetime_col = "Datetime" in data.columns
+        if isinstance(data.index, pd.DatetimeIndex):
+            time_index = data.index
+        elif has_datetime_col:
+            time_index = pd.to_datetime(data["Datetime"])
+        else:
+            time_index = np.arange(len(data))
+        ohlcv_pd = data.copy()
+
+    # Prepare data
+    n_bars = len(ohlcv_pd)
+    perm_index = start_index + 1
+    perm_n = n_bars - perm_index
+
+    log_bars = np.log(ohlcv_pd[["Open", "High", "Low", "Close"]])
+
+    # Start bar
+    start_bar = log_bars.iloc[start_index].to_numpy()
+
+    # Relative series
+    rel_open = (log_bars["Open"] - log_bars["Close"].shift()).to_numpy()
+    rel_high = (log_bars["High"] - log_bars["Open"]).to_numpy()
+    rel_low = (log_bars["Low"] - log_bars["Open"]).to_numpy()
+    rel_close = (log_bars["Close"] - log_bars["Open"]).to_numpy()
+
+    # Shuffle independently
+    idx = np.arange(perm_n)
+    rel_high = rel_high[perm_index:][np.random.permutation(idx)]
+    rel_low = rel_low[perm_index:][np.random.permutation(idx)]
+    rel_close = rel_close[perm_index:][np.random.permutation(idx)]
+    rel_open = rel_open[perm_index:][np.random.permutation(idx)]
+
+    # Build permuted OHLC
+    perm_bars = np.zeros((n_bars, 4))
+    perm_bars[:start_index] = log_bars.iloc[:start_index].to_numpy()
+    perm_bars[start_index] = start_bar
+
+    for i in range(perm_index, n_bars):
+        k = i - perm_index
+        perm_bars[i, 0] = perm_bars[i - 1, 3] + rel_open[k]   # Open
+        perm_bars[i, 1] = perm_bars[i, 0] + rel_high[k]       # High
+        perm_bars[i, 2] = perm_bars[i, 0] + rel_low[k]        # Low
+        perm_bars[i, 3] = perm_bars[i, 0] + rel_close[k]      # Close
+
+    perm_bars = np.exp(perm_bars)
+
+    # Rebuild OHLCV
+    perm_df = pd.DataFrame(
+        perm_bars,
+        columns=["Open", "High", "Low", "Close"],
+    )
+    perm_df["Volume"] = ohlcv_pd["Volume"].values
+
+    # Restore datetime structure
+    if is_polars:
+        if has_datetime_col:
+            perm_df.insert(0, "Datetime", time_index)
+        return pl.from_pandas(perm_df)
+    else:
+        if isinstance(data.index, pd.DatetimeIndex):
+            perm_df.index = time_index
+            perm_df.index.name = data.index.name or "Datetime"
+        elif has_datetime_col:
+            perm_df.insert(0, "Datetime", time_index)
+        return perm_df

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

@@ -0,0 +1,142 @@
+import math
+
+from investing_algorithm_framework.domain import BacktestEvaluationFocus
+BacktestEvaluationFocus
+
+
+def normalize(value, min_val, max_val):
+    """
+    Normalize a value to a range [0, 1].
+    """
+    if value is None or math.isnan(value) or math.isinf(value):
+        return 0
+    if min_val == max_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 value is None or (
+            isinstance(value, float) and
+            (math.isnan(value) or math.isinf(value))
+        ):
+            continue
+        if key in ranges:
+            value = normalize(value, ranges[key][0], ranges[key][1])
+        score += weight * value
+    return score
+
+
+def create_weights(
+    focus: BacktestEvaluationFocus | str | None = None,
+    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 (BacktestEvaluationFocus | str | None): The focus for ranking.
+        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.
+    """
+    if focus is None:
+        focus = BacktestEvaluationFocus.BALANCED
+
+    weights = focus.get_weights()
+
+    # if full custom dict is given → override everything
+    if custom_weights is not None:
+        weights = {**weights, **custom_weights}
+
+    return weights
+
+
+def rank_results(backtests, focus=None, weights=None, filter_fn=None):
+    """
+    Rank backtest results based on specified focus, weights, and filters.
+
+    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.
+        filter_fn (callable | dict, optional): A filter to apply to
+            backtests before ranking.
+            - If callable: receives metrics and should return True/False.
+            - If dict: mapping {metric_name: condition_fn},
+              all conditions must pass.
+
+    Returns:
+        list: Sorted list of backtests based on computed scores.
+    """
+
+    if weights is None:
+        weights = create_weights(focus=focus)
+
+    # Apply filtering
+    if filter_fn is not None:
+        if callable(filter_fn):
+            backtests = [
+                bt for bt in backtests
+                if filter_fn(bt.backtest_metrics)
+            ]
+        elif isinstance(filter_fn, dict):
+            backtests = [
+                bt for bt in backtests
+                if all(
+                    cond(getattr(bt.backtest_metrics, key, None))
+                    for key, cond in filter_fn.items()
+                )
+            ]
+
+    # 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)) and v is not None
+            and not math.isnan(v) and not math.isinf(v)
+        ]
+
+        if values:
+            ranges[key] = (min(values), max(values))
+
+    return sorted(
+        backtests,
+        key=lambda bt: compute_score(bt.backtest_metrics, weights, ranges),
+        reverse=True
+    )