save writes an external representation of R objects to the
specified file. The objects can be read back from the file at a later
date by using the function load or attach
(or data in some cases).
save.image() is just a short-cut for ‘save my current
workspace’, i.e., save(list = ls(all.names = TRUE), file =
".RData", envir = .GlobalEnv).
It is also what happens with q("yes").
Usage
save(..., list = character(),
file = stop("'file' must be specified"),
ascii = FALSE, version = NULL, envir = parent.frame(),
compress = isTRUE(!ascii), compression_level,
eval.promises = TRUE, precheck = TRUE)
save.image(file = ".RData", version = NULL, ascii = FALSE,
compress = !ascii, safe = TRUE)
Arguments
...
the names of the objects to be saved (as symbols or
character strings).
list
A character vector containing the names of objects to be
saved.
file
a (writable binary-mode) connection or the name of the
file where the data will be saved (when tilde expansion
is done). Must be a file name for save.image or
version = 1.
ascii
if TRUE, an ASCII representation of the data is
written. The default value of ascii is FALSE which
leads to a binary file being written. If NA and
version >= 2, a different ASCII representation is used which
writes double/complex numbers as binary fractions.
version
the workspace format version to use. NULL
specifies the current default format. The version used from R
0.99.0 to R 1.3.1 was version 1. The default format as from R
1.4.0 is version 2.
envir
environment to search for objects to be saved.
compress
logical or character string specifying whether saving
to a named file is to use compression. TRUE corresponds to
gzip compression, and character strings "gzip",
"bzip2" or "xz" specify the type of
compression. Ignored when file is a connection and
for workspace format version 1.
compression_level
integer: the level of compression to be
used. Defaults to 6 for gzip compression and to
9 for bzip2 or xz compression.
eval.promises
logical: should objects which are promises be
forced before saving?
precheck
logical: should the existence of the objects be
checked before starting to save (and in particular before opening
the file/connection)? Does not apply to version 1 saves.
safe
logical. If TRUE, a temporary file is used for
creating the saved workspace. The temporary file is renamed to
file if the save succeeds. This preserves an existing
workspace file if the save fails, but at the cost of using
extra disk space during the save.
Details
The names of the objects specified either as symbols (or character
strings) in ... or as a character vector in list are
used to look up the objects from environment envir. By default
promises are evaluated, but if eval.promises = FALSE
promises are saved (together with their evaluation environments).
(Promises embedded in objects are always saved unevaluated.)
All R platforms use the XDR (bigendian) representation of C ints and
doubles in binary save-d files, and these are portable across all R
platforms.
ASCII saves used to be useful for moving data between platforms but
are now mainly of historical interest. They can be more compact than
binary saves where compression is not used, but are almost always
slower to both read and write: binary saves compress much better than
ASCII ones. Further, decimal ASCII saves may not restore
double/complex values exactly, and what value is restored may depend
on the R platform.
Default values for the ascii, compress, safe and
version arguments can be modified with the
"save.defaults" option (used both by save and
save.image), see also the ‘Examples’ section. If a
"save.image.defaults" option is set it is used in preference to
"save.defaults" for function save.image (which allows
this to have different defaults). In addition,
compression_level can be part of the "save.defaults"
option.
A connection that is not already open will be opened in mode
"wb". Supplying a connection which is open and not in binary
mode gives an error.
Compression
Large files can be reduced considerably in size by compression. A
particular 46MB R object was saved as 35MB without compression in 2
seconds, 22MB with gzip compression in 8 secs, 19MB with
bzip2 compression in 13 secs and 9.4MB with xz
compression in 40 secs. The load times were 1.3, 2.8, 5.5 and 5.7
seconds respectively. These results are indicative, but the relative
performances do depend on the actual file: xz compressed
unusually well here.
It is possible to compress later (with gzip, bzip2
or xz) a file saved with compress = FALSE: the effect
is the same as saving with compression. Also, a saved file can be
uncompressed and re-compressed under a different compression scheme
(and see resaveRdaFiles for a way to do so from within R).
Parallel compression
That file can be a connection can be exploited to make use of
an external parallel compression utility such as pigz
(http://zlib.net/pigz/) or pbzip2
(http://compression.ca/pbzip2/) via a pipe
connection. For example, using 8 threads,
where the last requires xz 5.1.1 or later built with support
for multiple threads (and parallel compression is only effective for
large objects: at level 6 it will compress in serialized chunks of 12MB).
Warnings
The ... arguments only give the names of the objects
to be saved: they are searched for in the environment given by the
envir argument, and the actual objects given as arguments need
not be those found.
Saved R objects are binary files, even those saved with
ascii = TRUE, so ensure that they are transferred without
conversion of end-of-line markers and of 8-bit characters. The lines
are delimited by LF on all platforms.
Although the default version has not changed since R 1.4.0, this
does not mean that saved files are necessarily backwards compatible.
You will be able to load a saved image into an earlier version of R
unless use is made of later additions (for example, raw vectors,
external pointers and some S4 objects).
One such ‘later addition’ was long vectors, introduced in R
3.0.0 and loadable only on 64-bit platforms.
Loading files saved with ASCII = NA requires a C99-compliant C
function sscanf: this is a problem on Windows, first worked
around in R 3.1.2: they should be readable in earlier versions of R
on all other platforms.
Note
The most common reason for failure is lack of write permission in the
current directory. For save.image and for saving at the end of
a session this will shown by messages like
Error in gzfile(file, "wb") : unable to open connection
In addition: Warning message:
In gzfile(file, "wb") :
cannot open compressed file '.RDataTmp',
probable reason 'Permission denied'
See Also
dput, dump, load,
data.
For other interfaces to the underlying serialization format, see
serialize and saveRDS.
Examples
x <- stats::runif(20)
y <- list(a = 1, b = TRUE, c = "oops")
save(x, y, file = "xy.RData")
save.image()
unlink("xy.RData")
unlink(".RData")
# set save defaults using option:
options(save.defaults = list(ascii = TRUE, safe = FALSE))
save.image()
unlink(".RData")
Results
R version 3.3.1 (2016-06-21) -- "Bug in Your Hair"
Copyright (C) 2016 The R Foundation for Statistical Computing
Platform: x86_64-pc-linux-gnu (64-bit)
R is free software and comes with ABSOLUTELY NO WARRANTY.
You are welcome to redistribute it under certain conditions.
Type 'license()' or 'licence()' for distribution details.
R is a collaborative project with many contributors.
Type 'contributors()' for more information and
'citation()' on how to cite R or R packages in publications.
Type 'demo()' for some demos, 'help()' for on-line help, or
'help.start()' for an HTML browser interface to help.
Type 'q()' to quit R.
> library(base)
> png(filename="/home/ddbj/snapshot/RGM3/R_rel/result/base/save.Rd_%03d_medium.png", width=480, height=480)
> ### Name: save
> ### Title: Save R Objects
> ### Aliases: save save.image
> ### Keywords: file
>
> ### ** Examples
>
> x <- stats::runif(20)
> y <- list(a = 1, b = TRUE, c = "oops")
> save(x, y, file = "xy.RData")
> save.image()
> unlink("xy.RData")
> unlink(".RData")
>
> # set save defaults using option:
> options(save.defaults = list(ascii = TRUE, safe = FALSE))
> save.image()
> unlink(".RData")
>
>
>
>
>
> dev.off()
null device
1
>