lets-plot 4.6.2__cp312-cp312-macosx_10_15_x86_64.whl → 4.7.0rc1__cp312-cp312-macosx_10_15_x86_64.whl

lets_plot/_global_settings.py

@@ -18,6 +18,7 @@ ENV_OFFLINE = 'LETS_PLOT_OFFLINE'  # bool
 ENV_NO_JS = 'LETS_PLOT_NO_JS'  # bool
 ENV_MAX_WIDTH = 'LETS_PLOT_MAX_WIDTH'
 ENV_MAX_HEIGHT = 'LETS_PLOT_MAX_HEIGHT'
+ENV_MAGICK_EXPORT = 'LETS_PLOT_MAGICK_EXPORT'  # bool
 ENV_MAPTILES_KIND = 'LETS_PLOT_MAPTILES_KIND'
 ENV_MAPTILES_URL = 'LETS_PLOT_MAPTILES_URL'
 ENV_MAPTILES_THEME = 'LETS_PLOT_MAPTILES_THEME'
@@ -29,6 +30,7 @@ ENV_DEV_OFFLINE = 'LETS_PLOT_DEV_OFFLINE'  # bool
 ENV_DEV_NO_JS = 'LETS_PLOT_DEV_NO_JS'  # bool
 ENV_DEV_MAX_WIDTH = 'LETS_PLOT_DEV_MAX_WIDTH'
 ENV_DEV_MAX_HEIGHT = 'LETS_PLOT_DEV_MAX_HEIGHT'
+ENV_DEV_MAGICK_EXPORT = 'LETS_PLOT_DEV_MAGICK_EXPORT'  # bool
 ENV_DEV_MAPTILES_KIND = 'LETS_PLOT_DEV_MAPTILES_KIND'
 ENV_DEV_MAPTILES_URL = 'LETS_PLOT_DEV_MAPTILES_URL'
 ENV_DEV_MAPTILES_THEME = 'LETS_PLOT_DEV_MAPTILES_THEME'
@@ -45,6 +47,7 @@ JS_NAME = 'js_name'
 JS_URL_MANUAL = 'js_url_manual'
 MAX_WIDTH = 'max_width'
 MAX_HEIGHT = 'max_height'
+MAGICK_EXPORT = 'magick_export'
 
 MAPTILES_KIND = 'maptiles_kind'
 MAPTILES_URL = 'maptiles_url'
