ggsave#

ggsave(plot: PlotSpec | SupPlotsSpec | GGBunch, filename: str, *, path: str | None = None, iframe: bool = True, scale: float | None = None, w: float | None = None, h: float | None = None, unit: str | None = None, dpi: int | None = None) → str#

Export plot or bunch to a file. Supported formats: PNG, SVG, PDF, HTML.

The exported file is created in directory ${user.dir}/lets-plot-images if not specified otherwise (see the path parameter).

Parameters:
plotPlotSpec or GGBunch

Plot specification to export.

filenamestr

The name of file. It must end with a file extension corresponding to one of the supported formats: SVG, HTML (or HTM), PNG (requires CairoSVG library), PDF.

pathstr

Path to a directory to save image files in. By default, it is ${user.dir}/lets-plot-images.

iframebool, default=True

Whether to wrap HTML page into a iFrame. Only applicable when exporting to HTML. Some browsers may not display some UTF-8 characters correctly when setting iframe=True

scalefloat, default=2.0

Scaling factor for raster output. Only applicable when exporting to PNG or PDF.

wfloat, default=None

Width of the output image in units. Only applicable when exporting to PNG or PDF.

hfloat, default=None

Height of the output image in units. Only applicable when exporting to PNG or PDF.

unit{‘in’, ‘cm’, ‘mm’}, default=None

Unit of the output image. One of: ‘in’, ‘cm’, ‘mm’. Only applicable when exporting to PNG or PDF.

dpiint, default=None

Resolution in dots per inch. Only applicable when exporting to PNG or PDF.

Returns:
str

Absolute pathname of created file.

Notes

Output format is inferred from the filename extension.

For PNG and PDF formats:

  1. 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 maintains its original (pixel) aspect ratio.

      • It’s fitted within the specified w x h area.

      • Any extra space is left empty.

  2. If w, h are not specified:

    • The scale parameter is used to determine the output size.

Examples

1from lets_plot import *
2LetsPlot.setup_html()
3plot = ggplot() + geom_point(x=0, y=0)
4ggsave(plot, 'plot.html', path='.', iframe=False)


1from lets_plot import *
2LetsPlot.setup_html()
3plot = ggplot() + geom_point(x=0, y=0) + ggsize(800, 400)
4ggsave(plot, 'plot.png', w=8, h=4, unit='in', dpi=300)
On this page