save                  package:base                  R Documentation

Save R Objects

Description:

     '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 'data' in some cases).

     'save.image()' is just a short-cut for 'save my current
     workspace', i.e., 'save(list = ls(all=TRUE), file = ".RData")'. 
     It is also what happens with 'q("yes")'.

Usage:

     save(..., list = character(0),
          file = stop("'file' must be specified"),
          ascii = FALSE, version = NULL, envir = parent.frame(),
          compress = !ascii, 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 connection or the name of the file where the data will be
          saved.  Must be a file name for workspace format version 1.

   ascii: if 'TRUE', an ASCII representation of the data is written. 
          The default value of 'ascii' is 'FALSE' which leads to a more
          compact binary file being written.

 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 specifying whether saving to a named file is to use
          compression.  Ignored when 'file' is a connection and for
          workspace format version 1.

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.)

     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 example section
     below.  If a 'save.image.defaults' option is set it overrides
     'save.defaults' for function 'save.image' (which allows this to
     have different defaults).

     It is possible to compress later (with 'gzip') a file saved with
     'compress = FALSE': the effect is the same as saving with
     'compress = TRUE'.

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 or external pointers).

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'

     The defaults were changed to use compressed saves for 'save' in
     2.3.0 and for 'save.image' in 2.4.0.  Any recent version of R can
     read compressed save files, and a compressed file can be
     uncompressed (by 'gzip -d') for use with very old versions of R.

See Also:

     'dput', 'dump', 'load', 'data'.

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")

