Source code for spb.plotgrid

from spb.defaults import cfg
from spb.backends.matplotlib import MB
from spb.backends.plotly import PB
from spb.backends.bokeh import BB
from spb.interactive import IPlot, create_interactive_plot
from sympy.utilities.exceptions import sympy_deprecation_warning
from sympy.external import import_module


# NOTE: the code in this module, particularly the one about interactive widget
# plot, is ugly and probably difficult to comprehend. Turns out that it is
# extremely difficult to get ipywidgets (and in much less extent, panel) to
# work with different plotting libraries...


def _nrows_ncols(nr, nc, nplots):
    """Define the correct number of rows and/or columns based on the number
    of plots to be shown.
    """
    np = import_module('numpy')

    if (nc <= 0) and (nr <= 0):
        nc = 1
        nr = nplots
    elif nr <= 0:
        nr = int(np.ceil(nplots / nc))
    elif nc <= 0:
        nc = int(np.ceil(nplots / nr))
    elif nr == 1:
        nc = nplots
    elif nr * nc < nplots:
        nr += 1
        return _nrows_ncols(nr, nc, nplots)
    return nr, nc


def _are_all_plots_instances_of(plots, Backend):
    """Verify that plots (or interactive plots) are produces with the
    specified backend.
    """
    return all(
        isinstance(t, Backend) or
        (isinstance(t, IPlot) and isinstance(t.backend, Backend))
        for t in plots
    )


def _create_mpl_figure(
    mapping, imagegrid=False, size=None, is_iplot_panel=False
):
    matplotlib = import_module(
        'matplotlib',
        import_kwargs={'fromlist': ['pyplot', 'gridspec']},
        min_module_version='1.1.0',
        catch=(RuntimeError,))
    mpl_toolkits = import_module(
        'mpl_toolkits',
        import_kwargs={'fromlist': ['axes_grid1']},
        catch=(RuntimeError,))
    plt = matplotlib.pyplot

    def get_fig_panes_plots(fig):
        panes_plots = {}
        if is_iplot_panel:
            pn = import_module(
                'panel',
                min_module_version='0.12.0')
            pane = pn.pane.Matplotlib(fig, dpi=96)
            panes_plots[pane] = fig
            return pane, panes_plots
        return fig, panes_plots

    kw = {} if not size else {"figsize": size}
    if is_iplot_panel:
        fig = matplotlib.figure.Figure(**kw)
    else:
        fig = plt.figure(**kw)

    new_plots = []
    panes_plots = {}
    if imagegrid:
        gs = list(mapping.keys())[0].get_gridspec()
        grid = mpl_toolkits.axes_grid1.ImageGrid(
            fig, 111,
            nrows_ncols=(gs.nrows, gs.ncols),
            axes_pad=0.15,
            cbar_location="right",
            cbar_mode="single",
            cbar_size="7%",
            cbar_pad=0.15,
        )
        for (_, p), ax in zip(mapping.items(), grid):
            if isinstance(p, IPlot):
                p = p.backend
            # cpa: current plot attributes
            cpa = p._copy_kwargs()
            cpa["fig"] = fig
            cpa["ax"] = ax
            cpa["imagegrid"] = True
            p = MB(*p.series, **cpa)
            p.draw()
            new_plots.append(p)
        fig, panes_plots = get_fig_panes_plots(fig)
        return fig, new_plots, panes_plots

    for spec, p in mapping.items():
        if isinstance(p, IPlot):
            p = p.backend
        kw = {"projection": "3d"} if (len(p.series) > 0 and
            p.series[0].is_3D) else ({"projection": "polar"} if p.polar_axis
            else {})
        cur_ax = fig.add_subplot(spec, **kw)
        # cpa: current plot attributes
        cpa = p._copy_kwargs()
        cpa["fig"] = fig
        cpa["ax"] = cur_ax
        p = MB(*p.series, **cpa)
        p.draw()
        new_plots.append(p)

    fig.tight_layout()
    fig, panes_plots = get_fig_panes_plots(fig)
    return fig, new_plots, panes_plots


