investing-algorithm-framework 1.3.1__py3-none-any.whl → 7.25.6__py3-none-any.whl

investing_algorithm_framework/services/market_credential_service.py

@@ -0,0 +1,40 @@
+from typing import Union, List
+
+from investing_algorithm_framework.domain import MarketCredential
+
+
+class MarketCredentialService:
+    """
+    Service to manage market credentials.
+
+    This service is responsible for adding, retrieving, and
+    initializing market credentials.
+    """
+    def __init__(self):
+        self._market_credentials = {}
+
+    def add(self, market_data_credential: MarketCredential):
+        self._market_credentials[market_data_credential.market.upper()] \
+            = market_data_credential
+
+    def add_all(self, market_data_credentials: List[MarketCredential]):
+        for market_data_credential in market_data_credentials:
+            self.add(market_data_credential)
+
+    def get(self, market) -> Union[MarketCredential, None]:
+
+        if market.upper() not in self._market_credentials:
+            return None
+
+        return self._market_credentials[market.upper()]
+
+    def get_all(self) -> List[MarketCredential]:
+        return list(self._market_credentials.values())
+
+    def initialize(self):
+        """
+        Initialize all market credentials.
+        """
+
+        for market_credential in self.get_all():
+            market_credential.initialize()

investing_algorithm_framework/services/metrics/__init__.py

@@ -0,0 +1,119 @@
+from .volatility import get_annual_volatility
+from .sortino_ratio import get_sortino_ratio
+from .drawdown import get_drawdown_series, get_max_drawdown
+from .equity_curve import get_equity_curve
+from .price_efficiency import get_price_efficiency_ratio
+from .profit_factor import get_profit_factor, \
+    get_cumulative_profit_factor_series, get_rolling_profit_factor_series
+from .sharpe_ratio import get_sharpe_ratio, get_rolling_sharpe_ratio
+from .price_efficiency import get_price_efficiency_ratio
+from .equity_curve import get_equity_curve
+from .drawdown import get_drawdown_series, get_max_drawdown, \
+    get_max_drawdown_absolute, get_max_drawdown_duration, \
+    get_max_daily_drawdown
+from .cagr import get_cagr
+from .standard_deviation import get_standard_deviation_downside_returns, \
+    get_standard_deviation_returns
+from .returns import get_yearly_returns, get_monthly_returns, \
+    get_best_year, get_best_month, get_worst_month, get_total_return, \
+    get_average_yearly_return, get_average_monthly_return, \
+    get_percentage_winning_months, get_average_monthly_return_losing_months, \
+    get_average_monthly_return_winning_months, get_total_growth, \
+    get_percentage_winning_years, get_worst_year, get_cumulative_return, \
+    get_total_loss, get_cumulative_return_series
+from .exposure import get_average_trade_duration, \
+    get_trade_frequency, get_trades_per_day, get_trades_per_year, \
+    get_cumulative_exposure, get_exposure_ratio
+from .win_rate import get_win_rate, get_win_loss_ratio, get_current_win_rate, \
+    get_current_win_loss_ratio
+from .calmar_ratio import get_calmar_ratio
+from .generate import create_backtest_metrics, \
+    create_backtest_metrics_for_backtest
+from .risk_free_rate import get_risk_free_rate_us
+from .trades import get_negative_trades, get_positive_trades, \
+    get_number_of_trades, get_number_of_closed_trades, \
+    get_average_trade_size, get_average_trade_return, get_best_trade, \
+    get_worst_trade, get_average_trade_gain, get_median_trade_return, \
+    get_average_trade_loss, get_current_average_trade_loss, \
+    get_current_average_trade_duration, get_current_average_trade_gain, \
+    get_current_average_trade_return, get_number_of_open_trades, \
+    get_average_trade_duration
+from .mean_daily_return import get_mean_daily_return, get_mean_yearly_return
+from .standard_deviation import get_daily_returns_std
+
+__all__ = [
+    "get_mean_daily_return",
+    "get_daily_returns_std",
+    "get_annual_volatility",
+    "get_sortino_ratio",
+    "get_drawdown_series",
+    "get_max_drawdown",
+    "get_equity_curve",
+    "get_price_efficiency_ratio",
+    "get_sharpe_ratio",
+    "get_profit_factor",
+    "get_cumulative_profit_factor_series",
+    "get_rolling_profit_factor_series",
+    "get_sharpe_ratio",
+    "get_cagr",
+    "get_standard_deviation_returns",
+    "get_standard_deviation_downside_returns",
+    "get_max_drawdown_absolute",
+    "get_total_return",
+    "get_total_loss",
+    "get_total_growth",
+    "get_cumulative_exposure",
+    "get_exposure_ratio",
+    "get_win_rate",
+    "get_win_loss_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_monthly_return",
+    "get_percentage_winning_months",
+    "get_average_trade_duration",
+    "get_trade_frequency",
+    "get_win_rate",
+    "get_win_loss_ratio",
+    "get_calmar_ratio",
+    "get_max_drawdown_absolute",
+    "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_risk_free_rate_us",
+    "get_median_trade_return",
+    "get_average_trade_gain",
+    "get_average_trade_loss",
+    "get_average_trade_size",
+    "get_average_trade_return",
+    "get_number_of_trades",
+    "get_number_of_closed_trades",
+    "get_negative_trades",
+    "get_positive_trades",
+    "get_cumulative_return",
+    "get_cumulative_return_series",
+    "get_current_win_rate",
+    "get_current_win_loss_ratio",
+    "get_current_average_trade_loss",
+    "get_current_average_trade_duration",
+    "get_current_average_trade_gain",
+    "get_current_average_trade_return",
+    "get_number_of_open_trades",
+    "get_average_trade_duration",
+    "create_backtest_metrics_for_backtest",
+    "get_mean_yearly_return"
+]

