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

backtrader/plot/formatters.py

@@ -0,0 +1,200 @@
+#!/usr/bin/env python
+"""Plot Formatters Module - Custom formatters for matplotlib plots.
+
+This module provides custom formatters for matplotlib charts used in backtrader
+plotting, including volume formatters and date formatters that work with
+backtrader's internal date representation.
+
+Classes:
+    MyVolFormatter: Custom formatter for volume axis with K/M/B suffixes.
+    MyDateFormatter: Custom formatter for date axis.
+
+Functions:
+    patch_locator: Patch date locator with custom date limits.
+    patch_formatter: Patch date formatter with custom date handling.
+    getlocator: Create and patch date locator and formatter.
+
+Example:
+    >>> from backtrader.plot.formatters import MyVolFormatter, MyDateFormatter
+    >>> vol_fmt = MyVolFormatter(volmax=1000000)
+    >>> date_fmt = MyDateFormatter(dates, fmt='%Y-%m-%d')
+"""
+
+import matplotlib.dates as mdates
+import matplotlib.ticker as mplticker
+
+from ..utils import num2date
+
+
+class MyVolFormatter(mplticker.Formatter):
+    """Custom formatter for volume axis labels with magnitude suffixes.
+
+    This formatter formats volume values with appropriate suffixes (K, M, B, T, P)
+    based on the maximum volume value. For example, volumes in the thousands
+    will be displayed with 'K' suffix, millions with 'M' suffix, etc.
+
+    Attributes:
+        Suffixes: List of suffixes for different magnitudes.
+
+    Example:
+        >>> formatter = MyVolFormatter(volmax=1500000)
+        >>> label = formatter(1000000, 0)
+        >>> print(label)
+        1M
+    """
+
+    Suffixes = ["", "K", "M", "G", "T", "P"]
+
+    def __init__(self, volmax):
+        """Initialize the volume formatter.
+
+        Args:
+            volmax: Maximum volume value to be displayed. This determines
+                the appropriate suffix and divisor for formatting.
+        """
+        self.volmax = volmax
+        magnitude = 0
+        self.divisor = 1.0
+        while abs(volmax / self.divisor) >= 1000:
+            magnitude += 1
+            self.divisor *= 1000.0
+
+        self.suffix = self.Suffixes[magnitude]
+
+    def __call__(self, y, pos=0):
+        """Return the label for time x at position pos"""
+
+        if y > self.volmax * 1.20:
+            return ""
+
+        y = int(y / self.divisor)
+        return "%d%s" % (y, self.suffix)
+
+
+class MyDateFormatter(mplticker.Formatter):
+    """Custom formatter for date axis labels.
+
+    This formatter formats dates using backtrader's internal date representation
+    and displays them with the specified format string. It handles index-based
+    date lookups and ensures valid index bounds.
+
+    Example:
+        >>> formatter = MyDateFormatter(dates, fmt='%Y-%m-%d')
+        >>> label = formatter(100, 0)
+        >>> print(label)
+        2020-01-15
+    """
+
+    def __init__(self, dates, fmt="%Y-%m-%d"):
+        """Initialize the date formatter.
+
+        Args:
+            dates: Array or sequence of dates in backtrader's internal format.
+            fmt: strftime-compatible format string for date display.
+                Defaults to '%Y-%m-%d'.
+        """
+        self.dates = dates
+        self.lendates = len(dates)
+        self.fmt = fmt
+
+    def __call__(self, x, pos=0):
+        """Return the label for time x at position pos"""
+        ind = int(round(x))
+        if ind >= self.lendates:
+            ind = self.lendates - 1
+
+        if ind < 0:
+            ind = 0
+
+        return num2date(self.dates[ind]).strftime(self.fmt)
+
+
+def patch_locator(locator, xdates):
+    """Patch a date locator with custom date limit conversion methods.
+
+    This function patches the locator's datalim_to_dt and viewlim_to_dt methods
+    to work with backtrader's internal date array (xdates) instead of using
+    matplotlib's default date conversion.
+
+    Args:
+        locator: matplotlib date locator instance to patch.
+        xdates: Array of dates in backtrader's internal format.
+    """
+
+    def _patched_datalim_to_dt(self):
+        dmin, dmax = self.axis.get_data_interval()
+
+        # proxy access to xdates
+        dmin, dmax = xdates[int(dmin)], xdates[min(int(dmax), len(xdates) - 1)]
+
+        a, b = num2date(dmin, self.tz), num2date(dmax, self.tz)
+        return a, b
+
+    def _patched_viewlim_to_dt(self):
+        vmin, vmax = self.axis.get_view_interval()
+
+        # proxy access to xdates
+        vmin, vmax = xdates[int(vmin)], xdates[min(int(vmax), len(xdates) - 1)]
+        a, b = num2date(vmin, self.tz), num2date(vmax, self.tz)
+        return a, b
+
+    # patch the instance with a bound method
+    bound_datalim = _patched_datalim_to_dt.__get__(locator, locator.__class__)
+    locator.datalim_to_dt = bound_datalim
+
+    # patch the instance with a bound method
+    bound_viewlim = _patched_viewlim_to_dt.__get__(locator, locator.__class__)
+    locator.viewlim_to_dt = bound_viewlim
+
+
+def patch_formatter(formatter, xdates):
+    """Patch a date formatter with custom date formatting logic.
+
+    This function patches the formatter's __call__ method to work with
+    backtrader's internal date array (xdates) for index-based date lookups.
+
+    Args:
+        formatter: matplotlib date formatter instance to patch.
+        xdates: Array of dates in backtrader's internal format.
+    """
+
+    def newcall(self, x, pos=0):
+        if False and x < 0:  # noqa: SIM223  # intentionally-disabled upstream guard
+            raise ValueError(
+                "DateFormatter found a value of x=0, which is "
+                "an illegal date.  This usually occurs because "
+                "you have not informed the axis that it is "
+                "plotting dates, e.g., with ax.xaxis_date()"
+            )
+
+        x = xdates[int(x)]
+        dt = num2date(x, self.tz)
+        return self.strftime(dt, self.fmt)
+
+    bound_call = newcall.__get__(formatter, formatter.__class__)
+    formatter.__call__ = bound_call
+
+
+def getlocator(xdates, numticks=5, tz=None):
+    """Create a patched date locator and formatter for backtrader plots.
+
+    This function creates matplotlib date locator and formatter instances
+    patched to work with backtrader's internal date representation.
+
+    Args:
+        xdates: Array of dates in backtrader's internal format.
+        numticks: Target number of ticks on the axis. Defaults to 5.
+        tz: Timezone for date conversion. Defaults to None (local timezone).
+
+    Returns:
+        A tuple of (locator, formatter) where:
+            - locator: Patched matplotlib date locator instance.
+            - formatter: Patched matplotlib date formatter instance.
+    """
+    span = xdates[-1] - xdates[0]
+
+    locator, formatter = mdates.date_ticker_factory(span=span, tz=tz, numticks=numticks)
+
+    patch_locator(locator, xdates)
+    patch_formatter(formatter, xdates)
+    return locator, formatter

