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

lets_plot/bistro/residual.py

@@ -0,0 +1,341 @@
+#
+#  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.
+#
+try:
+    import numpy as np
+except ImportError:
+    np = None
+
+try:
+    import pandas as pd
+except ImportError:
+    pd = None
+
+try:
+    import polars as pl
+except ImportError:
+    pl = None
+
+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 *
+
+__all__ = ['residual_plot']
+
+_METHOD_DEF = 'lm'
+_METHOD_LM_DEG_DEF = 1
+_METHOD_LOESS_SPAN_DEF = .5
+_GEOM_DEF = 'point'
+_MARGINAL_DEF = "dens:r"
+_HLINE_DEF = True
+
+_HLINE_COLOR = "magenta"
+_HLINE_LINETYPE = 'dashed'
+_RESIDUAL_COL = "..residual.."
+
+
+def _extract_data_series(df, x, y):
+    xs = np.array(df[x])
+    ys = np.array(df[y])
+    if xs.size != ys.size:
+        raise Exception("All data series in dataset must have equal size "
+                        "{x_col} : {x_len} {y_col} : {y_len}".format(
+            x_col=x,
+            y_col=y,
+            x_len=xs.size,
+            y_len=ys.size
+        ))
+    if xs.size == 1:
+        raise Exception("Data should have at least two points.")
+
+    return xs, ys
+
+
+def _poly_transform(deg):
+    def _transform(X):
+        assert len(X.shape) > 1 and X.shape[1] == 1
+        return np.concatenate([np.power(X, d) for d in range(deg + 1)], axis=1).astype(float)
+
+    return _transform
+
+
+def _get_lm_predictor(xs_train, ys_train, deg):
+    import statsmodels.api as sm
+
+    X_train = xs_train.reshape(-1, 1)
+    transform = _poly_transform(deg)
+    model = sm.OLS(ys_train, transform(X_train)).fit()
+
+    return lambda xs: model.predict(transform(xs.reshape(-1, 1)))
+
+
+def _get_loess_predictor(xs_train, ys_train, span, seed, max_n):
+    import statsmodels.api as sm
+    from scipy.interpolate import interp1d
+
+    if max_n is not None:
+        np.random.seed(seed)
+        indices = np.random.choice(range(xs_train.size), size=max_n, replace=False)
+        xs_train = xs_train[indices]
+        ys_train = ys_train[indices]
+    lowess = sm.nonparametric.lowess(ys_train, xs_train, frac=span)
+    lowess_x = list(zip(*lowess))[0]
+    lowess_y = list(zip(*lowess))[1]
+    model = interp1d(lowess_x, lowess_y, bounds_error=False)
+
+    return lambda xs: np.array([model(x) for x in xs])
+
+
+def _get_predictor(xs_train, ys_train, method, deg, span, seed, max_n):
+    if method == 'lm':
+        return _get_lm_predictor(xs_train, ys_train, deg)
+    if method in ['loess', 'lowess']:
+        return _get_loess_predictor(xs_train, ys_train, span, seed, max_n)
+    if method == 'none':
+        return lambda xs: np.array([0] * xs.size)
+    else:
+        raise Exception("Unknown method '{0}'".format(method))
+
+
+def _get_stat_data(data, x, y, group_by, method, deg, span, seed, max_n):
+    def _get_group_stat_data(group_df):
+        xs, ys = _extract_data_series(group_df, x, y)
+        if len(xs) == 0:
+            return group_df.assign(**{_RESIDUAL_COL: []}), xs, ys
+        predictor = _get_predictor(xs, ys, method, deg, span, seed, max_n)
+        return group_df.assign(**{_RESIDUAL_COL: ys - predictor(xs)}), xs, ys
+
+    if isinstance(data, dict):
+        df = pd.DataFrame(data)
+    elif isinstance(data, pd.DataFrame):
+        df = data.copy()
+    elif pl is not None and isinstance(data, pl.DataFrame):
+        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()]
+    if group_by is None:
+        return _get_group_stat_data(df)
+    else:
+        df_list, xs_list, ys_list = zip(*[
+            _get_group_stat_data(df[df[group_by] == group_value])
+            for group_value in df[group_by].unique()
+        ])
+        return pd.concat(df_list), np.concatenate(xs_list), np.concatenate(ys_list)
+
+
+def residual_plot(data=None, x=None, y=None, *,
+                  method=_METHOD_DEF,
+                  deg=_METHOD_LM_DEG_DEF,
+                  span=_METHOD_LOESS_SPAN_DEF, seed=None, max_n=None,
+                  geom=_GEOM_DEF,
+                  bins=None, binwidth=None,
+                  color=None, size=None, alpha=None,
+                  color_by=None,
+                  show_legend=None,
+                  hline=_HLINE_DEF, marginal=_MARGINAL_DEF):
+    """
+    Produce a residual plot that shows the difference between the observed response and the fitted response values.
+
+    To use ``residual_plot()``, the `numpy` and `pandas` libraries are required.
+    Also, `statsmodels` and `scipy` are required for 'lm' and 'loess' methods.
+
+    Parameters
+    ----------
+    data : dict or Pandas or Polars ``DataFrame``
+        The data to be displayed.
+    x : str
+        Name of independent variable.
+    y : str
+        Name of dependent variable that will be fitted.
+    method : {'lm', 'loess', 'lowess', 'none'}, default='lm'
+        Fitting method: 'lm' (Linear Model) or 'loess'/'lowess' (Locally Estimated Scatterplot Smoothing).
+        If value of ``deg`` parameter is greater than 1 then linear model becomes polynomial of the given degree.
+        If method is 'none' then data lives as is.
+    deg : int, default=1
+        Degree of polynomial for linear regression model.
+    span : float, default=0.5
+        Only for 'loess' method. The fraction of source points closest to the current point is taken into account
+        for computing a least-squares regression. A sensible value is usually 0.25 to 0.5.
+    seed : int
+        Random seed for 'loess' sampling.
+    max_n : int
+        Maximum number of data-points for 'loess' method. If this quantity exceeded random sampling is applied to data.
+    geom : {'point', 'tile', 'hex', 'density2d', 'density2df', 'pointdensity', 'none'}, default='point'
+        The geometric object to use to display the data. No object will be used if ``geom='none'``.
+    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.
+    hline : bool, default=True
+        False - do not show horizontal line passing through 0.
+    marginal : str, default='dens:r'
+        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
+    -----
+    When using 'lm' and 'loess' methods,
+    this function requires the `statsmodels` and `scipy` libraries to be installed.
+
+    ----
+
+    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.residual import *
+        LetsPlot.setup_html()
+        n = 100
+        np.random.seed(42)
+        data = {
+            'x': np.random.uniform(size=n),
+            'y': np.random.normal(size=n)
+        }
+        residual_plot(data, 'x', 'y')
+
+    |
+
+    .. jupyter-execute::
+        :linenos:
+        :emphasize-lines: 9-11
+
+        import numpy as np
+        from lets_plot import *
+        from lets_plot.bistro.residual import *
+        LetsPlot.setup_html()
+        n, m = 1000, 5
+        np.random.seed(42)
+        x = np.random.uniform(low=-m, high=m, size=n)
+        y = x**2 + np.random.normal(size=n)
+        residual_plot({'x': x, 'y': y}, 'x', 'y', \\
+                      deg=2, geom='tile', binwidth=[1, .5], \\
+                      hline=False, marginal="hist:tr")
+
+    |
+
+    .. jupyter-execute::
+        :linenos:
+        :emphasize-lines: 10-13
+
+        import numpy as np
+        from lets_plot import *
+        from lets_plot.bistro.residual import *
+        LetsPlot.setup_html()
+        n = 200
+        np.random.seed(42)
+        x = np.random.uniform(size=n)
+        y = x * np.random.normal(size=n)
+        g = np.random.choice(['A', 'B'], size=n)
+        residual_plot({'x': x, 'y': y, 'g': g}, 'x', 'y', \\
+                      method='none', bins=[30, 15], \\
+                      size=5, alpha=.5, color_by='g', show_legend=False, \\
+                      marginal="hist:t:.2, hist:r, dens:tr, box:bl:.05")
+
+    |
+
+    .. jupyter-execute::
+        :linenos:
+        :emphasize-lines: 12
+
+        import numpy as np
+        from lets_plot import *
+        from lets_plot.bistro.residual import *
+        LetsPlot.setup_html()
+        n = 100
+        color, fill = "#bd0026", "#ffffb2"
+        np.random.seed(42)
+        data = {
+            'x': np.random.uniform(size=n),
+            'y': np.random.normal(size=n)
+        }
+        residual_plot(data, 'x', 'y', geom='none', hline=False, marginal='none') + \\
+            geom_hline(yintercept=0, size=1, color=color) + \\
+            geom_point(shape=21, size=3, color=color, fill=fill) + \\
+            ggmarginal('r', layer=geom_area(stat='density', color=color, fill=fill))
+
+    """
+    # requirements
+    if np is None:
+        raise ValueError("Module 'numpy' is required for residual plot")
+    if pd is None:
+        raise ValueError("Module 'pandas' is required for residual plot")
+    # prepare data
+    stat_data, xs, ys = _get_stat_data(data, x, y, color_by, method, deg, span, seed, max_n)
+    # prepare parameters
+    binwidth2d, bins2d = _get_bin_params_2d(xs, ys, binwidth, bins)
+    # prepare mapping
+    mapping_dict = {'x': x, 'y': _RESIDUAL_COL}
+    if color_by is not None:
+        mapping_dict['color'] = color_by
+        mapping_dict['fill'] = color_by
+    # prepare scales
+    if method == 'none':
+        scales = ylab(y)
+    else:
+        scales = ylab("{0} residual".format(y))
+    # prepare layers
+    layers = DummySpec()
+    # main layer
+    main_layer = _get_geom2d_layer(geom, binwidth2d, bins2d, color, color_by, size, alpha, show_legend)
+    if main_layer is not None:
+        layers += main_layer
+    # hline layer
+    if hline:
+        layers += geom_hline(yintercept=0, color=_HLINE_COLOR, linetype=_HLINE_LINETYPE)
+    # marginal layers
+    if marginal != 'none':
+        layers += _get_marginal_layers(marginal, binwidth2d, bins2d, color, color_by, show_legend)
+    # theme layer
+    theme_layer = theme(axis="blank",
+                        axis_text_x=element_text(),
+                        axis_title_x=element_text(),
+                        axis_line_y=element_line(),
+                        axis_ticks_y=element_line(),
+                        axis_text_y=element_text(),
+                        axis_title_y=element_text())
+
+    return ggplot(stat_data, aes(**mapping_dict)) + layers + scales + theme_layer

