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

investing_algorithm_framework/app/reporting/backtest_report.py

@@ -0,0 +1,349 @@
+import logging
+import os
+from pathlib import Path
+import webbrowser
+from dataclasses import dataclass
+from dataclasses import field
+from typing import List, Union
+
+import pandas as pd
+from IPython import get_ipython
+from IPython.display import display, HTML
+from jinja2 import Environment, FileSystemLoader
+
+from investing_algorithm_framework.domain import TimeFrame, Backtest, \
+    OperationalException, BacktestDateRange
+from .charts import get_equity_curve_with_drawdown_chart, \
+    get_rolling_sharpe_ratio_chart, get_monthly_returns_heatmap_chart, \
+    get_yearly_returns_bar_chart, get_ohlcv_data_completeness_chart
+from .tables import create_html_time_metrics_table, \
+    create_html_trade_metrics_table, create_html_key_metrics_table, \
+    create_html_trades_table
+
+logger = logging.getLogger("investing_algorithm_framework")
+
+
+def get_symbol_from_file_name(file_name: str) -> str:
+    """
+    Extract the symbol from the file name.
+
+    Args:
+        file_name (str): The file name from which to extract the symbol.
+
+    Returns:
+        str: The extracted symbol.
+    """
+    # Assuming the file name format is "symbol_timeframe.csv"
+    return file_name.split('_')[0].upper()
+
+def get_market_from_file_name(file_name: str) -> str:
+    """
+    Extract the market from the file name.
+
+    Args:
+        file_name (str): The file name from which to extract the market.
+
+    Returns:
+        str: The extracted market.
+    """
+    # Assuming the file name format is "symbol_market_timeframe.csv"
+    parts = file_name.split('_')
+    if len(parts) < 2:
+        raise ValueError("File name does not contain a valid market.")
+    return parts[1].upper()
+
+
+def get_time_frame_from_file_name(file_name: str) -> TimeFrame:
+    """
+    Extract the time frame from the file name.
+
+    Args:
+        file_name (str): The file name from which to extract the time frame.
+
+    Returns:
+        TimeFrame: The extracted time frame.
+    """
+    parts = file_name.split('_')
+
+    if len(parts) < 3:
+        raise ValueError(
+            "File name does not contain a valid time frame."
+        )
+    time_frame_str = parts[3]
+
+    try:
+        return TimeFrame.from_string(time_frame_str)
+    except ValueError:
+        raise ValueError(
+            f"Could not extract time frame from file name: {file_path}. "
+            f"Expected format 'OHLCV_<SYMBOL>_<MARKET>_<TIME_FRAME>_<START_DATE>_<END_DATE>.csv', "
+            f"got '{time_frame_str}'."
+        )
+
+
+@dataclass
+class BacktestReport:
+    """
+    A class to represent a backtest report. The backtest report contains
+    the results of a backtest, including metrics and an HTML report. Also,
+    it stores the path to the used strategy directory, which can be used to
+    load the strategy code later.
+
+    Attributes:
+        html_report (str): The HTML report content.
+        html_report_path (str): The file path where the HTML report is saved.
+        metrics (dict): A dictionary containing various metrics from the backtest.
+        results (BacktestResult): An instance of BacktestResult containing
+            the results of the backtest.
+        risk_free_rate (float): The risk-free rate used in the backtest.
+        strategy_path (str): The path to the strategy directory used in the
+            backtest.
+    """
+    backtest: Backtest = None
+    html_report: str = None
+    html_report_path: str = None
+
+    def show(
+        self,
+        backtest_date_range: BacktestDateRange,
+        browser: bool = False
+    ):
+        """
+        Display the HTML report in a Jupyter notebook cell.
+        """
+
+        if not self.html_report:
+            # If the HTML report is not created, create it
+            self._create_html_report(backtest_date_range)
+
+        # Save the html report to a tmp location
+        path = "/tmp/backtest_report.html"
+        with open(path, "w") as html_file:
+            html_file.write(self.html_report)
+
+        if browser:
+            webbrowser.open(f"file://{path}")
+
+        def in_jupyter_notebook():
+            try:
+                shell = get_ipython().__class__.__name__
+                return shell == 'ZMQInteractiveShell'
+            except (NameError, ImportError):
+                return False
+
+        if in_jupyter_notebook():
+            display(HTML(self.html_report))
+        else:
+            webbrowser.open(f"file://{path}")
+
+    def _create_html_report(self, backtest_date_range: BacktestDateRange):
+        """
+        Create an HTML report from the backtest metrics and results.
+
+        This method generates various charts and tables from the backtest
+        metrics and results, and renders them into an HTML template using
+        Jinja2.
+
+        Raises:
+            OperationalException: If no backtests are available to
+                create a report.
+
+        Returns:
+            None
+        """
+        # Get the first backtest
+        if not self.backtest:
+            raise OperationalException(
+                "No backtest available to create a report."
+            )
+
+
+        metrics = self.backtest.get_backtest_metrics(backtest_date_range)
+        run = self.backtest.get_backtest_run(backtest_date_range)
+        # Create plots
+        equity_with_drawdown_fig = get_equity_curve_with_drawdown_chart(
+            metrics.equity_curve, metrics.drawdown_series
+        )
+        equity_with_drawdown_plot_html = equity_with_drawdown_fig.to_html(
+            full_html=False, include_plotlyjs='cdn',
+            config={'responsive': True}, default_width="90%"
+        )
+        rolling_sharpe_ratio_fig = get_rolling_sharpe_ratio_chart(
+            metrics.rolling_sharpe_ratio
+        )
+        rolling_sharpe_ratio_plot_html = rolling_sharpe_ratio_fig.to_html(
+            full_html=False, include_plotlyjs='cdn',
+            config={'responsive': True}, default_width="90%"
+        )
+        monthly_returns_heatmap_fig = get_monthly_returns_heatmap_chart(
+            metrics.monthly_returns
+        )
+        monthly_returns_heatmap_html = monthly_returns_heatmap_fig.to_html(
+            full_html=False, include_plotlyjs='cdn',
+            config={'responsive': True}
+        )
+        yearly_returns_histogram_fig = get_yearly_returns_bar_chart(
+            metrics.yearly_returns
+        )
+        yearly_returns_histogram_html = yearly_returns_histogram_fig.to_html(
+            full_html=False, include_plotlyjs='cdn',
+            config={'responsive': True}
+        )
+
+        # Create OHLCV data completeness charts
+        data_files = []
+        ohlcv_data_completeness_charts_html = ""
+
+        for file in data_files:
+            try:
+                if file.endswith('.csv'):
+                    df = pd.read_csv(file, parse_dates=['Datetime'])
+                    file_name = os.path.basename(file)
+                    symbol = get_symbol_from_file_name(file_name)
+                    market = get_market_from_file_name(file_name)
+                    time_frame = get_time_frame_from_file_name(file_name)
+                    title = f"OHLCV Data Completeness for {market} - {symbol} - {time_frame.value}"
+                    ohlcv_data_completeness_chart_html = \
+                        get_ohlcv_data_completeness_chart(
+                            df,
+                            timeframe=time_frame.value,
+                            windowsize=200,
+                            title=title
+                        )
+
+                    ohlcv_data_completeness_charts_html += (
+                        '<div class="ohlcv-data-completeness-chart">'
+                        f'{ohlcv_data_completeness_chart_html}'
+                        '</div>'
+                    )
+
+            except Exception as e:
+                logger.warning(
+                    "Error creating OHLCV data completeness " +
+                    f"chart for {file}: {e}"
+                )
+                continue
+
+        # Create HTML tables
+        key_metrics_table_html = create_html_key_metrics_table(
+            metrics, run
+        )
+        trades_metrics_table_html = create_html_trade_metrics_table(
+            metrics, run
+        )
+        time_metrics_table_html = create_html_time_metrics_table(
+            metrics, run
+        )
+        trades_table_html = create_html_trades_table(run)
+
+        # Jinja2 environment setup
+        template_dir = os.path.join(os.path.dirname(__file__), 'templates')
+        env = Environment(loader=FileSystemLoader(template_dir))
+        template = env.get_template('report_template.html.j2')
+
+        # Render template with variables
+        html_rendered = template.render(
+            report=run,
+            equity_with_drawdown_plot_html=equity_with_drawdown_plot_html,
+            rolling_sharpe_ratio_plot_html=rolling_sharpe_ratio_plot_html,
+            monthly_returns_heatmap_html=monthly_returns_heatmap_html,
+            yearly_returns_histogram_html=yearly_returns_histogram_html,
+            key_metrics_table_html=key_metrics_table_html,
+            trades_metrics_table_html=trades_metrics_table_html,
+            time_metrics_table_html=time_metrics_table_html,
+            trades_table_html=trades_table_html,
+            data_completeness_charts_html=ohlcv_data_completeness_charts_html
+        )
+        self.html_report = html_rendered
+
+    @staticmethod
+    def _load_backtest(backtest_path: str) -> Backtest:
+        """
+        Load the backtest from a give path
+        and return an instance of Backtest.
+
+        Args:
+            backtest_path (str): The path to the backtest directory.
+
+        Returns:
+            Backtest: An instance of Backtest loaded from the
+                backtest directory.
+        """
+        return Backtest.open(backtest_path)
+
+    @staticmethod
+    def _is_backtest(backtest_path: Union[str, Path]) -> bool:
+        """
+        Check if the given path is a valid backtest report directory.
+
+        Args:
+            backtest_path (Union[str, Path]): The path to check.
+
+        Returns:
+            bool: True if the path is a valid backtest report directory,
+                False otherwise.
+        """
+        return (
+            os.path.exists(backtest_path) and
+            os.path.isdir(backtest_path) and
+            os.path.isfile(os.path.join(backtest_path, "results.json"))
+            and os.path.isfile(os.path.join(backtest_path, "metrics.json"))
+        )
+
+    @staticmethod
+    def open(
+        backtests: List[Backtest] = [],
+        directory_path=None
+    ) -> "BacktestReport":
+        """
+        Open the backtest report from a file.
+
+        Args:
+            backtests (List[Backtest], optional): A list of Backtest instances
+                to include in the report. If provided, it will use these
+                backtests as part of the report.
+            directory_path (str, optional): The directory path from
+                which the reports will be loaded.
+
+        Returns:
+            BacktestReport: An instance of BacktestReport loaded from the file.
+
+        Raises:
+            OperationalException: If the backtest path is not a valid backtest
+                report directory.
+        """
+        loaded_backtests = []
+
+        if directory_path is not None:
+            # Check if the directory is a valid backtest report directory
+            if BacktestReport._is_backtest(directory_path):
+                backtests.append(
+                    Backtest.open(directory_path)
+                )
+            else:
+                # Loop over all subdirectories
+                for root, dirs, _ in os.walk(directory_path):
+                    for dir_name in dirs:
+                        subdir_path = os.path.join(root, dir_name)
+                        if BacktestReport._is_backtest(subdir_path):
+                            loaded_backtests.append(
+                                Backtest.open(directory_path=subdir_path)
+                            )
+
+        if len(backtests) > 0:
+
+            for backtest in backtests:
+                if not isinstance(backtest, Backtest):
+                    raise OperationalException(
+                        "The provided backtest is not a valid Backtest instance."
+                    )
+
+            # Add the backtests to the backtests list
+            loaded_backtests.extend(backtests)
+
+        if len(loaded_backtests) == 0:
+            raise OperationalException(
+                f"The directory {directory_path} is not a valid backtest report."
+            )
+
+        return BacktestReport(backtest=loaded_backtests)

