lets-plot 4.7.2rc1__cp39-cp39-win_amd64.whl → 4.8.0rc1__cp39-cp39-win_amd64.whl

lets_plot/plot/core.py

@@ -19,8 +19,12 @@ def aes(x=None, y=None, **kwargs):
     Parameters
     ----------
     x, y, ... :
-        List of name value pairs giving aesthetics to map to variables.
+        Aesthetic mappings. Name-value pairs specifying which data variables to use for each aesthetic.
         The names for x and y aesthetics are typically omitted because they are so common; all other aesthetics must be named.
+        The specific list of supported aesthetics differs by geometry type.
+    group : str or list, optional
+        Data grouping control (not a true aesthetic). Use a variable name to group by that variable,
+        a list of variables to group by their interaction, or an empty list to disable all grouping.
 
     Returns
     -------
@@ -33,11 +37,25 @@ def aes(x=None, y=None, **kwargs):
     (aesthetics) of geometries. This function also standardizes aesthetic names by, for example, converting
     colour to color.
 
-    Aesthetic mappings are not to be confused with aesthetic settings; the latter are used to set aesthetics to
-    some constant values, e.g. make all points red in the plot. If one wants to make the color of a point
+    Aesthetic mappings are not to be confused with aesthetic settings; the latter is used to set aesthetics to
+    some constant values, e.g., make all points red in the plot. If one wants to make the color of a point
     depend on the value of a variable, he/she should project this variable to the color aesthetic via
     aesthetic mapping.
 
+    **Data Grouping**
+
+    The ``group`` parameter is not a true aesthetic but controls how data is grouped for visualization:
+
+    Default Grouping Behavior:
+        Lets-Plot automatically groups data by discrete variables mapped to aesthetics like ``color``, ``shape``,
+        ``linetype``, etc. This creates separate visual elements (lines, paths, polygons) for each unique
+        combination of these variables.
+
+    Explicit Group Control:
+        - Use ``group='variable_name'`` to group only by that specific variable, overriding default grouping
+        - Use ``group=['var1', 'var2', ...]`` to group by the interaction of multiple variables
+        - Use ``group=[]`` to disable all the grouping completely
+
     Examples
     --------
     .. jupyter-execute::
@@ -477,6 +495,8 @@ class PlotSpec(FeatureSpec):
         """
         Export the plot in SVG format.
 
+        Plots containing ``geom_livemap()`` are not supported.
+
         Parameters
         ----------
         self : ``PlotSpec``
@@ -503,18 +523,20 @@ class PlotSpec(FeatureSpec):
         --------
         .. jupyter-execute::
             :linenos:
-            :emphasize-lines: 9
+            :emphasize-lines: 10
 
             import numpy as np
             import io
             from lets_plot import *
             from IPython import display
             LetsPlot.setup_html()
+            np.random.seed(42)
             x = np.random.randint(10, size=100)
             p = ggplot({'x': x}, aes(x='x')) + geom_bar()
             file_like = io.BytesIO()
             p.to_svg(file_like)
             display.SVG(file_like.getvalue())
+
         """
         return _to_svg(self, path, w=w, h=h, unit=unit)
 
@@ -544,16 +566,20 @@ class PlotSpec(FeatureSpec):
         --------
         .. jupyter-execute::
             :linenos:
-            :emphasize-lines: 8
+            :emphasize-lines: 10
 
-            import numpy as np
             import io
+            from IPython.display import HTML
+            import numpy as np
             from lets_plot import *
             LetsPlot.setup_html()
+            np.random.seed(42)
             x = np.random.randint(10, size=100)
             p = ggplot({'x': x}, aes(x='x')) + geom_bar()
             file_like = io.BytesIO()
             p.to_html(file_like)
+            HTML(file_like.getvalue().decode('utf-8'))
+
         """
         return _to_html(self, path, iframe)
 
@@ -561,6 +587,8 @@ class PlotSpec(FeatureSpec):
         """
         Export a plot to a file or to a file-like object in PNG format.
 
+        Plots containing ``geom_livemap()`` are not supported.
+
         Parameters
         ----------
         self : ``PlotSpec``
