back-trader-python 1.4.0__py3-none-any.whl

backtrader/analyzers/vwr.py

@@ -0,0 +1,245 @@
+#!/usr/bin/env python
+"""VWR Analyzer Module - Variability-Weighted Return calculation.
+
+This module provides the VWR (Variability-Weighted Return) analyzer,
+an alternative to the Sharpe ratio using log returns.
+
+Classes:
+    VWR: Analyzer that calculates VWR metric.
+
+Example:
+    >>> cerebro = bt.Cerebro()
+    >>> cerebro.addanalyzer(bt.analyzers.VWR, _name='vwr')
+    >>> results = cerebro.run()
+    >>> print(results[0].analyzers.vwr.get_analysis())
+"""
+
+import math
+
+from ..analyzer import TimeFrameAnalyzerBase
+from ..dataseries import TimeFrame
+from ..mathsupport import standarddev
+from ..metabase import OwnerContext
+from .returns import Returns
+
+
+# Get VWR indicator
+class VWR(TimeFrameAnalyzerBase):
+    """Variability-Weighted Return: Better SharpeRatio with Log Returns
+
+    Alias:
+
+      - VariabilityWeightedReturn
+
+    See:
+
+      - https://www.crystalbull.com/sharpe-ratio-better-with-log-returns/
+
+    Params:
+
+      - ``timeframe`` (default: ``None``)
+        If ``None`` then the complete return over the entire backtested period
+        will be reported
+
+        Pass ``TimeFrame.NoTimeFrame`` to consider the entire dataset with no
+        time constraints
+
+      - ``compression`` (default: ``None``)
+
+        Only used for sub-day timeframes to, for example, work on an hourly
+        timeframe by specifying "TimeFrame.Minutes" and 60 as compression
+
+        If `None`, then the compression of the first data in the system will be
+        used
+
+      - ``tann`` (default: ``None``)
+
+        Number of periods to use for the annualization (normalization) of the
+        average returns. If ``None``, then standard ``t`` values will be used,
+        namely:
+
+          - ``days: 252``
+          - ``weeks: 52``
+          - ``months: 12``
+          - ``years: 1``
+
+      - ``tau`` (default: ``2.0``)
+
+        Factor for the calculation (see the literature)
+
+      - ``sdev_max`` (default: ``0.20``)
+
+        Max standard deviation (see the literature)
+
+      - ``fund`` (default: ``None``)
+
+        If `None`, the actual mode of the broker (fundmode - True/False) will
+        be autodetected to decide if the returns are based on the total net
+        asset value or on the fund value. See ``set_fundmode`` in the broker
+        documentation
+
+        Set it to ``True`` or ``False`` for a specific behavior
+
+    Methods:
+
+      - Get_analysis
+
+        Returns a dictionary with returns as values and the datetime points for
+        each return as keys
+
+        The returned dict contains the following keys:
+
+          - ``vwr``: Variability-Weighted Return
+    """
+
+    # Parameters
+    params = (
+        ("tann", None),
+        ("tau", 0.20),
+        ("sdev_max", 2.0),
+        ("fund", None),
+    )
+
+    # Trading periods per year
+    _TANN = {
+        TimeFrame.Days: 252.0,
+        TimeFrame.Weeks: 52.0,
+        TimeFrame.Months: 12.0,
+        TimeFrame.Years: 1.0,
+    }
+
+    # Initialize, get returns
+    def __init__(self, *args, **kwargs):
+        """Initialize the VWR analyzer.
+
+        Args:
+            *args: Positional arguments.
+            **kwargs: Keyword arguments for analyzer parameters.
+        """
+        # Call parent class __init__ method to support timeframe and compression parameters
+        super().__init__(*args, **kwargs)
+
+        # Children log return analyzer
+        self._pns = None
+        self._pis = None
+        self._fundmode = None
+        # Use OwnerContext so child analyzer can find this as its parent
+        with OwnerContext.set_owner(self):
+            self._returns = Returns(
+                timeframe=self.p.timeframe, compression=self.p.compression, tann=self.p.tann
+            )
+
+    # Start
+    def start(self):
+        """Initialize the analyzer at the start of the backtest.
+
+        Sets the fund mode and initializes lists to track period
+        start and end values.
+        """
+        super().start()
+        # Add an initial placeholder for [-1] operation
+        # Get fundmode
+        if self.p.fund is None:
+            self._fundmode = self.strategy.broker.fundmode
+        else:
+            self._fundmode = self.p.fund
+        # Get initial value based on fundmode
+        if not self._fundmode:
+            self._pis = [self.strategy.broker.getvalue()]  # keep initial value
+        else:
+            self._pis = [self.strategy.broker.fundvalue]  # keep initial value
+        # Initialize final value to None
+        self._pns = [None]  # keep final prices (value)
+
+    # Stop
+    def stop(self):
+        """Calculate the VWR metric when backtest ends.
+
+        VWR = rnorm100 * (1 - (sdev_p / sdev_max)^tau)
+        where sdev_p is the standard deviation of period returns.
+        """
+        super().stop()
+        # Check if no value has been seen after the last 'dt_over'
+        # If so, there is one 'pi' out of place and a None 'pn'. Purge
+        # If the last value is None, remove the last element
+        if self._pns[-1] is None:
+            self._pis.pop()
+            self._pns.pop()
+
+        # Get results from children
+        # Get returns
+        rs = self._returns.get_analysis()
+        ravg = rs["ravg"]
+        rnorm100 = rs["rnorm100"]
+
+        # make n 1 based in enumerate (number of periods and not index)
+        # skip initial placeholders for synchronization
+        # Calculate return for each period (usually yearly, then save to dts)
+        dts = []
+        invalid_input = False
+        for n, pipn in enumerate(zip(self._pis, self._pns), 1):
+            pi, pn = pipn
+            try:
+                dt = pn / (pi * math.exp(ravg * n)) - 1.0
+                if isinstance(dt, complex) or not math.isfinite(dt):
+                    invalid_input = True
+                    dt = 0.0
+            except (ZeroDivisionError, TypeError, ValueError, OverflowError):
+                invalid_input = True
+                dt = 0.0
+            if not math.isfinite(dt):
+                invalid_input = True
+                dt = 0.0
+            dts.append(dt)
+        # Calculate standard deviation of annual returns
+        sdev_p = standarddev(dts, bessel=True)
+        # Calculate VWR value
+        try:
+            invalid_output = (
+                invalid_input
+                or isinstance(sdev_p, complex)
+                or not math.isfinite(sdev_p)
+                or isinstance(rnorm100, complex)
+                or not math.isfinite(rnorm100)
+            )
+        except TypeError:
+            invalid_output = True
+        if invalid_output:
+            vwr = 0.0
+        elif self.p.sdev_max:
+            try:
+                vwr = rnorm100 * (1.0 - pow(sdev_p / self.p.sdev_max, self.p.tau))
+                if isinstance(vwr, complex) or not math.isfinite(vwr):
+                    vwr = 0.0
+            except (ZeroDivisionError, TypeError, ValueError, OverflowError):
+                vwr = 0.0
+        else:
+            vwr = 0.0
+        self.rets["vwr"] = vwr
+
+    # Fund notification
+    def notify_fund(self, cash, value, fundvalue, shares):
+        """Update the current period end value from fund notification.
+
+        Args:
+            cash: Current cash amount.
+            value: Current portfolio value.
+            fundvalue: Current fund value.
+            shares: Number of fund shares.
+        """
+        if not self._fundmode:
+            self._pns[-1] = value  # annotate last seen pn for the current period
+        else:
+            self._pns[-1] = fundvalue  # annotate last pn for current period
+
+    def on_dt_over(self):
+        """Handle timeframe boundary crossing.
+
+        Moves the current period end value to be the next period's
+        start value and creates a new placeholder.
+        """
+        self._pis.append(self._pns[-1])  # the last pn is pi in the next period
+        self._pns.append(None)  # placeholder for [-1] operation
+
+
+VariabilityWeightedReturn = VWR

