readRDS | R Documentation |
Functions to write a single R object to a file, and to restore it.
saveRDS(object, file = "", ascii = FALSE, version = NULL, compress = TRUE, refhook = NULL) readRDS(file, refhook = NULL) infoRDS(file)
object |
R object to serialize. |
file |
a connection or the name of the file where the R object is saved to or read from. |
ascii |
a logical. If |
version |
the workspace format version to use. |
compress |
a logical specifying whether saving to a named file is
to use |
refhook |
a hook function for handling reference objects. |
saveRDS
and readRDS
provide the means to save a single R
object to a connection (typically a file) and to restore the object, quite
possibly under a different name. This differs from save
and
load
, which save and restore one or more named objects into
an environment. They are widely used by R itself, for example to store
metadata for a package and to store the help.search
databases: the ".rds"
file extension is most often used.
Functions serialize
and unserialize
provide a slightly lower-level interface to serialization: objects
serialized to a connection by serialize
can be read back by
readRDS
and conversely.
Function infoRDS
retrieves meta-data about serialization produced
by saveRDS
or serialize
. infoRDS
cannot be used to
detect whether a file is a serialization nor whether it is valid.
All of these interfaces use the same serialization format, but save
writes a single line header (typically "RDXs\n"
) before the
serialization of a single object (a pairlist of all the objects to be
saved).
If file
is a file name, it is opened by gzfile
except for save(compress = FALSE)
which uses
file
. Only for the exception are marked encodings of
file
which cannot be translated to the native encoding handled
on Windows.
Compression is handled by the connection opened when file
is a
file name, so is only possible when file
is a connection if
handled by the connection. So e.g. url
connections will need to be wrapped in a call to gzcon
.
If a connection is supplied it will be opened (in binary mode) for the
duration of the function if not already open: if it is already open it
must be in binary mode for saveRDS(ascii = FALSE)
or to read
non-ASCII saves.
For readRDS
, an R object.
For saveRDS
, NULL
invisibly.
For infoRDS
, an R list with elements version
(version
number, currently 2 or 3), writer_version
(version of R that
produced the serialization), min_reader_version
(minimum version of
R that can read the serialization), format
(data representation)
and native_encoding
(native encoding of the session that produced
the serialization, available since version 3). The data representation is
given as "xdr"
for big-endian binary representation, "ascii"
for ASCII representation (produced via ascii = TRUE
or ascii
= NA
) or "binary"
(binary representation with native
‘endianness’ which can be produced by serialize
).
Files produced by saveRDS
(or serialize
to a file
connection) are not suitable as an interchange format between
machines, for example to download from a website. The
files produced by save
have a header identifying the
file type and so are better protected against erroneous use.
serialize
, save
and load
.
The ‘R Internals’ manual for details of the format used.
fil <- tempfile("women", fileext = ".rds") ## save a single object to file saveRDS(women, fil) ## restore it under a different name women2 <- readRDS(fil) identical(women, women2) ## or examine the object via a connection, which will be opened as needed. con <- gzfile(fil) readRDS(con) close(con) ## Less convenient ways to restore the object ## which demonstrate compatibility with unserialize() con <- gzfile(fil, "rb") identical(unserialize(con), women) close(con) con <- gzfile(fil, "rb") wm <- readBin(con, "raw", n = 1e4) # size is a guess close(con) identical(unserialize(wm), women) ## Format compatibility with serialize(): fil2 <- tempfile("women") con <- file(fil2, "w") serialize(women, con) # ASCII, uncompressed close(con) identical(women, readRDS(fil2)) fil3 <- tempfile("women") con <- bzfile(fil3, "w") serialize(women, con) # binary, bzip2-compressed close(con) identical(women, readRDS(fil3)) unlink(c(fil, fil2, fil3))
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.