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

backtrader/plot/scheme.py

@@ -0,0 +1,253 @@
+#!/usr/bin/env python
+"""Plot Scheme Module - Plotting configuration and styling.
+
+This module provides the PlotScheme class and color schemes for
+customizing the appearance of backtrader plots.
+
+Variables:
+    tableau20: 20-color palette for plots.
+    tableau10: 10-color palette for plots.
+    tableau10_light: 10 light-color palette.
+    tab10_index: Color index mapping.
+
+Classes:
+    PlotScheme: Configuration class for plot appearance.
+
+Example:
+    Using PlotScheme:
+    >>> scheme = PlotScheme()
+    >>> scheme.ytight = True
+    >>> cerebro.plot(scheme=scheme)
+"""
+
+tableau20 = [
+    "steelblue",  # 0
+    "lightsteelblue",  # 1
+    "darkorange",  # 2
+    "peachpuff",  # 3
+    "green",  # 4
+    "lightgreen",  # 5
+    "crimson",  # 6
+    "lightcoral",  # 7
+    "mediumpurple",  # 8
+    "thistle",  # 9
+    "saddlebrown",  # 10
+    "rosybrown",  # 11
+    "orchid",  # 12
+    "lightpink",  # 13
+    "gray",  # 14
+    "lightgray",  # 15
+    "olive",  # 16
+    "palegoldenrod",  # 17
+    "mediumturquoise",  # 18
+    "paleturquoise",  # 19
+]
+
+tableau10 = [
+    "blue",  # 'steelblue',  # 0
+    "darkorange",  # 1
+    "green",  # 2
+    "crimson",  # 3
+    "mediumpurple",  # 4
+    "saddlebrown",  # 5
+    "orchid",  # 6
+    "gray",  # 7
+    "olive",  # 8
+    "mediumturquoise",  # 9
+]
+
+tableau10_light = [
+    "lightsteelblue",  # 0
+    "peachpuff",  # 1
+    "lightgreen",  # 2
+    "lightcoral",  # 3
+    "thistle",  # 4
+    "rosybrown",  # 5
+    "lightpink",  # 6
+    "lightgray",  # 7
+    "palegoldenrod",  # 8
+    "paleturquoise",  # 9
+]
+
+tab10_index = [3, 0, 2, 1, 2, 4, 5, 6, 7, 8, 9]
+
+
+class PlotScheme:
+    """Configuration class for plot appearance and styling.
+
+    This class defines the visual appearance of backtrader plots, including
+    colors, fonts, margins, and other styling parameters. It can be customized
+    and passed to cerebro.plot() to change the look of generated charts.
+
+    Attributes:
+        ytight (bool): Whether to use tight packing on y-axis.
+        yadjust (float): Y-margin (top/bottom) for subcharts.
+        zdown (bool): Whether new lines are painted below previous ones.
+        tickrotation (int): Rotation of date labels on x-axis.
+        rowsmajor (int): Subparts for major charts (data feeds).
+        rowsminor (int): Subparts for minor charts (indicators/observers).
+        plotdist (float): Distance between subcharts.
+        grid (bool): Whether to show grid in charts.
+        style (str): Plot style for OHLC bars ('line', 'bar', or 'candle').
+        loc (str): Color for line-on-close plots.
+        barup (str): Color for bullish bars/candles.
+        barupfill (bool): Whether bullish candles are filled.
+        baralpha (float): Opacity for filled candlesticks.
+        fillalpha (float): Alpha blending for fill areas.
+        volume (bool): Whether to plot volume.
+        voloverlay (bool): Whether to overlay volume on data chart.
+        volscaling (float): Scaling factor for volume when overlaying.
+        volpushup (float): Vertical offset for overlaid volume.
+        volup (str): Color for bullish volume.
+        voldown (str): Color for bearish volume.
+        voltrans (float): Transparency for volume when overlaying.
+        subtxttrans (float): Transparency for text labels.
+        subtxtsize (int): Font size for labels on chart.
+        legendind (bool): Whether indicators have legend display.
+        legendindloc (str): Location of legend for indicators.
+        legenddataloc (str): Location of legend for data feeds.
+        linevalues (bool): Whether to plot last value after object name.
+        valuetags (bool): Whether to plot tags with last values.
+        hlinescolor (str): Default color for horizontal lines.
+        hlinesstyle (str): Default style for horizontal lines.
+        hlineswidth (float): Default width for horizontal lines.
+        lcolors (list): Default color scheme for lines.
+        fmt_x_ticks (str): strftime format for x-axis ticks.
+        fmt_x_data (str): strftime format for data point values.
+
+    Example:
+        >>> scheme = PlotScheme()
+        >>> scheme.ytight = True
+        >>> scheme.style = 'candle'
+        >>> cerebro.plot(scheme=scheme)
+    """
+
+    def __init__(self):
+        """Initialize PlotScheme with default styling values.
+
+        Sets all plotting parameters to their default values, which can be
+        customized after initialization to achieve the desired chart appearance.
+        """
+        self.ytight = False
+
+        # y-margin (top/bottom) for the subcharts. This will not overrule the
+        # option plotinfo.plotymargin
+        self.yadjust = 0.0
+        # Each new line is in z-order below the previous one. change it False
+        # to have lines painted above the previous line
+        self.zdown = True
+        # Rotation of the date labes on the x-axis
+        self.tickrotation = 15
+
+        # How many "subparts" takes a major chart (datas) in the overall chart
+        # This is proportional to the total number of subcharts
+        self.rowsmajor = 5
+
+        # How many "subparts" takes a minor chart (indicators/observers) in the
+        # overall chart. This is proportional to the total number of subcharts
+        # Together with rowsmajor, this defines a proportion ratio between data
+        # charts and indicators/observers charts
+        self.rowsminor = 1
+
+        # Distance in between subcharts
+        self.plotdist = 0.0
+
+        # Have a grid in the background of all charts
+        self.grid = True
+
+        # Default plotstyle for the OHLC bars which (line -> line on close)
+        # Other options: 'bar' and 'candle'
+        self.style = "line"
+
+        # Default color for the 'line on close' plot
+        self.loc = "black"
+        # Default color for a bullish bar/candle (0.75 -> intensity of gray)
+        self.barup = "0.75"
+        # Default color for a bearish bar/candle
+        self.bardown = "red"
+        # Level of transparency to apply to bars/cancles (NOT USED)
+        self.bartrans = 1.0
+
+        # Whether the candlesticks have to be filled or be transparent
+        self.barupfill = True
+        self.bardownfill = True
+
+        # Opacity for the filled candlesticks (1.0 opaque - 0.0 transparent)
+        self.baralpha = 1.0
+
+        # Alpha blending for fill areas between lines (_fill_gt and _fill_lt)
+        self.fillalpha = 0.20
+
+        # Whether to plot volume or not.Note: if the data in question has no
+        # volume values, volume plotting will be skipped even if this is True
+        self.volume = True
+
+        # Whether to overlay the volume on the data or use a separate subchart
+        self.voloverlay = True
+        # Scaling of the volume to the data when plotting as overlay
+        self.volscaling = 0.33
+        # Pushing overlay volume up for better visibility.
+        # Experimentation
+        # needed if the volume and data overlap too much
+        self.volpushup = 0.00
+
+        # Default color for the volume of a bullish day
+        self.volup = "#aaaaaa"  # 0.66 of gray
+        # Default color for the volume of a bearish day
+        self.voldown = "#cc6073"  # (204, 96, 115)
+        # Transparency to apply to the volume when overlaying
+        self.voltrans = 0.50
+
+        # Transparency for text labels (NOT USED CURRENTLY)
+        self.subtxttrans = 0.66
+        # Default font text size for labels on the chart
+        self.subtxtsize = 9
+
+        # Transparency for the legend (NOT USED CURRENTLY)
+        self.legendtrans = 0.25
+        # Whether indicators have a legend display in their charts
+        self.legendind = True
+        # Location of the legend for indicators (see matplotlib)
+        self.legendindloc = "upper left"
+
+        # Location of the legend for datafeeds (see matplotlib)
+        self.legenddataloc = "upper left"
+
+        # Plot the last value of a line after the Object name
+        self.linevalues = True
+
+        # Plot a tag at the end of each line with the last value
+        self.valuetags = True
+
+        # Default color for horizontal lines (see plotinfo.plothlines)
+        self.hlinescolor = "0.66"  # shade of gray
+        # Default style for horizontal lines
+        self.hlinesstyle = "--"
+        # Default width for horizontal lines
+        self.hlineswidth = 1.0
+
+        # Default color scheme: Tableau 10
+        self.lcolors = tableau10
+
+        # strftime Format string for the display of ticks on the x-axis
+        self.fmt_x_ticks = "%Y-%m-%d %H:%M"
+
+        # strftime Format string for the display of data points values
+        self.fmt_x_data = None
+
+    def color(self, idx):
+        """Get color from color scheme for given index.
+
+        Args:
+            idx (int): Color index to retrieve.
+
+        Returns:
+            str: Color name or hex string from the color scheme.
+
+        Example:
+            >>> scheme = PlotScheme()
+            >>> scheme.color(0)  # Returns first color in scheme
+            'blue'
+        """
+        colidx = tab10_index[idx % len(tab10_index)]
+        return self.lcolors[colidx]

