lets-plot 4.5.3a1__cp313-cp313-win_amd64.whl → 4.6.0__cp313-cp313-win_amd64.whl

lets_plot/plot/ggbunch_.py

@@ -0,0 +1,96 @@
+#  Copyright (c) 2025. JetBrains s.r.o.
+#  Use of this source code is governed by the MIT license that can be found in the LICENSE file.
+
+from numbers import Number
+from typing import List, Tuple
+
+from ._global_theme import _get_global_theme
+from .subplots import SupPlotsLayoutSpec
+from .subplots import SupPlotsSpec
+from .subplots_util import _strip_theme_if_global
+
+__all__ = ['ggbunch']
+
+
+def ggbunch(plots: List,
+            regions: List[Tuple[float, float, float, float, float, float]]
+            ) -> SupPlotsSpec:
+    """
+    Combine several plots into a single figure with custom layout.
+
+    Parameters
+    ----------
+    plots : List
+        A list where each element is one of:
+
+        - a plot specification
+        - a subplots specification
+        - None
+
+    regions : List[Tuple]
+        Layout parameters for each plot. Each region is specified as
+        (x, y, width, height, dx, dy) where:
+
+        - x, y: Position of the plot's top-left corner in relative coordinates ([0,0] is top-left corner, [1,1] is bottom-right corner of the container).
+        - width, height: Size of the plot relative to container dimensions (1 equal to the full container width/height).
+        - dx, dy: Pixel offsets to move the region (defaults to 0).
+
+    Returns
+    -------
+    `SupPlotsSpec`
+        A specification describing the combined figure with all plots and their layout.
+
+    Examples
+    --------
+    .. jupyter-execute::
+        :linenos:
+        :emphasize-lines: 10-14
+
+        import numpy as np
+        from lets_plot import *
+        LetsPlot.setup_html()
+        np.random.seed(42)
+        data = {'x': np.random.gamma(2.0, size=100)}
+        p1 = ggplot(data, aes(x='x')) + \\
+            geom_histogram(aes(color='x', fill='x'))
+        p2 = ggplot(data, aes(x='x')) + \\
+            geom_density() + theme_bw() + theme(axis='blank', panel_grid='blank')
+        ggbunch(
+            [p1, p2],
+            [(0, 0, 1, 1),
+             (0.5, 0.1, 0.3, 0.3)]
+        ) + ggsize(400, 300)
+
+    """
+
+    if not len(plots):
+        raise ValueError("Supplots list is empty.")
+
+    # Validate provided regions
+    for i, region in enumerate(regions):
+        if len(region) not in (4, 6):
+            raise ValueError(f"Region {i} must have 4 or 6 values, got {len(region)}")
+        if not all(isinstance(x, Number) for x in region):
+            raise ValueError(f"Region {i} contains non-numeric values: {region}")
+
+        # Validate size is positive
+        if any(x <= 0 for x in region[2:4]):
+            raise ValueError(f"Region {i} sizes must be positive: {region}")
+
+    # Convert regions tuples to lists
+    regions_list = [list(r) for r in regions]
+    layout = SupPlotsLayoutSpec(
+        name="free",
+        regions=regions_list
+    )
+
+    figures = [_strip_theme_if_global(fig) for fig in plots]
+
+    figure_spec = SupPlotsSpec(figures=figures, layout=layout)
+
+    # Apply global theme if defined
+    global_theme_options = _get_global_theme()
+    if global_theme_options is not None:
+        figure_spec += global_theme_options
+
+    return figure_spec

lets_plot/plot/gggrid_.py

@@ -3,10 +3,10 @@
 # Use of this source code is governed by the MIT license that can be found in the LICENSE file.
 #
 
-from lets_plot.plot.core import PlotSpec
 from ._global_theme import _get_global_theme
 from .subplots import SupPlotsLayoutSpec
 from .subplots import SupPlotsSpec
+from .subplots_util import _strip_theme_if_global
 
 __all__ = ['gggrid']
 
@@ -114,27 +114,12 @@ def gggrid(plots: list, ncol: int = None, *,
         align=align
     )
 