lets_plot/bistro/waterfall.py

@@ -0,0 +1,332 @@
+#  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, LayerSpec, FeatureSpecArray, aes
+from lets_plot.plot.util import as_annotated_data
+
+__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,
+                   base=None,
+                   calc_total=None, total_title=None,
+                   hline=None, hline_ontop=None,
+                   connector=None,
+                   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.
+
+    Parameters
+    ----------
+    data : dict or Pandas or Polars ``DataFrame``
+        The data to be displayed.
+    x : str
+        Name of a variable.
+    y : str
+        Name of a numeric variable.
+    measure : str
+        Kind of a calculation.
+        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;
+        '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.
+        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() <https://lets-plot.org/python/pages/api/lets_plot.scale_color_manual.html>`__ 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() <https://lets-plot.org/python/pages/api/lets_plot.scale_fill_manual.html>`__ function.
+    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 or list
+        Type of the box boundary lines.
+        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>`__.
+    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() <https://lets-plot.org/python/pages/api/lets_plot.layer_tooltips.html>`__ 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() <https://lets-plot.org/python/pages/api/lets_plot.layer_tooltips.html>`__ 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.
+    base : float, default=0.0
+        Values with measure 'absolute' or 'total' are relative to this value.
+    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() <https://lets-plot.org/python/pages/api/lets_plot.element_blank.html>`__ to draw nothing.
+        Set `element_line() <https://lets-plot.org/python/pages/api/lets_plot.element_line.html>`__ 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() <https://lets-plot.org/python/pages/api/lets_plot.element_blank.html>`__ to draw nothing.
+        Set `element_line() <https://lets-plot.org/python/pages/api/lets_plot.element_line.html>`__ to specify parameters.
+    relative_labels : dict
+        Result of the call to the `layer_labels() <https://lets-plot.org/python/pages/api/lets_plot.layer_labels.html>`__ function.
+        Specify content and formatting of annotation labels on relative change bars.
+        If specified, overrides ``label_format`` for relative bars.
+    absolute_labels : dict
+        Result of the call to the `layer_labels() <https://lets-plot.org/python/pages/api/lets_plot.layer_labels.html>`__ function.
+        Specify content and formatting of annotation labels on absolute value bars.
+        If specified, overrides ``label_format`` for absolute bars.
+    label : str or dict
+        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() <https://lets-plot.org/python/pages/api/lets_plot.element_blank.html>`__ to draw nothing.
+        Set `element_text() <https://lets-plot.org/python/pages/api/lets_plot.element_text.html>`__ to specify style parameters.
+        Use ``element_text(color='inherit')`` to make labels inherit the color of bar borders.
+    label_format : str
+        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'
+        - 'Num {}' -> 'Num 12.456789'
+        - '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
+    -------
+    ``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: 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
+
+        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='inherit'), \\
+                       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: 17-18
+
+        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,
+        }
+        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,
+        '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,
+        'base': base,
+        'calc_total': calc_total,
+        'total_title': total_title,
+        'hline': hline,
+        'hline_ontop': hline_ontop,
+        'connector': connector,
+        'relative_labels': relative_labels,
+        'absolute_labels': absolute_labels,
+        'label': label,
+        'label_format': label_format,
+        'background_layers': [layer.as_dict() for layer in layers]
+    }, **data_meta)

lets_plot/export/__init__.py

@@ -0,0 +1,6 @@
+#  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.
+
+from .ggsave_ import *
+
+__all__ = ggsave_.__all__