investing_algorithm_framework/app/reporting/charts/__init__.py

@@ -0,0 +1,19 @@
+from .equity_curve_drawdown import get_equity_curve_with_drawdown_chart
+from .equity_curve import get_equity_curve_chart
+from .rolling_sharp_ratio import get_rolling_sharpe_ratio_chart
+from .monthly_returns_heatmap import get_monthly_returns_heatmap_chart
+from .yearly_returns_barchart import get_yearly_returns_bar_chart
+from .ohlcv_data_completeness import get_ohlcv_data_completeness_chart
+from .entry_exist_signals import get_entry_and_exit_signals
+from .line_chart import create_line_scatter
+
+__all__ = [
+    "get_equity_curve_with_drawdown_chart",
+    "get_rolling_sharpe_ratio_chart",
+    "get_monthly_returns_heatmap_chart",
+    "get_yearly_returns_bar_chart",
+    "get_ohlcv_data_completeness_chart",
+    "get_entry_and_exit_signals",
+    "create_line_scatter",
+    "get_equity_curve_chart"
+]

investing_algorithm_framework/app/reporting/charts/entry_exist_signals.py

@@ -0,0 +1,66 @@
+import pandas as pd
+import plotly.graph_objects as go
+
+
+def get_entry_and_exit_signals(
+    entry_signals: pd.Series,
+    exit_signals: pd.Series,
+    price_data: pd.DataFrame
+):
+    """
+    Plots the price chart with entry and exit signals.
+
+    Args:
+        entry_signals (pd.Series): Series containing buy
+            signals with datetime index. Entry signals should
+            be boolean values.
+        exit_signals (pd.Series): Series containing exit signals
+            with datetime index. Exit signals should be boolean values.
+        price_data (pd.DataFrame): DataFrame containing price
+            data with datetime index and 'Close'
+
+    Returns:
+        go.Figure: Plotly figure with price chart and signals.
+    """
+    # Create the base candlestick or line chart
+    fig = go.Figure()
+
+    fig.add_trace(go.Scatter(
+        x=price_data.index,
+        y=price_data["Close"],
+        mode="lines",
+        name="Close Price",
+        line=dict(color="blue")
+    ))
+
+    # Entry points
+    entry_points = price_data[entry_signals]
+    fig.add_trace(go.Scatter(
+        x=entry_points.index,
+        y=entry_points["Close"],
+        mode="markers",
+        name="Entry",
+        marker=dict(symbol="triangle-up", color="green", size=10)
+    ))
+
+    # Exit points
+    exit_points = price_data[exit_signals]
+    fig.add_trace(go.Scatter(
+        x=exit_points.index,
+        y=exit_points["Close"],
+        mode="markers",
+        name="Exit",
+        marker=dict(symbol="triangle-down", color="red", size=10)
+    ))
+
+    # Layout settings
+    fig.update_layout(
+        title="Entry and Exit Signals",
+        xaxis_title="Date",
+        yaxis_title="Price",
+        legend=dict(x=0, y=1),
+        height=600,
+        template="plotly_white"
+    )
+
+    return fig