-    # Global Theme
-    global_theme_options = _get_global_theme()
-
-    def _strip_theme_if_global(fig):
-        # Strip global theme options from plots in grid (see issue: #966).
-        if global_theme_options is not None and fig is not None and 'theme' in fig.props() and fig.props()[
-            'theme'] == global_theme_options.props():
-            if isinstance(fig, PlotSpec):
-                fig = PlotSpec.duplicate(fig)
-                fig.props().pop('theme')
-                return fig
-            elif isinstance(fig, SupPlotsSpec):
-                fig = SupPlotsSpec.duplicate(fig)
-                fig.props().pop('theme')
-                return fig
-        return fig
-
     figures = [_strip_theme_if_global(fig) for fig in plots]
 
     figure_spec = SupPlotsSpec(figures=figures, layout=layout)
 
+    # Apply global theme if defined
+    global_theme_options = _get_global_theme()
     if global_theme_options is not None:
         figure_spec += global_theme_options
 

lets_plot/plot/plot.py

@@ -142,6 +142,9 @@ def ggsize(width, height):
 
 class GGBunch(FeatureSpec):
     """
+    Class `GGBunch` is deprecated and will be removed in future releases.
+    Please, use function `ggbunch()` to combine several plots into a single figure with custom layout.
+
     Collection of plots created by ggplot function.
     Use method `add_plot()` to add plot to 'bunch'.
     Each plot can have arbitrary location and size.
@@ -176,6 +179,10 @@ class GGBunch(FeatureSpec):
         """
         super().__init__('ggbunch', None)
         self.items = []
+        print("\n(!) WARN: class GGBunch is deprecated and will be removed in future releases.\n\n"
+              "  Please, use function ggbunch() to combine several plots into\n"
+              "  a single figure with custom layout.\n")
+
 
     def add_plot(self, plot_spec: PlotSpec, x, y, width=None, height=None):
         """

lets_plot/plot/pos.py

@@ -146,7 +146,7 @@ def position_jitter(width=None, height=None, seed=None):
     return _pos('jitter', width=width, height=height, seed=seed)
 
 
-def position_nudge(x=None, y=None):
+def position_nudge(x=None, y=None, unit=None):
     """
     Adjust position by nudging a given offset.
 
@@ -156,6 +156,13 @@ def position_nudge(x=None, y=None):
         Nudging width.
     y : float
         Nudging height.
+    unit : {'identity', 'size', 'px'}, default='identity'
+        Units for x and y nudging.
+        Possible values:
+
+        - 'identity': a unit of 1 corresponds to a difference of 1 in data space;
+        - 'size': a unit of 1 corresponds to the diameter of a point with `size=1`;
+        - 'px': the unit is measured in screen pixels.
 
     Returns
     -------
@@ -182,10 +189,10 @@ def position_nudge(x=None, y=None):
         t = np.random.choice(list('abcdefghijk'), size=n)
         ggplot({'x': x, 'y': y, 't': t}, aes('x', 'y')) + \\
             geom_point(size=5, shape=21, color='black', fill='red') + \\
-            geom_text(aes(label='t'), position=position_nudge(y=.05))
+            geom_text(aes(label='t'), position=position_nudge(y=.05, unit='identity'))
 
     """
-    return _pos('nudge', x=x, y=y)
+    return _pos('nudge', x=x, y=y, unit=unit)
 
 
 def position_jitterdodge(dodge_width=None, jitter_width=None, jitter_height=None, seed=None):

lets_plot/plot/scale.py

@@ -90,10 +90,8 @@ def scale_shape(solid=True, name=None, breaks=None, labels=None, lablim=None, li
                   labels=labels,
                   lablim=lablim,
                   limits=limits,
-                  expand=None,
                   na_value=na_value,
                   guide=guide,
-                  trans=None,
                   format=format,
                   #
                   solid=solid)
@@ -192,10 +190,8 @@ def scale_manual(aesthetic, values, *,
                   labels=labels,
                   lablim=lablim,
                   limits=limits,
-                  expand=None,
                   na_value=na_value,
                   guide=guide,
-                  trans=None,
                   format=format,
                   #
                   values=values)
@@ -668,7 +664,7 @@ def _is_color_scale(aesthetic):
 
 def scale_continuous(aesthetic, *,
                      name=None, breaks=None, labels=None, lablim=None,
-                     limits=None, na_value=None, guide=None, trans=None, format=None,
+                     limits=None, expand=None, na_value=None, guide=None, trans=None, format=None,
                      scale_mapper_kind=None,
                      **kwargs):
     """
