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

lets_plot/__init__.py

@@ -15,11 +15,13 @@ from ._global_settings import NO_JS, OFFLINE
 from .plot import *
 from .export import *
 from .frontend_context import *
+from .mapping import *
 from .settings_utils import *
 from .plot._global_theme import _set_global_theme
 
 __all__ = (plot.__all__ +
            frontend_context.__all__ +
+           mapping.__all__ +
            settings_utils.__all__ +
            export.__all__ +
            ['LetsPlot'])

lets_plot/_type_utils.py

@@ -39,6 +39,10 @@ def standardize_dict(value: Dict) -> Dict:
     return result
 
 
+def is_pandas_data_frame(v) -> bool:
+    return pandas and isinstance(v, pandas.DataFrame)
+
+
 def is_polars_dataframe(v):
     return polars and isinstance(v, polars.DataFrame)
 
@@ -55,6 +59,10 @@ def is_float(v):
     return isinstance(v, float) or (numpy and isinstance(v, numpy.floating))
 
 
+def is_ndarray(data) -> bool:
+    return numpy and isinstance(data, numpy.ndarray)
+
+
 def is_number(v):
     return is_int(v) or is_float(v)
 

lets_plot/_version.py

@@ -3,4 +3,4 @@
 # Use of this source code is governed by the MIT license that can be found in the LICENSE file.
 #
 # see: https://www.python.org/dev/peps/pep-0440/#developmental-releases
-__version__ = '4.3.3'
+__version__ = '4.4.0rc1'

lets_plot/bistro/__init__.py

@@ -6,9 +6,11 @@ from .im import *
 from .qq import *
 from .residual import *
 from .joint import *
+from .waterfall import *
 
 __all__ = (im.__all__ +
            corr.__all__ +
            qq.__all__ +
            residual.__all__ +
-           joint.__all__)
+           joint.__all__ +
+           waterfall.__all__)

lets_plot/bistro/corr.py

@@ -5,7 +5,7 @@
 """Correlation matrix implementation module"""
 from typing import Any
 
-from lets_plot.plot.util import is_data_frame
+from lets_plot.plot.util import is_pandas_data_frame
 
 try:
     import numpy
@@ -23,7 +23,7 @@ __all__ = ['corr_plot']
 
 
 def _is_corr_matrix(data: Any):
-    if is_data_frame(data):
+    if is_pandas_data_frame(data):
         if data.shape[0] != data.shape[1]:
             return False
 
@@ -418,7 +418,7 @@ class corr_plot:
         if _is_corr_matrix(data):
             coefficients = True
         else:
-            if is_data_frame(data):
+            if is_pandas_data_frame(data):
                 data = data.corr(numeric_only=True)
                 coefficients = True
             else:

lets_plot/bistro/im.py

@@ -4,11 +4,11 @@
 #
 from typing import Any
 
+from lets_plot._type_utils import is_ndarray
 from lets_plot.plot.geom_imshow_ import geom_imshow
 from lets_plot.plot.plot import ggplot, GGBunch
 from lets_plot.plot.scale_position import scale_x_continuous, scale_y_continuous
 from lets_plot.plot.theme_ import theme
-from lets_plot.plot.util import is_ndarray
 
 __all__ = ['image_matrix']
 

lets_plot/bistro/residual.py

@@ -17,12 +17,12 @@ try:
 except ImportError:
     pl = None
 
-from ..plot.plot import ggplot
+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_hline
 from ..plot.label import ylab
+from ..plot.plot import ggplot
 from ..plot.theme_ import *
-from ._plot2d_common import _get_bin_params_2d, _get_geom2d_layer, _get_marginal_layers
 
 __all__ = ['residual_plot']
 
@@ -114,7 +114,7 @@ def _get_stat_data(data, x, y, group_by, method, deg, span, seed, max_n):
     elif isinstance(data, pd.DataFrame):
         df = data.copy()
     elif pl is not None and isinstance(data, pl.DataFrame):
-        df = pd.DataFrame(data.to_dict(False))
+        df = pd.DataFrame(data.to_dict(as_series=False))
     else:
         raise Exception("Unsupported type of data: {0}".format(data))
     df = df[(df[x].notna()) & df[y].notna()]
