lets-plot 4.8.1rc1__cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.whl

lets_plot/plot/guide.py

@@ -0,0 +1,231 @@
+#
+# Copyright (c) 2019. 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__ = ['guide_legend', 'guide_colorbar', 'guides', 'layer_key']
+
+
+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
+    -------
+    ``FeatureSpec``
+        Legend guide specification.
+
+    Notes
+    -----
+    Legend type guide shows key (i.e., geoms) mapped onto values.
+
+    Examples
+    --------
+    .. jupyter-execute::
+        :linenos:
+        :emphasize-lines: 11
+
+        import numpy as np
+        from lets_plot import *
+        LetsPlot.setup_html()
+        n = 100
+        np.random.seed(42)
+        x = np.random.uniform(size=n)
+        y = np.random.uniform(size=n)
+        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, override_aes={'color': 'red'}))
+
+    """
+    return _guide('legend', **locals())
+
+
+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
+        Color bar height in px.
+    nbin : int
+        Number of bins in color bar.
+
+    Returns
+    -------
+    ``FeatureSpec``
+        Color guide specification.
+
+    Notes
+    -----
+    Color bar guide shows continuous color scales mapped onto values.
+    Color bar is available with scale_fill and scale_color.
+
+    Examples
+    --------
+    .. jupyter-execute::
+        :linenos:
+        :emphasize-lines: 12
+
+        import numpy as np
+        from lets_plot import *
+        LetsPlot.setup_html()
+        n = 50
+        np.random.seed(42)
+        x = np.random.uniform(size=n)
+        y = np.random.uniform(size=n)
+        v = np.random.normal(size=n)
+        ggplot({'x': x, 'y': y, 'v': v}, aes('x', 'y')) + \\
+            geom_point(aes(fill='v'), size=4, shape=21, color='black') + \\
+            scale_fill_gradient2(low='red', mid='yellow', high='blue', \\
+                                 guide=guide_colorbar(nbin=8, barwidth=10))
+
+    """
+    return _guide('colorbar', **locals())
+
+
+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)
+
+
+def guides(**kwargs):
+    """
+    Set guides for each scale.
+
+    Parameters
+    ----------
+    kwargs
+        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() <https://lets-plot.org/python/pages/api/lets_plot.layer_key.html>`__ function
+
+        The value can be either:
+
+        - A string ('colorbar', 'legend')
+        - A call to a guide function (`guide_colorbar() <https://lets-plot.org/python/pages/api/lets_plot.guide_colorbar.html>`__, `guide_legend() <https://lets-plot.org/python/pages/api/lets_plot.guide_legend.html>`__) specifying additional arguments
+        - 'none' to hide the guide
+
+    Returns
+    -------
+    ``FeatureSpec``
+        Guides specification.
+
+    Examples
+    --------
+    .. jupyter-execute::
+        :linenos:
+        :emphasize-lines: 13-14
+
+        import numpy as np
+        from lets_plot import *
+        LetsPlot.setup_html()
+        n = 25
+        np.random.seed(42)
+        x = np.random.uniform(size=n)
+        y = np.random.uniform(size=n)
+        c = np.random.choice(list('abcdefgh'), size=n)
+        v = np.random.normal(size=n)
+        ggplot({'x': x, 'y': y, 'c': c, 'v': v}, aes('x', 'y')) + \\
+            geom_point(aes(shape='c', color='v'), size=4) + \\
+            scale_color_gradient2(low='red', mid='yellow', high='blue') + \\
+            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() <https://lets-plot.org/python/pages/api/lets_plot.labs.html>`__ and
+    `guides() <https://lets-plot.org/python/pages/api/lets_plot.guides.html>`__ 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

@@ -0,0 +1,187 @@
+#
+# Copyright (c) 2019. 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, FeatureSpecArray
+from .guide import _guide, guides
+
+#
+# Plot title
+# Scale names: axis labels / legend titles
+#
+__all__ = ['ggtitle',
+           'labs',
+           'xlab', 'ylab']
+
+
+def ggtitle(label, subtitle=None):
+    """
+    Add title to the plot.
+
+    Parameters
+    ----------
+    label : str
+        The text for the plot title.
+    subtitle : str
+        The text for the plot subtitle.
+
+    Returns
+    -------
+    ``FeatureSpec``
+        Plot title specification.
+
+    Notes
+    -----
+    Split a long title/subtitle into two lines or more using ``\\n`` as a text separator.
+
+    Examples
+    --------
+    .. jupyter-execute::
+        :linenos:
+        :emphasize-lines: 5
+        
+        from lets_plot import *
+        LetsPlot.setup_html()
+        data = {'x': list(range(10)), 'y': list(range(10))}
+        ggplot(data, aes('x', 'y')) + geom_point(aes(size='y')) + \\
+            ggtitle('New Plot Title')
+
+    """
+    return labs(title=label, subtitle=subtitle)
+
+
+def xlab(label):
+    """
+    Add label to the x axis.
+
+    Parameters
+    ----------
+    label : str
+        The text for the x axis label.
+
+    Returns
+    -------
+    ``FeatureSpec``
+        Axis label specification.
+
+    Examples
+    --------
+    .. jupyter-execute::
+        :linenos:
+        :emphasize-lines: 5
+        
+        from lets_plot import *
+        LetsPlot.setup_html()
+        data = {'x': list(range(10)), 'y': list(range(10))}
+        ggplot(data, aes('x', 'y')) + geom_point(aes(size='y')) + \\
+            xlab('x axis label')
+
+    """
+    return labs(x=label)
+
+
+def ylab(label):
+    """
+    Add label to the y-axis.
+
+    Parameters
+    ----------
+    label : str
+        The text for the y-axis label.
+
+    Returns
+    -------
+    ``FeatureSpec``
+        Axis label specification.
+
+    Examples
+    --------
+    .. jupyter-execute::
+        :linenos:
+        :emphasize-lines: 5
+        
+        from lets_plot import *
+        LetsPlot.setup_html()
+        data = {'x': list(range(10)), 'y': list(range(10))}
+        ggplot(data, aes('x', 'y')) + geom_point(aes(size='y')) + \\
+            ylab('y axis label')
+
+    """
+    return labs(y=label)
+
+
+def labs(title=None, subtitle=None, caption=None, **labels):
+    """
+    Change plot title, axis labels and legend titles.
+
+    Parameters
+    ----------
+    title : str
+        The text for the plot title.
+    subtitle : str
+        The text for the plot subtitle.
+    caption : str
+        The text for the plot caption.
+    labels
+        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() <https://lets-plot.org/python/pages/api/lets_plot.layer_key.html>`__ function.
+
+        The value should be a string, e.g. ``color="New Color label"``.
+
+    Returns
+    -------
+    ``FeatureSpec`` or ``FeatureSpecArray``
+        Labels specification.
+
+    Examples
+    --------
+    .. jupyter-execute::
+        :linenos:
+        :emphasize-lines: 5-6
+        
+        from lets_plot import *
+        LetsPlot.setup_html()
+        data = {'x': list(range(10)), 'y': list(range(10))}
+        ggplot(data, aes('x', 'y')) + geom_point(aes(size='y')) + \\
+            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 = []
+
+    # handle ggtitle
+    if title is not None or subtitle is not None:
+        specs.append(FeatureSpec('ggtitle', name=None, text=title, subtitle=subtitle))
+
+    # plot caption
+    if caption is not None:
+        specs.append(FeatureSpec('caption', name=None, text=caption))
+
+    # guides
+    for key, label in labels.items():
+        specs.append(guides(**{key: _guide(name=None, title=label)}))
+
+    if len(specs) == 1:
+        return specs[0]
+    return FeatureSpecArray(*specs)