investing_algorithm_framework/services/metrics/cagr.py

@@ -0,0 +1,60 @@
+"""
+The Compound Annual Growth Rate (CAGR) normalizes returns over a one-year
+period, allowing you to compare performance across different timeframes.
+It assumes the investment grows at a steady rate and compounds over time.
+
+This formula is suitable whether your data spans:
+
+* Less than a year (e.g. 30 days)
+* Exactly a year (365 days)
+* More than a year (e.g. 500 days)
+"""
+
+import pandas as pd
+from typing import List
+from investing_algorithm_framework.domain import PortfolioSnapshot
+
+
+def get_cagr(snapshots: List[PortfolioSnapshot]) -> float:
+    """
+    Calculate the Compound Annual Growth Rate (CAGR) of a backtest report.
+    CAGR is a useful metric to evaluate the performance of an investment
+    over a period of time, normalizing the return to a one-year basis.
+
+    The formula for CAGR is:
+    CAGR = (End Value / Start Value) ^ (1 / Number of Years) - 1
+
+    Where:
+        - End Value is the final value of the investment
+        - Start Value is the initial value of the investment
+        - Number of Years is the total time period in years
+    This function assumes that the snapshots in the report are ordered by
+    creation date and that the net size represents the value of the investment.
+
+    Args:
+        snapshots (list[Snapshot]): A list of snapshots
+
+    Returns:
+        Float: The CAGR as a decimal. Returns 0.0 if not enough
+            data is available.
+    """
+
+    if len(snapshots) < 2:
+        return 0.0  # Not enough data
+
+    # Convert snapshots to DataFrame
+    data = [(s.total_value, s.created_at) for s in snapshots]
+    df = pd.DataFrame(data, columns=["total_value", "created_at"])
+    df['created_at'] = pd.to_datetime(df['created_at'])
+    df = df.sort_values('created_at')
+    start_value = df.iloc[0]['total_value']
+    end_value = df.iloc[-1]['total_value']
+    start_date = df.iloc[0]['created_at']
+    end_date = df.iloc[-1]['created_at']
+    num_days = (end_date - start_date).days
+
+    if num_days == 0 or start_value == 0:
+        return 0.0
+
+    # Apply CAGR formula
+    return (end_value / start_value) ** (365 / num_days) - 1

investing_algorithm_framework/services/metrics/calmar_ratio.py

@@ -0,0 +1,40 @@
+"""
+| **Calmar Ratio** | **Interpretation**                                          |
+| ---------------- | ----------------------------------------------------------- |
+| **> 3.0**        | **Excellent** – strong return vs. drawdown                  |
+| **2.0 – 3.0**    | **Very Good** – solid risk-adjusted performance             |
+| **1.0 – 2.0**    | **Acceptable** – decent, especially for volatile strategies |
+| **< 1.0**        | **Poor** – high drawdowns relative to return                |
+"""
+
+from typing import List
+from investing_algorithm_framework.domain import PortfolioSnapshot
+from .cagr import get_cagr
+from .drawdown import get_max_drawdown
+
+
+def get_calmar_ratio(snapshots: List[PortfolioSnapshot]):
+    """
+    Calculate the Calmar Ratio, which is the ratio of the annualized
+    return to the maximum drawdown.
+
+    Formula:
+        Calmar Ratio = CAGR / |Maximum Drawdown|
+
+    The Calmar Ratio is a measure of risk-adjusted return,
+    where a higher ratio indicates a more favorable risk-return profile.
+
+    Args:
+        snapshots (List[PortfolioSnapshot]): List of portfolio snapshots
+            from the backtest report.
+
+    Returns:
+        float: The Calmar Ratio.
+    """
+    cagr = get_cagr(snapshots)
+    max_drawdown = get_max_drawdown(snapshots)
+
+    if max_drawdown == 0 or max_drawdown is None:
+        return 0.0
+
+    return cagr / max_drawdown