@@ -82,6 +85,7 @@ def _get_env_val(actual_name: str) -> Any:
 _settings = {
     OFFLINE: _init_value(OFFLINE, False),  # default: download from CDN
     NO_JS: _init_value(NO_JS, False),
+    MAGICK_EXPORT: _init_value(MAGICK_EXPORT, True),  # default: use cairo for export
     # JS_BASE_URL: 'https://dl.bintray.com/jetbrains/lets-plot',
     # JS_BASE_URL: "https://cdnjs.cloudflare.com/ajax/libs/lets-plot",
     JS_BASE_URL: "https://cdn.jsdelivr.net/gh/JetBrains/lets-plot@v{version}".format(version=__version__),
@@ -97,6 +101,7 @@ _settings = {
 
     'dev_' + OFFLINE: _init_value('dev_' + OFFLINE, True),  # default: embed js into the notebook
     'dev_' + NO_JS: _init_value('dev_' + NO_JS, False),
+    'dev_' + MAGICK_EXPORT: _init_value('dev_' + MAGICK_EXPORT, True),  # default: use cairo for export
     # We don't publish "dev" version, it must be served on localhost:
     # $ cd lets-plot
     # ./gradlew js-package:jsBrowserDevelopmentWebpack

lets_plot/_kbridge.py

@@ -19,6 +19,13 @@ def _generate_svg(plot_spec: Dict, use_css_pixelated_image_rendering: bool = Tru
     plot_spec = _standardize_plot_spec(plot_spec)
     return lets_plot_kotlin_bridge.export_svg(plot_spec, use_css_pixelated_image_rendering)
 
+def _export_png(bytestring: Dict, output_width: float, output_height: float, unit: str, dpi: int, scale: float) -> str:
+    """
+    Export a plot to PNG format. Returns base64 encoded string of the PNG image.
+    """
+    plot_spec = _standardize_plot_spec(bytestring)
+    return lets_plot_kotlin_bridge.export_png(plot_spec, output_width, output_height, unit, dpi, scale)
+
 
 def _generate_static_html_page(plot_spec: Dict, iframe: bool) -> str:
     plot_spec = _standardize_plot_spec(plot_spec)

lets_plot/_type_utils.py

@@ -4,7 +4,7 @@
 #
 import json
 import math
-from datetime import datetime
+from datetime import datetime, date, time, timezone
 
 from typing import Dict
 
@@ -83,7 +83,7 @@ def _standardize_value(v):
         if math.isfinite(v):
             return float(v)
         # None for special values like 'nan' etc. because
-        # some json parsers (like com.google.gson.Gson) do not handle them well.
+        # some JSON parsers (like com.google.gson.Gson) do not handle them well.
         return None
     if is_int(v):
         return float(v)
@@ -95,13 +95,36 @@ def _standardize_value(v):
         return [_standardize_value(elem) for elem in v]
     if isinstance(v, tuple):
         return tuple(_standardize_value(elem) for elem in v)
-    if (numpy and isinstance(v, numpy.ndarray)) or (pandas and isinstance(v, pandas.Series)) or (jnp and isinstance(v, jnp.ndarray)):
+
+    if (numpy and isinstance(v, numpy.ndarray)):
+        # Process each array element individually.
+        # Don't use '.tolist()' because this will implicitly
+        # convert 'datetime64' values to unpredictable 'datetime' objects.
+        return [_standardize_value(x) for x in v]
+
+    if (pandas and isinstance(v, pandas.Series)) or (jnp and isinstance(v, jnp.ndarray)):
         return _standardize_value(v.tolist())
+
+    # Universal NaT/NaN check
+    if pandas and pandas.isna(v):
+        return None
+
     if isinstance(v, datetime):
-        if pandas and v is pandas.NaT:
+        # Datetime: to milliseconds since epoch (time zone aware)
+        return v.timestamp() * 1000
+    if isinstance(v, date):
+        # Local date: to milliseconds since epoch (midnight UTC)
+        return datetime.combine(v, time.min, tzinfo=timezone.utc).timestamp() * 1000
+    if isinstance(v, time):
+        # Local time: to milliseconds since midnight
+        return float(v.hour * 3600_000 + v.minute * 60_000 + v.second * 1000 + v.microsecond // 1000)
+    if numpy and isinstance(v, numpy.datetime64):
+        try:
+            # numpy.datetime64: to milliseconds since epoch (Unix time)
+            return float(v.astype('datetime64[ms]').astype(numpy.int64))
+        except:
             return None
-        else:
-            return v.timestamp() * 1000  # convert from second to millisecond
+
     if shapely and isinstance(v, shapely.geometry.base.BaseGeometry):
         return json.dumps(shapely.geometry.mapping(v))
     try:

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.6.2'
+__version__ = '4.7.0rc1'

lets_plot/bistro/im.py

@@ -53,8 +53,8 @@ def image_matrix(image_data_array,
 
     Returns
     -------
-    `ggbunch`
-        Plot bunch object.
+    `SupPlotsSpec`
+        A specification describing the combined figure with all plots and their layout.
 
     Examples
     --------

lets_plot/bistro/waterfall.py

@@ -1,7 +1,7 @@
 #  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, aes
+from lets_plot.plot.core import PlotSpec, LayerSpec, FeatureSpecArray, aes
 from lets_plot.plot.util import as_annotated_data
 
 __all__ = ['waterfall_plot']
@@ -17,7 +17,9 @@ def waterfall_plot(data, x, y, *,
                    calc_total=None, total_title=None,
                    hline=None, hline_ontop=None,
                    connector=None,
-                   label=None, label_format=None) -> PlotSpec:
+                   relative_labels=None, absolute_labels=None,
+                   label=None, label_format=None,
+                   background_layers=None) -> PlotSpec:
     """
     A waterfall plot shows the cumulative effect of sequentially introduced positive or negative values.
 
@@ -31,7 +33,8 @@ def waterfall_plot(data, x, y, *,
         Name of a numeric variable.
     measure : str
         Kind of a calculation.
-        Values in 'measure' column could be:
+        It takes the name of a data column.
+        The values in the column could be:
 
         'absolute' - the value is shown as is;
         'relative' - the value is shown as a difference from the previous value;
@@ -43,10 +46,14 @@ def waterfall_plot(data, x, y, *,
         Color of the box boundary lines.
         For more info see `Color and Fill <https://lets-plot.org/python/pages/aesthetics.html#color-and-fill>`__.
         Use 'flow_type' to color lines by the direction of the flow.
+        Flow type names: "Absolute", "Increase", "Decrease" and "Total".
+        You could use these names to change the default colors with the `scale_color_manual()` function.
     fill : str
         Fill color of the boxes.
         For more info see `Color and Fill <https://lets-plot.org/python/pages/aesthetics.html#color-and-fill>`__.
         Use 'flow_type' to color boxes by the direction of the flow.
+        Flow type names: "Absolute", "Increase", "Decrease" and "Total".
+        You could use these names to change the default colors with the `scale_fill_manual()` function.
     size : float, default=0.0
         Line width of the box boundary lines.
     alpha : float
@@ -98,13 +105,27 @@ def waterfall_plot(data, x, y, *,
         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.
+    relative_labels : dict
+        Result of the call to the `layer_labels()` function.
+        Specify content and formatting of annotation labels on relative change bars.
+        If specified, overrides `label_format` for relative bars.
+        See `layer_labels() <https://lets-plot.org/python/pages/api/lets_plot.layer_labels.html>`__.
+    absolute_labels : dict
+        Result of the call to the `layer_labels()` function.
+        Specify content and formatting of annotation labels on absolute value bars.
+        If specified, overrides `label_format` for absolute bars.
+        See `layer_labels() <https://lets-plot.org/python/pages/api/lets_plot.layer_labels.html>`__.
     label : str or dict
-        Label on the box. Shows change value.
+        Style configuration for labels on bars. Applied to default labels or to
+        relative/absolute labels when `relative_labels` or `absolute_labels` are specified.
         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.
+        Set `element_text()` to specify style parameters.
+        Use `element_text(color='inherit')` to make labels inherit the color of bar borders.
+        See `element_text() <https://lets-plot.org/python/pages/api/lets_plot.element_text.html>`__.
     label_format : str
-        Format used to transform label mapping values to a string.
+        Format string used to transform label values to text. Applied to default labels or to
+        relative/absolute labels when `relative_labels` or `absolute_labels` are specified.
+        Can be overridden by formatting specified in `relative_labels` or `absolute_labels`.
         Examples:
 
         - '.2f' -> '12.45'
@@ -112,6 +133,8 @@ def waterfall_plot(data, x, y, *,
         - 'TTL: {.2f}$' -> 'TTL: 12.45$'
 
         For more info see `Formatting <https://lets-plot.org/python/pages/formats.html>`__.
+    background_layers : LayerSpec or FeatureSpecArray
+        Background layers to be added to the plot.
 
     Returns
     -------
@@ -152,6 +175,40 @@ def waterfall_plot(data, x, y, *,
 
     |
 
+    .. jupyter-execute::
+        :linenos:
+        :emphasize-lines: 21-25
+
+        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))
+        }
+        band_data = {
+            'xmin': [-0.5, 2.5],
+            'xmax': [2.5, 5.5],
+            'name': ['Q1', 'Q2']
+        }
+        text_data = {
+            'x': [0, 3],
+            'y': [2.7, 2.7],
+            'name': ['Q1', 'Q2']
+        }
+        waterfall_plot(data, 'x', 'y', label_format='.2f',
+                       background_layers=geom_band(
+                           aes(xmin='xmin', xmax='xmax', fill='name', color='name'),
+                           data=band_data, alpha=0.2
+                       )) + \\
+            geom_text(aes(x='x', y='y', label='name'), data=text_data, size=10) + \\
+            ggtitle("Waterfall with background layers")
+
+    |
+
     .. jupyter-execute::
         :linenos:
         :emphasize-lines: 12-18
@@ -172,7 +229,7 @@ def waterfall_plot(data, x, y, *,
                        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'), \\
+                       label=element_text(color='inherit'), \\
                        total_title="Result", show_legend=True)
 
     |
@@ -206,7 +263,7 @@ def waterfall_plot(data, x, y, *,
 
     .. jupyter-execute::
         :linenos:
-        :emphasize-lines: 11
+        :emphasize-lines: 17-18
 
         from lets_plot import *
         from lets_plot.bistro.waterfall import *
@@ -214,15 +271,36 @@ def waterfall_plot(data, x, y, *,
         data = {
             'company': ["Badgersoft"] * 7 + ["AIlien Co."] * 7,
             'accounts': ["initial", "revenue", "costs", "Q1", "revenue", "costs", "Q2"] * 2,
-            'values': [200, 200, -100, None, 250, -100, None, \\
+            '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') + \\
+        colors = {
+            "Absolute": "darkseagreen",
+            "Increase": "palegoldenrod",
+            "Decrease": "paleturquoise",
+            "Total": "palegreen",
+        }
+        waterfall_plot(data, 'accounts', 'values', measure='measure', group='company',
+                       size=.75, label=element_text(color="black")) + \\
+            scale_fill_manual(values=colors) + \\
             facet_wrap(facets='company', scales='free_x')
 
     """
     data, mapping, data_meta = as_annotated_data(data, aes(x=x, y=y))
+
+    if background_layers is None:
+        layers = []
+    elif isinstance(background_layers, LayerSpec):
+        layers = [background_layers]
+    elif isinstance(background_layers, FeatureSpecArray):
+        for sublayer in background_layers.elements():
+            if not isinstance(sublayer, LayerSpec):
+                raise TypeError("Invalid 'layer' type: {}".format(type(sublayer)))
+        layers = background_layers.elements()
+    else:
+        raise TypeError("Invalid 'layer' type: {}".format(type(background_layers)))
+
     return PlotSpec(data=data, mapping=None, scales=[], layers=[], bistro={
         'name': 'waterfall',
         'x': x,
@@ -247,6 +325,9 @@ def waterfall_plot(data, x, y, *,
         'hline': hline,
         'hline_ontop': hline_ontop,
         'connector': connector,
+        'relative_labels': relative_labels,
+        'absolute_labels': absolute_labels,
         'label': label,
         'label_format': label_format,
-    }, **data_meta)
+        'background_layers': [layer.as_dict() for layer in layers]
+    }, **data_meta)

lets_plot/export/ggsave_.py

@@ -48,10 +48,10 @@ def ggsave(plot: Union[PlotSpec, SupPlotsSpec, GGBunch], filename: str, *, path:
     h : float, default=None
         Height of the output image in units.
         Only applicable when exporting to PNG or PDF.
-    unit : {'in', 'cm', 'mm'}, default=None
+    unit : {'in', 'cm', 'mm'}, default='in'
         Unit of the output image. One of: 'in', 'cm', 'mm'.
         Only applicable when exporting to PNG or PDF.
-    dpi : int, default=None
+    dpi : int, default=300
         Resolution in dots per inch.
         Only applicable when exporting to PNG or PDF.
 
@@ -66,19 +66,27 @@ def ggsave(plot: Union[PlotSpec, SupPlotsSpec, GGBunch], filename: str, *, path:
 
     For PNG and PDF formats:
 
-    1. If `w`, `h`, `unit`, and `dpi` are all specified:
+    - If `w`, `h`, `unit`, and `dpi` are all specified:
 
-       - `scale` is ignored.
-       - The plot's pixel size (default or set by `ggsize()`) is converted to the specified units using the given dpi.
-       - If the aspect ratio of `w` and `h` differs from the plot's pixel aspect ratio:
+      - The plot's pixel size (default or set by `ggsize()`) is ignored.
+      - The output size is calculated using the specified `w`, `h`, `unit`, and `dpi`.
 
-         * The plot maintains its original (pixel) aspect ratio.
-         * It's fitted within the specified `w` x `h` area.
-         * Any extra space is left empty.
+        - The plot is resized to fit the specified `w` x `h` area, which may affect the layout, tick labels, and other elements.
 
-    2. If `w`, `h` are not specified:
+    - If only `dpi` is specified:
 
-       - The `scale` parameter is used to determine the output size.
+      - The plot's pixel size (default or set by `ggsize()`) is converted to inches using the standard display PPI of 96.
+      - The output size is then calculated based on the specified DPI.
+
+        - The plot maintains its aspect ratio, preserving layout, tick labels, and other visual elements.
+        - Useful for printing - the plot will appear nearly the same size as on screen.
+
+    - If `w`, `h` are not specified:
+
+      - The `scale` parameter is used to determine the output size.
+
+        - The plot maintains its aspect ratio, preserving layout, tick labels, and other visual elements.
+        - Useful for generating high-resolution images suitable for publication.
 
     Examples
     --------
@@ -99,8 +107,8 @@ def ggsave(plot: Union[PlotSpec, SupPlotsSpec, GGBunch], filename: str, *, path:
 
         from lets_plot import *
         LetsPlot.setup_html()
-        plot = ggplot() + geom_point(x=0, y=0) + ggsize(800, 400)
-        ggsave(plot, 'plot.png', w=8, h=4, unit='in', dpi=300)
+        plot = ggplot() + geom_point(x=0, y=0)
+        ggsave(plot, 'plot.png', w=4, h=3)
 
     """
 
@@ -125,7 +133,7 @@ def ggsave(plot: Union[PlotSpec, SupPlotsSpec, GGBunch], filename: str, *, path:
         return _to_svg(plot, pathname)
     elif ext in ['html', 'htm']:
         return _to_html(plot, pathname, iframe=iframe)
-    elif ext in ['png', 'pdf']:
+    elif ext in ['png', 'pdf', 'bmp']:
         return _export_as_raster(plot, pathname, scale, export_format=ext, w=w, h=h, unit=unit, dpi=dpi)
     else:
         raise ValueError(