@@ -622,13 +650,14 @@ class PlotSpec(FeatureSpec):
         --------
         .. jupyter-execute::
             :linenos:
-            :emphasize-lines: 9
+            :emphasize-lines: 10
 
             import numpy as np
             import io
             from lets_plot import *
             from IPython import display
             LetsPlot.setup_html()
+            np.random.seed(42)
             x = np.random.randint(10, size=100)
             p = ggplot({'x': x}, aes(x='x')) + geom_bar()
             file_like = io.BytesIO()
@@ -642,6 +671,8 @@ class PlotSpec(FeatureSpec):
         """
         Export a plot to a file or to a file-like object in PDF format.
 
+        Plots containing ``geom_livemap()`` are not supported.
+
         Parameters
         ----------
         self : ``PlotSpec``

lets_plot/plot/facet.py

@@ -38,11 +38,11 @@ def facet_grid(x=None, y=None, *, scales=None, x_order=1, y_order=1,
         Specify the format pattern for displaying faceting values in rows.
     x_labwidth : int, default=None
         The maximum label length (in characters) before a line breaking is applied.
-        If the original facet label already contains ``\\\\n`` as a text separator, it splits at those points first,
+        If the original facet label already contains ``\\n`` as a text separator, it splits at those points first,
         then wraps each part according to ``x_labwidth``.
     y_labwidth : int, default=None
         The maximum label length (in characters) before a line breaking is applied.
-        If the original facet label already contains ``\\\\n`` as a text separator, it splits at those points first,
+        If the original facet label already contains ``\\n`` as a text separator, it splits at those points first,
         then wraps each part according to ``y_labwidth``.
 
     Returns
@@ -138,7 +138,7 @@ def facet_wrap(facets, ncol=None, nrow=None, *, scales=None, order=1, format=Non
         Direction: either 'h' for horizontal or 'v' for vertical.
     labwidth : int or list
         The maximum label length (in characters) before a line breaking is applied.
-        If the original facet label already contains ``\\\\n`` as a text separator, it splits at those points first,
+        If the original facet label already contains ``\\n`` as a text separator, it splits at those points first,
         then wraps each part according to ``labwidth``.
 
 

lets_plot/plot/geom.py

@@ -22,7 +22,7 @@ __all__ = ['geom_point', 'geom_path', 'geom_line',
            'geom_boxplot', 'geom_violin', 'geom_sina', 'geom_ydotplot',
            'geom_area_ridges',
            'geom_ribbon', 'geom_area', 'geom_density',
-           'geom_density2d', 'geom_density2df', 'geom_jitter',
+           'geom_density2d', 'geom_density2df', 'geom_pointdensity', 'geom_jitter',
            'geom_qq', 'geom_qq2', 'geom_qq_line', 'geom_qq2_line',
            'geom_freqpoly', 'geom_step', 'geom_rect',
            'geom_segment', 'geom_curve', 'geom_spoke',
@@ -510,21 +510,48 @@ def geom_line(mapping=None, *, data=None, stat=None, position=None, show_legend=
 
     .. jupyter-execute::
         :linenos:
-        :emphasize-lines: 12-13
+        :emphasize-lines: 11-12
 
         import numpy as np
         import pandas as pd
         from lets_plot import *
         LetsPlot.setup_html()
+        n = 100
         np.random.seed(42)
-        t = np.arange(100)
+        x = np.random.uniform(0, 2, size=n)
+        y = x**2 + np.random.normal(scale=.5, size=n)
+        ggplot({'x': x, 'y': y}, aes('x', 'y')) + \\
+            geom_point() + \\
+            geom_line(stat='smooth', method='loess',
+                      color='red', linetype='longdash')
+
+    |
+
+    .. jupyter-execute::
+        :linenos:
+        :emphasize-lines: 13-16,19
+
+        import numpy as np
+        import pandas as pd
+        from lets_plot import *
+        LetsPlot.setup_html()
+        np.random.seed(42)
+        t = np.linspace(0, 1, 100)
         x1 = np.cumsum(np.random.normal(size=t.size))
         x2 = np.cumsum(np.random.normal(size=t.size))
         df = pd.DataFrame({'t': t, 'x1': x1, 'x2': x2})
-        df = pd.melt(df, id_vars=['t'], value_vars=['x1', 'x2'])
-        ggplot(df, aes(x='t', y='value', group='variable')) + \\
-            geom_line(aes(color='variable'), size=1, alpha=0.5) + \\
-            geom_line(stat='smooth', color='red', linetype='longdash')
+        melted_df = pd.melt(df, id_vars=['t'], value_vars=['x1', 'x2'])
+        gggrid([
+            ggplot(df) + \\
+                geom_line(aes(x='t', y='x1'), size=1, alpha=0.5,
+                          color="red", manual_key="x1") + \\
+                geom_line(aes(x='t', y='x2'), size=1, alpha=0.5,
+                          color="blue", manual_key="x2") + \\
+                ggtitle('Two geom_line() layers'),
+            ggplot(melted_df, aes(x='t', y='value', group='variable')) + \\
+                geom_line(aes(color='variable'), size=1, alpha=0.5) + \\
+                ggtitle('One geom_line() layer')
+        ])
 
     """
     return _geom('line',
@@ -804,8 +831,10 @@ def geom_bar(mapping=None, *, data=None, stat=None, position=None, show_legend=N
     -----
     ``geom_bar()`` makes the height of the bar proportional to the number
     of observed variable values, mapped to x-axis. Is intended to use for discrete data.
-    If used for continuous data with stat='bin' produces histogram for binned data.
-    ``geom_bar()`` handles no group aesthetics.
+    If used for continuous data with ``stat='bin'`` produces histogram for binned data.
+
+    ``geom_bar()`` handles no group aesthetics. Stacking and dodging are controlled by the position adjustment.
+    With ``position='identity'``, groups are neither stacked nor dodged (bars overlap).
 
     Computed variables:
 
@@ -906,6 +935,7 @@ def geom_histogram(mapping=None, *, data=None, stat=None, position=None, show_le
                    binwidth=None,
                    center=None,
                    boundary=None,
+                   breaks=None,
                    color_by=None, fill_by=None,
                    **other_args):
     """
@@ -965,6 +995,9 @@ def geom_histogram(mapping=None, *, data=None, stat=None, position=None, show_le
         Specify x-value to align bin centers to.
     boundary : float
         Specify x-value to align bin boundary (i.e., point between bins) to.
+    breaks : list of float
+        Specify exact positions of bin boundaries.
+        Overrides ``bins``, ``binwidth``, ``center`` and ``boundary``.
     color_by : {'fill', 'color', 'paint_a', 'paint_b', 'paint_c'}, default='color'
         Define the color aesthetic for the geometry.
     fill_by : {'fill', 'color', 'paint_a', 'paint_b', 'paint_c'}, default='fill'
@@ -991,7 +1024,6 @@ def geom_histogram(mapping=None, *, data=None, stat=None, position=None, show_le
     - ..density.. : normalized number of points so that plot area is 1.
     - ..sumprop.. : normalized number of points so that sum of y-values is 1.
     - ..sumpct.. : normalized number of points so that sum of y-values is 100.
-    - ..binwidth.. : width of each bin.
 
     ``geom_histogram()`` understands the following aesthetics mappings:
 
@@ -1037,6 +1069,21 @@ def geom_histogram(mapping=None, *, data=None, stat=None, position=None, show_le
 
     |
 
+    .. jupyter-execute::
+        :linenos:
+        :emphasize-lines: 7-8
+
+        import numpy as np
+        from lets_plot import *
+        LetsPlot.setup_html()
+        np.random.seed(42)
+        data = {'age': np.random.gamma(4.0, size=1000, scale=10.0)}
+        age_breaks = [0, 12, 17, 64, 100]
+        ggplot(data) + geom_histogram(aes(x='age'), breaks=age_breaks,
+                                      color="black", fill="gray80")
+
+    |
+
     .. jupyter-execute::
         :linenos:
         :emphasize-lines: 8-10
@@ -1070,6 +1117,7 @@ def geom_histogram(mapping=None, *, data=None, stat=None, position=None, show_le
                  binwidth=binwidth,
                  center=center,
                  boundary=boundary,
+                 breaks=breaks,
                  color_by=color_by, fill_by=fill_by,
                  **other_args)
 
@@ -5656,6 +5704,232 @@ def geom_density2df(mapping=None, *, data=None, stat=None, position=None, show_l
                  **other_args)
 
 
+def geom_pointdensity(mapping=None, *, data=None, stat=None, position=None, show_legend=None, inherit_aes=None,
+                      manual_key=None, sampling=None,
+                      tooltips=None,
+                      method=None,
+                      kernel=None,
+                      adjust=None,
+                      bw=None,
+                      n=None,
+                      map=None, map_join=None, use_crs=None,
+                      color_by=None, fill_by=None,
+                      **other_args):
+    """
+    Plots data points and colors each point by the local density of nearby points.
+
+    Parameters
+    ----------
+    mapping : ``FeatureSpec``
+        Set of aesthetic mappings created by `aes() <https://lets-plot.org/python/pages/api/lets_plot.aes.html>`__ function.
+        Aesthetic mappings describe the way that variables in the data are
+        mapped to plot "aesthetics".
+    data : dict or Pandas or Polars ``DataFrame``
+        The data to be displayed in this layer. If None, the default, the data
+        is inherited from the plot data as specified in the call to ggplot.
+    stat : str, default='pointdensity'
+        The statistical transformation to use on the data for this layer, as a string.
+    position : str or ``FeatureSpec``, default='identity'
+        Position adjustment.
+        Either a position adjustment name: 'dodge', 'jitter', 'nudge', 'jitterdodge', 'fill',
+        'stack' or 'identity', or the result of calling a position adjustment function (e.g., `position_dodge() <https://lets-plot.org/python/pages/api/lets_plot.position_dodge.html>`__ etc.).
+    show_legend : bool, default=True
+        False - do not show legend for this layer.
+    inherit_aes : bool, default=True
+        False - do not combine the layer aesthetic mappings with the plot shared mappings.
+    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() <https://lets-plot.org/python/pages/api/lets_plot.layer_key.html>`__ function.
+    sampling : ``FeatureSpec``
+        Result of the call to the ``sampling_xxx()`` function.
+        To prevent any sampling for this layer pass value "none" (string "none").
+    tooltips : ``layer_tooltips``
+        Result of the call to the `layer_tooltips() <https://lets-plot.org/python/pages/api/lets_plot.layer_tooltips.html>`__ function.
+        Specify appearance, style and content.
+        Set tooltips='none' to hide tooltips from the layer.
+    method : {'auto', 'neighbours', 'kde2d'}, default='auto'
+        The method to compute the density estimate.
+
+        - ``'neighbours'`` – estimates density from the number of nearby points.
+        - ``'kde2d'`` – estimates density using a smoothed 2D kernel density.
+        - ``'auto'`` – automatically selects an estimation method based on data size.
+
+    kernel : str, default='gaussian'
+        The kernel we use to calculate the density function.
+        Choose among 'gaussian', 'cosine', 'optcosine', 'rectangular' (or 'uniform'),
+        'triangular', 'biweight' (or 'quartic'), 'epanechikov' (or 'parabolic').
+        Only used when ``method='kde2d'``.
+    bw : str or list of float
+        The method (or exact value) of bandwidth.
+        Either a string (choose among 'nrd0' and 'nrd'), or a float array of length 2.
+        Only used when ``method='kde2d'``.
+    adjust : float
+        If ``method='neighbours'``, adjust the radius in which to count neighbours.
+        If ``method='kde2d'``, adjust the value of bandwidth by multiplying it.
+    n : list of int
+        The number of sampled points for plotting the function
+        (on x and y direction correspondingly).
+        Only used when ``method='kde2d'``.
+    map : ``GeoDataFrame`` or ``Geocoder``
+        Data containing coordinates of points.
+    map_join : str or list
+        Keys used to join map coordinates with data.
+        First value in pair - column/columns in ``data``.
+        Second value in pair - column/columns in ``map``.
+    use_crs : str, optional, default="EPSG:4326" (aka WGS84)
+        EPSG code of the coordinate reference system (CRS) or the keyword "provided".
+        If an EPSG code is given, then all the coordinates in ``GeoDataFrame`` (see the ``map`` parameter)
+        will be projected to this CRS.
+        Specify "provided" to disable any further re-projection and to keep the ``GeoDataFrame``'s original CRS.
+    color_by : {'fill', 'color', 'paint_a', 'paint_b', 'paint_c'}, default='color'
+        Define the color aesthetic for the geometry.
+    fill_by : {'fill', 'color', 'paint_a', 'paint_b', 'paint_c'}, default='fill'
+        Define the fill aesthetic for the geometry.
+    other_args
+        Other arguments passed on to the layer.
+        These are often aesthetics settings used to set an aesthetic to a fixed value,
+        like color='red', fill='blue', size=3 or shape=21.
+        They may also be parameters to the paired geom/stat.
+
+    Returns
+    -------
+    ``LayerSpec``
+        Geom object specification.
+
+    Notes
+    -----
+    Computed variables:
+
+    - ..density.. : density estimate (mapped by default).
+    - ..count.. : density * number of points (corresponds to number of nearby points for ``'neighbours'`` method).
+    - ..scaled.. : density estimate, scaled to maximum of 1.
+
+    ``geom_pointdensity()`` understands the following aesthetics mappings:
+
+    - x : x-axis value.
+    - y : y-axis value.
+    - alpha : transparency level of the point. Accept values between 0 and 1.
+    - color (colour) : color of the geometry. For more info see `Color and Fill <https://lets-plot.org/python/pages/aesthetics.html#color-and-fill>`__.
+    - fill : fill color. Is applied only to the points of shapes having inner area. For more info see `Color and Fill <https://lets-plot.org/python/pages/aesthetics.html#color-and-fill>`__.
+    - shape : shape of the point, an integer from 0 to 25. For more info see `Point Shapes <https://lets-plot.org/python/pages/aesthetics.html#point-shapes>`__.
+    - angle : rotation angle of the point shape, in degrees.
+    - size : size of the point.
+    - stroke : width of the shape border. Applied only to the shapes having border.
+    - weight : used by 'pointdensity' stat to compute weighted density.
+
+    ----
+
+    The ``data`` and ``map`` parameters of ``GeoDataFrame`` type support shapes ``Point`` and ``MultiPoint``.
+
+    The ``map`` parameter of ``Geocoder`` type implicitly invokes
+    `get_centroids() <https://lets-plot.org/python/pages/api/lets_plot.geo_data.NamesGeocoder.html#lets_plot.geo_data.NamesGeocoder.get_centroids>`__ function.
+
+    ----
+
+    The conventions for the values of ``map_join`` parameter are as follows:
+
+    - Joining data and ``GeoDataFrame`` object
+
+      Data has a column named 'State_name' and ``GeoDataFrame`` has a matching column named 'state':
+
+      - map_join=['State_Name', 'state']
+      - map_join=[['State_Name'], ['state']]
+
+    - Joining data and ``Geocoder`` object
+
+      Data has a column named 'State_name'. The matching key in ``Geocoder`` is always 'state' (providing it is a state-level geocoder) and can be omitted:
+
+      - map_join='State_Name'
+      - map_join=['State_Name']
+
+    - Joining data by composite key
+
+      Joining by composite key works like in examples above, but instead of using a string for a simple key you need to use an array of strings for a composite key. The names in the composite key must be in the same order as in the US street addresses convention: 'city', 'county', 'state', 'country'. For example, the data has columns 'State_name' and 'County_name'. Joining with a 2-keys county level ``Geocoder`` object (the ``Geocoder`` keys 'county' and 'state' are omitted in this case):
+
+      - map_join=['County_name', 'State_Name']
+
+    ----
+
+    To hide axis tooltips, set 'blank' or the result of `element_blank() <https://lets-plot.org/python/pages/api/lets_plot.element_blank.html>`__
+    to the ``axis_tooltip``, ``axis_tooltip_x`` or ``axis_tooltip_y`` parameter of the `theme() <https://lets-plot.org/python/pages/api/lets_plot.theme.html>`__.
+
+    Examples
+    --------
+    .. jupyter-execute::
+        :linenos:
+        :emphasize-lines: 9
+
+        import numpy as np
+        from lets_plot import *
+        LetsPlot.setup_html()
+        n = 1000
+        np.random.seed(42)
+        x = np.random.normal(size=n)
+        y = np.random.normal(size=n)
+        ggplot({'x': x, 'y': y}, aes('x', 'y')) + \\
+            geom_pointdensity()
+
+    |
+
+    .. jupyter-execute::
+        :linenos:
+        :emphasize-lines: 10-11
+
+        import numpy as np
+        from lets_plot import *
+        LetsPlot.setup_html()
+        n = 5_000
+        np.random.seed(42)
+        x = np.random.poisson(size=n) + np.random.normal(scale=.1, size=n)
+        y = np.random.normal(size=n)
+        gggrid([
+            ggplot({'x': x, 'y': y}, aes('x', 'y')) + \\
+                geom_pointdensity(aes(color='..count..'),
+                                  method=method) + \\
+                ggtitle("method='{0}'".format(method))
+            for method in ['neighbours', 'kde2d']
+        ])
+
+    |
+
+    .. jupyter-execute::
+        :linenos:
+        :emphasize-lines: 10-12
+
+        import numpy as np
+        from lets_plot import *
+        LetsPlot.setup_html()
+        n = 1000
+        np.random.seed(42)
+        data = {'x': 10 * np.random.normal(size=n) - 100, \\
+                'y': 3 * np.random.normal(size=n) + 40}
+        ggplot(data, aes('x', 'y')) + \\
+            geom_livemap(zoom=4) + \\
+            geom_pointdensity(aes(fill='..density..'),
+                              color='black', shape=21,
+                              show_legend=False) + \\
+            scale_fill_viridis()
+
+    """
+    return _geom('pointdensity',
+                 mapping=mapping,
+                 data=data,
+                 stat=stat,
+                 position=position,
+                 show_legend=show_legend,
+                 inherit_aes=inherit_aes,
+                 manual_key=manual_key,
+                 sampling=sampling,
+                 tooltips=tooltips,
+                 method=method,
+                 kernel=kernel,
+                 adjust=adjust,
+                 bw=bw, n=n,
+                 map=map, map_join=map_join, use_crs=use_crs,
+                 color_by=color_by, fill_by=fill_by,
+                 **other_args)
+
+
 def geom_jitter(mapping=None, *, data=None, stat=None, position=None, show_legend=None, inherit_aes=None,
                 manual_key=None, sampling=None,
                 tooltips=None,
@@ -8368,19 +8642,24 @@ def geom_pie(mapping=None, *, data=None, stat=None, position=None, show_legend=N
 
     .. jupyter-execute::
         :linenos:
-        :emphasize-lines: 9-10
+        :emphasize-lines: 9-15
 
         from lets_plot import *
         from lets_plot.geo_data import *
         LetsPlot.setup_html()
-        data = {"city": ["New York", "New York", "Philadelphia", "Philadelphia"], \\
-                "est_pop_2020": [4_381_593, 3_997_959, 832_685, 748_846], \\
+        data = {"city": ["New York", "New York", "Philadelphia", "Philadelphia"],
+                "est_pop_2020": [4_381_593, 3_997_959, 832_685, 748_846],
                 "sex": ["female", "male", "female", "male"]}
         centroids = geocode_cities(data["city"]).get_centroids()
         ggplot() + geom_livemap() + \\
-            geom_pie(aes(slice="est_pop_2020", fill="sex", size="est_pop_2020"), \\
-                     stat='identity', data=data, map=centroids, map_join="city") + \\
-            scale_size(guide='none')
+            geom_pie(aes(fill="sex", weight="est_pop_2020", size="..sum..", group=["city", "sex"]),
+                     data=data, map=centroids, map_join="city",
+                     tooltips=layer_tooltips().title("@city")
+                                              .format("@est_pop_2020", ".3~s")
+                                              .line("population (@sex):\\n@est_pop_2020 (@..proppct..)")
+                                              .format("@..sum..", ".3~s")
+                                              .line("population (total):\\n@..sum..")) + \\
+            scale_size(range=[4, 10], guide='none')
 
     """
     if 'stroke_color' in other_args:

lets_plot/plot/geom_livemap_.py

@@ -63,17 +63,25 @@ def geom_livemap(*,
     data_size_zoomin : int, default=0
         Control how zooming-in of the map widget increases size of geometry objects (circles, lines etc.) on map
         when the size is set by means of mapping between the data and the ``size`` aesthetic.
+
         0 - size never increases;
+
         -1 - size will be increasing without limits;
+
         n - a number of zooming-in steps (counting from the initial state of the map widget)
         when size of objects will be increasing. Farther zooming will no longer affect the size.
+
     const_size_zoomin : int, default=-1
         Control how zooming-in of the map widget increases size of geometry objects (circles, lines etc.) on map
         when the size is not linked to a data (i.e. constant size).
+
         0 - size never increases;
+
         -1 - size will be increasing without limits;
+
         n - a number of zooming-in steps (counting from the initial state of the map widget)
         when size of objects will be increasing. Farther zooming will no longer affect the size.
+
     other_args
         Other arguments passed on to the layer.
 

lets_plot/plot/gggrid_.py

@@ -19,7 +19,8 @@ def gggrid(plots: list, ncol: int = None, *,
            hspace: float = None,
            vspace: float = None,
            fit: bool = None,
-           align: bool = None
+           align: bool = None,
+           guides: str = None
            ) -> SupPlotsSpec:
     """
     Combine several plots on one figure, organized in a regular grid.
@@ -27,10 +28,10 @@ def gggrid(plots: list, ncol: int = None, *,
     Parameters
     ----------
     plots : list
-        A list where each element is a plot specification, a subplots specification, or None.
-        Use value None to fill-in empty cells in grid.
+        A list where each element is a plot specification, a subplot specification, or None.
+        Use None to fill in empty cells in the grid.
     ncol : int
-        Number of columns in grid.
+        Number of columns in the grid.
         If not specified, shows plots horizontally, in one row.
     sharex, sharey : bool or str, default=False
         Controls sharing of axis limits between subplots in the grid.
@@ -41,9 +42,9 @@ def gggrid(plots: list, ncol: int = None, *,
         - 'col' - share limits between subplots in the same column.
 
     widths : list of numbers
-        Relative width of each column of grid, left to right.
+        Relative width of each column in the grid, left to right.
     heights : list of numbers
-        Relative height of each row of grid, top-down.
+        Relative height of each row in the grid, top-down.
     hspace : float, default=4.0
         Cell horizontal spacing in px.
     vspace : float, default=4.0
@@ -54,6 +55,17 @@ def gggrid(plots: list, ncol: int = None, *,
     align : bool, default=False
         If True, align inner areas (i.e. "geom" bounds) of plots.
         However, cells containing other (sub)grids are not participating in the plot "inner areas" layouting.
+    guides : str, default='auto'
+        Specifies how guides (legends and colorbars) should be treated in the layout.
+
+        - 'collect' - collect guides from all subplots, removing duplicates.
+        - 'keep' - keep guides in their original subplots; do not collect at this level.
+        - 'auto' - allow guides to be collected if an upper-level layout uses ``guides='collect'``; otherwise, keep them in subplots.
+
+        Duplicates are identified by comparing visual properties:
+
+        - For legends: title, labels, and all aesthetic values (colors, shapes, sizes, etc.).
+        - For colorbars: title, domain limits, breaks, and color gradient.
 
     Returns
     -------
@@ -111,7 +123,8 @@ def gggrid(plots: list, ncol: int = None, *,
         hspace=hspace,
         vspace=vspace,
         fit=fit,
-        align=align
+        align=align,
+        guides=guides
     )
 
     figures = [_strip_theme_if_global(fig) for fig in plots]