investing_algorithm_framework/app/reporting/charts/equity_curve.py

@@ -0,0 +1,37 @@
+import pandas as pd
+from plotly import graph_objects as go
+
+
+def get_equity_curve_chart(equity_curve_series):
+    equity_curve_df = pd.DataFrame(
+        equity_curve_series, columns=["value", "datetime"]
+    )
+
+    # Normalize equity to start at 1
+    equity_curve_df["value"] = (
+        equity_curve_df["value"] / equity_curve_df["value"].iloc[0]
+    )
+
+    fig = go.Figure()
+
+    # Draw equity curve
+    fig.add_trace(
+        go.Scatter(
+            x=equity_curve_df["datetime"],
+            y=equity_curve_df["value"],
+            mode="lines",
+            line=dict(color="rgba(0, 128, 0, 0.8)", width=1),
+            name="Equity Curve",
+            hovertemplate="<b>Equity</b><br>%{x}<br>Value: %{y:.2f}<extra></extra>"
+        )
+    )
+
+    fig.update_layout(
+        xaxis=dict(title=None),
+        yaxis=dict(title="Cumulative Equity (log)", type="log"),
+        title="Equity Curve with Drawdown",
+        hovermode="x unified",
+        legend=dict(orientation="h", yanchor="bottom", y=1.02, xanchor="right", x=1)
+    )
+
+    return fig

