lets-plot 4.3.3__cp312-cp312-win_amd64.whl → 4.4.0__cp312-cp312-win_amd64.whl

lets_plot/plot/geom_function_.py

@@ -75,7 +75,8 @@ def _get_mapping(mapping):
     return aes(**{**x_mapping_dict, **mapping_dict, **y_mapping_dict})
 
 
-def geom_function(mapping=None, *, data=None, stat=None, geom=None, position=None, show_legend=None, tooltips=None,
+def geom_function(mapping=None, *, data=None, stat=None, geom=None, position=None, show_legend=None, manual_key=None,
+                  tooltips=None,
                   fun=None, xlim=None, n=None,
                   color_by=None,
                   **other_args):
@@ -104,6 +105,9 @@ def geom_function(mapping=None, *, data=None, stat=None, geom=None, position=Non
         'stack' or 'identity', or the result of calling a position adjustment function (e.g., `position_dodge()` etc.).
     show_legend : bool, default=True
         False - do not show legend for this layer.
+    manual_key : str or `layer_key`
+        The key to show in the manual legend.
+        Specify text for the legend label or advanced settings using the `layer_key()` function.
     tooltips : `layer_tooltips`
         Result of the call to the `layer_tooltips()` function.
         Specify appearance, style and content.
@@ -133,7 +137,7 @@ def geom_function(mapping=None, *, data=None, stat=None, geom=None, position=Non
     - x : x-axis value.
     - alpha : transparency level of a layer. Accept values between 0 and 1.
     - color (colour) : color of the geometry. String in the following formats: RGB/RGBA (e.g. "rgb(0, 0, 255)"); HEX (e.g. "#0000FF"); color name (e.g. "red"); role name ("pen", "paper" or "brush").
-    - linetype : type of the line. Codes and names: 0 = 'blank', 1 = 'solid', 2 = 'dashed', 3 = 'dotted', 4 = 'dotdash', 5 = 'longdash', 6 = 'twodash'.
+    - linetype : type of the line. Codes and names: 0 = 'blank', 1 = 'solid', 2 = 'dashed', 3 = 'dotted', 4 = 'dotdash', 5 = 'longdash', 6 = 'twodash'. For more info see https://lets-plot.org/python/pages/aesthetics.html#line-types.
     - size : line width.
 
     Examples
@@ -195,6 +199,7 @@ def geom_function(mapping=None, *, data=None, stat=None, geom=None, position=Non
                  stat=fun_stat,
                  position=position,
                  show_legend=show_legend,
+                 manual_key=manual_key,
                  sampling=None,
                  tooltips=tooltips,
                  color_by=color_by,

lets_plot/plot/geom_imshow_.py

@@ -10,7 +10,7 @@ from .geom import _geom
 from .scale import scale_gradientn
 from .scale import scale_grey
 from .util import as_boolean
-from .util import is_ndarray
+from .._type_utils import is_ndarray
 
 try:
     import png

lets_plot/plot/geom_livemap_.py

@@ -86,6 +86,10 @@ def geom_livemap(*,
     -----
     `geom_livemap()` draws a map, which can be dragged and zoomed.
 
+    ----
+
+    By default the livemap area has a non-zero inset. You can get rid of this with the theme: `theme(plot_inset=0)`.
+
     Examples
     --------
     .. jupyter-execute::

lets_plot/plot/ggtb_.py

@@ -0,0 +1,11 @@
+#
+# Copyright (c) 2024. JetBrains s.r.o.
+# Use of this source code is governed by the MIT license that can be found in the LICENSE file.
+#
+from .core import FeatureSpec
+
+__all__ = ['ggtb']
+
+
+def ggtb():
+    return FeatureSpec(kind='ggtoolbar', name=None)

lets_plot/plot/guide.py

@@ -4,21 +4,27 @@
 #
 from .core import FeatureSpec
 
-__all__ = ['guide_legend', 'guide_colorbar', 'guides']
+__all__ = ['guide_legend', 'guide_colorbar', 'guides', 'layer_key']
 
 
-def guide_legend(nrow=None, ncol=None, byrow=None):
+def guide_legend(title=None, *, nrow=None, ncol=None, byrow=None, override_aes=None):
     """
     Legend guide.
 
     Parameters
     ----------
+    title : str
+        Title of guide.
     nrow : int
         Number of rows in legend's guide.
     ncol : int
         Number of columns in legend's guide.
     byrow : bool, default=True
         Type of output: by row, or by column.
+    override_aes : dict
+        Dictionary that maps aesthetic parameters to new values, overriding the default legend appearance.
+        Each value can be a constant applied to all keys or a list that changes particular keys.
+
 
     Returns
     -------
@@ -45,18 +51,20 @@ def guide_legend(nrow=None, ncol=None, byrow=None):
         c = np.random.choice(list('abcdefgh'), size=n)
         ggplot({'x': x, 'y': y, 'c': c}, aes('x', 'y')) + \\
             geom_point(aes(shape='c'), size=4, alpha=.7) + \\
-            scale_shape(guide=guide_legend(nrow=3))
+            scale_shape(guide=guide_legend(nrow=3, override_aes={'color': 'red'}))
 
     """
     return _guide('legend', **locals())
 
 
-def guide_colorbar(barwidth=None, barheight=None, nbin=None):
+def guide_colorbar(title=None, *, barwidth=None, barheight=None, nbin=None):
     """
     Continuous color bar guide.
 
     Parameters
     ----------
+    title : str
+        Title of guide.
     barwidth : float
         Color bar width in px.
     barheight : float
@@ -98,6 +106,8 @@ def guide_colorbar(barwidth=None, barheight=None, nbin=None):
 
 
 def _guide(name, **kwargs):
+    if 'title' in kwargs and isinstance(kwargs['title'], int):
+        raise ValueError("Use keyword arguments for all other than 'title' parameters.")
     return FeatureSpec('guide', name=name, **kwargs)
 
 
@@ -108,10 +118,17 @@ def guides(**kwargs):
     Parameters
     ----------
     kwargs
-        Name-guide pairs where name should be an aesthetic.
-        The guide can either be a string ('colorbar', 'legend'),
-        or a call to a guide function (`guide_colorbar()`, `guide_legend()`)
-        specifying additional arguments, or 'none' to hide the guide.
+        Key-value pairs where the key can be:
+        
+        - An aesthetic name
+        - 'manual' - a key referring to the default custom legend
+        - A group name referring to a custom legend where the group is defined via the `layer_key()` function
+
+        The value can be either:
+
+        - A string ('colorbar', 'legend')
+        - A call to a guide function (`guide_colorbar()`, `guide_legend()`) specifying additional arguments
+        - 'none' to hide the guide
 
     Returns
     -------
@@ -139,5 +156,74 @@ def guides(**kwargs):
             guides(shape=guide_legend(ncol=2), \\
                    color=guide_colorbar(nbin=8, barwidth=20))
 
+    |
+
+    .. jupyter-execute::
+        :linenos:
+        :emphasize-lines: 11
+
+        import numpy as np
+        from lets_plot import *
+        LetsPlot.setup_html()
+        n = 10
+        np.random.seed(42)
+        x = list(range(n))
+        y = np.random.uniform(size=n)
+        ggplot({'x': x, 'y': y}, aes('x', 'y')) + \\
+            geom_point(color='red', manual_key="point") + \\
+            geom_line(color='blue', manual_key="line") + \\
+            guides(manual=guide_legend('Zones', ncol=2))
+
     """
     return FeatureSpec('guides', name=None, **kwargs)
+
+
+def layer_key(label, group=None, *, index=None, **kwargs):
+    """
+    Configure custom legend.
+
+    Parameters
+    ----------
+    label : str
+        Text for the element in the custom legend.
+    group : str, default='manual'
+        Group name by which elements are combined into a legend group.
+    index : int
+        Position of the element in the custom legend.
+    kwargs :
+        A list of aesthetic parameters to use in the custom legend.
+
+    Returns
+    -------
+    `FeatureSpec`
+        Custom legend specification.
+
+    Notes
+    -----
+    The group name specified with the `group` parameter can be used in the `labs()` and `guides()` functions
+    to further customize the display of this group (e.g. change its name).
+    In particular, items in the 'manual' group will be displayed without a title unless you change it manually.
+
+    |
+
+    If you set the same group and label for a legend element in different layers, they will merge into one complex legend element.
+
+    Examples
+    --------
+    .. jupyter-execute::
+        :linenos:
+        :emphasize-lines: 9-10
+
+        import numpy as np
+        from lets_plot import *
+        LetsPlot.setup_html()
+        n = 10
+        np.random.seed(42)
+        x = list(range(n))
+        y = np.random.uniform(size=n)
+        ggplot({'x': x, 'y': y}, aes('x', 'y')) + \\
+            geom_point(color='red', manual_key=layer_key("point", shape=21)) + \\
+            geom_line(color='blue', linetype=2, manual_key=layer_key("line", linetype=1))
+
+    """
+    return FeatureSpec('layer_key', name=None, label=label, group=group, index=index, **kwargs)

lets_plot/plot/label.py

@@ -3,7 +3,7 @@
 # Use of this source code is governed by the MIT license that can be found in the LICENSE file.
 #
 from .core import FeatureSpec, FeatureSpecArray
-from .scale import _scale
+from .guide import _guide, guides
 
 #
 # Plot title
@@ -112,7 +112,7 @@ def ylab(label):
 
 def labs(title=None, subtitle=None, caption=None, **labels):
     """
-    Change plot title and axis label.
+    Change plot title, axis labels and legend titles.
 
     Parameters
     ----------
@@ -123,7 +123,13 @@ def labs(title=None, subtitle=None, caption=None, **labels):
     caption : str
         The text for the plot caption.
     labels
-        Name-value pairs where name should be an aesthetic and value should be a string, e.g. `color="New Color label"`.
+        Name-value pairs where the name can be:
+
+        - An aesthetic name
+        - 'manual' - a key referring to the default custom legend
+        - A group name referring to a custom legend where the group is defined via the `layer_key()` function
+
+        The value should be a string, e.g. `color="New Color label"`.
 
     Returns
     -------
@@ -143,6 +149,24 @@ def labs(title=None, subtitle=None, caption=None, **labels):
             labs(title='New plot title', subtitle='The plot subtitle', caption='The plot caption', \\
                  x='New x axis label', y='New y axis label', size='New legend title')
 
+    |
+
+    .. jupyter-execute::
+        :linenos:
+        :emphasize-lines: 11
+
+        import numpy as np
+        from lets_plot import *
+        LetsPlot.setup_html()
+        n = 10
+        np.random.seed(42)
+        x = list(range(n))
+        y = np.random.uniform(size=n)
+        ggplot({'x': x, 'y': y}, aes('x', 'y')) + \\
+            geom_point(color='red', manual_key="point") + \\
+            geom_line(color='blue', manual_key="line") + \\
+            labs(manual='Zones')
+
     """
     specs = []
 
@@ -154,9 +178,9 @@ def labs(title=None, subtitle=None, caption=None, **labels):
     if caption is not None:
         specs.append(FeatureSpec('caption', name=None, text=caption))
 
-    # scales
-    for aes, label in labels.items():
-        specs.append(_scale(aesthetic=aes, name=label))
+    # guides
+    for key, label in labels.items():
+        specs.append(guides(**{key: _guide(name=None, title=label)}))
 
     if len(specs) == 1:
         return specs[0]

lets_plot/plot/marginal_layer.py

@@ -41,11 +41,10 @@ def ggmarginal(sides: str, *, size=None, layer: Union[LayerSpec, FeatureSpecArra
     --------
     .. jupyter-execute::
         :linenos:
-        :emphasize-lines: 24
+        :emphasize-lines: 23
 
         import numpy as np
         from lets_plot import *
-        from lets_plot.mapping import as_discrete
         LetsPlot.setup_html()
         LetsPlot.set_theme(theme_light())
 

lets_plot/plot/plot.py

@@ -6,10 +6,10 @@ import numbers
 
 from lets_plot._global_settings import has_global_value, get_global_val, MAX_WIDTH, MAX_HEIGHT
 from lets_plot.geo_data_internals.utils import is_geocoder
+from lets_plot.plot._global_theme import _get_global_theme
 from lets_plot.plot.core import FeatureSpec
 from lets_plot.plot.core import PlotSpec
-from lets_plot.plot.util import as_annotated_data
-from lets_plot.plot._global_theme import _get_global_theme
+from lets_plot.plot.util import as_annotated_data, key_int2str
 
 __all__ = ['ggplot', 'ggsize', 'GGBunch']
 
@@ -83,6 +83,8 @@ def ggplot(data=None, mapping=None):
     if is_geocoder(data):
         data = data.get_geocodes()
 
+    data = key_int2str(data)
+
     data, mapping, data_meta = as_annotated_data(data, mapping)
 
     plot_spec = PlotSpec(data, mapping, scales=[], layers=[], **data_meta)

lets_plot/plot/scale_colormap_mpl.py

@@ -0,0 +1,295 @@
+#  Copyright (c) 2024. JetBrains s.r.o.
+#  Use of this source code is governed by the MIT license that can be found in the LICENSE file.
+
+#
+#
+
+from typing import List
+
+from .scale import _is_color_scale
+from .scale import scale_gradientn
+
+try:
+    import matplotlib
+except ImportError:
+    matplotlib = None
+
+__all__ = ['scale_cmapmpl',
+           'scale_fill_cmapmpl',
+           'scale_color_cmapmpl'
+           ]
+
+
+def _cmapmpl_to_hex(cmap) -> List[str]:
+    """
+    Convert matplotlib colormap to list of hex colors.
+
+    Parameters
+    ----------
+    cmap: str or matplotlib colormap object
+
+    Returns
+    -------
+    List of hex color strings.
+    """
+    if matplotlib is None:
+        raise ImportError('matplotlib is not available. Please install it first.')
+
+    if isinstance(cmap, str):
+        cmap = matplotlib.colormaps[cmap]
+        if cmap is None:
+            raise ValueError(f"Unknown colormap: '{cmap}'")
+
+    if isinstance(cmap, matplotlib.colors.ListedColormap):
+        # colors from a discrete colormap (like "Dark2")
+        colors = cmap.colors
+    else:
+        # colors from a continuous colormap (like "plasma")
+        colors = cmap(range(64))
+
+    return [matplotlib.colors.to_hex(c) for c in colors]
+
+
+def scale_cmapmpl(aesthetic, *,
+                  cmap,
+                  name=None, breaks=None, labels=None, lablim=None,
+                  limits=None, na_value=None, guide=None, trans=None, format=None):
+    """
+    Create a scale for color-related aesthetic using matplotlib colormap.
+
+    Parameters
+    ----------
+    aesthetic : str or list
+        The name(s) of the aesthetic(s) that this scale works with.
+        Valid values are: 'color', 'fill', 'paint_a', 'paint_b', 'paint_c'.
+    cmap : str or matplotlib colormap object
+        The name of colormap or the colormap object to use.
+    name : str
+        The name of the scale - used as the axis label or the legend title.
+        If None, the default, the name of the scale
+        is taken from the first mapping used for that aesthetic.
+    breaks : list or dict
+        A list of data values specifying the positions of ticks, or a dictionary which maps the tick labels to the breaks values.
+    labels : list of str or dict
+        A list of labels on ticks, or a dictionary which maps the breaks values to the tick labels.
+    lablim : int, default=None
+        The maximum label length (in characters) before trimming is applied.
+    limits : list
+        A numeric vector of length two providing limits of the scale.
+    na_value
+        Missing values will be replaced with this value.
+    guide
+        Guide to use for this scale. It can either be a string ('colorbar', 'legend')
+        or a call to a guide function (`guide_colorbar()`, `guide_legend()`)
+        specifying additional arguments. 'none' will hide the guide.
+    trans : {'identity', 'log10', 'log2', 'symlog', 'sqrt', 'reverse'}
+        Name of built-in transformation.
+    format : str
+        Define the format for labels on the scale. The syntax resembles Python's:
+
+        - '.2f' -> '12.45'
+        - 'Num {}' -> 'Num 12.456789'
+        - 'TTL: {.2f}$' -> 'TTL: 12.45$'
+
+        For more info see https://lets-plot.org/python/pages/formats.html.
+
+    Returns
+    -------
+    `FeatureSpec`
+        The scale specification.
+
+    Notes
+    -----
+    This function requires matplotlib to be installed.
+
+    Examples
+    --------
+
+    .. jupyter-execute::
+        :linenos:
+        :emphasize-lines: 6
+
+        from lets_plot import *
+        LetsPlot.setup_html()
+        x = list(range(50))
+        ggplot({'x': x}, aes(x='x')) + \\
+            geom_tile(aes(color='x', fill='x')) + \\
+            scale_cmapmpl(aesthetic=['color', 'fill'], cmap='plasma', breaks=[5, 25, 45]) + \\
+            coord_cartesian() + \\
+            ggsize(600, 200)
+
+    """
+    if not _is_color_scale(aesthetic):
+        raise ValueError(
+            f"Invalid aesthetic: {aesthetic}. Expected one of: 'color', 'fill', 'paint_a', 'paint_b', 'paint_c'")
+
+    return scale_gradientn(aesthetic,
+                           colors=_cmapmpl_to_hex(cmap),
+                           name=name,
+                           breaks=breaks,
+                           labels=labels,
+                           lablim=lablim,
+                           limits=limits,
+                           na_value=na_value,
+                           guide=guide,
+                           trans=trans,
+                           format=format
+                           )
+
+
+def scale_fill_cmapmpl(cmap, *,
+                       name=None, breaks=None, labels=None, lablim=None,
+                       limits=None, na_value=None, guide=None, trans=None, format=None):
+    """
+    Create a scale for the 'fill' aesthetic using matplotlib colormap.
+
+    Parameters
+    ----------
+    cmap : str or matplotlib colormap object
+        The name of colormap or the colormap object to use.
+    name : str
+        The name of the scale - used as the axis label or the legend title.
+        If None, the default, the name of the scale
+        is taken from the first mapping used for that aesthetic.
+    breaks : list or dict
+        A list of data values specifying the positions of ticks, or a dictionary which maps the tick labels to the breaks values.
+    labels : list of str or dict
+        A list of labels on ticks, or a dictionary which maps the breaks values to the tick labels.
+    lablim : int, default=None
+        The maximum label length (in characters) before trimming is applied.
+    limits : list
+        A numeric vector of length two providing limits of the scale.
+    na_value
+        Missing values will be replaced with this value.
+    guide
+        Guide to use for this scale. It can either be a string ('colorbar', 'legend')
+        or a call to a guide function (`guide_colorbar()`, `guide_legend()`)
+        specifying additional arguments. 'none' will hide the guide.
+    trans : {'identity', 'log10', 'log2', 'symlog', 'sqrt', 'reverse'}
+        Name of built-in transformation.
+    format : str
+        Define the format for labels on the scale. The syntax resembles Python's:
+
+        - '.2f' -> '12.45'
+        - 'Num {}' -> 'Num 12.456789'
+        - 'TTL: {.2f}$' -> 'TTL: 12.45$'
+
+        For more info see https://lets-plot.org/python/pages/formats.html.
+
+    Returns
+    -------
+    `FeatureSpec`
+        The scale specification.
+
+    Notes
+    -----
+    This function requires matplotlib to be installed.
+
+    Examples
+    --------
+
+    .. jupyter-execute::
+        :linenos:
+        :emphasize-lines: 6
+
+        from lets_plot import *
+        LetsPlot.setup_html()
+        x = list(range(50))
+        ggplot({'x': x}, aes(x='x')) + \\
+            geom_tile(aes(fill='x')) + \\
+            scale_fill_cmapmpl('plasma', breaks=[5, 25, 45]) + \\
+            coord_cartesian() + \\
+            ggsize(600, 200)
+
+    """
+
+    return scale_cmapmpl('fill',
+                         cmap=cmap,
+                         name=name,
+                         breaks=breaks,
+                         labels=labels,
+                         lablim=lablim,
+                         limits=limits,
+                         na_value=na_value,
+                         guide=guide,
+                         trans=trans,
+                         format=format)
+
+
+def scale_color_cmapmpl(cmap, *,
+                        name=None, breaks=None, labels=None, lablim=None, limits=None,
+                        na_value=None, guide=None, trans=None, format=None):
+    """
+    Create a scale for the 'color' aesthetic using matplotlib colormap.
+
+    Parameters
+    ----------
+    cmap : str or matplotlib colormap object
+        The name of colormap or the colormap object to use.
+    name : str
+        The name of the scale - used as the axis label or the legend title.
+        If None, the default, the name of the scale
+        is taken from the first mapping used for that aesthetic.
+    breaks : list or dict
+        A list of data values specifying the positions of ticks, or a dictionary which maps the tick labels to the breaks values.
+    labels : list of str or dict
+        A list of labels on ticks, or a dictionary which maps the breaks values to the tick labels.
+    lablim : int, default=None
+        The maximum label length (in characters) before trimming is applied.
+    limits : list
+        A numeric vector of length two providing limits of the scale.
+    na_value
+        Missing values will be replaced with this value.
+    guide
+        Guide to use for this scale. It can either be a string ('colorbar', 'legend')
+        or a call to a guide function (`guide_colorbar()`, `guide_legend()`)
+        specifying additional arguments. 'none' will hide the guide.
+    trans : {'identity', 'log10', 'log2', 'symlog', 'sqrt', 'reverse'}
+        Name of built-in transformation.
+    format : str
+        Define the format for labels on the scale. The syntax resembles Python's:
+
+        - '.2f' -> '12.45'
+        - 'Num {}' -> 'Num 12.456789'
+        - 'TTL: {.2f}$' -> 'TTL: 12.45$'
+
+        For more info see https://lets-plot.org/python/pages/formats.html.
+
+    Returns
+    -------
+    `FeatureSpec`
+        The scale specification.
+
+    Notes
+    -----
+    This function requires matplotlib to be installed.
+
+    Examples
+    --------
+
+    .. jupyter-execute::
+        :linenos:
+        :emphasize-lines: 6
+
+        from lets_plot import *
+        LetsPlot.setup_html()
+        x = list(range(50))
+        ggplot({'x': x}, aes(x='x')) + \\
+            geom_tile(aes(color='x'), size=2) + \\
+            scale_color_cmapmpl('plasma', breaks=[5, 25, 45]) + \\
+            coord_cartesian() + \\
+            ggsize(600, 200)
+
+    """
+
+    return scale_cmapmpl('color',
+                         cmap=cmap,
+                         name=name,
+                         breaks=breaks,
+                         labels=labels,
+                         lablim=lablim,
+                         limits=limits,
+                         na_value=na_value,
+                         guide=guide,
+                         trans=trans,
+                         format=format)