investing_algorithm_framework/services/metrics/drawdown.py

@@ -0,0 +1,218 @@
+""""
+Max Drawdown (MDD) — a key risk metric that shows the worst
+peak-to-trough decline of a portfolio:
+
+| **Max Drawdown (%)** | **Interpretation**                                                   |
+|-----------------------|----------------------------------------------------------------------|
+| **0% to -5%**         | 🟢 Excellent — Very low risk, typical for conservative strategies     |
+| **-5% to -10%**       | ✅ Good — Moderate volatility, acceptable for balanced portfolios     |
+| **-10% to -20%**      | ⚠️ Elevated Risk — Common in growth or actively managed strategies    |
+| **-20% to -40%**      | 🔻 High Risk — Significant drawdown, typical of aggressive strategies |
+| **> -40%**            | 🚨 Very High Risk — Risk of capital loss or strategy failure          |
+"""
+from typing import List, Tuple
+import pandas as pd
+from datetime import datetime
+from investing_algorithm_framework.domain import PortfolioSnapshot, Trade
+from .equity_curve import get_equity_curve
+
+
+def get_drawdown_series(snapshots: List[PortfolioSnapshot]) -> List[Tuple[float, datetime]]:
+    """
+    Calculate the drawdown series of a backtest report.
+
+    The drawdown is calculated as the percentage difference
+    between the current equity value and the maximum equity value
+    observed up to that point in time.
+
+    Args:
+        snapshots (List[PortfolioSnapshot]): List of portfolio snapshots
+
+    Returns:
+        List[Tuple[datetime, float]]: A list of tuples with datetime
+            and drawdown percentage. The drawdown is expressed as a
+            negative percentage, where 0% means no drawdown and -100%
+            means the portfolio has lost all its value.
+    """
+    equity_curve = get_equity_curve(snapshots)
+
+    drawdown_series = []
+    max_value = None
+
+    for value, timestamp in equity_curve:
+        # Skip zero or negative values to avoid division by zero
+        if value <= 0:
+            drawdown_series.append((0.0, timestamp))
+            continue
+
+        if max_value is None or max_value <= 0:
+            max_value = value
+        max_value = max(max_value, value)
+        drawdown = (value - max_value) / max_value  # This will be <= 0
+        drawdown_series.append((drawdown, timestamp))
+
+    return drawdown_series
+
+
+def get_max_drawdown(snapshots: List[PortfolioSnapshot]) -> float:
+    """
+    Calculate the maximum drawdown of the portfolio as a percentage from the peak.
+
+    Max Drawdown is the maximum observed loss from a peak to a
+    trough before a new peak is achieved.
+
+    It is expressed here as a negative percentage.
+
+    Args:
+        snapshots (List[PortfolioSnapshot]): List of portfolio snapshots
+
+    Returns:
+        float: The maximum drawdown as a negative percentage (e.g., -12.5 for a 12.5% drawdown).
+    """
+    equity_curve = get_equity_curve(snapshots)
+
+    if not equity_curve:
+        return 0.0
+
+    peak = equity_curve[0][0]
+
+    # Handle zero or negative starting value
+    if peak <= 0:
+        # Find first positive value as the peak
+        for equity, _ in equity_curve:
+            if equity > 0:
+                peak = equity
+                break
+        else:
+            # No positive values found
+            return 0.0
+
+    max_drawdown_pct = 0.0
+
+    for equity, _ in equity_curve:
+        # Skip non-positive values
+        if equity <= 0:
+            continue
+
+        if equity > peak:
+            peak = equity
+
+        # Avoid division by zero (shouldn't happen now but extra safety)
+        if peak <= 0:
+            continue
+
+        drawdown_pct = (equity - peak) / peak  # Will be 0 or negative
+        max_drawdown_pct = min(max_drawdown_pct, drawdown_pct)
+
+    return abs(max_drawdown_pct)
+
+
+def get_max_daily_drawdown(snapshots: List[PortfolioSnapshot]) -> float:
+    """
+    Calculate the maximum daily drawdown of the portfolio as a percentage from the peak.
+
+    This is the largest drop in equity (in percentage) from a peak to a trough
+    during the backtest period, calculated on a daily basis.
+
+    Args:
+        snapshots (List[PortfolioSnapshot]): List of portfolio snapshots
+
+    Returns:
+        float: The maximum daily drawdown as a negative percentage (e.g., -5.0 for a 5% drawdown).
+    """
+    # Create DataFrame from snapshots
+    data = [(s.created_at, s.total_value) for s in snapshots]
+    df = pd.DataFrame(data, columns=["created_at", "total_value"])
+    df['created_at'] = pd.to_datetime(df['created_at'])
+    df = df.sort_values('created_at').drop_duplicates('created_at')\
+        .set_index('created_at')
+
+    # Resample to daily frequency using last value of the day
+    daily_df = df.resample('1D').last().dropna()
+
+    if daily_df.empty:
+        return 0.0
+
+    # Filter out non-positive values
+    positive_values = daily_df[daily_df['total_value'] > 0]['total_value']
+
+    if positive_values.empty:
+        return 0.0
+
+    peak = positive_values.iloc[0]
+    max_daily_drawdown_pct = 0.0
+
+    for equity in positive_values:
+        if equity > peak:
+            peak = equity
+
+        # Avoid division by zero (shouldn't happen but extra safety)
+        if peak <= 0:
+            continue
+
+        drawdown_pct = (equity - peak) / peak
+        max_daily_drawdown_pct = min(max_daily_drawdown_pct, drawdown_pct)
+
+    return abs(max_daily_drawdown_pct)  # Return as positive percentage
+
+def get_max_drawdown_duration(snapshots: List[PortfolioSnapshot]) -> int:
+    """
+    Calculate the maximum duration of drawdown in days.
+
+    This is the longest period where the portfolio equity was below its peak.
+
+    Args:
+        snapshots (List[PortfolioSnapshot]): List of portfolio snapshots
+
+    Returns:
+        int: The maximum drawdown duration in days.
+    """
+    equity_curve = get_equity_curve(snapshots)
+    if not equity_curve:
+        return 0
+
+    peak = equity_curve[0][0]
+    max_duration = 0
+    current_duration = 0
+
+    for equity, _ in equity_curve:
+        if equity < peak:
+            current_duration += 1
+        else:
+            max_duration = max(max_duration, current_duration)
+            current_duration = 0
+            peak = equity  # Reset peak to current equity
+
+    max_duration = max(max_duration, current_duration)  # Final check
+
+    return max_duration
+
+
+def get_max_drawdown_absolute(snapshots: List[PortfolioSnapshot]) -> float:
+    """
+    Calculate the maximum absolute drawdown of the portfolio.
+
+    This is the largest drop in equity (in currency units) from a peak to a trough
+    during the backtest period.
+
+    Args:
+        snapshots (List[PortfolioSnapshot]): List of portfolio snapshots
+
+    Returns:
+        float: The maximum absolute drawdown as a positive number (e.g., €10,000).
+    """
+    equity_curve = get_equity_curve(snapshots)
+    if not equity_curve:
+        return 0.0
+
+    peak = equity_curve[0][0]
+    max_drawdown = 0.0
+
+    for equity, _ in equity_curve:
+        if equity > peak:
+            peak = equity
+
+        drawdown = peak - equity  # Drop from peak
+        max_drawdown = max(max_drawdown, drawdown)
+
+    return abs(max_drawdown)  # Return as positive number (e.g., €10,000)

investing_algorithm_framework/services/metrics/equity_curve.py

@@ -0,0 +1,24 @@
+from datetime import datetime
+from typing import List
+from investing_algorithm_framework.domain import PortfolioSnapshot
+
+
+def get_equity_curve(
+    snapshots: List[PortfolioSnapshot]
+) -> list[tuple[float, datetime]]:
+    """
+    Calculate the total size of the portfolio at each snapshot timestamp.
+
+    Args:
+        snapshots (List[PortfolioSnapshot]): List of portfolio snapshots.
+    Returns:
+        list[tuple[datetime, float]]: A list of tuples with
+            timestamps and total sizes.
+    """
+    series = []
+    for snapshot in snapshots:
+        timestamp = snapshot.created_at
+        total_size = snapshot.total_value
+        series.append((total_size, timestamp))
+
+    return series