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

investing_algorithm_framework/services/metrics/sharpe_ratio.py

@@ -0,0 +1,137 @@
+"""
+The Sharpe Ratio is a widely used risk-adjusted performance metric. It
+measures the excess return per unit of risk (volatility), where risk is
+represented by the standard deviation of returns.
+
+| Sharpe Ratio   | Interpretation                              |
+| -------------- | ------------------------------------------- |
+| **< 0**        | Bad: Underperforms risk-free asset          |
+| **0.0 – 1.0**  | Suboptimal: Returns do not justify risk     |
+| **1.0 – 1.99** | Acceptable: Reasonable risk-adjusted return |
+| **2.0 – 2.99** | Good: Strong risk-adjusted performance      |
+| **3.0+**       | Excellent: Exceptional risk-adjusted return |
+
+Sharpe Ratio is highly sensitive to the volatility estimate: Inconsistent sampling frequency, short backtests, or low trade frequency can distort it.
+
+Different strategies have different risk profiles:
+
+High-frequency strategies may have high Sharpe Ratios (>3).
+
+Trend-following strategies might have lower Sharpe (1–2) but strong CAGR and Calmar.
+
+Use risk-free rate (~4–5% annual currently) if your backtest spans long periods.
+
+### 📌 Practical Notes about the implementation:
+
+- Use **daily returns** for consistent Sharpe Ratio calculation and **annualize** the result using this formula:
+
+
+Sharpe Ratio Formula:
+    Sharpe Ratio = (Mean Daily Return × Periods Per Year - Risk-Free Rate) /
+                   (Standard Deviation of Daily Returns × sqrt(Periods Per Year))
+
+- You can also calculate a **rolling Sharpe Ratio** (e.g., over a 90-day window) to detect changes in performance stability over time.
+
+Mean daily return is either based on the real returns from the backtest or the CAGR, depending on the data duration.
+
+When do we use actual returns vs CAGR?
+
+| Data Duration | Use This Approach                                               | Reason                                                            |
+| ------------- | --------------------------------------------------------------- | ----------------------------------------------------------------- |
+| **< 1 year**  | Use **CAGR** directly and avoid Sharpe Ratio                    | Not enough data to estimate volatility robustly                   |
+| **1–2 years** | Use **CAGR + conservative vol estimate** OR Sharpe with caution | Sharpe may be unstable, consider adding error bars or disclaimers |
+| **> 2 years** | Use **Sharpe Ratio** based on periodic returns                  | Adequate data to reliably estimate risk-adjusted return           |
+
+"""
+
+from typing import Optional, List, Tuple
+
+import math
+import pandas as pd
+import numpy as np
+from datetime import datetime
+
+from investing_algorithm_framework.domain import PortfolioSnapshot
+from .mean_daily_return import get_mean_daily_return
+from .standard_deviation import get_daily_returns_std
+
+
+def get_sharpe_ratio(
+    snapshots: List[PortfolioSnapshot], risk_free_rate: float,
+) -> float:
+    """
+    Calculate the Sharpe Ratio from a backtest report using daily or
+    weekly returns.
+
+    The Sharpe Ratio is calculated as:
+        (Annualized Return - Risk-Free Rate) / Annualized Std Dev of Returns
+
+    Args:
+        snapshots (List[PortfolioSnapshot]): List of portfolio snapshots
+        risk_free_rate (float, optional): Annual risk-free rate as a
+            decimal (e.g., 0.047 for 4.7%).
+
+    Returns:
+        float: The Sharpe Ratio.
+    """
+    snapshots = sorted(snapshots, key=lambda s: s.created_at)
+    mean_daily_return = get_mean_daily_return(snapshots)
+    std_daily_return = get_daily_returns_std(snapshots)
+
+    if std_daily_return == 0:
+        return float('nan')  # Avoid division by zero
+
+    # Formula: Sharpe Ratio = (Mean Daily Return × Periods Per Year - Risk-Free Rate) /
+    # (Standard Deviation of Daily Returns × sqrt(Periods Per Year))
+    return (mean_daily_return * 365 - risk_free_rate) / \
+              (std_daily_return * math.sqrt(365))
+
+
+def get_rolling_sharpe_ratio(
+    snapshots: List[PortfolioSnapshot], risk_free_rate: float
+) -> List[Tuple[float, datetime]]:
+    """
+    Calculate the rolling Sharpe Ratio over a 365-day window.
+
+    Args:
+        snapshots (List[PortfolioSnapshot]): Time-sorted list of snapshots.
+        risk_free_rate (float): Annualized risk-free rate (e.g., 0.03 for 3%).
+
+    Returns:
+        List[Tuple[float, datetime]]: List of (sharpe_ratio, snapshot_date).
+    """
+    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()
+
+    # Returns as percentage change
+    returns_s = daily_df['total_value'].pct_change().dropna()
+
+    # Rolling Annualised Sharpe
+    rolling = returns_s.rolling(window=365)
+    rolling_sharpe_s = np.sqrt(365) * (
+        rolling.mean() / rolling.std()
+    )
+
+    # Ensure chronological order
+    snapshots = sorted(snapshots, key=lambda s: s.created_at)
+
+    result = []
+    for date, sharpe in rolling_sharpe_s.items():
+
+        if pd.isna(sharpe):
+            result.append((sharpe, date))
+            continue
+
+        # Find the corresponding snapshot
+        snapshot = next((s for s in snapshots if s.created_at == date), None)
+
+        if snapshot:
+            result.append((sharpe, snapshot.created_at))
+
+    return result