@@ -208,6 +208,11 @@ def residual_plot(data=None, x=None, y=None, *,
     `PlotSpec`
         Plot object specification.
 
+    Notes
+    -----
+    When using 'lm' and 'loess' methods,
+    this function requires the `statsmodels` and `scipy` libraries to be installed.
+
     Examples
     --------
     .. jupyter-execute::

lets_plot/bistro/waterfall.py

@@ -0,0 +1,242 @@
+#  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 lets_plot.plot.core import PlotSpec
+
+__all__ = ['waterfall_plot']
+
+
+def waterfall_plot(data, x, y, *,
+                   measure=None, group=None,
+                   color=None, fill=None, size=None, alpha=None, linetype=None,
+                   width=None,
+                   show_legend=None, relative_tooltips=None, absolute_tooltips=None,
+                   sorted_value=None, threshold=None, max_values=None,
+                   calc_total=None, total_title=None,
+                   hline=None, hline_ontop=None,
+                   connector=None,
+                   label=None, label_format=None) -> PlotSpec:
+    """
+    A waterfall plot shows the cumulative effect of sequentially introduced positive or negative values.
+
+    Parameters
+    ----------
+    data : dict or Pandas or Polars `DataFrame`
+        The data to be displayed.
+    x : str
+        Name of a variable. All values should be distinct.
+    y : str
+        Name of a numeric variable.
+    measure : str
+        Kind of a calculation.
+        Values in 'measure' column could be:
+
+        'absolute' - the value is shown as is;
+        'relative' - the value is shown as a difference from the previous value;
+        'total' - the value is shown as a cumulative sum of all previous values.
+
+    group : str
+        Grouping variable. Each group calculates its own statistics.
+    color : str
+        Color of the box boundary lines.
+        Use 'flow_type' to color lines by the direction of the flow.
+    fill : str
+        Fill color of the boxes.
+        Use 'flow_type' to color boxes by the direction of the flow.
+    size : float, default=0.0
+        Line width of the box boundary lines.
+    alpha : float
+        Transparency level of the boxes. Accept values between 0 and 1.
+    linetype : int or str
+        Type of the box boundary lines.
+        Codes and names: 0 = 'blank', 1 = 'solid', 2 = 'dashed',
+        3 = 'dotted', 4 = 'dotdash', 5 = 'longdash', 6 = 'twodash'.
+    width : float, default=0.9
+        Width of the boxes. Typically range between 0 and 1.
+        Values that are greater than 1 lead to overlapping of the boxes.
+    show_legend : bool, default=False
+        True - show the legend.
+    relative_tooltips : `layer_tooltips` or str
+        Tooltips for boxes with relative values.
+        Result of the call to the `layer_tooltips()` function.
+        Specify appearance, style and content.
+        When 'none', tooltips are not shown.
+        When 'detailed', a more detailed (compared to the default) version of the tooltips is shown.
+    absolute_tooltips : `layer_tooltips` or str
+        Tooltips for boxes with absolute values.
+        Result of the call to the `layer_tooltips()` function.
+        Specify appearance, style and content.
+        When 'none', tooltips are not shown.
+        When 'detailed', a more detailed (compared to the default) version of the tooltips is shown.
+    sorted_value : bool, default=False
+        Sorts categories by absolute value of the changes.
+    threshold : float
+        Groups all categories under a certain threshold value into "Other" category.
+    max_values : int
+        Groups all categories with the smallest changes, except the first `max_values`, into "Other" category.
+    calc_total : bool, default=True
+        Setting the `calc_total` to True will put the final cumulative sum into a new separate box.
+        Taken into account only if the 'measure' column isn't provided.
+    total_title : str
+        The header of the last box with the final cumulative sum, if 'measure' column isn't provided.
+        Also used as a title in the legend for columns of type 'total'.
+    hline : str or dict
+        Horizontal line passing through 0.
+        Set 'blank' or result of `element_blank()` to draw nothing.
+        Set `element_line()` to specify parameters.
+    hline_ontop : bool, default=True
+        Option to place horizontal line over the other layers.
+    connector : str or dict
+        Line between neighbouring boxes connecting the end of the previous box and the beginning of the next box.
+        Set 'blank' or result of `element_blank()` to draw nothing.
+        Set `element_line()` to specify parameters.
+    label : str or dict
+        Label on the box. Shows change value.
+        Set 'blank' or result of `element_blank()` to draw nothing.
+        Set `element_text()` to specify parameters.
+        Use 'flow_type' for `color` parameter of the `element_text()` to color labels by the direction of the flow.
+    label_format : str
+        Format used to transform label mapping values to a string.
+        Examples:
+
+        - '.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
+    -------
+    `PlotSpec`
+        Plot object specification.
+
+    Notes
+    -----
+    Computed variables:
+
+    - ..x.. : category id.
+    - ..xlabel.. : category name.
+    - ..ymin.. : lower value of the change.
+    - ..ymax.. : upper value of the change.
+    - ..measure.. : kind of a calculation: absolute, relative or total.
+    - ..flow_type.. : direction of the flow: increasing, decreasing, or the result (total).
+    - ..initial.. : initial value of the change.
+    - ..value.. : current cumsum (result of the change) or absolute value (depending on the 'measure' column).
+    - ..dy.. : value of the change.
+
+    Examples
+    --------
+    .. jupyter-execute::
+        :linenos:
+        :emphasize-lines: 11
+
+        import numpy as np
+        from lets_plot import *
+        from lets_plot.bistro.waterfall import *
+        LetsPlot.setup_html()
+        categories = list("ABCDEF")
+        np.random.seed(42)
+        data = {
+            'x': categories,
+            'y': np.random.normal(size=len(categories))
+        }
+        waterfall_plot(data, 'x', 'y')
+
+    |
+
+    .. jupyter-execute::
+        :linenos:
+        :emphasize-lines: 12-18
+
+        import numpy as np
+        from lets_plot import *
+        from lets_plot.bistro.waterfall import *
+        LetsPlot.setup_html()
+        n, m = 10, 5
+        categories = list(range(n))
+        np.random.seed(42)
+        data = {
+            'x': categories,
+            'y': np.random.randint(2 * m + 1, size=len(categories)) - m
+        }
+        waterfall_plot(data, 'x', 'y', \\
+                       threshold=2, \\
+                       width=.7, size=1, fill="white", color='flow_type', \\
+                       hline=element_line(linetype='solid'), hline_ontop=False, \\
+                       connector=element_line(linetype='dotted'), \\
+                       label=element_text(color='flow_type'), \\
+                       total_title="Result", show_legend=True)
+
+    |
+
+    .. jupyter-execute::
+        :linenos:
+        :emphasize-lines: 11-20
+
+        import numpy as np
+        from lets_plot import *
+        from lets_plot.bistro.waterfall import *
+        LetsPlot.setup_html()
+        categories = list("ABCDEFGHIJKLMNOP")
+        np.random.seed(42)
+        data = {
+            'x': categories,
+            'y': np.random.uniform(-1, 1, size=len(categories))
+        }
+        waterfall_plot(data, 'x', 'y', sorted_value=True, max_values=5, calc_total=False, \\
+                       relative_tooltips=layer_tooltips().title("Category: @..xlabel..")
+                                                         .format("@..initial..", ".2~f")
+                                                         .format("@..value..", ".2~f")
+                                                         .format("@..dy..", ".2~f")
+                                                         .line("@{..flow_type..}d from @..initial.. to @..value..")
+                                                         .line("Difference: @..dy..")
+                                                         .disable_splitting(), \\
+                       size=1, alpha=.5, \\
+                       label=element_text(color="black"), label_format=".4f")
+
+    |
+
+    .. jupyter-execute::
+        :linenos:
+        :emphasize-lines: 11
+
+        from lets_plot import *
+        from lets_plot.bistro.waterfall import *
+        LetsPlot.setup_html()
+        data = {
+            'company': ["Badgersoft"] * 7 + ["AIlien Co."] * 7,
+            'accounts': ["initial", "revenue", "costs", "Q1", "revenue", "costs", "Q2"] * 2,
+            'values': [200, 200, -100, None, 250, -100, None, \\
+                       150, 50, -100, None, 100, -100, None],
+            'measure': ['absolute', 'relative', 'relative', 'total', 'relative', 'relative', 'total'] * 2,
+        }
+        waterfall_plot(data, 'accounts', 'values', measure='measure', group='company') + \\
+            facet_wrap(facets='company', scales='free_x')
+
+    """
+    return PlotSpec(data=data, mapping=None, scales=[], layers=[], bistro={
+        'name': 'waterfall',
+        'x': x,
+        'y': y,
+        'measure': measure,
+        'group': group,
+        'color': color,
+        'fill': fill,
+        'size': size,
+        'alpha': alpha,
+        'linetype': linetype,
+        'width': width,
+        'show_legend': show_legend,
+        'relative_tooltips': relative_tooltips,
+        'absolute_tooltips': absolute_tooltips,
+        'sorted_value': sorted_value,
+        'threshold': threshold,
+        'max_values': max_values,
+        'calc_total': calc_total,
+        'total_title': total_title,
+        'hline': hline,
+        'hline_ontop': hline_ontop,
+        'connector': connector,
+        'label': label,
+        'label_format': label_format,
+    })

lets_plot/geo_data/to_geo_data_frame.py

@@ -121,7 +121,11 @@ class BoundariesGeoDataFrame:
         geo_rings: List[ShapelyLinearRing] = [
             ShapelyLinearRing([(p.lon, p.lat) for p in ring.points]) for ring in polygon.rings
         ]
-        return ShapelyPolygon(shell=geo_rings[0], holes=geo_rings[1:])
+
+        if len(geo_rings) == 0:
+            return ShapelyPolygon()
+        else:
+            return ShapelyPolygon(shell=geo_rings[0], holes=geo_rings[1:])
 
     def _geo_parse_point(self, geometry_data: GeoPoint) -> ShapelyPoint:
         return ShapelyPoint((geometry_data.lon, geometry_data.lat))

lets_plot/mapping.py

@@ -1,6 +1,8 @@
 #  Copyright (c) 2020. JetBrains s.r.o.
 #  Use of this source code is governed by the MIT license that can be found in the LICENSE file.
 
+__all__ = ['as_discrete']
+
 
 class MappingMeta:
     def __init__(self, variable, annotation, levels, **parameters):
@@ -18,7 +20,7 @@ class MappingMeta:
 
 def as_discrete(variable, label=None, order_by=None, order=None, levels=None):
     """
-    The function is used to annotate a numeric data series as categorical data with the possibility of its ordering for the purposes of given visualization.
+    The function converts a column to a discrete scale and allows you to specify the order of its values.
 
     Parameters
     ----------
@@ -52,11 +54,10 @@ def as_discrete(variable, label=None, order_by=None, order=None, levels=None):
     --------
     .. jupyter-execute::
         :linenos:
-        :emphasize-lines: 13
+        :emphasize-lines: 12
 
         import numpy as np
         from lets_plot import *
-        from lets_plot.mapping import as_discrete
         LetsPlot.setup_html()
         n = 100
         np.random.seed(42)
@@ -72,11 +73,10 @@ def as_discrete(variable, label=None, order_by=None, order=None, levels=None):
 
     .. jupyter-execute::
         :linenos:
-        :emphasize-lines: 12
+        :emphasize-lines: 11
 
         import numpy as np
         from lets_plot import *
-        from lets_plot.mapping import as_discrete
         LetsPlot.setup_html()
         n = 100
         np.random.seed(42)
@@ -91,11 +91,10 @@ def as_discrete(variable, label=None, order_by=None, order=None, levels=None):
 
     .. jupyter-execute::
         :linenos:
-        :emphasize-lines: 13-14
+        :emphasize-lines: 12-13
 
         import numpy as np
         from lets_plot import *
-        from lets_plot.mapping import as_discrete
         LetsPlot.setup_html()
         n = 100
         np.random.seed(42)