Add doc strings for plot_portfolio.py and plot_signals.py. Bug fix for _buy_and_hold_strategy, since not invested cash was not taken into account.

Author: niklasniedermeier

src/backtest_bay/plot/plot_portfolio.py

@@ -11,19 +11,31 @@
 
 
 def plot_portfolio(portfolio, title, tac, cash):
-    """Main function to plot the portfolio performance and metrics."""
+    """Plots the portfolio performance and associated financial metrics.
+
+    Args:
+        portfolio (pd.DataFrame): A DataFrame containing the portfolio's assets, shares,
+            and prices.
+        title (str): Title of the plot.
+        tac (float): Transaction costs.
+        cash (float): Initial cash.
+
+    Returns:
+        (go.Figure) Figure with portfolio performance and metrics.
+    """
+    # Note that there is no need to validate the inputs 'portfolio', 'tac' and 'cash',
+    # since they are already checked in 'download_data.py' and 'backtest_signals.py".
     portfolio_return = _calculate_portfolio_return(portfolio["assets"])
     annualized_return = _calculate_annualized_return(portfolio["assets"])
     annualized_volatility = _calculate_annualized_volatility(portfolio["assets"])
+    trades = _calculate_trades(portfolio["shares"])
 
-    # Benchmark: Buy and Hold Strategy
     portfolio["buy_and_hold"] = _buy_and_hold_strategy(cash, portfolio["Close"])
     buy_and_hold_return = _calculate_annualized_return(portfolio["buy_and_hold"])
     buy_and_hold_volatility = _calculate_annualized_volatility(
         portfolio["buy_and_hold"]
     )
 
-    trades = _calculate_trades(portfolio["shares"])
     fig = make_subplots(
         rows=2,
         cols=1,
@@ -33,7 +45,10 @@ def plot_portfolio(portfolio, title, tac, cash):
         specs=[[{"type": "xy"}], [{"type": "domain"}]],
     )
 
-    for trace in _create_portfolio_traces(portfolio):
+    portfolio_traces = _create_portfolio_traces(
+        portfolio.index, portfolio["cash"], portfolio["assets"]
+    )
+    for trace in portfolio_traces:
         fig.add_trace(trace, row=1, col=1)
 
     metrics_table = _create_metrics_table(
@@ -52,13 +67,13 @@ def plot_portfolio(portfolio, title, tac, cash):
     return fig
 
 
-def _create_portfolio_traces(portfolio):
+def _create_portfolio_traces(index, cash, assets):
     """Create Plotly traces for cash and assets over time."""
     traces = [
-        go.Scatter(x=portfolio.index, y=portfolio["cash"], mode="lines", name="Cash"),
+        go.Scatter(x=index, y=cash, mode="lines", name="Cash"),
         go.Scatter(
-            x=portfolio.index,
-            y=portfolio["assets"],
+            x=index,
+            y=assets,
             mode="lines",
             name="Assets (Cash + Holdings)",
         ),
@@ -160,6 +175,7 @@ def _calculate_trades(shares):
 
 
 def _calculate_annualized_volatility(stock):
+    """Calculates the annualized volatility for a stock."""
     if len(stock) <= 1:
         return 0
 
@@ -176,10 +192,13 @@ def _calculate_annualized_volatility(stock):
 
 
 def _buy_and_hold_strategy(initial_cash, prices):
+    """Calculates the portfolio development using a buy and hold strategy."""
     first_price = prices.iloc[0]
 
     if first_price == 0:
         return 0
 
     shares = np.floor(initial_cash / first_price)
-    return shares * prices
+    not_invested_cash = initial_cash - shares * first_price
+    portfolio_buy_and_hold = shares * prices + not_invested_cash
+    return portfolio_buy_and_hold

src/backtest_bay/plot/plot_signals.py

@@ -9,19 +9,30 @@
 pd.options.plotting.backend = "plotly"
 
 
-def plot_signals(df, title):
-    """Create Plotly figure to plot trading signals."""
-    df["signal_plot"] = _map_signals_for_plotting(df["signal"])
+def plot_signals(data, title):
+    """Plots trading signals alongside candlestick charts.
+
+    Args:
+        data (pd.DataFrame): A DataFrame containing stock price data and trading
+            signals. Expected columns: "Open", "High","Low","Close","signal".
+        title (str): The title of the plot.
+
+    Returns:
+        (go.Figure): Figure with trading signals alongside candlestick charts.
+    """
+    # Note that there is no need to validate the input 'data', since 'data' is already
+    # checked in 'download_data.py'.
+    data["signal_plot"] = _map_signals_for_plotting(data["signal"])
 
     fig = make_subplots(
         rows=2, cols=1, shared_xaxes=True, row_heights=[0.7, 0.3], vertical_spacing=0.1
     )
 
     fig.add_trace(
-        _create_candlestick_trace(df[["Open", "High", "Low", "Close"]]), row=1, col=1
+        _create_candlestick_trace(data[["Open", "High", "Low", "Close"]]), row=1, col=1
     )
 
-    buy_trace, sell_trace = _create_signal_traces(df["signal_plot"])
+    buy_trace, sell_trace = _create_signal_traces(data["signal_plot"])
     fig.add_trace(buy_trace, row=2, col=1)
     fig.add_trace(sell_trace, row=2, col=1)
 
@@ -38,7 +49,7 @@ def plot_signals(df, title):
         row=2,
         col=1,
         tickvals=[-1, 0, 1],
-        ticktext=["Sell", "Hold", "Buy"],
+        ticktext=["Sell", "", "Buy"],
     )
 
     return fig

tests/plot/test_plot_portfolio.py

@@ -102,6 +102,8 @@ def test_calculate_trades(shares, expected):
     ],
 )
 def test_calculate_annualized_volatility(stock_prices, expected_volatility):
+    """Test if _calculate_annualized_volatility correctly calculates annualized
+    volatility."""
     stock = pd.Series(
         stock_prices, index=pd.date_range(start="2022-01-01", periods=len(stock_prices))
     )
@@ -113,16 +115,15 @@ def test_calculate_annualized_volatility(stock_prices, expected_volatility):
 @pytest.mark.parametrize(
     ("initial_cash", "prices", "expected"),
     [
-        # Standard case with positive prices
-        (100, pd.Series([10, 12, 15, 18]), pd.Series([100.0, 120.0, 150.0, 180.0])),
+        # Enough cash
+        (105, pd.Series([10, 12, 15, 18]), pd.Series([105.0, 125.0, 155.0, 185.0])),
         #  Not enough cash to buy even one share
-        (5, pd.Series([10, 12, 15, 18]), pd.Series([0.0, 0.0, 0.0, 0.0])),
+        (5, pd.Series([10, 12, 15, 18]), pd.Series([5.0, 5.0, 5.0, 5.0])),
         # Cash exactly enough to buy one share
         (10, pd.Series([10, 12, 15, 18]), pd.Series([10.0, 12.0, 15.0, 18.0])),
     ],
 )
-def test_buy_and_hold_strategy(initial_cash, prices, expected):
-    """Test if _calculate_annualized_volatility correctly calculates annualized
-    volatility."""
+def test_buy_and_hold_strategy_correct_calculation(initial_cash, prices, expected):
+    """Test if _buy_and_hold_strategy correctly calculates buy and hold strategy."""
     result = _buy_and_hold_strategy(initial_cash, prices)
     pd.testing.assert_series_equal(result, expected)