investing_algorithm_framework/app/reporting/charts/equity_curve_drawdown.py

@@ -0,0 +1,74 @@
+import pandas as pd
+from plotly.subplots import make_subplots
+from plotly import graph_objects as go
+
+
+def get_equity_curve_with_drawdown_chart(equity_curve_series, drawdown_series):
+    equity_curve_df = pd.DataFrame(
+        equity_curve_series, columns=["value", "datetime"]
+    )
+    drawdown_df = pd.DataFrame(
+        drawdown_series, columns=["value", "datetime"]
+    )
+
+    # Normalize equity to start at 1
+    equity_curve_df["value"] = (
+        equity_curve_df["value"] / equity_curve_df["value"].iloc[0]
+    )
+
+    fig = make_subplots(
+        rows=2,
+        cols=1,
+        shared_xaxes=True,
+        vertical_spacing=0.05,
+        row_heights=[0.7, 0.3],
+        subplot_titles=["", ""]
+    )
+
+    # Draw equity curve
+    fig.add_trace(
+        go.Scatter(
+            x=equity_curve_df["datetime"],
+            y=equity_curve_df["value"],
+            mode="lines",
+            line=dict(color="rgba(0, 128, 0, 0.8)", width=1),
+            name="Equity Curve",
+            hovertemplate="<b>Equity</b><br>%{x}<br>Value: %{y:.2f}<extra></extra>"
+        ),
+        row=1,
+        col=1
+    )
+
+    # Drawdown area
+    fig.add_trace(
+        go.Scatter(
+            x=drawdown_df["datetime"],
+            y=drawdown_df["value"],
+            mode="lines",
+            fill="tozeroy",
+            fillcolor="rgba(255, 99, 71, 0.3)",
+            line=dict(color="rgba(255, 99, 71, 0.8)", width=1),
+            name="Drawdown"
+        ),
+        row=2,
+        col=1
+    )
+
+    # Final layout
+    fig.update_layout(
+        xaxis=dict(title=None),
+        yaxis=dict(title="Cumulative Equity (log)", type="log"),
+        xaxis2=dict(title=None),
+        yaxis2=dict(
+            title="Drawdown",
+            tickformat=".0%",
+            tickvals=[-0.2, -0.15, -0.1, -0.05, 0]  # Clean % ticks
+        ),
+        template="plotly_white",
+        height=600,
+        showlegend=False,
+        hovermode="x unified",  # Enables vertical hover line
+        margin=dict(l=0, r=0, t=0, b=0),
+    )
+
+    return fig