@@ -691,6 +687,10 @@ def scale_continuous(aesthetic, *,
         The maximum label length (in characters) before trimming is applied.
     limits : list
         A numeric vector of length two providing limits of the scale.
+    expand : list
+        A numeric vector of length two giving multiplicative and additive expansion constants.
+        The vector size == 1 => only multiplicative expand (and additive expand by default).
+        Defaults: multiplicative = 0.05, additive = 0.
     na_value
         Missing values will be replaced with this value.
     guide
@@ -737,6 +737,22 @@ def scale_continuous(aesthetic, *,
             coord_cartesian() + \\
             ggsize(600, 200)
 
+    |
+
+    .. jupyter-execute::
+        :linenos:
+        :emphasize-lines: 9
+
+        from lets_plot import *
+        LetsPlot.setup_html()
+        data = {
+            'x': [0, 1, 2],
+            'y': [0, 1, 2]
+        }
+        ggplot(data) + \\
+            geom_point(aes(x='x', y='y'), size=15) + \\
+            scale_continuous(['x','y'], expand=[0, 0]) #  no expansion - points right on the edges
+
     """
     if _is_color_scale(aesthetic):
         scale_mapper_kind = 'color_gradient' if scale_mapper_kind is None else scale_mapper_kind
@@ -747,7 +763,7 @@ def scale_continuous(aesthetic, *,
                   labels=labels,
                   lablim=lablim,
                   limits=limits,
-                  expand=None,
+                  expand=expand,
                   na_value=na_value,
                   guide=guide,
                   trans=trans,
@@ -992,7 +1008,6 @@ def scale_gradient(aesthetic, *,
                   labels=labels,
                   lablim=lablim,
                   limits=limits,
-                  expand=None,
                   na_value=na_value,
                   guide=guide,
                   trans=trans,
@@ -1242,7 +1257,6 @@ def scale_gradient2(aesthetic, *,
                   labels=labels,
                   lablim=lablim,
                   limits=limits,
-                  expand=None,
                   na_value=na_value,
                   guide=guide,
                   trans=trans,
@@ -1498,7 +1512,6 @@ def scale_gradientn(aesthetic, *,
                   labels=labels,
                   lablim=lablim,
                   limits=limits,
-                  expand=None,
                   na_value=na_value,
                   guide=guide,
                   trans=trans,
@@ -1746,7 +1759,6 @@ def scale_hue(aesthetic, *,
                   labels=labels,
                   lablim=lablim,
                   limits=limits,
-                  expand=None,
                   na_value=na_value,
                   guide=guide,
                   trans=trans,
@@ -1933,7 +1945,8 @@ def scale_color_hue(h=None, c=None, l=None, h_start=None, direction=None, name=N
 
 def scale_discrete(aesthetic, *,
                    direction=None,
-                   name=None, breaks=None, labels=None, lablim=None, limits=None, na_value=None, guide=None, format=None,
+                   name=None, breaks=None, labels=None, lablim=None,
+                   limits=None, expand=None, na_value=None, guide=None, format=None,
                    scale_mapper_kind=None,
                    **kwargs):
     """
@@ -1960,6 +1973,10 @@ def scale_discrete(aesthetic, *,
     limits : list
         A vector specifying the data range for the scale
         and the default order of their display in guides.
+    expand : list
+        A numeric vector of length two giving multiplicative and additive expansion constants.
+        The vector size == 1 => only multiplicative expand (and additive expand by default).
+        Defaults: multiplicative = 0.05, additive = 0.
     na_value
         Missing values will be replaced with this value.
     guide
@@ -2006,6 +2023,22 @@ def scale_discrete(aesthetic, *,
         ggplot() + geom_point(aes(x, y, color=z, fill=z), shape=21, size=4) + \\
             scale_discrete(aesthetic=['color', 'fill'], guide='none')
 
+    |
+
+    .. jupyter-execute::
+        :linenos:
+        :emphasize-lines: 9
+
+        from lets_plot import *
+        LetsPlot.setup_html()
+        data = {
+            'x': [0, 1, 2],
+            'y': [0, 1, 2]
+        }
+        ggplot(data) + \\
+            geom_point(aes(x='x', y='y'), size=15) + \\
+            scale_discrete(['x','y'], expand=[0, 0]) #  no expansion - points right on the edges
+
     """
     return _scale(aesthetic=aesthetic,
                   name=name,
@@ -2013,7 +2046,7 @@ def scale_discrete(aesthetic, *,
                   labels=labels,
                   lablim=lablim,
                   limits=limits,
-                  expand=None,
+                  expand=expand,
                   na_value=na_value,
                   guide=guide,
                   format=format,
@@ -2266,7 +2299,6 @@ def scale_grey(aesthetic, *,
                   labels=labels,
                   lablim=lablim,
                   limits=limits,
-                  expand=None,
                   na_value=na_value,
                   guide=guide,
                   trans=trans,
@@ -2550,7 +2582,6 @@ def scale_brewer(aesthetic, *,
                   labels=labels,
                   lablim=lablim,
                   limits=limits,
-                  expand=None,
                   na_value=na_value,
                   guide=guide,
                   trans=trans,
@@ -2858,7 +2889,6 @@ def scale_viridis(aesthetic, *,
                   labels=labels,
                   lablim=lablim,
                   limits=limits,
-                  expand=None,
                   na_value=na_value,
                   guide=guide,
                   trans=trans,
@@ -3146,7 +3176,6 @@ def scale_alpha(range=None, name=None, breaks=None, labels=None, lablim=None, li
                   labels=labels,
                   lablim=lablim,
                   limits=limits,
-                  expand=None,
                   na_value=na_value,
                   guide=guide,
                   trans=trans,
@@ -3221,7 +3250,6 @@ def scale_size(range=None, name=None, breaks=None, labels=None, lablim=None, lim
                   labels=labels,
                   lablim=lablim,
                   limits=limits,
-                  expand=None,
                   na_value=na_value,
                   guide=guide,
                   trans=trans,
@@ -3300,7 +3328,6 @@ def scale_size_area(max_size=None, name=None, breaks=None, labels=None, lablim=N
                   labels=labels,
                   lablim=lablim,
                   limits=limits,
-                  expand=None,
                   na_value=na_value,
                   guide=guide,
                   trans=trans,
@@ -3375,7 +3402,6 @@ def scale_linewidth(range=None, name=None, breaks=None, labels=None, lablim=None
                   labels=labels,
                   lablim=lablim,
                   limits=limits,
-                  expand=None,
                   na_value=na_value,
                   guide=guide,
                   trans=trans,
@@ -3449,7 +3475,6 @@ def scale_stroke(range=None, name=None, breaks=None, labels=None, lablim=None, l
                   labels=labels,
                   lablim=lablim,
                   limits=limits,
-                  expand=None,
                   na_value=na_value,
                   guide=guide,
                   trans=trans,

lets_plot/plot/subplots.py

@@ -67,7 +67,7 @@ class SupPlotsSpec(FeatureSpec):
                 supplots = supplots.__add__(spec)
             return supplots
 
-        elif isinstance(other, FeatureSpec) and other.kind in ["ggsize", "theme", "ggtoolbar"]:
+        elif isinstance(other, FeatureSpec) and other.kind in ["ggsize", "theme", "ggtitle", "caption", "ggtoolbar"]:
 
             supplots = SupPlotsSpec.duplicate(self)
             # ToDo: duplication!

lets_plot/plot/subplots_util.py

@@ -0,0 +1,24 @@
+#  Copyright (c) 2025. JetBrains s.r.o.
+#  Use of this source code is governed by the MIT license that can be found in the LICENSE file.
+
+from lets_plot.plot.core import PlotSpec
+from ._global_theme import _get_global_theme
+from .subplots import SupPlotsSpec
+
+
+def _strip_theme_if_global(fig):
+    # Strip this global theme if defined
+    global_theme_options = _get_global_theme()
+
+    # Strip global theme options from plots in grid (see issue: #966).
+    if global_theme_options is not None and fig is not None and 'theme' in fig.props() and fig.props()[
+        'theme'] == global_theme_options.props():
+        if isinstance(fig, PlotSpec):
+            fig = PlotSpec.duplicate(fig)
+            fig.props().pop('theme')
+            return fig
+        elif isinstance(fig, SupPlotsSpec):
+            fig = SupPlotsSpec.duplicate(fig)
+            fig.props().pop('theme')
+            return fig
+    return fig

lets_plot/plot/theme_.py

@@ -10,6 +10,7 @@ __all__ = [
     "element_line",
     'element_rect',
     'element_text',
+    'element_markdown',
     'margin',
     'element_geom',
 ]
@@ -48,12 +49,11 @@ def theme(*,
           legend_key_size=None, legend_key_width=None, legend_key_height=None,
           legend_key_spacing=None, legend_key_spacing_x=None, legend_key_spacing_y=None,
           legend_box=None, legend_box_just=None, legend_box_spacing=None,
-          # ToDo: other legend options...
+          legend_ticks=None, legend_ticks_length=None,
 
           panel_background=None,
           panel_border=None,
           panel_border_ontop=None,
-          # ToDo: other panel options...
 
           panel_grid=None,
           panel_grid_ontop=None,
@@ -99,20 +99,20 @@ def theme(*,
     Parameters
     ----------
     exponent_format : {'e', 'pow', 'pow_full'} or tuple, default='e'
-        Format for numeric labels in scientific notation.
+        Controls the appearance of numbers formatted with 'e' or 'g' types.
 
-        - e for "e" notation (e.g. 1e+6);
-        - pow_full for "power" notation (e.g. 1x10^6). This will enable superscript formatting for the exponent;
-        - pow works as pow_full but will shorten powers of 10 (e.g. 10^6 instead of 1x10^6).
+        Value is either a string - style, or a tuple: (style, lower_exp_bound, upper_exp_bound)
+        where style can be:
+        
+        - 'e' : e-notation (e.g., 1e+6)
+        - 'pow' : superscript powers of 10 in shortened form (e.g., 10^6)
+        - 'pow_full' : superscript powers of 10 with coefficient (e.g., 1×10^6)
 
-        If parameter is a tuple, then it should be a three-element tuple:
+        For 'g' type formatting, scientific notation is applied when the number's exponent
+        is less than or equal to the lower_exp_bound (-7 by default) or greater than or equal
+        to the upper_exp_bound (6 by default, but can be affected by `precision` in format specifier).
 
-        - the first element is the format - 'e', 'pow', 'pow_full';
-        - the second element is minimum exponent value from which to use scientific notation (default is -7);
-        - the third element is maximum exponent value from which to use scientific notation (default is taken from `precision` of the current formatting, see `Formatting <https://lets-plot.org/python/pages/formats.html>`__).
-
-        Minimum and maximum exponent values are only taken into account when "g" format is used,
-        see `Formatting <https://lets-plot.org/python/pages/formats.html>`__.
+        See `Formatting <https://lets-plot.org/python/pages/formats.html>`__.
 
         Superscript is not supported when exporting to PNG/PDF.
     line : str or dict
@@ -221,6 +221,14 @@ def theme(*,
         Justification of each legend within the overall bounding box, when there are multiple legends.
     legend_box_spacing : float
         Spacing between plotting area and legend box.
+    legend_ticks : str or dict
+        Tick marks in colorbars.
+        Set 'blank' or result of `element_blank()` to draw nothing and assign no space.
+        Set `element_line()` to specify all tick mark parameters.
+        `legend_ticks_*` DOES NOT inherit from `line`.
+        By default, the colorbar tick marks are drawn with the same color as the colorbar background.
+    legend_ticks_length : float
+        Length of colorbar tick marks in px.
     panel_background : str or dict
         Background of plotting area.
         Set 'blank' or result of `element_blank()` to draw nothing.
@@ -576,7 +584,7 @@ def element_text(
     face : str
         Font face ("plain", "italic", "bold", "bold_italic").
     size : int
-        Text size in pt.
+        Text size in px.
     angle : float
         Angle to rotate the text (in degrees).
     hjust : float
@@ -593,12 +601,11 @@ def element_text(
         Can be used with values out of range, but behaviour is not specified.
     margin : number or list of numbers
         Margins around the text.
-
         The margin may be specified using a number or a list of numbers:
+
         - a number or list of one number - the same margin it applied to all four sides;
         - a list of two numbers - the first margin applies to the top and bottom, the second - to the left and right;
-        - a list of three numbers -  the first margin applies to the top, the second - to the right and left,
-        the third - to the bottom;
+        - a list of three numbers - the first margin applies to the top, the second - to the right and left, the third - to the bottom;
         - a list of four numbers - the margins are applied to the top, right, bottom and left in that order.
 
         It is acceptable to use None for any side; in this case, the default side value for this element will be used.
@@ -628,6 +635,87 @@ def element_text(
     return locals()
 
 
+def element_markdown(
+        color=None,
+        family=None,
+        face=None,
+        size=None,
+        angle=None,
+        # ToDo: lineheight
+        hjust=None,
+        vjust=None,
+        margin=None,
+        blank=False,
+) -> dict:
+    """
+    Specify how non-data components of the plot are drawn.
+    This theme element draws texts with Markdown support.
+
+    Parameters
+    ----------
+    color : str
+        Text color.
+    family : str
+        Font family.
+    face : {'plain', 'italic', 'bold', 'bold_italic'}, default='plain'
+        Font face.
+    size : int
+        Text size in px.
+    angle : float
+        Angle to rotate the text (in degrees).
+    hjust : float
+        Horizontal justification (in [0, 1]).
+        0 - left-justified;
+        1 - right-justified;
+        0.5 - center-justified.
+        Can be used with values out of range, but behaviour is not specified.
+    vjust : float
+        Vertical justification (in [0, 1]).
+        0 - bottom-justified;
+        1 - top-justified;
+        0.5 - middle-justified.
+        Can be used with values out of range, but behaviour is not specified.
+    margin : number or list of numbers
+        Margins around the text.
+        The margin may be specified using a number or a list of numbers:
+
+        - a number or list of one number - the same margin it applied to all four sides;
+        - a list of two numbers - the first margin applies to the top and bottom, the second - to the left and right;
+        - a list of three numbers -  the first margin applies to the top, the second - to the right and left, the third - to the bottom;
+        - a list of four numbers - the margins are applied to the top, right, bottom and left in that order.
+
+        It is acceptable to use None for any side; in this case, the default side value for this element will be used.
+    blank : bool, default=False
+        If True - draws nothing, and assigns no space.
+
+    Returns
+    -------
+    `dict`
+        Theme element specification.
+
+    Examples
+    --------
+    .. jupyter-execute::
+        :linenos:
+        :emphasize-lines: 12
+
+        from lets_plot import *
+        LetsPlot.setup_html()
+        ggplot() + \\
+            geom_blank() + \\
+            labs(
+                title='*Hello*, **world**',
+                subtitle='_Simple plot_',
+                caption='*Powered by **lets-plot***',
+                x='Title **X**',
+                y='Title **Y**'
+            ) + \\
+            theme(title=element_markdown())
+
+    """
+    return {'markdown': True, **locals()}
+
+
 def margin(t=None, r=None, b=None, l=None):
     """
     Function `margin()` is deprecated.