File: ggsave.Rd

package info (click to toggle)
r-cran-ggplot2 3.5.1%2Bdfsg-1
  • links: PTS, VCS
  • area: main
  • in suites: sid, trixie
  • size: 9,944 kB
  • sloc: sh: 15; makefile: 5
file content (127 lines) | stat: -rw-r--r-- 4,289 bytes parent folder | download
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/save.R
\name{ggsave}
\alias{ggsave}
\title{Save a ggplot (or other grid object) with sensible defaults}
\usage{
ggsave(
  filename,
  plot = last_plot(),
  device = NULL,
  path = NULL,
  scale = 1,
  width = NA,
  height = NA,
  units = c("in", "cm", "mm", "px"),
  dpi = 300,
  limitsize = TRUE,
  bg = NULL,
  create.dir = FALSE,
  ...
)
}
\arguments{
\item{filename}{File name to create on disk.}

\item{plot}{Plot to save, defaults to last plot displayed.}

\item{device}{Device to use. Can either be a device function
(e.g. \link{png}), or one of "eps", "ps", "tex" (pictex),
"pdf", "jpeg", "tiff", "png", "bmp", "svg" or "wmf" (windows only). If
\code{NULL} (default), the device is guessed based on the \code{filename} extension.}

\item{path}{Path of the directory to save plot to: \code{path} and \code{filename}
are combined to create the fully qualified file name. Defaults to the
working directory.}

\item{scale}{Multiplicative scaling factor.}

\item{width, height}{Plot size in units expressed by the \code{units} argument.
If not supplied, uses the size of the current graphics device.}

\item{units}{One of the following units in which the \code{width} and \code{height}
arguments are expressed: \code{"in"}, \code{"cm"}, \code{"mm"} or \code{"px"}.}

\item{dpi}{Plot resolution. Also accepts a string input: "retina" (320),
"print" (300), or "screen" (72). Applies only to raster output types.}

\item{limitsize}{When \code{TRUE} (the default), \code{ggsave()} will not
save images larger than 50x50 inches, to prevent the common error of
specifying dimensions in pixels.}

\item{bg}{Background colour. If \code{NULL}, uses the \code{plot.background} fill value
from the plot theme.}

\item{create.dir}{Whether to create new directories if a non-existing
directory is specified in the \code{filename} or \code{path} (\code{TRUE}) or return an
error (\code{FALSE}, default). If \code{FALSE} and run in an interactive session,
a prompt will appear asking to create a new directory when necessary.}

\item{...}{Other arguments passed on to the graphics device function,
as specified by \code{device}.}
}
\description{
\code{ggsave()} is a convenient function for saving a plot. It defaults to
saving the last plot that you displayed, using the size of the current
graphics device. It also guesses the type of graphics device from the
extension.
}
\details{
Note: Filenames with page numbers can be generated by including a C
integer format expression, such as \verb{\%03d} (as in the default file name
for most R graphics devices, see e.g. \code{\link[=png]{png()}}).
Thus, \code{filename = "figure\%03d.png"} will produce successive filenames
\code{figure001.png}, \code{figure002.png}, \code{figure003.png}, etc. To write a filename
containing the \verb{\%} sign, use \code{\%\%}. For example, \code{filename = "figure-100\%\%.png"}
will produce the filename \verb{figure-100\%.png}.
}
\section{Saving images without ggsave()}{


In most cases \code{ggsave()} is the simplest way to save your plot, but
sometimes you may wish to save the plot by writing directly to a
graphics device. To do this, you can open a regular R graphics
device such as \code{png()} or \code{pdf()}, print the plot, and then close
the device using \code{dev.off()}. This technique is illustrated in the
examples section.
}

\examples{
\dontrun{
ggplot(mtcars, aes(mpg, wt)) +
  geom_point()

# here, the device is inferred from the filename extension
ggsave("mtcars.pdf")
ggsave("mtcars.png")

# setting dimensions of the plot
ggsave("mtcars.pdf", width = 4, height = 4)
ggsave("mtcars.pdf", width = 20, height = 20, units = "cm")

# passing device-specific arguments to '...'
ggsave("mtcars.pdf", colormodel = "cmyk")

# delete files with base::unlink()
unlink("mtcars.pdf")
unlink("mtcars.png")

# specify device when saving to a file with unknown extension
# (for example a server supplied temporary file)
file <- tempfile()
ggsave(file, device = "pdf")
unlink(file)

# save plot to file without using ggsave
p <-
  ggplot(mtcars, aes(mpg, wt)) +
  geom_point()
png("mtcars.png")
print(p)
dev.off()

}
}
\seealso{
The \href{https://ggplot2-book.org/themes#sec-saving}{saving section} of the online ggplot2 book.
}