investing-algorithm-framework 7.19.14__py3-none-any.whl

investing_algorithm_framework/app/analysis/backtest_data_ranges.py

@@ -0,0 +1,121 @@
+import pandas as pd
+from typing import List, Union
+
+from datetime import timezone
+from investing_algorithm_framework.domain import BacktestDateRange, \
+    OperationalException
+
+
+def select_backtest_date_ranges(
+    df: pd.DataFrame, window: Union[str, int] = '365D'
+) -> List[BacktestDateRange]:
+    """
+    Identifies the best upturn, worst downturn, and sideways periods
+    for the given window duration. This allows you to quickly select
+    interesting periods for backtesting.
+
+    Args:
+        df (pd.DataFrame): DataFrame with a DateTime index
+            and 'Close' column.
+        window (Union[str, int]): Duration of the window
+            to analyze. Can be a string like '365D' or an
+            integer representing days.
+
+    Returns:
+        List[BacktestDateRange]: List of BacktestDateRange
+            objects representing the best upturn, worst
+            downturn, and most sideways periods.
+    """
+    df = df.copy()
+    df = df.sort_index()
+
+    if isinstance(window, int):
+        window = pd.Timedelta(days=window)
+    elif isinstance(window, str):
+        window = pd.to_timedelta(window)
+    else:
+        raise OperationalException("window must be a string or integer")
+
+    # Check if the window is larger than the DataFrame
+    if len(df) == 0:
+        raise OperationalException("DataFrame is empty")
+
+    if df.index[-1] - df.index[0] < window:
+        raise OperationalException(
+            "Window duration is larger than the data duration"
+        )
+
+    if len(df) < 2 or df.index[-1] - df.index[0] < window:
+        raise OperationalException(
+            "DataFrame must contain at least two rows and span "
+            "the full window duration"
+        )
+
+    best_upturn = {
+        "name": "UpTurn", "return": float('-inf'), "start": None, "end": None
+    }
+    worst_downturn = {
+        "name": "DownTurn", "return": float('inf'), "start": None, "end": None
+    }
+    most_sideways = {
+        "name": "SideWays",
+        "volatility": float('inf'),
+        "return": None,
+        "start": None,
+        "end": None
+    }
+
+    for i in range(len(df)):
+        start_time = df.index[i]
+        end_time = start_time + window
+        window_df = df[(df.index >= start_time) & (df.index <= end_time)]
+
+        if len(window_df) < 2 or (window_df.index[-1] - start_time) < window:
+            continue
+
+        start_price = window_df['Close'].iloc[0]
+        end_price = window_df['Close'].iloc[-1]
+        ret = (end_price / start_price) - 1  # relative return
+        volatility = window_df['Close'].std()
+
+        # Ensure datetime for BacktestDateRange and with timezone utc
+        start_time = pd.Timestamp(start_time).to_pydatetime()
+        start_time = start_time.replace(tzinfo=timezone.utc)
+        end_time = pd.Timestamp(window_df.index[-1]).to_pydatetime()
+        end_time = end_time.replace(tzinfo=timezone.utc)
+
+        if ret > best_upturn["return"]:
+            best_upturn.update(
+                {"return": ret, "start": start_time, "end": end_time}
+            )
+
+        if ret < worst_downturn["return"]:
+            worst_downturn.update(
+                {"return": ret, "start": start_time, "end": end_time}
+            )
+
+        if volatility < most_sideways["volatility"]:
+            most_sideways.update({
+                "return": ret,
+                "volatility": volatility,
+                "start": start_time,
+                "end": end_time
+            })
+
+    return [
+        BacktestDateRange(
+            start_date=best_upturn['start'],
+            end_date=best_upturn['end'],
+            name=best_upturn['name']
+        ),
+        BacktestDateRange(
+            start_date=worst_downturn['start'],
+            end_date=worst_downturn['end'],
+            name=worst_downturn['name']
+        ),
+        BacktestDateRange(
+            start_date=most_sideways['start'],
+            end_date=most_sideways['end'],
+            name=most_sideways['name']
+        )
+    ]

investing_algorithm_framework/app/analysis/backtest_utils.py