lets_plot/plot/marginal_layer.py

@@ -0,0 +1,181 @@
+#  Copyright (c) 2022. 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 Union
+
+from .core import FeatureSpec, LayerSpec, DummySpec, FeatureSpecArray
+
+__all__ = ["ggmarginal"]
+
+
+def ggmarginal(sides: str, *, size=None, layer: Union[LayerSpec, FeatureSpecArray]) -> FeatureSpec:
+    """
+    Convert a given geometry layer to a marginal layer.
+    You can add one or more marginal layers to a plot to create a marginal plot.
+
+    Parameters
+    ----------
+    sides : str
+        A string specifying which sides of the plot the marginal layer will appear on.
+        It should be set to a string containing any of "trbl", for top, right, bottom, and left.
+    size : number or list of numbers, default=0.1
+        Size of marginal geometry (width or height, depending on the margin side) as a fraction of the entire
+        plotting area of the plot.
+        The value should be in range [0.01..0.95].
+    layer : ``LayerSpec``
+        A marginal geometry layer.
+        The result of calling of the ``geom_xxx()``/``stat_xxx()`` function.
+        Marginal plot works best with ``density``, ``histogram``, ``boxplot``, ``violin`` and ``freqpoly`` geometry layers.
+
+    Returns
+    -------
+    ``FeatureSpec``
+        An object specifying a marginal geometry layer or a list of marginal geometry layers.
+
+    Notes
+    -----
+    A marginal plot is a scatterplot (sometimes a 2D density plot or other bivariate plot) that has histograms,
+    boxplots, or other distribution visualization layers in the margins of the x- and y-axes.
+
+    Examples
+    --------
+    .. jupyter-execute::
+        :linenos:
+        :emphasize-lines: 23
+
+        import numpy as np
+        from lets_plot import *
+        LetsPlot.setup_html()
+        LetsPlot.set_theme(theme_light())
+
+        np.random.seed(0)
+
+        cov0=[[1, -.8],
+             [-.8, 1]]
+        cov1=[[ 10, .1],
+               [.1, .1]]
+
+        x0, y0 = np.random.multivariate_normal(mean=[-2,0], cov=cov0, size=200).T
+        x1, y1 = np.random.multivariate_normal(mean=[0,1], cov=cov1, size=200).T
+
+        data = dict(
+            x = np.concatenate((x0,x1)),
+            y = np.concatenate((y0,y1)),
+            c = ["A"]*200 + ["B"]*200
+        )
+
+        p = ggplot(data, aes("x", "y", color="c", fill="c")) + geom_point()
+        p + ggmarginal("tr", layer=geom_density(alpha=0.3, show_legend=False))
+
+    """
+
+    if not isinstance(sides, str):
+        raise TypeError("'sides' must be a string.")
+    if not 0 < len(sides) <= 4:
+        raise ValueError("'sides' must be a string containing 1 to 4 chars: 'l','r','t','b'.")
+
+    # In some cases (only boxplot so far) a layer may consist of multiple sub-layers of type LayerSpec.
+    if isinstance(layer, LayerSpec):
+        sublayers = [layer]
+    elif isinstance(layer, FeatureSpecArray):
+        for sublayer in layer.elements():
+            if not isinstance(sublayer, LayerSpec):
+                raise TypeError("Invalid 'layer' type: {}".format(type(sublayer)))
+        sublayers = layer.elements()
+    else:
+        raise TypeError("Invalid 'layer' type: {}".format(type(layer)))
+
+    result = DummySpec()
+
+    for sublayer in sublayers:
+        for i in range(len(sides)):
+            side = sides[i]
+            margin_size = _to_size(size, i)
+            marginal_layer = _to_marginal(side, margin_size, sublayer)
+            result = result + marginal_layer
+
+    return result
+
+
+def _to_size(size, side_index: int) -> float:
+    if size is None:
+        return None
+
+    if isinstance(size, float):
+        return size
+
+    if not (isinstance(size, list) or isinstance(size, tuple)):
+        raise TypeError("Invalid 'size' type: {}. Expected: float, list or tuple.".format(type(size)))
+
+    try:
+        return size[side_index]
+    except IndexError:
+        return None
+
+
+def _to_marginal(side: str, size, layer: LayerSpec) -> LayerSpec:
+    if side not in ['l', 'r', 't', 'b']:
+        raise ValueError("Invalid 'side' value: {}. Valid values: 'l','r','t','b'.".format(side))
+
+    if size is not None:
+        if not 0.01 <= size <= 0.95:
+            raise ValueError("Invalid 'size' value: {}. Should be in range [0.01..0.95].".format(size))
+
+    layer_copy = LayerSpec.duplicate(layer)
+    marginal_options = dict(
+        marginal=True,
+        margin_side=side,
+        margin_size=size
+    )
+
+    layer_props = layer_copy.props()
+    layer_props.update(marginal_options)
+
+    layer_kind = None
+    stat = layer_props.get('stat')
+    if stat is not None:
+        if stat == 'bin':
+            layer_kind = 'histogram'
+        elif stat == 'ydensity':
+            layer_kind = 'violin'
+        elif stat in ('density', 'boxplot', 'boxplot_outlier'):
+            layer_kind = stat
+    else:
+        geom = layer_props.get('geom')
+        if geom in ('histogram', 'boxplot', 'violin', 'density', 'freqpoly'):
+            layer_kind = geom
+
+    auto_settings = {}
+
+    # choose a proper orientation
+    if (side in ('l', 'r') and layer_kind in ('histogram', 'density', 'freqpoly')):
+        auto_settings['orientation'] = 'y'
+
+    if layer_kind in ('boxplot', 'boxplot_outlier', 'violin'):
+        if side in ('l', 'r'):
+            auto_settings['x'] = 0
+        elif side in ('t', 'b'):
+            auto_settings['y'] = 0
+            auto_settings['orientation'] = 'y'
+
+    # Update layer's options with auto-generated and try not to override user-defined options.
+    filtered = {k: v for k, v in layer_props.items() if v is not None}
+    layer_props.update(
+        {**auto_settings, **filtered}
+    )
+
+    # For 'histogram' set mapping of x or y to '..density..' for compatibility with 'density' geom.
+    if layer_kind == 'histogram':
+        if side in ('l', 'r'):
+            added_mapping = {'x': '..density..'}
+        elif side in ('t', 'b'):
+            added_mapping = {'y': '..density..'}
+
+        aes_feature_spec = layer_props.get('mapping')
+        mappings = aes_feature_spec.props() if isinstance(aes_feature_spec, FeatureSpec) else {}
+        filtered_mappings = {k: v for k, v in mappings.items() if v is not None}
+        updated_mappings = {**added_mapping, **filtered_mappings}
+        updated_aes_feature_spec = FeatureSpec('mapping', name=None, **updated_mappings)
+        layer_props['mapping'] = updated_aes_feature_spec
+
+    return layer_copy