backtrader/plot/utils.py

@@ -0,0 +1,104 @@
+#!/usr/bin/env python
+"""Plot Utils Module - Plotting utility functions.
+
+This module provides utility functions for plotting, including
+box styling and color manipulation.
+
+Functions:
+    tag_box_style: Create a box path with a tab/pointer.
+    color_by_alpha: Modify color alpha channel.
+    clip_obj: Clip object to visible area.
+
+Example:
+    Creating a box style:
+    >>> from backtrader.plot.utils import tag_box_style
+    >>> path = tag_box_style(0, 0, 1, 1, 0.1)
+"""
+
+from colorsys import hls_to_rgb as hls2rgb
+from colorsys import rgb_to_hls as rgb2hls
+
+import matplotlib.colors as mplcolors
+import matplotlib.path as mplpath
+
+
+def tag_box_style(x0, y0, width, height, mutation_size, mutation_aspect=1):
+    """Create a box path with a tab/pointer.
+
+    Given the location and size of the box, return the path of
+    the box around it.
+
+    Args:
+        x0: X coordinate of box origin.
+        y0: Y coordinate of box origin.
+        width: Width of the box.
+        height: Height of the box.
+        mutation_size: Reference scale for the mutation.
+        mutation_aspect: Aspect ratio for the mutation.
+
+    Returns:
+        A matplotlib Path object representing the box.
+    """
+
+    # Note that we are ignoring mutation_aspect. This is okay in general.
+    mypad = 0.2
+    pad = mutation_size * mypad
+
+    # width and height with padding added.
+    width, height = (
+        width + 2.0 * pad,
+        height + 2.0 * pad,
+    )
+
+    # boundary of the padded box
+    x0, y0 = (
+        x0 - pad,
+        y0 - pad,
+    )
+    x1, y1 = x0 + width, y0 + height
+
+    cp = [(x0, y0), (x1, y0), (x1, y1), (x0, y1), (x0 - pad, (y0 + y1) / 2.0), (x0, y0), (x0, y0)]
+
+    com = [
+        mplpath.Path.MOVETO,
+        mplpath.Path.LINETO,
+        mplpath.Path.LINETO,
+        mplpath.Path.LINETO,
+        mplpath.Path.LINETO,
+        mplpath.Path.LINETO,
+        mplpath.Path.CLOSEPOLY,
+    ]
+
+    path = mplpath.Path(cp, com)
+
+    return path
+
+
+def shade_color(color, percent):
+    """Shade Color
+    This color utility function allows the user to easily darken or
+    lighten a color for plotting purposes.
+    Parameters
+    ----------
+    color : string, list, hexvalue
+        Any acceptable Matplotlib color value, such as
+        'red', 'slategrey', '#FFEE11', (1,0,0)
+    percent :  the amount by which to brighten or darken the color.
+    Returns
+    -------
+    color : tuple of floats
+        tuple representing converted rgb values
+    """
+
+    rgb = mplcolors.colorConverter.to_rgb(color)
+
+    h, lightness, s = rgb2hls(*rgb)
+
+    lightness *= 1 + float(percent) / 100
+
+    lightness = min(1, lightness)
+    lightness = max(0, lightness)
+
+    r, g, b = hls2rgb(h, lightness, s)
+
+    return r, g, b