investing_algorithm_framework/services/metrics/sortino_ratio.py

@@ -0,0 +1,74 @@
+"""
+The Sortino Ratio is a risk-adjusted performance metric that tells you how
+much return you're getting per unit of downside risk — a more nuanced
+alternative to the Sharpe Ratio, especially when returns are not
+symmetrically distributed.
+
+| **Sortino Ratio** | **Interpretation**                                                   |
+|-------------------|----------------------------------------------------------------------|
+| **< 0**           | 🚫 Bad — Portfolio underperforms the risk-free rate with downside risk |
+| **0 to 1**        | ⚠️ Suboptimal — Low excess return relative to downside risk          |
+| **1 to 2**        | ✅ Acceptable/Good — Reasonable performance for most portfolios       |
+| **2 to 3**        | 💪 Strong — Very good risk-adjusted returns                          |
+| **> 3**           | 🌟 Excellent — Rare, may indicate exceptional strategy or overfitting |
+
+Formula:
+Sortino Ratio = (Mean Daily Return × Periods Per Year - Risk-Free Rate) /
+               (Downside Standard Deviation of Daily Returns × sqrt(Periods Per Year))
+
+"""
+
+from typing import Optional
+
+import math
+import numpy as np
+from typing import List
+from investing_algorithm_framework.domain import PortfolioSnapshot
+from .mean_daily_return import get_mean_daily_return
+from .risk_free_rate import get_risk_free_rate_us
+from .standard_deviation import get_downside_std_of_daily_returns
+
+
+def get_sortino_ratio(
+    snapshots: List[PortfolioSnapshot], risk_free_rate: float
+) -> float:
+    """
+    Calculate the Sortino Ratio for a given report.
+
+    The formula for Sortino Ratio is:
+        Sortino Ratio = (Annualized Return - Risk-Free Rate) / Downside Standard Deviation
+
+    Where:
+        - Annualized Return is the CAGR of the investment
+        - Risk-Free Rate is the return of a risk-free asset (e.g. treasury bills)
+        - Downside Standard Deviation is the standard deviation of negative returns
+
+    Args:
+        snapshots (List[PortfolioSnapshot]): List of portfolio snapshots
+            from the backtest report.
+        risk_free_rate (float): Annual risk-free rate as a decimal
+            (e.g., 0.047 for 4.7%).
+
+    Returns:
+        float: The Sortino Ratio.
+    """
+    snapshots = sorted(snapshots, key=lambda s: s.created_at)
+
+    if not snapshots:
+        return float('inf')
+
+    mean_daily_return = get_mean_daily_return(snapshots)
+    std_downside_daily_return = get_downside_std_of_daily_returns(snapshots)
+
+    if std_downside_daily_return == 0:
+        return float('nan')  # or 0.0, depending on preference
+
+    # Formula: Sharpe Ratio = (Mean Daily Return × Periods Per Year - Risk-Free Rate) /
+    # (Standard Deviation of Daily Returns × sqrt(Periods Per Year))
+    ratio = (mean_daily_return * 365 - risk_free_rate) / \
+        (std_downside_daily_return * math.sqrt(365))
+
+    if np.float64("inf") == ratio or np.float64("-inf") == ratio:
+        return float('inf')
+
+    return ratio if not np.isnan(ratio) else 0.0