def _create_panel_figure(mapping, panel_kw):
    pn = import_module(
        'panel',
        min_module_version='0.12.0')
    pn.extension("plotly")

    panes_plots = {}
    fig = pn.GridSpec(**panel_kw)
    for spec, p in mapping.items():
        rs = spec.rowspan
        cs = spec.colspan
        if isinstance(p, IPlot):
            # a panel's `pane` must receive a figure of some kind, not another
            # panel's object, otherwise there will be performance penalty,
            # especially noticeable with Plotly and Bokeh
            p = p.backend
        _fig = p.fig
        if isinstance(p, PB):
            pane = pn.pane.Plotly(_fig.to_dict())
            fig[slice(rs.start, rs.stop), slice(cs.start, cs.stop)] = pane
        else:
            pane = pn.pane.panel(_fig)
            fig[slice(rs.start, rs.stop), slice(cs.start, cs.stop)] = pane
        panes_plots[pane] = p
    return fig, panes_plots


def _create_ipywidgets_figure(mapping, panel_kw):
    ipy = import_module('ipywidgets')
    plotly = import_module(
        'plotly',
        import_kwargs={'fromlist': ['graph_objects']},
        warn_not_installed=True,
        min_module_version='5.0.0')
    go = plotly.graph_objects

    fig = ipy.GridspecLayout(**panel_kw)
    bokeh_outputs_plots = []
    for spec, p in mapping.items():
        rs = spec.rowspan
        cs = spec.colspan
        plot_fig = p.fig
        if isinstance(p, PB):
            # ipywidgets requires Plotly's FigureWidget
            plot_fig = go.FigureWidget(p.fig.to_dict())
        elif _are_all_plots_instances_of([p], BB):
            bokeh = import_module(
                'bokeh',
                import_kwargs={'fromlist': ['io']},
                warn_not_installed=True,
                min_module_version='2.3.0')
            # let's assume cfg["bokeh"]["height"] is an integer
            min_height = str(cfg["bokeh"]["height"]) + "px"
            new_fig = ipy.Output(layout=ipy.Layout(
                height='auto', min_height=min_height,
                width='100%', max_width="100%")
            )
            with new_fig:
                bokeh.io.show(plot_fig)
            bokeh_outputs_plots.append((new_fig, p))
            plot_fig = new_fig
        fig[slice(rs.start, rs.stop), slice(cs.start, cs.stop)] = ipy.Box([plot_fig])
    return fig, bokeh_outputs_plots


def _check_gs(gs):
    """Helper function to verify the provided GridSpec.
    """
    if not isinstance(gs, dict):
        raise TypeError("`gs` must be a dictionary.")

    matplotlib = import_module(
        'matplotlib',
        import_kwargs={'fromlist': ['pyplot', 'gridspec']},
        min_module_version='1.1.0',
        catch=(RuntimeError,))

    SubplotSpec = matplotlib.gridspec.SubplotSpec
    if not isinstance(list(gs.keys())[0], SubplotSpec):
        raise ValueError(
            "Keys of `gs` must be of elements of type "
            "matplotlib.gridspec.SubplotSpec. Use "
            "matplotlib.gridspec.GridSpec to create them.")


def _get_all_parameters(plots):
    """Loop over the provided plots and extract the original parameters.
    """
    all_parameters, all_plots = {}, []
    for plot in plots:
        if isinstance(plot, IPlot):
            all_plots.append(plot.backend)
            # all_plots.append(plot)
            all_parameters.update(plot._original_params)
        else:
            all_plots.append(plot)

    return all_parameters, all_plots


def _get_plots_imodule(plots):
    """Verify that all plots uses the same interactive module, and return it.
    """
    imodules = set()
    for plot in plots:
        if isinstance(plot, IPlot):
            imodules.add(plot.backend.imodule)
        else:
            imodules.add(plot.imodule)

    if None in imodules:
        imodules.remove(None)

    if len(imodules) > 1:
        raise ValueError(
            "The provided interactive plots uses different interactive "
            "modules. This is not supported. Please, only chose one "
            "interactive module for all plots.\n"
            f"Received interactive modules: {imodules}")
    return imodules.pop() if len(imodules) > 0 else None


def _check_imodules(plots_imodule, plotgrid_imodule):
    def raise_error(plots_imodule, plotgrid_imodule):
        raise ValueError(
            "The interactive module used by `plotgrid` is different from "
            "the interactive module used by the plots. This is not supported. "
            "Please, only chose one interactive module. Received:\n"
            f"plotgrid imodule={plotgrid_imodule}\n"
            f"plots imodule={plots_imodule}"
        )
    default_imodule = cfg["interactive"]["module"]
    if (plots_imodule is None) and (plotgrid_imodule is None):
        pass
    elif plots_imodule is None:
        if plotgrid_imodule != default_imodule:
            raise_error(default_imodule, plotgrid_imodule)
    elif plotgrid_imodule is None:
        if plots_imodule != default_imodule:
            raise_error(plots_imodule, default_imodule)
    elif plotgrid_imodule != plots_imodule:
        raise_error(plots_imodule, plotgrid_imodule)


