Plotting ¶

See Charts and Plotting for more information about plotting Python charts in Excel.

plot
PlotBridgeBase

plot ¶

plot(figure=None, name=None, width=None, height=None, top=None, left=None, sheet=None, allow_html=None, allow_svg=None, allow_resize=None, reset=False, bridge_cls=None, **kwargs)

Plots a figure to Excel as an embedded image.

This can be called from an Excel worksheet function, or from anywhere else such as a macro or menu function. If called from a worksheet function the image will be placed below the calling cell, and repeated calls will update the image rather than create new ones. If called from elsewhere the image will be placed below the current selection, and each call will create a new image.

The figure can be any of the following:

A matplotlib Figure, Subplot, Artist or Animation object
A plotly Figure object
A bokeh Plot object
An altair Chart object

If no figure is provided the current matplotlib.pyplot figure is used.

Parameters:

Parameters:	figure – Figure to plot. This can be an instance of any of the following: matplotlib.figure.Figure matplotlib.artist.Artist matplotlib.axes._subplots.SubplotBase matplotlib.animation.Animation plotly.graph_objects.Figure bokeh.models.plots.Plot altair.vegalite.v4.api.Chart If None, the active matplotlib.pyplot figure is used. name – Name of Picture object in Excel. If this is None then a name will be chosen, and if called from a UDF then repeated calls will re-use the same name. width – Initial width of the picture in Excel, in points. If set then height must also be set. If None the width will be taken from the figure. height – Initial height of the picture in Excel, in points. If set then width must also be set. If None the height will be taken from the figure. top – Initial location of the top of the plot in Excel, in points. If set then left must also be set. If None, the picture will be placed below the current or selected cell. left – Initial location of the left of the plot in Excel, in points. If set then top must also be set. If None, the picture will be placed below the current or selected cell. sheet – Name of the sheet to add the picture to. If none, the current sheet is used. allow_html – Some figures may be rendered as HTML and displayed using a web control, if the plotting library and the version of Excel being used allows. This can be disabled by setting this option to False. The default value may be changed by setting `plot_allow_html` in the `[PYXLL]` section of the config file. allow_svg – Some figures may be rendered as SVG, if the plotting library and the version of Excel being used allows. This can be disabled by setting this option to False. The default value may be changed by setting `plot_allow_svg` in the `[PYXLL]` section of the config file. allow_resize – If enabled, the figure will be re-drawn after the image is resized in Excel, and when the selection changes. This is enabled by default and can be disabled by setting this option to False. The default value may be changed by setting `plot_allow_svg` in the `[PYXLL]` section of the config file. New in PyXLL 5.7 reset – Reset the image size and position to the values specified. If `False` (default) the arguments `width`, `height`, `top` and `left` only affect the initial size and position of the image, allowing the user to resize and reposition it without it being reset each time it is updated. @Since PyXLL 5.4.0 bridge_cls – Class to use for exporting the plot as an image. If None this will be selected automatically based on the type of figure. kwargs – Additional arguments will be called to the implementation specific method for exporting the figure to an image.

figure –
Figure to plot. This can be an instance of any of the following:
- matplotlib.figure.Figure
- matplotlib.artist.Artist
- matplotlib.axes._subplots.SubplotBase
- matplotlib.animation.Animation
- plotly.graph_objects.Figure
- bokeh.models.plots.Plot
- altair.vegalite.v4.api.Chart
If None, the active matplotlib.pyplot figure is used.
name – Name of Picture object in Excel. If this is None then a name will be chosen, and if called from a UDF then repeated calls will re-use the same name.
width – Initial width of the picture in Excel, in points. If set then height must also be set. If None the width will be taken from the figure.
height – Initial height of the picture in Excel, in points. If set then width must also be set. If None the height will be taken from the figure.
top – Initial location of the top of the plot in Excel, in points. If set then left must also be set. If None, the picture will be placed below the current or selected cell.
left – Initial location of the left of the plot in Excel, in points. If set then top must also be set. If None, the picture will be placed below the current or selected cell.
sheet – Name of the sheet to add the picture to. If none, the current sheet is used.
allow_html –
Some figures may be rendered as HTML and displayed using a web control, if the plotting library and the version of Excel being used allows.

This can be disabled by setting this option to False.

The default value may be changed by setting plot_allow_html in the [PYXLL] section of the config file.
allow_svg –
Some figures may be rendered as SVG, if the plotting library and the version of Excel being used allows.

This can be disabled by setting this option to False.

The default value may be changed by setting plot_allow_svg in the [PYXLL] section of the config file.
allow_resize –
If enabled, the figure will be re-drawn after the image is resized in Excel, and when the selection changes.

This is enabled by default and can be disabled by setting this option to False.

The default value may be changed by setting plot_allow_svg in the [PYXLL] section of the config file.

New in PyXLL 5.7
reset –
Reset the image size and position to the values specified. If False (default) the arguments width, height, top and left only affect the initial size and position of the image, allowing the user to resize and reposition it without it being reset each time it is updated.

@Since PyXLL 5.4.0
bridge_cls – Class to use for exporting the plot as an image. If None this will be selected automatically based on the type of figure.
kwargs – Additional arguments will be called to the implementation specific method for exporting the figure to an image.

Note

The options width, height, top and left only affect the image when it is initially created. If a subsequent call to plot updates an existing image (for example, if called from a worksheet function or if a name is passed) then it will not be resized or moved from its current location.

PlotBridgeBase ¶

class PlotBridgeBase

Base class for plotting bridges used by plot.

This can be used to add support for plotting libraries other than the standard ones supported by PyXLL.

All methods must be implemented by the derived class.

__init__(self, figure): Construct the plot bridge for exporting a figure. The figure is the object passed to plot.

can_export(self, format)

Return True if the figure can be exported in a specific format.

Valid formats are ‘html’, ‘svg’, ‘png’ and ‘gif’.

get_size_hint(self, dpi)

Return (width, height) tuple the figure should be exported as or None.

Width and height are in points (72th of an inch).

If no size hint is available return None.

export(self, width, height, dpi, format, filename, **kwargs)

Export the figure to a file as a given size and format.

Parameters:	width – Width of the image to export in points. height – Height of the image to export in points. dpi – DPI to use to export the image. format – Format to export the image to. Valid formats are ‘html’, ‘svg’, ‘png’ and ‘gif’. filename – Filename to export the image to. kwargs – Additional kwargs passed to `plot`.

« Menu Functions

Custom Task Panes »