backtrader/bokeh/__init__.py

@@ -0,0 +1,155 @@
+#!/usr/bin/env python
+"""
+Backtrader Bokeh Module
+
+Provides Bokeh-based live plotting functionality, including:
+- Real-time data push and chart updates
+- Extensible tab system
+- Navigation controls (pause/play/forward/backward)
+- Theme system (black/white themes)
+- Memory optimization (lookback control)
+
+Example:
+    import backtrader as bt
+    from backtrader.bokeh import LivePlotAnalyzer, Blackly
+
+    cerebro = bt.Cerebro()
+    cerebro.adddata(data)
+    cerebro.addstrategy(MyStrategy)
+
+    # Add live plot analyzer
+    cerebro.addanalyzer(LivePlotAnalyzer,
+                       scheme=Blackly(),
+                       lookback=100)
+
+    cerebro.run()
+"""
+
+import importlib
+import os
+import sys
+
+_BOKEH_PACKAGE_ROOT = os.path.realpath(os.path.dirname(__file__))
+_BOKEH_PACKAGE_PARENT = os.path.dirname(_BOKEH_PACKAGE_ROOT)
+
+
+def _is_local_bokeh_module(module):
+    """Return whether a top-level ``bokeh`` module resolves to this package."""
+    module_file = getattr(module, "__file__", None)
+    if module_file and os.path.realpath(module_file).startswith(_BOKEH_PACKAGE_ROOT + os.sep):
+        return True
+
+    return any(
+        os.path.realpath(module_path) == _BOKEH_PACKAGE_ROOT
+        for module_path in getattr(module, "__path__", ())
+    )
+
+
+def _ensure_external_bokeh():
+    """Load the third-party Bokeh package when this package directory shadows it.
+
+    Some test and embedded environments add ``backtrader/`` directly to
+    ``sys.path``. In that layout, a bare ``import bokeh`` resolves to this
+    package rather than the third-party dependency. Resolve the optional
+    dependency while temporarily excluding that shadowing path.
+    """
+    loaded = sys.modules.get("bokeh")
+    if loaded is not None and not _is_local_bokeh_module(loaded):
+        return loaded
+
+    original_path = sys.path[:]
+    try:
+        sys.path[:] = [
+            entry
+            for entry in sys.path
+            if os.path.realpath(entry or os.getcwd()) != _BOKEH_PACKAGE_PARENT
+        ]
+        for name in list(sys.modules):
+            module = sys.modules.get(name)
+            if name == "bokeh" or name.startswith("bokeh."):
+                if module is not None and _is_local_bokeh_module(module):
+                    sys.modules.pop(name, None)
+        return importlib.import_module("bokeh")
+    except ImportError:
+        return None
+    finally:
+        sys.path[:] = original_path
+
+
+_ensure_external_bokeh()
+
+if __name__ != "bokeh":
+    from . import tabs
+    from .schemes import Blackly, Scheme, Tradimo
+    from .tab import BokehTab
+    from .utils import get_datanames, get_strategy_label, sanitize_source_name
+
+# Custom tab registry
+_custom_tabs = []
+
+
+def register_tab(tab_class):
+    """Register a custom tab.
+
+    Args:
+        tab_class: Tab class that inherits from BokehTab
+    """
+    if not issubclass(tab_class, BokehTab):
+        raise ValueError("tab_class must be a subclass of BokehTab")
+    _custom_tabs.append(tab_class)
+
+
+def get_registered_tabs():
+    """Get all registered custom tabs."""
+    return _custom_tabs.copy()
+
+
+# Lazy import to avoid circular dependencies
+def __getattr__(name):
+    """Lazy load module attributes."""
+    if name == "BacktraderBokeh":
+        from .app import BacktraderBokeh
+
+        return BacktraderBokeh
+    if name == "LivePlotAnalyzer":
+        from .analyzers import LivePlotAnalyzer
+
+        return LivePlotAnalyzer
+    if name == "RecorderAnalyzer":
+        from .analyzers import RecorderAnalyzer
+
+        return RecorderAnalyzer
+    if name == "LiveClient":
+        from .live import LiveClient
+
+        return LiveClient
+    if name == "LiveDataHandler":
+        from .live import LiveDataHandler
+
+        return LiveDataHandler
+    if name == "BokehPlot":
+        from .plot_adapter import BokehPlot
+
+        return BokehPlot
+
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+__all__ = [
+    "BacktraderBokeh",
+    "Scheme",
+    "Blackly",
+    "Tradimo",
+    "BokehTab",
+    "LivePlotAnalyzer",
+    "RecorderAnalyzer",
+    "LiveClient",
+    "LiveDataHandler",
+    "BokehPlot",
+    "tabs",
+    "register_tab",
+    "get_registered_tabs",
+    "get_datanames",
+    "get_strategy_label",
+    "sanitize_source_name",
+]

