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

lets_plot/bistro/joint.py

@@ -0,0 +1,192 @@
+#
+#  Copyright (c) 2023. JetBrains s.r.o.
+#  Use of this source code is governed by the MIT license that can be found in the LICENSE file.
+#
+from ._plot2d_common import _get_bin_params_2d, _get_geom2d_layer, _get_marginal_layers
+from ..plot.core import DummySpec, aes
+from ..plot.geom import geom_smooth
+from ..plot.label import xlab, ylab
+from ..plot.plot import ggplot
+
+__all__ = ['joint_plot']
+
+_GEOM_DEF = 'point'
+
+_REG_LINE_METHOD = 'lm'
+_REG_LINE_COLOR = "magenta"
+_REG_LINE_LINETYPE = 'dashed'
+
+
+def _get_marginal_def(geom_kind, color_by=None):
+    if geom_kind in ['density2d', 'density2df'] or color_by is not None:
+        return "dens:tr"
+    else:
+        return "hist:tr"
+
+
+def _is_reg_line_needed(reg_line, geom_kind):
+    if reg_line is not None:
+        return reg_line
+    if geom_kind in ['point', 'pointdensity']:
+        return True
+    else:
+        return False
+
+
+def joint_plot(data, x, y, *,
+               geom=None,
+               bins=None, binwidth=None,
+               color=None, size=None, alpha=None,
+               color_by=None,
+               show_legend=None,
+               reg_line=None,
+               se=None,
+               marginal=None):
+    """
+    Produce a joint plot that contains bivariate and univariate graphs at the same time.
+
+    Parameters
+    ----------
+    data : dict or Pandas or Polars ``DataFrame``
+        The data to be displayed.
+    x, y : str
+        Names of a variables.
+    geom : {'point', 'tile', 'hex', 'density2d', 'density2df', 'pointdensity'}, default='point'
+        The geometric object to use to display the data.
+    bins : int or list of int
+        Number of bins in both directions, vertical and horizontal. Overridden by ``binwidth``.
+        If only one value given - interpret it as list of two equal values.
+        Applicable simultaneously for 'tile'/'hex' geom and 'histogram' marginal.
+    binwidth : float or list of float
+        The width of the bins in both directions, vertical and horizontal.
+        Overrides ``bins``. The default is to use bin widths that cover the entire range of the data.
+        If only one value given - interpret it as list of two equal values.
+        Applicable simultaneously for 'tile'/'hex' geom and 'histogram' marginal.
+    color : str
+        Color of the geometry.
+        For more info see `Color and Fill <https://lets-plot.org/python/pages/aesthetics.html#color-and-fill>`__.
+    size : float
+        Size of the geometry.
+    alpha : float
+        Transparency level of the geometry. Accept values between 0 and 1.
+    color_by : str
+        Name of grouping variable.
+    show_legend : bool, default=True
+        False - do not show legend for the main layer.
+    reg_line : bool
+        True - show the line of linear regression.
+    se : bool, default=True
+        Display confidence interval around regression line.
+    marginal : str
+        Description of marginal layers packed to string value.
+        Different marginals are separated by the ',' char.
+        Parameters of a marginal are separated by the ':' char.
+        First parameter of a marginal is a geometry name.
+        Possible values: 'dens'/'density', 'hist'/'histogram', 'box'/'boxplot'.
+        Second parameter is a string specifying which sides of the plot the marginal layer will appear on.
+        Possible values: 't' (top), 'b' (bottom), 'l' (left), 'r' (right).
+        Third parameter (optional) is size of marginal.
+        To suppress marginals use ``marginal='none'``.
+        Examples:
+        "hist:tr:0.3",
+        "dens:tr,hist:bl",
+        "box:tr:.05, hist:bl, dens:bl".
+
+    Returns
+    -------
+    ``PlotSpec``
+        Plot object specification.
+
+    Notes
+    -----
+    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: 11
+
+        import numpy as np
+        from lets_plot import *
+        from lets_plot.bistro.joint import *
+        LetsPlot.setup_html()
+        n = 100
+        np.random.seed(42)
+        data = {
+            'x': np.random.normal(size=n),
+            'y': np.random.normal(size=n)
+        }
+        joint_plot(data, 'x', 'y')
+
+    |
+
+    .. jupyter-execute::
+        :linenos:
+        :emphasize-lines: 11-13
+
+        import numpy as np
+        from lets_plot import *
+        from lets_plot.bistro.joint import *
+        LetsPlot.setup_html()
+        n = 500
+        np.random.seed(42)
+        data = {
+            'x': np.random.normal(size=n),
+            'y': np.random.normal(size=n)
+        }
+        joint_plot(data, 'x', 'y', geom='tile', \\
+                   binwidth=[.5, .5], color="black", \\
+                   marginal="hist:tr,box:bl") + \\
+            theme_minimal()
+
+    |
+
+    .. jupyter-execute::
+        :linenos:
+        :emphasize-lines: 12
+
+        import numpy as np
+        from lets_plot import *
+        from lets_plot.bistro.joint import *
+        LetsPlot.setup_html()
+        n = 500
+        np.random.seed(42)
+        data = {
+            'x': np.concatenate((np.random.normal(loc=-1, size=n), np.random.normal(loc=2, size=n))),
+            'y': np.concatenate((np.random.normal(loc=-.5, size=n), np.random.normal(loc=1.5, size=n))),
+            'g': ["A"] * n + ["B"] * n
+        }
+        joint_plot(data, 'x', 'y', geom='density2df', color_by='g', alpha=.75)
+
+    """
+    # prepare parameters
+    geom_kind = geom or _GEOM_DEF
+    binwidth2d, bins2d = _get_bin_params_2d(data[x], data[y], binwidth, bins)
+    # prepare mapping
+    mapping_dict = {'x': x, 'y': y}
+    if color_by is not None:
+        mapping_dict['color'] = color_by
+        mapping_dict['fill'] = color_by
+    # prepare layers
+    layers = DummySpec()
+    # main layer
+    main_layer = _get_geom2d_layer(geom_kind, binwidth2d, bins2d, color, color_by, size, alpha, show_legend)
+    if main_layer is not None:
+        layers += main_layer
+    # smooth layer
+    if _is_reg_line_needed(reg_line, geom_kind):
+        layers += geom_smooth(
+            aes(group=color_by),
+            method=_REG_LINE_METHOD, se=se,
+            color=_REG_LINE_COLOR, linetype=_REG_LINE_LINETYPE
+        )
+    # marginal layers
+    if len(data[x]) == 0:
+        marginal = 'none'
+    defined_marginal = marginal or _get_marginal_def(geom_kind, color_by)
+    if defined_marginal != 'none':
+        layers += _get_marginal_layers(defined_marginal, binwidth2d, bins2d, color, color_by, show_legend)
+
+    return ggplot(data, aes(**mapping_dict)) + layers + xlab(x) + ylab(y)