investing_algorithm_framework/services/metrics/standard_deviation.py

@@ -0,0 +1,157 @@
+import numpy as np
+import pandas as pd
+
+
+def get_standard_deviation_downside_returns(snapshots):
+    """
+    Calculate the standard deviation of downside returns from the net size
+    of the reports.
+
+    Args:
+        report (BacktestReport): The report containing the equity curve.
+
+    Returns:
+        float: The standard deviation of downside returns.
+    """
+
+    if len(snapshots) < 2:
+        return 0.0  # Not enough data
+
+    # Create DataFrame of net_size over time
+    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').drop_duplicates('created_at').copy()
+
+    # Compute percentage returns
+    df['return'] = df['total_value'].pct_change()
+    df = df.dropna()
+
+    if df.empty:
+        return 0.0
+
+    # Filter downside returns
+    downside_returns = df['return'][df['return'] < 0]
+
+    if downside_returns.empty:
+        return 0.0
+
+    # Compute standard deviation of downside returns
+    downside_std = downside_returns.std(ddof=1)  # ddof=1 for sample std dev
+
+    # Handle edge cases
+    if np.isnan(downside_std):
+        return 0.0
+
+    return downside_std
+
+
+def get_standard_deviation_returns(snapshots):
+    """
+    Calculate the standard deviation of returns from the net size
+    of the reports.
+
+    Args:
+        report (BacktestReport): The report containing the equity curve.
+
+    Returns:
+        float: The standard deviation of downside returns.
+    """
+
+    if len(snapshots) < 2:
+        return 0.0  # Not enough data
+
+    # Create DataFrame of net_size over time
+    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').drop_duplicates('created_at').copy()
+
+    # Compute percentage returns
+    df['return'] = df['total_value'].pct_change()
+    df = df.dropna()
+
+    if df.empty:
+        return 0.0
+
+    # Filter downside returns
+    df_returns = df['return']
+
+    if df_returns.empty:
+        return 0.0
+
+    std = df_returns.std(ddof=1)  # ddof=1 for sample std dev
+
+    # Handle edge cases
+    if np.isnan(std):
+        return 0.0
+
+    return std
+
+def get_daily_returns_std(snapshots):
+    """
+    Calculate the standard deviation of daily returns from a list of snapshots.
+    Resamples data to daily frequency using end-of-day values.
+
+    Args:
+        snapshots (List[PortfolioSnapshot]): Snapshots with total_value and created_at.
+
+    Returns:
+        float: Standard deviation of daily returns.
+    """
+    if len(snapshots) < 2:
+        return 0.0  # Not enough data
+
+    # 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.drop_duplicates("created_at").set_index("created_at")
+    df = df.sort_index()
+
+    # Resample to daily frequency (end of day)
+    daily_df = df.resample("D").last().dropna()
+
+    # Calculate daily returns
+    daily_df["return"] = daily_df["total_value"].pct_change().dropna()
+
+    if daily_df["return"].empty:
+        return 0.0
+
+    return daily_df["return"].std()
+
+
+def get_downside_std_of_daily_returns(snapshots):
+    """
+    Calculate the downside standard deviation of daily returns from a list of snapshots.
+    Resamples data to daily frequency using end-of-day values.
+
+    Args:
+        snapshots (List[PortfolioSnapshot]): Snapshots with total_value and created_at.
+
+    Returns:
+        float: Downside standard deviation of daily returns.
+    """
+    if len(snapshots) < 2:
+        return 0.0  # Not enough data
+
+    # 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.drop_duplicates("created_at").set_index("created_at")
+    df = df.sort_index()
+
+    # Resample to daily frequency (end of day)
+    daily_df = df.resample("D").last().dropna()
+
+    # Calculate daily returns
+    daily_df["return"] = daily_df["total_value"].pct_change().dropna()
+
+    # Filter only negative returns for downside deviation
+    negative_returns = daily_df["return"][daily_df["return"] < 0]
+
+    if negative_returns.empty:
+        return 0.0
+
+    return negative_returns.std()