backtrader/bokeh/analyzers/__init__.py

@@ -0,0 +1,13 @@
+#!/usr/bin/env python
+"""
+Bokeh analyzers module.
+
+Provides the following analyzers:
+- LivePlotAnalyzer: Live plotting analyzer
+- RecorderAnalyzer: Data recording analyzer
+"""
+
+from .plot import LivePlotAnalyzer
+from .recorder import RecorderAnalyzer
+
+__all__ = ["LivePlotAnalyzer", "RecorderAnalyzer"]

backtrader/bokeh/analyzers/plot.py

@@ -0,0 +1,192 @@
+#!/usr/bin/env python
+"""
+Live plotting analyzer.
+
+Provides real-time plotting functionality based on Bokeh Server.
+"""
+
+import asyncio
+import threading
+from threading import Lock
+
+from backtrader.utils.log_message import get_logger
+
+try:
+    import tornado.ioloop
+
+    TORNADO_AVAILABLE = True
+except ImportError:
+    TORNADO_AVAILABLE = False
+
+import backtrader as bt
+
+from ..app import BacktraderBokeh
+from ..live.client import LiveClient
+from ..schemes import Tradimo
+from ..webapp import Webapp
+
+_logger = get_logger(__name__)
+
+
+class LivePlotAnalyzer(bt.Analyzer):
+    """Live plotting analyzer.
+
+    Provides real-time plotting functionality based on Bokeh Server, including:
+    - WebSocket real-time data push
+    - Pause/resume functionality
+    - Forward/backward navigation
+    - Data lookback control
+
+    Args:
+        scheme: Theme instance, defaults to Tradimo
+        style: Chart style, 'bar' or 'candle'
+        lookback: Amount of historical data to retain
+        address: Server address
+        port: Server port
+        title: Title
+        autostart: Whether to auto-start the server
+
+    Example:
+        cerebro.addanalyzer(LivePlotAnalyzer,
+                          scheme=Blackly(),
+                          lookback=100,
+                          port=8999)
+    """
+
+    params = (
+        ("scheme", None),  # Theme
+        ("style", "bar"),  # Chart style
+        ("lookback", 100),  # Historical data retention
+        ("address", "localhost"),  # Server address
+        ("port", 8999),  # Server port
+        ("title", None),  # Title
+        ("autostart", True),  # Auto-start
+    )
+
+    def __init__(self, **kwargs):
+        """Initialize live plot analyzer.
+
+        Args:
+            **kwargs: Keyword arguments overriding default parameters:
+                - scheme: Theme instance (defaults to Tradimo)
+                - style: Chart style ('bar' or 'candle')
+                - lookback: Number of bars to retain in display
+                - address: Server address (default: 'localhost')
+                - port: Server port (default: 8999)
+                - title: Chart title (default: 'Live {StrategyName}')
+                - autostart: Whether to auto-start server (default: True)
+        """
+        super().__init__()
+
+        # Set title
+        title = self.p.title
+        if title is None:
+            title = f"Live {type(self.strategy).__name__}"
+
+        # Set auto-start
+        autostart = kwargs.get("autostart", self.p.autostart)
+
+        # Get theme
+        scheme = self.p.scheme
+        if scheme is None:
+            scheme = Tradimo()
+
+        # Create Webapp
+        self._webapp = Webapp(
+            title=title,
+            template="basic.html.j2",
+            scheme=scheme,
+            on_root_model=self._app_cb_build_root_model,
+            on_session_destroyed=self._on_session_destroyed,
+            autostart=autostart,
+            address=self.p.address,
+            port=self.p.port,
+        )
+
+        self._lock = Lock()
+        self._clients = {}
+        self._app_kwargs = kwargs
+
+    def _create_app(self):
+        """Create BacktraderBokeh application instance.
+
+        Returns:
+            BacktraderBokeh instance
+        """
+        return BacktraderBokeh(
+            style=self.p.style, scheme=self.p.scheme or Tradimo(), **self._app_kwargs
+        )
+
+    def _on_session_destroyed(self, session_context):
+        """Session destroyed callback.
+
+        Args:
+            session_context: Bokeh session context
+        """
+        with self._lock:
+            session_id = session_context.id
+            if session_id in self._clients:
+                self._clients[session_id].stop()
+                del self._clients[session_id]
+
+    def _t_server(self):
+        """Server thread method."""
+        if not TORNADO_AVAILABLE:
+            _logger.error("Tornado is not available. Cannot start Bokeh server.")
+            return
+
+        asyncio.set_event_loop(asyncio.new_event_loop())
+        loop = tornado.ioloop.IOLoop.current()
+        self._webapp.start(loop)
+
+    def _app_cb_build_root_model(self, doc):
+        """Build root model callback.
+
+        Args:
+            doc: Bokeh document
+
+        Returns:
+            Root model
+        """
+        client = LiveClient(doc, self._create_app(), self.strategy, self.p.lookback)
+
+        with self._lock:
+            self._clients[doc.session_context.id] = client
+
+        return client.model
+
+    def start(self):
+        """Start from backtrader.
+
+        Starts the Bokeh Server.
+        """
+        _logger.debug("Starting LivePlotAnalyzer...")
+
+        t = threading.Thread(target=self._t_server)
+        t.daemon = True
+        t.start()
+
+    def stop(self):
+        """Stop from backtrader."""
+        _logger.debug("Stopping LivePlotAnalyzer...")
+
+        with self._lock:
+            for client in self._clients.values():
+                client.stop()
+
+    def next(self):
+        """Receive new data from backtrader.
+
+        Updates all connected clients.
+        """
+        with self._lock:
+            for client in self._clients.values():
+                client.next()
+
+    def get_analysis(self):
+        """Return analysis results.
+
+        Returns:
+            dict: Empty dict (this analyzer is for plotting, does not produce analysis data)
+        """
+        return {}