@@ -0,0 +1,107 @@
+import os
+from pathlib import Path
+from typing import List, Union, Callable
+from logging import getLogger
+from random import Random
+
+from investing_algorithm_framework.domain import Backtest
+
+
+logger = getLogger("investing_algorithm_framework")
+
+
+def save_backtests_to_directory(
+    backtests: List[Backtest],
+    directory_path: Union[str, Path],
+    dir_name_generation_function: Callable[[Backtest], str] = None,
+    filter_function: Callable[[Backtest], bool] = None
+) -> 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.
+        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 metadata 'id' will be used.
+            Defaults to None.
+        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.
+
+    Returns:
+        None
+    """
+
+    if not os.path.exists(directory_path):
+        os.makedirs(directory_path)
+
+    for backtest in backtests:
+
+        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:
+            # Check if there is an ID in the backtest metadata
+            dir_name = backtest.metadata.get('id', None)
+
+        if dir_name is None:
+            logger.warning(
+                "Backtest metadata does not contain an 'id' field. "
+                "Generating a random directory name."
+            )
+            dir_name = str(Random().randint(100000, 999999))
+
+        backtest.save(os.path.join(directory_path, dir_name))
+
+
+def load_backtests_from_directory(
+    directory_path: Union[str, Path],
+    filter_function: Callable[[Backtest], bool] = None
+) -> 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.
+
+    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
+
+    for file_name in os.listdir(directory_path):
+        file_path = os.path.join(directory_path, file_name)
+
+        try:
+            backtest = Backtest.open(file_path)
+
+            if filter_function is not None:
+                if not filter_function(backtest):
+                    continue
+
+            backtests.append(backtest)
+        except Exception as e:
+            logger.error(
+                f"Failed to load backtest from {file_path}: {e}"
+            )
+
+    return backtests

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/app/analysis/ranking.py

@@ -0,0 +1,297 @@
+import math
+from typing import List
+from statistics import mean
+
+from investing_algorithm_framework.domain import BacktestEvaluationFocus, \
+    BacktestDateRange, Backtest, BacktestMetrics, OperationalException
+
+
+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.
+        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: List[Backtest],
+    focus=None,
+    weights=None,
+    filter_fn=None,
+    backtest_date_range: BacktestDateRange = None
+) -> List[Backtest]:
+    """
+    Rank backtest results based on specified focus, weights, and filters.
+
+    Args:
+        backtests (List[Backtest]): 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.
+        backtest_date_range (BacktestDateRange, optional): If provided,
+            only backtests matching this date range are considered.
+
+    Returns:
+        List[Backtest]: Sorted list of backtests based on computed scores.
+    """
+
+    if weights is None:
+        weights = create_weights(focus=focus)
+
+    # Pair backtests with their metrics
+    paired = []
+    for backtest in backtests:
+        if backtest_date_range is not None:
+            metrics = backtest.get_backtest_metrics(backtest_date_range)
+        else:
+            metrics = backtest.backtest_summary
+
+        if metrics is not None:
+            paired.append((backtest, metrics))
+
+    # Apply filtering on metrics
+    if filter_fn is not None:
+        if callable(filter_fn):
+            paired = [
+                (bt, m) for bt, m in paired if filter_fn(m)
+            ]
+        elif isinstance(filter_fn, dict):
+            paired = [
+                (bt, m) for bt, m in paired
+                if all(
+                    cond(getattr(m, key, None))
+                    for key, cond in filter_fn.items()
+                )
+            ]
+
+    # Compute normalization ranges
+    ranges = {}
+    for key in weights:
+        values = [
+            getattr(m, key, None) for _, m in paired
+        ]
+        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))
+
+    # Sort Backtests by score
+    ranked = sorted(
+        paired,
+        key=lambda bm: compute_score(bm[1], weights, ranges),
+        reverse=True
+    )
+
+    return [bt for bt, _ in ranked]
+
+
+def combine_backtest_metrics(
+    backtest_metrics: List[BacktestMetrics]
+) -> BacktestMetrics:
+    """
+    Combine backtest metrics from multiple backtests into a single list.
+
+    Args:
+        backtest_metrics (List[BacktestMetrics]): List of backtest
+            metrics to combine.
+
+    Returns:
+        BacktestMetrics: Combined list of backtest metrics.
+    """
+    if not backtest_metrics:
+        raise OperationalException("No BacktestMetrics provided")
+
+        # Helper to take mean safely
+
+    def safe_mean(values):
+        vals = [v for v in values if v is not None]
+        return mean(vals) if vals else 0.0
+
+        # Dates
+
+    start_date = min(m.backtest_start_date for m in backtest_metrics)
+    end_date = max(m.backtest_end_date for m in backtest_metrics)
+
+    # Aggregate
+    return BacktestMetrics(
+        backtest_start_date=start_date,
+        backtest_end_date=end_date,
+        equity_curve=[],  # leave empty to avoid misleading curves
+        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]),
+        final_value=safe_mean([m.final_value for m in backtest_metrics]),
+        cagr=safe_mean([m.cagr for m in backtest_metrics]),
+        sharpe_ratio=safe_mean([m.sharpe_ratio for m in backtest_metrics]),
+        rolling_sharpe_ratio=[],
+        sortino_ratio=safe_mean([m.sortino_ratio for m in backtest_metrics]),
+        calmar_ratio=safe_mean([m.calmar_ratio for m in backtest_metrics]),
+        profit_factor=safe_mean([m.profit_factor for m in backtest_metrics]),
+        gross_profit=sum(m.gross_profit or 0 for m in backtest_metrics),
+        gross_loss=sum(m.gross_loss or 0 for m in backtest_metrics),
+        annual_volatility=safe_mean(
+            [m.annual_volatility for m in backtest_metrics]),
+        monthly_returns=[],
+        yearly_returns=[],
+        drawdown_series=[],
+        max_drawdown=max(m.max_drawdown for m in backtest_metrics),
+        max_drawdown_absolute=max(
+            m.max_drawdown_absolute for m in backtest_metrics),
+        max_daily_drawdown=max(m.max_daily_drawdown for m in backtest_metrics),
+        max_drawdown_duration=max(
+            m.max_drawdown_duration for m in backtest_metrics),
+        trades_per_year=safe_mean(
+            [m.trades_per_year for m in backtest_metrics]
+        ),
+        trade_per_day=safe_mean([m.trade_per_day for m in backtest_metrics]),
+        exposure_ratio=safe_mean(
+            [m.exposure_ratio 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'),
+            default=None
+        ),
+        worst_trade=min(
+            (m.worst_trade for m in backtest_metrics if m.worst_trade),
+            key=lambda t: t.net_gain if t else float('inf'),
+            default=None
+        ),
+        average_trade_duration=safe_mean(
+            [m.average_trade_duration for m in backtest_metrics]),
+        number_of_trades=sum(m.number_of_trades for m in backtest_metrics),
+        win_rate=safe_mean([m.win_rate for m in backtest_metrics]),
+        win_loss_ratio=safe_mean([m.win_loss_ratio for m in backtest_metrics]),
+        percentage_winning_months=safe_mean(
+            [m.percentage_winning_months for m in backtest_metrics]),
+        percentage_winning_years=safe_mean(
+            [m.percentage_winning_years for m in backtest_metrics]),
+        average_monthly_return=safe_mean(
+            [m.average_monthly_return for m in backtest_metrics]),
+        average_monthly_return_losing_months=safe_mean(
+            [m.average_monthly_return_losing_months for m in backtest_metrics]
+        ),
+        average_monthly_return_winning_months=safe_mean(
+            [m.average_monthly_return_winning_months for m in backtest_metrics]
+        ),
+        best_month=max(
+            (m.best_month for m in backtest_metrics if m.best_month),
+            key=lambda x: x[0] if x else float('-inf'),
+            default=None
+        ),
+        best_year=max((m.best_year for m in backtest_metrics if m.best_year),
+                      key=lambda x: x[0] if x else float('-inf'),
+                      default=None),
+        worst_month=min(
+            (m.worst_month for m in backtest_metrics if m.worst_month),
+            key=lambda x: x[0] if x else float('inf'),
+            default=None
+        ),
+        worst_year=min(
+            (m.worst_year for m in backtest_metrics if m.worst_year),
+            key=lambda x: x[0] if x else float('inf'),
+            default=None
+        ),
+    )