backtrader/plot/locator.py

@@ -0,0 +1,353 @@
+#!/usr/bin/env python
+
+"""
+Redefine/Override matplotlib locators to make them work with index base x-axis
+which can be converted from/to dates
+"""
+
+import datetime
+import warnings
+
+import numpy as np
+from dateutil.relativedelta import relativedelta
+from matplotlib.dates import (
+    HOURS_PER_DAY,
+    MIN_PER_HOUR,
+    MONTHS_PER_YEAR,
+)
+from matplotlib.dates import AutoDateFormatter as ADFormatter
+from matplotlib.dates import AutoDateLocator as ADLocator
+from matplotlib.dates import MicrosecondLocator
+from matplotlib.dates import RRuleLocator as RRLocator
+from matplotlib.dates import num2date, rrulewrapper
+
+from ..utils.log_message import get_logger, throttled_warning
+
+logger = get_logger(__name__)
+
+
+def _idx2dt(idx, dates, tz):
+    """Convert an index to a datetime object.
+
+    Args:
+        idx: Index value or datetime.date object.
+        dates: Array of date values.
+        tz: Timezone to use for conversion.
+
+    Returns:
+        datetime.datetime: The corresponding datetime object.
+    """
+    if isinstance(idx, datetime.date):
+        return idx
+
+    ldates = len(dates)
+
+    idx = int(round(idx))
+    if idx >= ldates:
+        idx = ldates - 1
+    if idx < 0:
+        idx = 0
+
+    return num2date(dates[idx], tz)
+
+
+class RRuleLocator(RRLocator):
+    """Locator for date-based ticks using rrules.
+
+    This locator extends matplotlib's RRuleLocator to work with index-based
+    x-axis that can be converted from/to dates. It handles the conversion
+    between data indices and datetime objects.
+
+    Attributes:
+        _dates: Array of date values for index conversion.
+    """
+
+    def __init__(self, dates, o, tz=None):
+        """Initialize the RRuleLocator.
+
+        Args:
+            dates: Array of date values for index conversion.
+            o: RRule object defining the tick frequency and rules.
+            tz: Timezone to use for datetime conversion. Defaults to None.
+        """
+        self._dates = dates
+        super().__init__(o, tz)
+
+    def datalim_to_dt(self):
+        """Convert an axis data interval to datetime objects.
+
+        Returns:
+            tuple: A pair of datetime objects representing the data limits.
+        """
+        dmin, dmax = self.axis.get_data_interval()
+        if dmin > dmax:
+            dmin, dmax = dmax, dmin
+
+        return (_idx2dt(dmin, self._dates, self.tz), _idx2dt(dmax, self._dates, self.tz))
+
+    def viewlim_to_dt(self):
+        """Convert the view interval to datetime objects.
+
+        Returns:
+            tuple: A pair of datetime objects representing the view limits.
+        """
+        vmin, vmax = self.axis.get_view_interval()
+        if vmin > vmax:
+            vmin, vmax = vmax, vmin
+
+        return (_idx2dt(vmin, self._dates, self.tz), _idx2dt(vmax, self._dates, self.tz))
+
+    def tick_values(self, vmin, vmax):
+        """Return the tick values for the given range.
+
+        Args:
+            vmin: Minimum value of the range.
+            vmax: Maximum value of the range.
+
+        Returns:
+            list: List of indices corresponding to tick positions.
+        """
+        import bisect
+
+        dtnums = super().tick_values(vmin, vmax)
+        return [bisect.bisect_left(self._dates, x) for x in dtnums]
+
+
+class AutoDateLocator(ADLocator):
+    """Locator for automatic date-based tick positioning.
+
+    This locator extends matplotlib's AutoDateLocator to work with index-based
+    x-axis that can be converted from/to dates. It automatically selects the
+    appropriate tick frequency based on the date range.
+
+    Attributes:
+        _dates: Array of date values for index conversion.
+    """
+
+    def __init__(self, dates, *args, **kwargs):
+        """Initialize the AutoDateLocator.
+
+        Args:
+            dates: Array of date values for index conversion.
+            *args: Additional positional arguments passed to parent class.
+            **kwargs: Additional keyword arguments passed to parent class.
+        """
+        self._dates = dates
+        super().__init__(*args, **kwargs)
+
+    def datalim_to_dt(self):
+        """Convert an axis data interval to datetime objects.
+
+        Returns:
+            tuple: A pair of datetime objects representing the data limits.
+        """
+        dmin, dmax = self.axis.get_data_interval()
+        if dmin > dmax:
+            dmin, dmax = dmax, dmin
+
+        return (_idx2dt(dmin, self._dates, self.tz), _idx2dt(dmax, self._dates, self.tz))
+
+    def viewlim_to_dt(self):
+        """Convert the view interval to datetime objects.
+
+        Returns:
+            tuple: A pair of datetime objects representing the view limits.
+        """
+        vmin, vmax = self.axis.get_view_interval()
+        if vmin > vmax:
+            vmin, vmax = vmax, vmin
+
+        return (_idx2dt(vmin, self._dates, self.tz), _idx2dt(vmax, self._dates, self.tz))
+
+    def tick_values(self, vmin, vmax):
+        """Return the tick values for the given range.
+
+        Args:
+            vmin: Minimum value of the range.
+            vmax: Maximum value of the range.
+
+        Returns:
+            list: List of indices corresponding to tick positions.
+        """
+        import bisect
+
+        dtnums = super().tick_values(vmin, vmax)
+        return [bisect.bisect_left(self._dates, x) for x in dtnums]
+
+    def get_locator(self, dmin, dmax):
+        """Pick the best locator based on a distance.
+
+        Args:
+            dmin: Minimum datetime value.
+            dmax: Maximum datetime value.
+
+        Returns:
+            matplotlib.ticker.Locator: The appropriate locator for the date range.
+        """
+        delta = relativedelta(dmax, dmin)
+        tdelta = dmax - dmin
+
+        # take absolute difference
+        if dmin > dmax:
+            delta = -delta
+            tdelta = -tdelta
+
+        # The following uses a mix of calls to relativedelta and timedelta
+        # methods because there is incomplete overlap in the functionality of
+        # these similar functions, and it's best to avoid doing our own math
+        # whenever possible.
+        numYears = float(delta.years)
+        numMonths = (numYears * MONTHS_PER_YEAR) + delta.months
+        numDays = tdelta.days  # Avoids estimates of days/month, days/year
+        numHours = (numDays * HOURS_PER_DAY) + delta.hours
+        numMinutes = (numHours * MIN_PER_HOUR) + delta.minutes
+        numSeconds = np.floor(tdelta.total_seconds())
+        numMicroseconds = np.floor(tdelta.total_seconds() * 1e6)
+
+        nums = [numYears, numMonths, numDays, numHours, numMinutes, numSeconds, numMicroseconds]
+
+        use_rrule_locator = [True] * 6 + [False]
+
+        # Default setting of bymonth, etc. to pass to rrule
+        # [unused (for year), bymonth, bymonthday, byhour, byminute,
+        #  bysecond, unused (for microseconds)]
+        byranges = [None, 1, 1, 0, 0, 0, None]
+
+        usemicro = False  # use as a flag to avoid raising an exception
+
+        # Loop over all the frequencies and try to find one that gives at
+        # least a minticks tick positions.  Once this is found, look for
+        # an interval from a list specific to that frequency that gives no
+        # more than maxticks tick positions. Also, set up some ranges
+        # (bymonth, etc.) as appropriate to be passed to rrulewrapper.
+        for i, (freq, num) in enumerate(zip(self._freqs, nums)):
+            # If this particular frequency doesn't give enough ticks, continue
+            if num < self.minticks:
+                # Since we're not using this particular frequency, set
+                # the corresponding by_ to None so the rrule can act as
+                # appropriate
+                byranges[i] = None
+                continue
+
+            # Find the first available interval that doesn't give too many
+            # ticks
+            for interval in self.intervald[freq]:
+                if num <= interval * (self.maxticks[freq] - 1):
+                    break
+            else:
+                # We went through the whole loop without breaking, default to
+                # the last interval in the list and raise a warning
+                warnings.warn(
+                    "AutoDateLocator was unable to pick an "
+                    "appropriate interval for this date range. "
+                    "It may be necessary to add an interval value "
+                    "to the AutoDateLocator's intervald dictionary."
+                    " Defaulting to {}.".format(interval)
+                )
+
+            # Set some parameters as appropriate
+            self._freq = freq
+
+            if self._byranges[i] and self.interval_multiples:
+                byranges[i] = self._byranges[i][::interval]
+                interval = 1
+            else:
+                byranges[i] = self._byranges[i]
+
+            # We found what frequency to use
+            break
+        else:
+            if False:
+                raise ValueError("No sensible date limit could be found in the AutoDateLocator.")
+            usemicro = True
+
+        if not usemicro and use_rrule_locator[i]:
+            _, bymonth, bymonthday, byhour, byminute, bysecond, _ = byranges
+
+            rrule = rrulewrapper(
+                self._freq,
+                interval=interval,
+                dtstart=dmin,
+                until=dmax,
+                bymonth=bymonth,
+                bymonthday=bymonthday,
+                byhour=byhour,
+                byminute=byminute,
+                bysecond=bysecond,
+            )
+
+            locator = RRuleLocator(self._dates, rrule, self.tz)
+        else:
+            if usemicro:
+                interval = 1  # not set because the for else: was met
+            locator = MicrosecondLocator(interval, tz=self.tz)
+
+        locator.set_axis(self.axis)
+        try:
+            # try for matplotlib < 3.6.0
+            locator.set_view_interval(*self.axis.get_view_interval())
+            locator.set_data_interval(*self.axis.get_data_interval())
+        except Exception:
+            throttled_warning(
+                logger,
+                "plot.locator.legacy_interval_api_fallback",
+                "AutoDateLocator legacy interval API unavailable; using axis interval fallback",
+                exc_info=False,
+            )
+            try:
+                # try for matplotlib >= 3.6.0
+                self.axis.set_view_interval(*self.axis.get_view_interval())
+                self.axis.set_data_interval(*self.axis.get_data_interval())
+                locator.set_axis(self.axis)
+            except Exception:
+                throttled_warning(
+                    logger,
+                    "plot.locator.axis_interval_sync_recovery",
+                    "AutoDateLocator axis interval synchronization failed; retaining locator fallback",
+                    exc_info=False,
+                )
+        return locator
+
+
+class AutoDateFormatter(ADFormatter):
+    """Formatter for automatic date-based tick labels.
+
+    This formatter extends matplotlib's AutoDateFormatter to work with
+    index-based x-axis that can be converted from/to dates. It automatically
+    formats date labels based on the tick frequency.
+
+    Attributes:
+        _dates: Array of date values for index conversion.
+    """
+
+    def __init__(self, dates, locator, tz=None, defaultfmt="%Y-%m-%d"):
+        """Initialize the AutoDateFormatter.
+
+        Args:
+            dates: Array of date values for index conversion.
+            locator: The locator instance to use for tick positioning.
+            tz: Timezone to use for datetime conversion. Defaults to None.
+            defaultfmt: Default format string for dates. Defaults to "%Y-%m-%d".
+        """
+        self._dates = dates
+        super().__init__(locator, tz, defaultfmt)
+
+    def __call__(self, x, pos=None):
+        """Return the label for time x at position pos.
+
+        Args:
+            x: The index value to convert to a date label.
+            pos: The position of the tick. Defaults to None.
+
+        Returns:
+            str: The formatted date label.
+        """
+        x = int(round(x))
+        ldates = len(self._dates)
+        if x >= ldates:
+            x = ldates - 1
+
+        if x < 0:
+            x = 0
+
+        return super()