investing-algorithm-framework 3.7.0__py3-none-any.whl → 7.19.15__py3-none-any.whl

investing_algorithm_framework/services/market_credential_service.py

@@ -4,7 +4,14 @@ from investing_algorithm_framework.domain import MarketCredential
 
 
 class MarketCredentialService:
-    _market_credentials = {}
+    """
+    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()] \
@@ -23,3 +30,11 @@ class MarketCredentialService:
 
     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,114 @@
+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
+
+__all__ = [
+    "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"
+]

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,181 @@
+""""
+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:
+        if max_value is None:
+            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]
+    max_drawdown_pct = 0.0
+
+    for equity, _  in equity_curve:
+        if equity > peak:
+            peak = equity
+
+        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
+
+    peak = daily_df['total_value'].iloc[0]
+    max_daily_drawdown_pct = 0.0
+    for equity in daily_df['total_value']:
+        if equity > peak:
+            peak = equity
+
+        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 (e.g., 5.0 for a 5% drawdown)
+
+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

investing_algorithm_framework/services/metrics/exposure.py

@@ -0,0 +1,210 @@
+"""
+High exposure (>1) means you’re deploying capital aggressively, possibly with many simultaneous positions.
+
+Exposure around 1 means capital is nearly fully invested most of the time, but not overlapping.
+
+Low exposure (<1) means capital is mostly idle or only partially invested.
+"""
+
+from datetime import datetime, timedelta
+from typing import List
+
+from investing_algorithm_framework.domain import Trade
+
+
+def get_exposure_ratio(
+    trades: List["Trade"], start_date: datetime, end_date: datetime
+) -> float:
+    """
+    Calculates the exposure ratio (time in market) as the fraction of the total
+    backtest duration where at least one position was open.
+
+    Unlike cumulative exposure, overlapping trades are not double-counted.
+    The result is always between 0 and 1.
+
+    Args:
+        trades (List[Trade]): List of trades executed during the backtest.
+        start_date (datetime): The start date of the backtest.
+        end_date (datetime): The end date of the backtest.
+
+    Returns:
+        A float between 0 and 1 representing the exposure ratio.
+    """
+    if not trades:
+        return 0.0
+
+    # Collect trade intervals
+    intervals = []
+    for trade in trades:
+        entry = max(trade.opened_at, start_date)
+        exit = min(trade.closed_at or end_date, end_date)
+        if exit > entry:
+            intervals.append((entry, exit))
+
+    if not intervals:
+        return 0.0
+
+    # Sort intervals by start time
+    intervals.sort(key=lambda x: x[0])
+
+    # Merge overlapping intervals
+    merged = []
+    current_start, current_end = intervals[0]
+    for start, end in intervals[1:]:
+        if start <= current_end:  # overlap
+            current_end = max(current_end, end)
+        else:
+            merged.append((current_start, current_end))
+            current_start, current_end = start, end
+    merged.append((current_start, current_end))
+
+    # Total time with at least one open trade
+    total_exposed_time = sum((end - start for start, end in merged), timedelta(0))
+
+    backtest_duration = end_date - start_date
+    if backtest_duration.total_seconds() == 0:
+        return 0.0
+
+    return total_exposed_time.total_seconds() \
+        / backtest_duration.total_seconds()
+
+
+def get_cumulative_exposure(
+    trades: List[Trade], start_date: datetime, end_date: datetime
+) -> float:
+    """
+    Calculates the exposure time as a fraction of the total backtest duration
+    that the strategy had capital deployed (i.e., at least one open position).
+
+    This value can be greater than 1 if the strategy had overlapping trades.
+    For example, if the strategy had two trades open at the same time,
+    the exposure factor would be 2.0, indicating that capital was deployed
+    for twice the duration of the backtest period.
+
+    Args:
+        trades (List[Trade]): List of trades executed during the backtest.
+        start_date (datetime): The start date.
+        end_date (datetime): The end date.
+
+    Returns:
+        A float representing the exposure factor, which is the fraction of time
+        the strategy had capital deployed during the backtest period.
+
+    """
+    if not trades:
+        return 0.0
+
+    total_trade_duration = timedelta(0)
+    for trade in trades:
+        entry = trade.opened_at
+        exit = trade.closed_at or end_date  # open trades counted up to end
+
+        if exit > entry:
+            total_trade_duration += exit - entry
+
+    backtest_duration = end_date - start_date
+
+    if backtest_duration.total_seconds() == 0:
+        return 0.0
+
+    return (total_trade_duration.total_seconds()
+            / backtest_duration.total_seconds())
+
+
+def get_average_trade_duration(trades: List[Trade]):
+    """
+    Calculates the average duration of trades in the backtest report.
+
+    Args:
+        trades (List[Trade]): List of trades executed during the backtest.
+
+    Returns:
+        A float representing the average trade duration in hours.
+    """
+    if not trades:
+        return 0.0
+
+    total_duration = 0
+
+    for trade in trades:
+        trade_duration = trade.duration
+
+        if trade_duration is not None:
+            total_duration += trade_duration
+
+    average_trade_duration = total_duration / len(trades)
+    return average_trade_duration
+
+
+def get_trade_frequency(
+    trades: List[Trade], start_date: datetime, end_date: datetime
+) -> float:
+    """
+    Calculates the trade frequency as the number of trades per day
+    during the backtest period.
+
+    Args:
+        trades (List[Trade]): List of trades executed during the backtest.
+        start_date (datetime): The start date of the backtest.
+        end_date (datetime): The end date of the backtest.
+
+    Returns:
+        A float representing the average number of trades per day.
+    """
+
+    if not trades:
+        return 0.0
+
+    total_days = (end_date - start_date).days + 1
+    if total_days <= 0:
+        return 0.0
+
+    return len(trades) / total_days
+
+
+def get_trades_per_day(
+    trades: List[Trade], start_date: datetime, end_date: datetime
+) -> float:
+    """
+    Calculates the average number of trades per day during the backtest period.
+
+    Args:
+        trades (List[Trade]): List of trades executed during the backtest.
+        start_date (datetime): The start date of the backtest.
+        end_date (datetime): The end date of the backtest.
+
+    Returns:
+        A float representing the average number of trades per day.
+    """
+    if not trades:
+        return 0.0
+
+    total_days = (end_date - start_date).days + 1
+    if total_days <= 0:
+        return 0.0
+
+    return len(trades) / total_days
+
+
+def get_trades_per_year(
+    trades: List[Trade], start_date: datetime, end_date: datetime
+) -> float:
+    """
+    Calculates the average number of trades per year during the backtest period.
+
+    Args:
+        trades (List[Trade]): List of trades executed during the backtest.
+        start_date (datetime): The start date of the backtest.
+        end_date (datetime): The end date of the backtest.
+
+    Returns:
+        A float representing the average number of trades per year.
+    """
+    if not trades:
+        return 0.0
+
+    total_years = (end_date - start_date).days / 365.25
+    if total_years <= 0:
+        return 0.0
+
+    return len(trades) / total_years