investing_algorithm_framework/app/reporting/charts/line_chart.py

@@ -0,0 +1,11 @@
+import plotly.graph_objects as go
+
+
+def create_line_scatter(x, y, name, colour = 'blue'):
+    return go.Scatter(
+        x=x,
+        y=y,
+        mode='lines',
+        name=name,
+        line=dict(color=colour)
+    )

investing_algorithm_framework/app/reporting/charts/monthly_returns_heatmap.py

@@ -0,0 +1,70 @@
+import pandas as pd
+import plotly.graph_objects as go
+
+
+def get_monthly_returns_heatmap_chart(monthly_return_series):
+    df = pd.DataFrame(monthly_return_series, columns=["Return", "Timestamp"])
+    df["Timestamp"] = pd.to_datetime(df["Timestamp"], errors='coerce')
+    df["Year"] = df["Timestamp"].dt.year
+    df["Month"] = df["Timestamp"].dt.strftime("%b")
+
+    month_order = ["Jan", "Feb", "Mar", "Apr", "May", "Jun",
+                   "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"]
+    df["Month"] = pd.Categorical(
+        df["Month"], categories=month_order, ordered=True
+    )
+
+    # Ensure all months are present for each year
+    all_years = df["Year"].unique()
+    all_months = pd.DataFrame(
+        [(year, month) for year in all_years for month in month_order],
+        columns=["Year", "Month"]
+    )
+    df = pd.merge(
+        all_months,
+        df,
+        on=["Year", "Month"],
+        how="left"
+    ).fillna({"Return": 0.0})
+
+    # Pivot to matrix form
+    pivot_df = df.pivot(index="Year", columns="Month", values="Return")
+    pivot_df = pivot_df.reindex(columns=month_order)
+    pivot_df = pivot_df.sort_index(ascending=True)  # Change to ascending order
+
+    z = pivot_df.values
+    text = [
+        [f"{v * 100:.2f}%" if pd.notna(v) else "" for v in row] for row in z
+    ]
+    hover_template = "Year %{y}<br>Month %{x}<br>" + \
+        "Return: %{z:.2%}<extra></extra>"
+    fig = go.Figure(data=go.Heatmap(
+        z=z,
+        x=pivot_df.columns,
+        y=pivot_df.index,
+        text=text,
+        texttemplate="%{text}",
+        textfont={"size": 12},
+        colorscale="RdYlGn",
+        showscale=False,
+        hovertemplate=hover_template,
+        zmin=-0.1,
+        zmax=0.1
+    ))
+
+    fig.update_layout(
+        title="Monthly Returns Heatmap (%)",
+        xaxis_title="Month",
+        yaxis=dict(
+            title=None,
+            tickmode='array',
+            tickvals=list(pivot_df.index),
+            ticktext=[str(year) for year in pivot_df.index],
+            autorange=True  # Remove 'reversed' to match ascending order
+        ),
+        template="plotly_white",
+        margin=dict(l=0, r=0, t=40, b=20),
+        height=350,
+        showlegend=False
+    )
+    return fig