lets_plot/bistro/qq.py

@@ -0,0 +1,207 @@
+#  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 lets_plot.plot.core import PlotSpec
+
+__all__ = ['qq_plot']
+
+
+def qq_plot(data=None, sample=None, *, x=None, y=None,
+            distribution=None, dparams=None, quantiles=None,
+            group=None,
+            show_legend=None,
+            marginal=None,
+            color=None, fill=None, alpha=None, size=None, shape=None,
+            line_color=None, line_size=None, linetype=None) -> PlotSpec:
+    """
+    Produce a Q-Q plot (quantile-quantile plot).
+
+    Supply the ``sample`` parameter to compare distribution of observations with a theoretical distribution
+    ('normal' or as otherwise specified by the ``distribution`` parameter).
+
+    Alternatively, supply ``x`` and ``y`` parameters to compare the distribution of ``x`` with the distribution of ``y``.
+
+    Parameters
+    ----------
+    data : dict or Pandas or Polars ``DataFrame``
+        The data to be displayed.
+    sample : str
+        Name of variable specifying a vector of observations used for computing of "sample quantiles".
+        Use this parameter to produce a "sample vs. theoretical" Q-Q plot.
+    x, y : str
+        Names of variables specifying two vectors of observations used for computing of
+        x and y "sample quantiles".
+        Use these two parameters to produce a "sample X vs. sample Y" Q-Q plot.
+    distribution : {'norm', 'uniform', 't', 'gamma', 'exp', 'chi2'}, default='norm'
+        Distribution function to use. Could be specified if ``sample`` is.
+    dparams : list
+        Additional parameters (of float type) passed on to distribution function.
+        Could be specified if ``sample`` is.
+        If ``distribution`` is ``'norm'`` then ``dparams`` is a pair [mean, std] (=[0.0, 1.0] by default).
+        If ``distribution`` is ``'uniform'`` then ``dparams`` is a pair [a, b] (=[0.0, 1.0] by default).
+        If ``distribution`` is ``'t'`` then ``dparams`` is an integer number [d] (=[1] by default).
+        If ``distribution`` is ``'gamma'`` then ``dparams`` is a pair [alpha, beta] (=[1.0, 1.0] by default).
+        If ``distribution`` is ``'exp'`` then ``dparams`` is a float number [lambda] (=[1.0] by default).
+        If ``distribution`` is ``'chi2'`` then ``dparams`` is an integer number [k] (=[1] by default).
+    quantiles : list, default=[0.25, 0.75]
+        Pair of quantiles to use when fitting the Q-Q line.
+    group : str
+        Grouping parameter.
+        If it is specified and color-parameters isn't then different groups will has different colors.
+    show_legend : bool, default=True
+        False - do not show legend.
+    marginal : str, default='dens:tr'
+        Description of marginal layers packed to string value.
+        Different marginals are separated by the ',' char.
+        Parameters of a marginal are separated by the ':' char.
+        First parameter of a marginal is a geometry name.
+        Possible values: 'dens'/'density', 'hist'/'histogram', 'box'/'boxplot'.
+        Second parameter is a string specifying which sides of the plot the marginal layer will appear on.
+        Possible values: 't' (top), 'b' (bottom), 'l' (left), 'r' (right).
+        Third parameter (optional) is size of marginal.
+        To suppress marginals use ``marginal='none'``.
+        Examples:
+        "hist:tr:0.3",
+        "dens:tr,hist:bl",
+        "box : tr : .05, dens : bl".
+    color : str
+        Color of a points.
+        For more info see `Color and Fill <https://lets-plot.org/python/pages/aesthetics.html#color-and-fill>`__.
+    fill : str
+        Color to paint shape's inner points. Is applied only to the points of shapes having inner points.
+        For more info see `Color and Fill <https://lets-plot.org/python/pages/aesthetics.html#color-and-fill>`__.
+    alpha : float, default=0.5
+        Transparency level of points. Accept values between 0 and 1.
+    size : float, default=3.0
+        Size of the points.
+    shape : int
+        Shape of the points, an integer from 0 to 25.
+        For more info see `Point Shapes <https://lets-plot.org/python/pages/aesthetics.html#point-shapes>`__.
+    line_color : str, default='#FF0000'
+        Color of the fitting line.
+        For more info see `Color and Fill <https://lets-plot.org/python/pages/aesthetics.html#color-and-fill>`__.
+    line_size : float, default=0.75
+        Width of the fitting line.
+    linetype : int or str or list
+        Type of the fitting line.
+        Accept codes or names (0 = 'blank', 1 = 'solid', 2 = 'dashed', 3 = 'dotted', 4 = 'dotdash', 5 = 'longdash', 6 = 'twodash'),
+        a hex string (up to 8 digits for dash-gap lengths),
+        or a list pattern [offset, [dash, gap, ...]] / [dash, gap, ...].
+        For more info see `Line Types <https://lets-plot.org/python/pages/aesthetics.html#line-types>`__.
+
+    Returns
+    -------
+    ``PlotSpec``
+        Plot object specification.
+
+    Notes
+    -----
+    The Q-Q plot is used for comparing two probability distributions
+    (sample and theoretical or two sample) by plotting their quantiles against each other.
+
+    If the two distributions being compared are similar, the points in the Q-Q plot
+    will approximately lie on the straight line.
+
+    ----
+
+    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: 8
+
+        import numpy as np
+        from lets_plot.bistro.qq import qq_plot
+        from lets_plot import *
+        LetsPlot.setup_html()
+        n = 100
+        np.random.seed(42)
+        x = np.random.normal(0, 1, n)
+        qq_plot(data={'x': x}, sample='x')
+
+    |
+
+    .. jupyter-execute::
+        :linenos:
+        :emphasize-lines: 8-10
+
+        import numpy as np
+        from lets_plot.bistro.qq import qq_plot
+        from lets_plot import *
+        LetsPlot.setup_html()
+        n = 100
+        np.random.seed(42)
+        x = np.random.exponential(1, n)
+        qq_plot({'x': x}, 'x', \\
+                distribution='exp', quantiles=[0, .9], \\
+                color='black', line_size=.25)
+
+    |
+
+    .. jupyter-execute::
+        :linenos:
+        :emphasize-lines: 12-13
+
+        import numpy as np
+        from lets_plot.bistro.qq import qq_plot
+        from lets_plot import *
+        LetsPlot.setup_html()
+        n = 100
+        np.random.seed(42)
+        data = {
+            'x': np.random.normal(0, 1, n),
+            'y': np.random.normal(1, 2, n),
+            'g': np.random.choice(['a', 'b'], n),
+        }
+        qq_plot(data, x='x', y='y', group='g', \\
+                shape=21, alpha=.2, size=5, linetype=5)
+
+    |
+
+    .. jupyter-execute::
+        :linenos:
+        :emphasize-lines: 11-12
+
+        import numpy as np
+        from lets_plot.bistro.qq import qq_plot
+        from lets_plot import *
+        LetsPlot.setup_html()
+        n = 150
+        np.random.seed(42)
+        data = {
+            'x': np.random.normal(0, 5, n),
+            'g': np.random.choice(['a', 'b', 'c'], n),
+        }
+        qq_plot(data, 'x', dparams=[0, 5], group='g', \\
+                line_color='black', line_size=.5) + \\
+            scale_color_brewer(type='qual', palette='Set1') + \\
+            facet_grid(x='g') + \\
+            coord_fixed() + \\
+            xlab("Norm distribution quantiles") + \\
+            ggtitle("Interaction of the qq_plot() with other layers") + \\
+            theme_classic()
+
+    """
+    return PlotSpec(data=data, mapping=None, scales=[], layers=[], bistro={
+        'name': 'qqplot',
+        'sample': sample,
+        'x': x,
+        'y': y,
+        'distribution': distribution,
+        'dparams': dparams,
+        'quantiles': quantiles,
+        'group': group,
+        'show_legend': show_legend,
+        'marginal': marginal,
+        'color': color,
+        'fill': fill,
+        'alpha': alpha,
+        'size': size,
+        'shape': shape,
+        'line_color': line_color,
+        'line_size': line_size,
+        'linetype': linetype,
+    })