save.Rd 7.18 KB
Newer Older
Radford Neal's avatar
Radford Neal committed
1 2
% File src/library/base/man/save.Rd
% Part of the R package, http://www.R-project.org
3
% Copyright 1995-2011 R Core Team
Radford Neal's avatar
Radford Neal committed
4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20
% Distributed under GPL 2 or later

\name{save}
\alias{save}
\alias{save.image}
\title{Save R Objects}
\description{
  \code{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 \code{load} (or \code{data} in some cases).

  \code{save.image()} is just a short-cut for \sQuote{save my current
    workspace},
  i.e., \code{save(list = ls(all=TRUE), file = ".RData")}.  It is also what
  happens with \code{\link{q}("yes")}.
}
\usage{
Radford Neal's avatar
Radford Neal committed
21
save(\dots, list = character(),
Radford Neal's avatar
Radford Neal committed
22 23 24 25 26 27 28 29 30 31 32 33 34
     file = stop("'file' must be specified"),
     ascii = FALSE, version = NULL, envir = parent.frame(),
     compress = !ascii, compression_level,
     eval.promises = TRUE, precheck = TRUE)

save.image(file = ".RData", version = NULL, ascii = FALSE,
           compress = !ascii, safe = TRUE)
}
\arguments{
  \item{\dots}{the names of the objects to be saved (as symbols or
    character strings).}
  \item{list}{A character vector containing the names of objects to be
    saved.}
Radford Neal's avatar
Radford Neal committed
35
  \item{file}{a (writable binary-mode) \link{connection} or the name of the
Radford Neal's avatar
Radford Neal committed
36 37
    file where the data will be saved (when \link{tilde expansion}
    is done).  Must be a file name for \code{version = 1}.}
Radford Neal's avatar
Radford Neal committed
38 39
  \item{ascii}{if \code{TRUE}, an ASCII representation of the data is
    written.  The default value of \code{ascii} is \code{FALSE} which
Radford Neal's avatar
Radford Neal committed
40
    leads to a binary file being written.}
Radford Neal's avatar
Radford Neal committed
41
  \item{version}{the workspace format version to use.  \code{NULL}
42 43
    specifies the current default format.  This is currently version 2,
    and this is currently the only one allowed.}
Radford Neal's avatar
Radford Neal committed
44 45 46 47 48
  \item{envir}{environment to search for objects to be saved.}
  \item{compress}{logical or character string specifying whether saving
    to a named file is to use compression.  \code{TRUE} corresponds to
    \command{gzip} compression, and (from \R 2.10.0) character strings
    \code{"gzip"}, \code{"bzip2"} or \code{"xz"} specify the
49
    type of compression.  Ignored when \code{file} is a connection.}
Radford Neal's avatar
Radford Neal committed
50 51 52 53 54 55 56
  \item{compression_level}{integer: the level of compression to be
    used.  Defaults to \code{6} for \command{gzip} compression and to
    \code{9} for \command{bzip2} or \command{xz} compression.}
  \item{eval.promises}{logical: should objects which are promises be
    forced before saving?}
  \item{precheck}{logical: should the existence of the objects be
    checked before starting to save (and in particular before opening
57
    the file/connection)?}
Radford Neal's avatar
Radford Neal committed
58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73
  \item{safe}{logical.  If \code{TRUE}, a temporary file is used for
    creating the saved workspace.  The temporary file is renamed to
    \code{file} if the save succeeds.  This preserves an existing
    workspace \code{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 \code{\dots} or as a character vector in \code{list} are
  used to look up the objects from environment \code{envir}.  By default
  \link{promises} are evaluated, but if \code{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
Radford Neal's avatar
Radford Neal committed
74
  platforms.  (ASCII saves used to be useful for moving data between
Radford Neal's avatar
Radford Neal committed
75 76 77 78
  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.)
Radford Neal's avatar
Radford Neal committed
79 80

  Default values for the \code{ascii}, \code{compress}, \code{safe} and
Radford Neal's avatar
Radford Neal committed
81 82 83 84 85 86
  \code{version} arguments can be modified with the
  \code{"save.defaults"} option (used both by \code{save} and
  \code{save.image}), see also the \sQuote{Examples} section.  If a
  \code{"save.image.defaults"} option is set it is used in preference to
  \code{"save.defaults"} for function \code{save.image} (which allows
  this to have different defaults).
Radford Neal's avatar
Radford Neal committed
87 88

  A connection that is not already open will be opened in mode
Radford Neal's avatar
Radford Neal committed
89
  \code{"wb"}.
Radford Neal's avatar
Radford Neal committed
90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112
}

\section{Compression}{
  Large files can be reduced considerably in size by compression.  A
  particular 46MB dataset was saved as 35MB without compression in 2
  seconds, 22MB with \command{gzip} compression in 8 secs, 19MB with
  \command{bzip2} compression in 13 secs and 9.4MB with \command{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 and \command{xz} did
  unusually well here.
  
  It is possible to compress later (with \command{gzip}, \command{bzip2}
  or \command{xz}) a file saved with \code{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 \code{\link{resaveRdaFiles}} for a way to do so from within \R).
}

\note{
  The most common reason for failure is lack of write permission in the
  current directory.  For \code{save.image} and for saving at the end of
  a session this will shown by messages like
Radford Neal's avatar
Radford Neal committed
113
\preformatted{    Error in gzfile(file, "wb") : unable to open connection
Radford Neal's avatar
Radford Neal committed
114 115 116 117 118 119 120 121 122 123
    In addition: Warning message:
    In gzfile(file, "wb") :
      cannot open compressed file '.RDataTmp',
      probable reason 'Permission denied'
}
  
  The defaults were changed to use compressed saves for \code{save} in
  2.3.0 and for \code{save.image} in 2.4.0.  Any recent version of \R
  can read compressed save files, and a compressed file can be
  uncompressed (by \code{gzip -d}) for use with very old versions of \R.
Radford Neal's avatar
Radford Neal committed
124 125 126 127 128
#ifdef windows

  \code{file} can be a UTF-8-encoded filepath that cannot be translated to
  the current locale.
#endif
Radford Neal's avatar
Radford Neal committed
129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150
}

\section{Warnings}{
  The \code{\dots} arguments only give the \emph{names} of the objects
  to be saved: they are searched for in the environment given by the
  \code{envir} argument, and the actual objects given as arguments need
  not be those found.

  Saved \R objects are binary files, even those saved with
  \code{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 or
  external pointers).
}
\seealso{
  \code{\link{dput}}, \code{\link{dump}}, \code{\link{load}},
  \code{\link{data}}.
Radford Neal's avatar
Radford Neal committed
151 152

  For other interfaces to the underlying serialization format, see
Radford Neal's avatar
Radford Neal committed
153
  \code{\link{serialize}} and \code{\link{saveRDS}}.
Radford Neal's avatar
Radford Neal committed
154 155 156 157
}
\examples{
x <- stats::runif(20)
y <- list(a = 1, b = TRUE, c = "oops")
Radford Neal's avatar
Radford Neal committed
158
save(x, y, file = "xy.RData")
Radford Neal's avatar
Radford Neal committed
159
save.image()
Radford Neal's avatar
Radford Neal committed
160
unlink("xy.RData")
Radford Neal's avatar
Radford Neal committed
161 162 163 164 165 166 167 168
unlink(".RData")

# set save defaults using option:
options(save.defaults=list(ascii=TRUE, safe=FALSE))
save.image()
unlink(".RData")
}
\keyword{file}