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

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=’in’

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

dpiint, default=300

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:

  • If w, h, unit, and dpi are all specified:

    • 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 is resized to fit the specified w x h area, which may affect the layout, tick labels, and other elements.

  • If only dpi is specified:

    • 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

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)
4ggsave(plot, 'plot.png', w=4, h=3)
On this page