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

investing_algorithm_framework/services/metrics/returns.py

@@ -0,0 +1,452 @@
+from typing import List, Tuple
+from datetime import datetime, date
+
+import pandas as pd
+
+from investing_algorithm_framework.domain import PortfolioSnapshot, Trade, \
+    OperationalException
+
+
+def get_monthly_returns(snapshots: List[PortfolioSnapshot]) -> List[Tuple[float, datetime]]:
+    """
+    Calculate the monthly returns from a list of portfolio snapshots.
+
+    Monthly return is calculated as the percentage change in portfolio value
+    from the end of one month to the end of the next month.
+
+    Args:
+        snapshots (List[PortfolioSnapshot]): List of portfolio snapshots.
+
+    Returns:
+        List[Tuple[float, datetime]]: A list of tuples containing the monthly return
+            and the corresponding month.
+    """
+
+    # 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 monthly frequency using last value of the month
+    monthly_df = df.resample('ME').last().dropna()
+    monthly_df['return'] = monthly_df['total_value'].pct_change()
+    monthly_df = monthly_df.dropna()
+
+    # Ensure returns are Python floats, not numpy floats
+    monthly_returns = [
+        (float(row['return']), row.name) for _, row in monthly_df.iterrows()
+    ]
+    return monthly_returns
+
+
+def get_yearly_returns(snapshots: List[PortfolioSnapshot]) -> List[Tuple[float, date]]:
+    """
+    Calculate the yearly returns from a list of portfolio snapshots.
+
+    Yearly return is calculated as the percentage change in portfolio value
+    from the end of one year to the end of the next year.
+
+    Args:
+        snapshots (List[PortfolioSnapshot]): List of portfolio snapshots.
+
+    Returns:
+        List[Tuple[float, date]]: A list of tuples containing the yearly return
+            and the corresponding year.
+    """
+
+    # 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')
+
+    # Remove timezone information if present to avoid warning
+    if df.index.tz is not None:
+        df.index = df.index.tz_localize(None)
+
+    # Resample to yearly frequency using last value of the year
+    yearly_df = df.resample('YE').last().dropna()
+    yearly_df['return'] = yearly_df['total_value'].pct_change()
+    yearly_df = yearly_df.dropna()
+
+    # Yearly returns with date objects only representing the year
+    yearly_df.index = yearly_df.index.to_period('Y').to_timestamp()
+    yearly_returns = [
+        (float(row['return']), row.name) for _, row in yearly_df.iterrows()
+    ]
+    return yearly_returns
+
+
+def get_percentage_winning_months(snapshots: List[PortfolioSnapshot]) -> float:
+    """
+    Calculate the percentage of winning months from portfolio snapshots.
+
+    A winning month is defined as a month where the portfolio value at the end
+    of the month is greater than at the start of the month.
+
+    Args:
+        snapshots (List[PortfolioSnapshot]): List of portfolio snapshots.
+
+    Returns:
+        float: The percentage of winning months.
+    """
+
+    monthly_returns = get_monthly_returns(snapshots)
+    winning_months = sum(1 for r, _ in monthly_returns if r > 0)
+
+    if not monthly_returns:
+        return 0.0
+
+    return (winning_months / len(monthly_returns))
+
+
+def get_best_month(snapshots: List[PortfolioSnapshot]) -> Tuple[float, datetime]:
+    """
+    Get the best month in terms of return from portfolio snapshots.
+
+    Args:
+        snapshots (List[PortfolioSnapshot]): List of portfolio snapshots.
+
+    Returns:
+        Tuple[float, datetime]: The best monthly return and the corresponding month.
+    """
+
+    monthly_returns = get_monthly_returns(snapshots)
+
+    if not monthly_returns:
+        return 0.0, None
+
+    return max(monthly_returns, key=lambda x: x[0])
+
+def get_worst_month(snapshots: List[PortfolioSnapshot]) -> Tuple[float, datetime]:
+    """
+    Get the worst month in terms of return from portfolio snapshots.
+
+    Args:
+        snapshots (List[PortfolioSnapshot]): List of portfolio snapshots.
+
+    Returns:
+        Tuple[float, datetime]: The worst monthly return and the corresponding month.
+    """
+
+    monthly_returns = get_monthly_returns(snapshots)
+
+    if not monthly_returns:
+        return 0.0, None
+
+    return min(monthly_returns, key=lambda x: x[0])
+
+def get_best_year(
+    snapshots: List[PortfolioSnapshot]
+) -> Tuple[float, datetime]:
+    """
+    Get the best year in terms of return from portfolio snapshots.
+
+    Args:
+        snapshots (List[PortfolioSnapshot]): List of portfolio snapshots.
+
+    Returns:
+        Tuple[float, datetime]: The best yearly return and the corresponding year.
+    """
+
+    yearly_returns = get_yearly_returns(snapshots)
+
+    if not yearly_returns:
+        return None, None
+
+    return max(yearly_returns, key=lambda x: x[0])
+
+
+def get_worst_year(
+    snapshots: List[PortfolioSnapshot]
+) -> Tuple[float, date]:
+    """
+    Get the worst year in terms of return from portfolio snapshots.
+
+    Args:
+        snapshots (List[PortfolioSnapshot]): List of portfolio snapshots.
+
+    Returns:
+        Tuple[float, datetime]: The worst yearly return and the corresponding year.
+    """
+
+    yearly_returns = get_yearly_returns(snapshots)
+
+    if not yearly_returns:
+        return None, None
+
+    return min(yearly_returns, key=lambda x: x[0])
+
+
+def get_average_monthly_return(snapshots: List[PortfolioSnapshot]) -> float:
+    """
+    Calculate the average monthly return from portfolio snapshots.
+
+    The average monthly return is calculated as the mean of all monthly returns.
+
+    Args:
+        snapshots (List[PortfolioSnapshot]): List of portfolio snapshots.
+
+    Returns:
+        float: The average monthly return as a percentage.
+    """
+
+    monthly_returns = get_monthly_returns(snapshots)
+
+    if not monthly_returns:
+        return 0.0
+
+    return sum(r for r, _ in monthly_returns) / len(monthly_returns)
+
+def get_average_monthly_return_winning_months(snapshots: List[PortfolioSnapshot]) -> float:
+    """
+    Calculate the average monthly return from winning months in portfolio snapshots.
+
+    The average monthly return is calculated as the mean of all monthly returns
+    where the return is positive.
+
+    Args:
+        snapshots (List[PortfolioSnapshot]): List of portfolio snapshots.
+
+    Returns:
+        float: The average monthly return from winning months as a percentage.
+    """
+
+    monthly_returns = get_monthly_returns(snapshots)
+    winning_months = [r for r, _ in monthly_returns if r > 0]
+
+    if not winning_months:
+        return 0.0
+
+    return sum(winning_months) / len(winning_months)
+
+def get_average_monthly_return_losing_months(snapshots: List[PortfolioSnapshot]) -> float:
+    """
+    Calculate the average monthly return from losing months in portfolio snapshots.
+
+    The average monthly return is calculated as the mean of all monthly returns
+    where the return is negative.
+
+    Args:
+        snapshots (List[PortfolioSnapshot]): List of portfolio snapshots.
+
+    Returns:
+        float: The average monthly return from losing months as a percentage.
+    """
+
+    monthly_returns = get_monthly_returns(snapshots)
+    losing_months = [r for r, _ in monthly_returns if r < 0]
+
+    if not losing_months:
+        return 0.0
+
+    return sum(losing_months) / len(losing_months)
+
+
+def get_average_yearly_return(snapshots: List[PortfolioSnapshot]) -> float:
+    """
+    Calculate the average yearly return from portfolio snapshots.
+
+    The average yearly return is calculated as the mean of all yearly returns.
+
+    Args:
+        snapshots (List[PortfolioSnapshot]): List of portfolio snapshots.
+
+    Returns:
+        float: The average yearly return as a percentage.
+    """
+
+    yearly_returns = get_yearly_returns(snapshots)
+
+    if not yearly_returns:
+        return 0.0
+
+    return sum(r for r, _ in yearly_returns) / len(yearly_returns)
+
+
+def get_total_return(
+    snapshots: List[PortfolioSnapshot]
+) -> Tuple[float, float]:
+    """
+    Calculate the total return from portfolio snapshots.
+
+    The total return is calculated as the percentage change in portfolio value
+    from the first snapshot to the last snapshot.
+
+    Args:
+        snapshots (List[PortfolioSnapshot]): List of portfolio snapshots.
+
+    Returns:
+        Tuple[Float, Float]: First number is the absolute return and the
+            second number is the percentage total return
+    """
+
+    if not snapshots or len(snapshots) < 2:
+        return 0.0, 0.0
+
+    initial_value = snapshots[0].total_value
+    final_value = snapshots[-1].total_value
+
+    if initial_value == 0:
+        return 0.0, 0.0
+
+    absolute_return = final_value - initial_value
+    percentage = (absolute_return / initial_value)
+    return absolute_return, percentage
+
+
+def get_total_loss(
+    snapshots: List[PortfolioSnapshot]
+) -> Tuple[float, float]:
+    """
+    Calculate the total loss from portfolio snapshots.
+
+    The total loss is calculated as the percentage change in portfolio value
+    from the first snapshot to the last snapshot, only if there is a loss.
+
+    Args:
+        snapshots (List[PortfolioSnapshot]): List of portfolio snapshots.
+
+    Returns:
+        Tuple[Float, Float]: First number is the absolute loss and the
+            second number is the percentage total loss
+    """
+
+    if not snapshots or len(snapshots) < 2:
+        return 0.0, 0.0
+
+    initial_value = snapshots[0].total_value
+    final_value = snapshots[-1].total_value
+
+    if initial_value == 0:
+        return 0.0, 0.0
+
+    absolute_return = final_value - initial_value
+
+    if absolute_return >= 0:
+        return 0.0, 0.0
+
+    percentage = (absolute_return / initial_value)
+    return absolute_return, percentage
+
+
+def get_total_growth(
+    snapshots: List[PortfolioSnapshot]
+) -> Tuple[float, float]:
+    """
+    Calculate the total growth from portfolio snapshots.
+
+    The total return is calculated as the percentage change in portfolio value
+    from the first snapshot to the last snapshot added to the initial value.
+
+    Args:
+        snapshots (List[PortfolioSnapshot]): List of portfolio snapshots.
+
+    Returns:
+        Tuple[Float, Float]: First number is the absolute return and the
+            second number is the percentage total return
+    """
+
+    if not snapshots or len(snapshots) < 2:
+        return 0.0, 0.0
+
+    initial_value = snapshots[0].total_value
+    final_value = snapshots[-1].total_value
+
+    if initial_value == 0:
+        return 0.0, 0.0
+
+    growth = final_value - initial_value
+    growth_percentage = (growth / initial_value)
+    return growth, growth_percentage
+
+
+def get_percentage_winning_years(snapshots: List[PortfolioSnapshot]) -> float:
+    """
+    Calculate the percentage of winning years from portfolio snapshots.
+
+    A winning year is defined as a year where the portfolio value at the end
+    of the year is greater than at the start of the year.
+
+    Args:
+        snapshots (List[PortfolioSnapshot]): List of portfolio snapshots.
+
+    Returns:
+        float: The percentage of winning years.
+    """
+
+    yearly_returns = get_yearly_returns(snapshots)
+    winning_years = sum(1 for r, _ in yearly_returns if r > 0)
+
+    if not yearly_returns:
+        return 0.0
+
+    return winning_years / len(yearly_returns)
+
+
+def get_final_value(snapshots: List[PortfolioSnapshot]) -> float:
+    """
+    Calculate the final portfolio value from portfolio snapshots.
+
+    Args:
+        snapshots (List[PortfolioSnapshot]): List of portfolio snapshots.
+
+    Returns:
+        float: The final portfolio value.
+    """
+
+    if not snapshots:
+        return 0.0
+
+    return snapshots[-1].total_value
+
+
+def get_cumulative_return(snapshots: list[PortfolioSnapshot]) -> float:
+    """
+    Calculate cumulative return over the full period of snapshots.
+    Returns a single float (e.g., 0.25 for +25%).
+    """
+    if len(snapshots) < 2:
+        return 0.0
+
+    # Sort snapshots by date
+    snapshots = sorted(snapshots, key=lambda s: s.created_at)
+
+    start_value = snapshots[0].total_value
+    end_value = snapshots[-1].total_value
+
+    if start_value == 0:
+        return 0.0
+
+    return (end_value / start_value) - 1
+
+
+def get_cumulative_return_series(
+    snapshots: list[PortfolioSnapshot]
+) -> List[Tuple[float, datetime]]:
+    """
+    Calculate cumulative returns from a list of PortfolioSnapshot objects.
+
+    Args:
+        snapshots (list[PortfolioSnapshot]): List of snapshots ordered by time.
+
+    Returns:
+        List[Tuple[float, datetime]]: Cumulative returns for each snapshot.
+    """
+
+    # Ensure snapshots are sorted by date
+    snapshots = sorted(snapshots, key=lambda s: s.get_created_at())
+
+    initial_value = snapshots[0].get_total_value()
+    if initial_value == 0:
+        raise ValueError("Initial portfolio value cannot be zero.")
+
+    cumulative_returns = []
+    for snap in snapshots:
+        cum_return = (snap.get_total_value() / initial_value) - 1
+        cumulative_returns.append((cum_return, snap.created_at))
+
+    return cumulative_returns

investing_algorithm_framework/services/metrics/risk_free_rate.py

@@ -0,0 +1,28 @@
+import yfinance as yf
+import logging
+
+
+logger = logging.getLogger("investing_algorithm_framework")
+
+
+def get_risk_free_rate_us():
+    """
+    Retrieves the US 10-year Treasury yield from Yahoo Finance.
+
+    Returns:
+        float or None: The latest yield as a decimal (e.g., 0.0423 for 4.23%), or None if unavailable.
+    """
+    try:
+        ten_year = yf.Ticker("^TNX")
+        hist = ten_year.history(period="5d")
+
+        if hist.empty or "Close" not in hist.columns:
+            logger.warning("Risk-free rate data is unavailable or malformed.")
+            return None
+
+        latest_yield = hist["Close"].dropna().iloc[-1] / 100
+        return latest_yield
+
+    except Exception as e:
+        logger.warning(f"Could not retrieve risk-free rate: {e}")
+        return None

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           |
+
+"""
+
+import math
+from datetime import datetime
+from typing import List, Tuple
+
+import numpy as np
+import pandas as pd
+
+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