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

investing_algorithm_framework/{app/reporting → services}/metrics/returns.py

@@ -3,7 +3,8 @@ from datetime import datetime, date
 
 import pandas as pd
 
-from investing_algorithm_framework.domain import PortfolioSnapshot, Trade
+from investing_algorithm_framework.domain import PortfolioSnapshot, Trade, \
+    OperationalException
 
 
 def get_monthly_returns(snapshots: List[PortfolioSnapshot]) -> List[Tuple[float, datetime]]:
@@ -51,7 +52,7 @@ def get_yearly_returns(snapshots: List[PortfolioSnapshot]) -> List[Tuple[float,
         snapshots (List[PortfolioSnapshot]): List of portfolio snapshots.
 
     Returns:
-        List[Tuple[float, datetime]]: A list of tuples containing the yearly return
+        List[Tuple[float, date]]: A list of tuples containing the yearly return
             and the corresponding year.
     """
 
@@ -62,6 +63,10 @@ def get_yearly_returns(snapshots: List[PortfolioSnapshot]) -> List[Tuple[float,
     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()
@@ -75,127 +80,6 @@ def get_yearly_returns(snapshots: List[PortfolioSnapshot]) -> List[Tuple[float,
     return yearly_returns
 
 
-def get_average_loss(trades: List[Trade]) -> Tuple[float, float]:
-    """
-    Calculate the average loss from a list of trades
-
-    The average loss is calculated as the mean of all negative returns.
-
-    Args:
-        trades (List[Trade]): List of trades.
-
-    Returns:
-        Tuple[float, float]: The average loss
-        percentage of the average loss
-    """
-
-    losses = [t.net_gain for t in trades if t.net_gain < 0]
-    cost = sum(t.cost for t in trades if t.net_gain < 0)
-
-    if not losses:
-        return 0.0, 0.0
-
-    average_loss = sum(losses) / len(losses)
-    percentage = (average_loss / cost) * 100 if cost > 0 else 0.0
-    return average_loss, percentage
-
-
-def get_average_gain(trades: List[Trade]) -> Tuple[float, float]:
-    """
-    Calculate the average gain from a list of trades.
-
-    The average gain is calculated as the mean of all positive returns.
-
-    Args:
-        trades (List[Trade]): List of trades.
-
-    Returns:
-        Tuple[float, float]: The average gain
-        percentage of the average loss
-    """
-
-    gains = [t.net_gain for t in trades if t.net_gain > 0]
-    cost = sum(t.cost for t in trades if t.net_gain > 0)
-
-    if not gains:
-        return 0.0, 0.0
-
-    average_gain = sum(gains) / len(gains)
-    percentage = (average_gain / cost) * 100 if cost > 0 else 0.0
-    return average_gain, percentage
-
-
-def get_best_trade(trades: List[Trade]) -> Trade:
-    """
-    Get the trade with the highest net gain.
-
-    Args:
-        trades (List[Trade]): List of trades.
-
-    Returns:
-        Trade: The trade with the highest net gain.
-    """
-
-    if not trades:
-        return None
-
-    return max(trades, key=lambda t: t.net_gain)
-
-def get_best_trade_date(trades: List[Trade]) -> Tuple[float, datetime]:
-    """
-    Get the date of the trade with the highest net gain.
-
-    Args:
-        trades (List[Trade]): List of trades.
-
-    Returns:
-        Tuple[float, datetime]: The highest net gain and the corresponding trade date.
-    """
-
-    best_trade = get_best_trade(trades)
-
-    if best_trade is None:
-        return 0.0, None
-
-    return best_trade.closed_at
-
-
-def get_worst_trade_date(trades: List[Trade]) -> Tuple[float, datetime]:
-    """
-    Get the date of the trade with the lowest net gain (worst trade).
-
-    Args:
-        trades (List[Trade]): List of trades.
-
-    Returns:
-        Tuple[float, datetime]: The lowest net gain and the corresponding trade date.
-    """
-
-    worst_trade = get_worst_trade(trades)
-
-    if worst_trade is None:
-        return 0.0, None
-
-    return worst_trade.closed_at
-
-
-def get_worst_trade(trades: List[Trade]) -> Trade:
-    """
-    Get the trade with the lowest net gain (worst trade).
-
-    Args:
-        trades (List[Trade]): List of trades.
-
-    Returns:
-        Trade: The trade with the lowest net gain.
-    """
-
-    if not trades:
-        return None
-
-    return min(trades, key=lambda t: t.net_gain)
-
-
 def get_percentage_winning_months(snapshots: List[PortfolioSnapshot]) -> float:
     """
     Calculate the percentage of winning months from portfolio snapshots.
@@ -216,7 +100,7 @@ def get_percentage_winning_months(snapshots: List[PortfolioSnapshot]) -> float:
     if not monthly_returns:
         return 0.0
 
-    return (winning_months / len(monthly_returns)) * 100
+    return (winning_months / len(monthly_returns))
 
 
 def get_best_month(snapshots: List[PortfolioSnapshot]) -> Tuple[float, datetime]:
@@ -271,12 +155,14 @@ def get_best_year(
     yearly_returns = get_yearly_returns(snapshots)
 
     if not yearly_returns:
-        return 0.0, None
+        return None, None
 
     return max(yearly_returns, key=lambda x: x[0])
 
 
-def get_worst_year(snapshots: List[PortfolioSnapshot]) -> Tuple[float, datetime]:
+def get_worst_year(
+    snapshots: List[PortfolioSnapshot]
+) -> Tuple[float, date]:
     """
     Get the worst year in terms of return from portfolio snapshots.
 
@@ -290,7 +176,7 @@ def get_worst_year(snapshots: List[PortfolioSnapshot]) -> Tuple[float, datetime]
     yearly_returns = get_yearly_returns(snapshots)
 
     if not yearly_returns:
-        return 0.0, None
+        return None, None
 
     return min(yearly_returns, key=lambda x: x[0])
 
@@ -313,7 +199,7 @@ def get_average_monthly_return(snapshots: List[PortfolioSnapshot]) -> float:
     if not monthly_returns:
         return 0.0
 
-    return sum(r for r, _ in monthly_returns) / len(monthly_returns) * 100  # Convert to percentage
+    return sum(r for r, _ in monthly_returns) / len(monthly_returns)
 
 def get_average_monthly_return_winning_months(snapshots: List[PortfolioSnapshot]) -> float:
     """
@@ -335,7 +221,7 @@ def get_average_monthly_return_winning_months(snapshots: List[PortfolioSnapshot]
     if not winning_months:
         return 0.0
 
-    return sum(winning_months) / len(winning_months) * 100  # Convert to percentage
+    return sum(winning_months) / len(winning_months)
 
 def get_average_monthly_return_losing_months(snapshots: List[PortfolioSnapshot]) -> float:
     """
@@ -357,7 +243,7 @@ def get_average_monthly_return_losing_months(snapshots: List[PortfolioSnapshot])
     if not losing_months:
         return 0.0
 
-    return sum(losing_months) / len(losing_months) * 100  # Convert to percentage
+    return sum(losing_months) / len(losing_months)
 
 
 def get_average_yearly_return(snapshots: List[PortfolioSnapshot]) -> float:
@@ -378,10 +264,12 @@ def get_average_yearly_return(snapshots: List[PortfolioSnapshot]) -> float:
     if not yearly_returns:
         return 0.0
 
-    return sum(r for r, _ in yearly_returns) / len(yearly_returns) * 100  # Convert to percentage
+    return sum(r for r, _ in yearly_returns) / len(yearly_returns)
 
 
-def get_total_return(snapshots: List[PortfolioSnapshot]) -> float:
+def get_total_return(
+    snapshots: List[PortfolioSnapshot]
+) -> Tuple[float, float]:
     """
     Calculate the total return from portfolio snapshots.
 
@@ -392,19 +280,88 @@ def get_total_return(snapshots: List[PortfolioSnapshot]) -> float:
         snapshots (List[PortfolioSnapshot]): List of portfolio snapshots.
 
     Returns:
-        float: The total return as a percentage.
+        Tuple[Float, Float]: First number is the absolute return and the
+            second number is the percentage total return
     """
 
-    if not snapshots:
-        return 0.0
+    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
+        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
 
-    return ((final_value - initial_value) / initial_value) * 100
+    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:
@@ -427,27 +384,69 @@ def get_percentage_winning_years(snapshots: List[PortfolioSnapshot]) -> float:
     if not yearly_returns:
         return 0.0
 
-    return (winning_years / len(yearly_returns)) * 100
+    return winning_years / len(yearly_returns)
 
 
-def get_total_net_gain(snapshots: List[PortfolioSnapshot]) -> float:
+def get_final_value(snapshots: List[PortfolioSnapshot]) -> float:
     """
-    Calculate the total net gain from portfolio snapshots.
-
-    The total net gain is calculated as the difference between the final
-    portfolio value and the initial portfolio value.
+    Calculate the final portfolio value from portfolio snapshots.
 
     Args:
         snapshots (List[PortfolioSnapshot]): List of portfolio snapshots.
 
     Returns:
-        float: The total net gain.
+        float: The final portfolio value.
     """
 
     if not snapshots:
         return 0.0
 
-    initial_value = snapshots[0].total_value
-    final_value = snapshots[-1].total_value
+    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 final_value - initial_value
+    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/{app/reporting/metrics/sharp_ratio.py → services/metrics/sharpe_ratio.py}

@@ -49,16 +49,15 @@ from typing import Optional, List, Tuple
 import math
 import pandas as pd
 import numpy as np
-from datetime import datetime, timedelta
+from datetime import datetime
 
 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_daily_returns_std
 
 
 def get_sharpe_ratio(
-    snapshots: List[PortfolioSnapshot], risk_free_rate: Optional[float] = None,
+    snapshots: List[PortfolioSnapshot], risk_free_rate: float,
 ) -> float:
     """
     Calculate the Sharpe Ratio from a backtest report using daily or
@@ -79,8 +78,8 @@ def get_sharpe_ratio(
     mean_daily_return = get_mean_daily_return(snapshots)
     std_daily_return = get_daily_returns_std(snapshots)
 
-    if risk_free_rate is None:
-        risk_free_rate = get_risk_free_rate_us()
+    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))
@@ -89,21 +88,18 @@ def get_sharpe_ratio(
 
 
 def get_rolling_sharpe_ratio(
-    snapshots: List[PortfolioSnapshot], risk_free_rate: Optional[float] = None
+    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, optional): Annualized risk-free rate (e.g., 0.03 for 3%).
+        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).
     """
-    if risk_free_rate is None:
-        risk_free_rate = get_risk_free_rate_us()
-
     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'])

investing_algorithm_framework/{app/reporting → services}/metrics/sortino_ratio.py

@@ -30,7 +30,7 @@ from .standard_deviation import get_downside_std_of_daily_returns
 
 
 def get_sortino_ratio(
-    snapshots: List[PortfolioSnapshot], risk_free_rate: Optional[float] = None,
+    snapshots: List[PortfolioSnapshot], risk_free_rate: float
 ) -> float:
     """
     Calculate the Sortino Ratio for a given report.
@@ -46,9 +46,8 @@ def get_sortino_ratio(
     Args:
         snapshots (List[PortfolioSnapshot]): List of portfolio snapshots
             from the backtest report.
-        risk_free_rate (float, optional): Annual risk-free rate as a decimal
-            (e.g., 0.047 for 4.7%). If not provided, defaults to the US risk-free
-            rate.
+        risk_free_rate (float): Annual risk-free rate as a decimal
+            (e.g., 0.047 for 4.7%).
 
     Returns:
         float: The Sortino Ratio.
@@ -61,9 +60,6 @@ def get_sortino_ratio(
     mean_daily_return = get_mean_daily_return(snapshots)
     std_downside_daily_return = get_downside_std_of_daily_returns(snapshots)
 
-    if risk_free_rate is None:
-        risk_free_rate = get_risk_free_rate_us()
-
     if std_downside_daily_return == 0:
         return float('nan')  # or 0.0, depending on preference