backtrader/position.py

@@ -0,0 +1,290 @@
+#!/usr/bin/env python
+"""Position Module - Position tracking and management.
+
+This module provides the Position class for tracking the size and price
+of trading positions. It maintains position state including opening
+and closing amounts.
+
+Classes:
+    Position: Tracks position size, price, and related attributes.
+
+Example:
+    Getting position from broker:
+    >>> position = broker.getposition(data)
+    >>> print(f"Size: {position.size}, Price: {position.price}")
+"""
+
+
+# Position class, keeps and updates position size and price, has no relationship with any other assets, only keeps size and price
+class Position:
+    """Keeps and updates the size and price of a position.
+
+    The Position object has no relationship to any specific asset. It only
+    keeps size and price information.
+
+    Attributes:
+        size: Current position size (positive for long, negative for short).
+        price: Current price of the position.
+        price_orig: Original price when position was opened.
+        upopened: Amount of position opened in last update.
+        upclosed: Amount of position closed in last update.
+        adjbase: Adjustment base for position calculations.
+
+    Example:
+        >>> position = Position(size=100, price=50.0)
+        >>> print(len(position))  # Returns True if size != 0
+    """
+
+    # Information displayed when printing position
+    def __str__(self):
+        return (
+            "--- Position Begin\n"
+            f"- Size: {self.size}\n"
+            f"- Price: {self.price}\n"
+            f"- Price orig: {self.price_orig}\n"
+            f"- Closed: {self.upclosed}\n"
+            f"- Opened: {self.upopened}\n"
+            f"- Adjbase: {self.adjbase}\n"
+            "--- Position End"
+        )
+
+    # Initialize based on different size and price
+    def __init__(self, size=0, price=0.0):
+        """Initialize a Position instance.
+
+        Args:
+            size: Initial position size (default: 0).
+            price: Initial price for the position (default: 0.0).
+        """
+        self.datetime = None
+        self.size = size
+        if size:
+            self.price = self.price_orig = price
+        else:
+            self.price = 0.0
+
+        self.adjbase = None
+
+        self.upopened = 0
+        self.upclosed = 0
+        self.set(size, price)
+
+        self.updt = None
+
+    # Modify position's size and price
+    def fix(self, size, price):
+        """Fix the position to a specific size and price.
+
+        Args:
+            size: The new position size.
+            price: The new position price.
+
+        Returns:
+            bool: True if size equals oldsize, False otherwise.
+        """
+        oldsize = self.size
+        self.size = size
+        self.price = price
+        return self.size == oldsize
+
+    # Set position's size and price
+    def set(self, size, price):
+        """Set position's size and price, calculating opening and closing amounts.
+
+        Args:
+            size: The new position size.
+            price: The new position price.
+
+        Returns:
+            tuple: (size, price, upopened, upclosed) calculated values.
+        """
+        # If current position > 0 and theoretical size > current size, means new position opening;
+        # If theoretical size <= current position, opening amount is minimum of 0 and theoretical size;
+        # Closing amount equals minimum of current position and current position minus theoretical position
+        if self.size > 0:
+            if size > self.size:
+                self.upopened = size - self.size  # new 10 - old 5 -> 5
+                self.upclosed = 0
+            else:
+                # same side min(0, 3) -> 0 / reversal min(0, -3) -> -3
+                self.upopened = min(0, size)
+                # same side min(10, 10 - 5) -> 5
+                # reversal min(10, 10 - -5) -> min(10, 15) -> 10
+                self.upclosed = min(self.size, self.size - size)
+        # Similar effect when current position < 0
+        elif self.size < 0:
+            if size < self.size:
+                self.upopened = size - self.size  # ex: -5 - -3 -> -2
+                self.upclosed = 0
+            else:
+                # same side max(0, -5) -> 0 / reversal max(0, 5) -> 5
+                self.upopened = max(0, size)
+                # same side max(-10, -10 - -5) -> max(-10, -5) -> -5
+                # reversal max(-10, -10 - 5) -> max(-10, -15) -> -10
+                self.upclosed = max(self.size, self.size - size)
+        # If current position equals 0, opening equals the new size being set
+        else:  # self.size == 0
+            self.upopened = size
+            self.upclosed = 0
+        # Actual position size
+        self.size = size
+        # Original price
+        self.price_orig = self.price
+        # If position size > 0, current price equals price, otherwise current price equals 0
+        if size:
+            self.price = price
+        else:
+            self.price = 0.0
+
+        return self.size, self.price, self.upopened, self.upclosed
+
+    def __repr__(self):
+        return f"Position(size={self.size}, price={self.price})"
+
+    def __eq__(self, other):
+        if not isinstance(other, Position):
+            return NotImplemented
+        return self.size == other.size and self.price == other.price
+
+    # Explicit: Position is mutable, so it must not be hashable
+    __hash__ = None
+
+    # When calling len(position), return absolute value of position
+    def __len__(self):
+        return abs(self.size)
+
+    # When calling bool(position), check if current size equals 0
+    def __bool__(self):
+        return bool(self.size != 0)
+
+    __nonzero__ = __bool__
+
+    # Clone position information
+    def clone(self):
+        """Create a copy of the current position.
+
+        Returns:
+            Position: A new Position instance with the same size and price,
+                including all internal state fields.
+        """
+        pos = Position(size=self.size, price=self.price)
+        pos.adjbase = self.adjbase
+        pos.datetime = self.datetime
+        pos.updt = self.updt
+        pos.upopened = self.upopened
+        pos.upclosed = self.upclosed
+        pos.price_orig = self.price_orig
+        return pos
+
+    # Create a position instance, then update size and price
+    def pseudoupdate(self, size, price):
+        """Create a pseudo-update by cloning and updating.
+
+        Args:
+            size: The size to add to the position.
+            price: The price for the update.
+
+        Returns:
+            Position: A new Position instance after update.
+        """
+        return Position(self.size, self.price).update(size, price)
+
+    # Update size and price
+    def update(self, size, price, dt=None):
+        """
+        Updates the current position and returns the updated size, price and
+        units used to open/close a position
+        # Update current position and return updated size, price and position size needed to open/close
+
+        Args:
+            size (int): amount to update the position's size
+                if size < 0: A sell operation has taken place
+                if size > 0: A buy operation has taken place
+            # Amount to update position size, if size < 0, a sell operation will be executed, if size > 0, a buy operation will be executed
+            price (float):
+                Must always be positive to ensure consistency
+            # Price, must always be positive to maintain consistency
+            dt (datetime.datetime): record datetime update (datetime.datetime)
+
+        Returns:
+
+            A tuple (non-named) contaning
+               size - new position size
+                   Simply the sum of the existing size plus the "size" argument
+               price - new position price
+                   If a position is increased, the new average price will be
+                   returned
+                   If a position is reduced, the price of the remaining size
+                   does not change
+                   If a position is closed,  the price is nullified
+                   If a position is reversed, the price is the price given as
+                   argument
+               opened - amount of contracts from argument "size" that were used
+                   to open/increase a position.
+                   A position can be opened from 0 or can be a reversal.
+                   If a reversal is performed, then opened is less than "size",
+                   because part of "size" will have been used to close the
+                   existing position
+               closed - the amount of units from arguments "size" that were used to
+                   close/reduce a position
+
+            Both opened and closed carry the same sign as the "size" argument
+            because they refer to a part of the "size" argument
+            # Result will return a tuple containing the following data:
+            # size represents new position size, simply existing position size plus new position increment
+            # price represents new position price, returns different price based on different position
+            # opened represents position size to be newly opened
+            # closed represents position size to be closed
+        """
+        # Update position time
+        self.datetime = dt  # record datetime update (datetime.datetime)
+        # Original price
+        self.price_orig = self.price
+        # Old position size
+        oldsize = self.size
+        # New position size
+        self.size += size
+        # If size is 0
+        if not self.size:
+            # Update closed existing position
+            # Update opening, closing and price
+            opened, closed = 0, size
+            self.price = 0.0
+        # If position size is 0, need to open size amount
+        elif not oldsize:
+            # Update opened a position from 0
+            opened, closed = size, 0
+            self.price = price
+        # If original position size is 0
+        elif oldsize > 0:  # existing "long" position updated
+            # If increased position > 0, need new opening, and calculate average position price
+            if size > 0:  # increased position
+                opened, closed = size, 0
+                self.price = (self.price * oldsize + size * price) / self.size
+            # If after closing size, position still > 0, close size
+            elif self.size > 0:  # reduced position
+                opened, closed = 0, size
+                # self.price = self.price
+            # In other cases, need to open self.size, close -oldsize
+            else:  # self.size < 0 # reversed position form plus to minus
+                opened, closed = self.size, -oldsize
+                self.price = price
+        # Original position is negative
+        else:  # oldsize < 0 - existing short position updated
+            # If newly added position is also negative, open size
+            if size < 0:  # increased position
+                opened, closed = size, 0
+                self.price = (self.price * oldsize + size * price) / self.size
+            # If current self.size < 0, close size
+            elif self.size < 0:  # reduced position
+                opened, closed = 0, size
+                # self.price = self.price
+            # In other cases, need to open self.size, close -oldsize
+            else:  # self.size > 0 - reversed position from minus to plus
+                opened, closed = self.size, -oldsize
+                self.price = price
+        # Opening and closing amounts
+        self.upopened = opened
+        self.upclosed = closed
+
+        return self.size, self.price, opened, closed