[docs] def plotgrid(*args, **kwargs): """Combine multiple plots into a grid-like layout. This function has two modes of operation, depending on the input arguments. Make sure to read the examples to fully understand them. Parameters ========== args : sequence A sequence of aldready created plots. This, in combination with ``nr`` and ``nc`` represents the first mode of operation, where a basic grid with (nc * nr) subplots will be created. nr, nc : int, optional Number of rows and columns. By default, ``nc = 1`` and ``nr = -1``: this will create as many rows as necessary, and a single column. By setting ``nr = 1`` a grid with a single row and as many columns as necessary will be created. gs : dict, optional A dictionary mapping Matplotlib's ``GridSpec`` objects to the plots. The keys represent the cells of the layout. Each cell will host the associated plot. This represents the second mode of operation, as it allows to create more complicated layouts. imagegrid : boolean, optional Requests Matplotlib's ``ImageGrid`` axes [#fn2]_ to be used. This is best suited for plots with equal aspect ratio sharing a common colorbar. Default to False. panel_kw : dict, optional A dictionary of keyword arguments to be passed to panel's ``GridSpec`` for further customization. Default to ``dict(sizing_mode="stretch_width")``. Refer to [#fn1]_ for more information. show : boolean, optional It applies only to Matplotlib figures. Default to True. Returns ======= fig : ``plt.Figure`` or ``pn.GridSpec`` If all input plots are instances of ``MatplotlibBackend``, than a Matplotlib ``Figure`` will be returned. Otherwise an instance of Holoviz Panel's ``GridSpec`` will be returned. Examples ======== First mode of operation with instances of ``MatplotlibBackend``: .. plot:: :include-source: True :context: reset from sympy import symbols, sin, cos, tan, exp, sqrt, Matrix, gamma, I from spb import * x, y, z = symbols("x, y, z") p1 = plot(sin(x), backend=MB, title="sin(x)", show=False) p2 = plot(tan(x), backend=MB, adaptive=False, detect_poles=True, title="tan(x)", show=False) p3 = plot(exp(-x), backend=MB, title="exp(-x)", show=False) plotgrid(p1, p2, p3) When plots represents images with equal aspect ratio and common colorbar, set ``imagegrid=True``: .. plot:: :include-source: True :context: reset from sympy import symbols, sin, cos, pi, I from spb import * z = symbols("z") options = dict(coloring="b", show=False, grid=False) p1 = plot_complex(sin(z), (z, -pi-pi*I, pi+pi*I), **options) p2 = plot_complex(cos(z), (z, -pi-pi*I, pi+pi*I), **options) plotgrid(p1, p2, nr=1, imagegrid=True) Second mode of operation, using Matplotlib ``GridSpec``: .. plot:: :include-source: True :context: reset from sympy import * from spb import * from matplotlib.gridspec import GridSpec x, y, z = symbols("x, y, z") p1 = plot(sin(x), cos(x), adaptive=False, show=False) expr = Tuple(1, sin(x**2 + y**2)) p2 = plot_vector(expr, (x, -2, 2), (y, -2, 2), streamlines=True, scalar=False, use_cm=False, title=r"$\\vec{F}(x, y) = %s$" % latex(expr), xlabel="x", ylabel="y", show=False) p3 = plot_complex(gamma(z), (z, -3-3*I, 3+3*I), title=r"$\gamma(z)$", grid=False, show=False) gs = GridSpec(3, 4) mapping = { gs[2, :]: p1, gs[0:2, 0:2]: p2, gs[0:2, 2:]: p3, } plotgrid(gs=mapping) Interactive-widget plotgrid with first mode of operation, illustrating: * ``plotgrid`` accepts interactive plots. * the use of the ``prange`` class (parametric range). * the same interactive module, ``imodule``, must be used on the plots as well as on the plotgrid. Here, ``imodule="panel"`` has been used, but users can change it to ``imodule="ipywidgets"``, provided that ``%matplotlib widget`` is executed first. .. panel-screenshot:: :small-size: 800, 675 from sympy import * from spb import * from sympy.abc import a, b, c, d, x imodule = "panel" options = dict( imodule=imodule, show=False, params={ a: (1, 0, 2), b: (5, 0, 10), c: (0, 0, 2*pi), d: (10, 1, 20) }) p1 = plot(sin(x*a + c) * exp(-abs(x) / b), prange(x, -d, d), **options) p2 = plot(cos(x*a + c) * exp(-abs(x) / b), (x, -10, 10), **options) plotgrid(p1, p2, imodule=imodule) References ========== .. [#fn1] https://panel.holoviz.org/reference/layouts/GridSpec.html .. [#fn2] https://matplotlib.org/stable/api/_as_gen/mpl_toolkits.axes_grid1.axes_grid.ImageGrid.html """ nr = kwargs.get("nr", -1) nc = kwargs.get("nc", 1) nr, nc = _nrows_ncols(nr, nc, len(args)) show = kwargs.pop("show", True) gs = kwargs.get("gs", None) all_parameters = {} # TODO: remove new_args new_args = [] if len(args) > 0: plots_imodule = _get_plots_imodule(args) all_parameters, new_args = _get_all_parameters(args) elif gs: _check_gs(gs) plots = list(gs.values()) plots_imodule = _get_plots_imodule(plots) all_parameters, new_args = _get_all_parameters(plots) else: plots_imodule = None _check_imodules(plots_imodule, kwargs.get("imodule", None)) is_iplot = len(all_parameters) > 0 p = PlotGrid(nr, nc, *args, show=False, is_iplot=is_iplot, **kwargs) if is_iplot: kwargs["plotgrid"] = p kwargs["params"] = all_parameters kwargs["show"] = show return create_interactive_plot(**kwargs) if not show: return p if p.is_matplotlib_fig: p.show() return p return p.show()
class PlotGrid: """Implement the logic to create a grid of plots. Refer to ``plotgrid`` about examples. """ _panel_row_height = 350 def __init__(self, nrows, ncolumns, *args, **kwargs): self.matplotlib = import_module( 'matplotlib', import_kwargs={'fromlist': ['pyplot', 'gridspec']}, min_module_version='1.1.0', catch=(RuntimeError,)) self.plt = self.matplotlib.pyplot self.nrows = nrows self.ncolumns = ncolumns self.args = args self.size = kwargs.get("size", None) # requests Matplotlib's ImageGrid axis to be used self.imagegrid = kwargs.get("imagegrid", False) self._fig = None # If args are all instances of MB, than new plots will be created. # All of them will share the same figure, but uses a different axes. # Need to store the new plots in order to update them, in case of # interactive widget plot. self._new_plots = [] # the following is used when imodule="ipywidgets". It maps bokeh # outputs to plots, so that bokeh outputs can be reconstructed after # the plots have updated their data. self._bokeh_outputs_plots = [] # the following is used when imodule="panel". It maps plots to panes, # so that panel can update what is shown on the pane after the plots # have updated their data. self._panes_plots = {} self._is_iplot = kwargs.get("is_iplot", False) self._imodule = kwargs.get("imodule", cfg["interactive"]["module"]) # validate GridSpec, if provided self.gs = kwargs.get("gs", None) if self.gs: _check_gs(self.gs) self.is_matplotlib_fig = _are_all_plots_instances_of( self.gs.values(), MB) self.is_bokeh_fig = _are_all_plots_instances_of( self.gs.values(), BB) else: self.is_matplotlib_fig = _are_all_plots_instances_of(args, MB) self.is_bokeh_fig = _are_all_plots_instances_of(args, BB) self.panel_kw = kwargs.get("panel_kw", dict()) if kwargs.get("show", True): self.show() @property def backend(self): # TODO: follow sympy doc procedure to create this deprecation sympy_deprecation_warning( "`backend` is deprecated. Use `fig` instead.", deprecated_since_version="1.12", active_deprecations_target='---') @property def _series(self): # TODO: follow sympy doc procedure to create this deprecation sympy_deprecation_warning( "`_series` is deprecated.", deprecated_since_version="1.12", active_deprecations_target='---') def close(self): """Close the current plot, if it is a Matplotlib figure.""" self.plt.close(self.fig) @property def fig(self): if self._fig is None: self._create_figure() return self._fig def save(self, path, **kwargs): """Save the current plot at the specified location. Refer to: * [#fn10]_ to visualize all the available keyword arguments when saving a Matplotlib figure. * [#fn11]_ to visualize all the available keyword arguments when saving a Holoviz's Panel object. References ========== .. [#fn10] https://matplotlib.org/stable/api/_as_gen/matplotlib.pyplot.savefig.html .. [#fn11] https://panel.holoviz.org/api/panel.viewable.html#panel.viewable.Viewable.save """ if self.is_matplotlib_fig: self.fig.savefig(path, **kwargs) else: self.fig.save(path, **kwargs) def _create_figure(self, **kwargs): GridSpec = self.matplotlib.gridspec.GridSpec gs = self.gs is_iplot_panel = self._is_iplot and (self._imodule == "panel") if (gs is None) and (len(self.args) == 0): self._fig = self.plt.figure() elif (gs is None): # First mode of operation nr, nc = self.nrows, self.ncolumns gs = GridSpec(nr, nc) mapping = {} c = 0 for i in range(nr): for j in range(nc): if c < len(self.args): mapping[gs[i, j]] = self.args[c] c += 1 if self.is_matplotlib_fig: self._fig, self._new_plots, self._panes_plots = _create_mpl_figure( mapping, self.imagegrid, self.size, is_iplot_panel) else: size = self.size # NOTE: assumimg all plots are of the same backend self._new_plots = self.args if self._imodule == "panel": self.panel_kw.setdefault( "width", 800 if not size else size[0]) self.panel_kw.setdefault( "height", nr * self._panel_row_height if not size else size[1] ) self._fig, self._panes_plots = _create_panel_figure( mapping, self.panel_kw) else: get_size = lambda t: str(t) + "px" if isinstance(t, int) else t self.panel_kw.setdefault("width", "800px" if not size else get_size(size[0])) if not self.is_bokeh_fig: # NOTE: this doesn't work well with bokeh self.panel_kw.setdefault("height", str(nr * self._panel_row_height) + "px" if not size else get_size(size[1])) self.panel_kw["n_rows"] = nr self.panel_kw["n_columns"] = nc self._fig, self._bokeh_outputs_plots = _create_ipywidgets_figure( mapping, self.panel_kw) else: # Second mode of operation if self.is_matplotlib_fig: self._fig, self._new_plots, self._panes_plots = _create_mpl_figure( gs, self.imagegrid, self.size, is_iplot_panel) else: for plot in gs.values(): if isinstance(plot, IPlot): self._new_plots.append(plot.backend) else: self._new_plots.append(plot) if self._imodule == "panel": self._fig, self._panes_plots = _create_panel_figure( gs, self.panel_kw) else: first_element = list(gs.keys())[0] mpl_gs = first_element.get_gridspec() self.panel_kw = { "n_rows": mpl_gs.nrows, "n_columns": mpl_gs.ncols} self._fig, self._bokeh_outputs_plots = _create_ipywidgets_figure( gs, self.panel_kw) def _action_post_update(self): """With Holoviz's Panel, plots are contained into `panes`: they are ultimately responsible to update what is shown on the screen. This method is executed by the interactive widget plot after all subplots have updated their data. """ for pane, plot in self._panes_plots.items(): pane.param.trigger("object") if isinstance(plot, PB): pane.object = plot.fig.to_dict() elif isinstance(plot, self.matplotlib.figure.Figure): pane.object = plot else: pane.object = plot.fig def update_interactive(self, params): """Implement the logic to update the data generated by interactive-widget plots. Parameters ========== params : dict Map parameter-symbols to numeric values. """ for p in self._new_plots: if isinstance(p, IPlot): p.backend.update_interactive(params) else: p.update_interactive(params) # update bokeh panes if ipywidgets was used to create # this visualization bokeh = import_module( 'bokeh', import_kwargs={'fromlist': ['io']}, warn_not_installed=True, min_module_version='2.3.0') IPython = import_module( "IPython", import_kwargs={'fromlist': ['display']}, warn_not_installed=True) for (bokeh_output, plot) in self._bokeh_outputs_plots: with bokeh_output: IPython.display.clear_output(True) bokeh.io.show(plot.fig) def show(self, **kwargs): """Display the current plot. Parameters ========== **kwargs : dict Keyword arguments to be passed to plt.show() if a Matplotlib figure is created. """ if (self._fig is None) or self.is_matplotlib_fig: self._create_figure() if self.is_matplotlib_fig: if not self.imagegrid: self._fig.tight_layout() self.plt.show(**kwargs) else: # holoviz's panel object must be shown on an interactive cell return self.fig