investing_algorithm_framework/app/reporting/charts/ohlcv_data_completeness.py

@@ -0,0 +1,51 @@
+import plotly.graph_objects as go
+import pandas as pd
+import plotly.io as pio
+
+def get_ohlcv_data_completeness_chart(
+    df,
+    timeframe='1min',
+    windowsize=100,
+    title="OHLCV Data completenes"
+):
+    df = df.copy()
+    df['Datetime'] = pd.to_datetime(df['Datetime'])
+    df = df.sort_values('Datetime').tail(windowsize)
+    start = df['Datetime'].iloc[0]
+    end = df['Datetime'].iloc[-1]
+    freq = pd.to_timedelta(timeframe)
+    expected = pd.date_range(start, end, freq=freq)
+    actual = df['Datetime']
+    missing = expected.difference(actual)
+
+    # Calculte the percentage completeness
+    completeness = len(actual) / len(expected) * 100
+    title += f" ({completeness:.2f}% complete)"
+    fig = go.Figure()
+    fig.add_trace(
+        go.Scatter(
+            x=actual,
+            y=[1]*len(actual),
+            mode='markers',
+            name='Present',
+            marker=dict(color='green', size=6)
+        )
+    )
+    fig.add_trace(
+        go.Scatter(
+            x=missing,
+            y=[1]*len(missing),
+            mode='markers',
+            name='Missing',
+            marker=dict(color='red', size=6, symbol='x')
+        )
+    )
+    fig.update_layout(
+        title=title,
+        xaxis_title='Datetime',
+        yaxis=dict(showticklabels=False),
+        height=300,
+        showlegend=True
+    )
+
+    return pio.to_html(fig, full_html=False, include_plotlyjs='cdn')