load {base} | R Documentation

## Reload Saved Datasets

### Description

Reload datasets written with the function `save`.

### Usage

    load(file, envir = parent.frame(), verbose = FALSE)

### Arguments

`file` | a (readable binary-mode) connection or a character string giving the name of the file to load (when tilde expansion is done).
`envir` | the environment where the data should be loaded.
`verbose` | should item names be printed during loading?

### Details

`load` can load R objects saved in the current or any earlier format. It can read a compressed file (see `save`) directly from a file or from a suitable connection (including a call to `url`).

A not-open connection will be opened in mode `"rb"` and closed after use. Any connection other than a `gzfile` or `gzcon` connection will be wrapped in `gzcon` to allow compressed saves to be handled: note that this leaves the connection in an altered state (in particular, binary-only), and that it needs to be closed explicitly (it will not be garbage-collected).

Only R objects saved in the current format (used since R 1.4.0) can be read from a connection. If no input is available on a connection a warning will be given, but any input not in the current format will result in a error.

Loading from an earlier version will give a warning about the ‘magic number’: magic numbers `1971:1977` are from R < 0.99.0, and `RD[ABX]1` from R 0.99.0 to R 1.3.1. These are all obsolete, and you are strongly recommended to re-save such files in a current format.

The `verbose` argument is mainly intended for debugging. If it is `TRUE`, then as objects from the file are loaded, their names will be printed to the console. If `verbose` is set to an integer value greater than one, additional names corresponding to attributes and other parts of individual objects will also be printed. Larger values will print names to a greater depth.

Objects can be saved with references to namespaces, usually as part of the environment of a function or formula. As from R 3.1.0 such objects can be loaded even if the namespace is not available: it is replaced by a reference to the global environment with a warning. The warning identifies the first object with such a reference (but there may be more than one).

### Value

A character vector of the names of objects created, invisibly.

### Warning

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. `load` tries to detect such a conversion and gives an informative error message.

`load(<file>)` replaces all existing objects with the same names in the current environment (typically your workspace, `.GlobalEnv`) and hence potentially overwrites important data. It is considerably safer to use `envir =` to load into a different environment, or to `attach(file)` which `load()`s into a new entry in the `search` path.

### Note

`file` can be a UTF-8-encoded filepath that cannot be translated to the current locale.

### See Also

`save`, `download.file`; further `attach` as wrapper for `load()`.

For other interfaces to the underlying serialization format, see `unserialize` and `readRDS`.

### Examples

    ## save all data
    xx <- pi # to ensure there is some data
    save(list = ls(all = TRUE), file= "all.RData")
    rm(xx)

    ## restore the saved values to the current environment
    local({
       load("all.RData")
       ls()
    })

    xx <- exp(1:3)
    ## restore the saved values to the user's workspace
    load("all.RData") ## which is here *equivalent* to
    ## load("all.RData", .GlobalEnv)
    ## This however annihilates all objects in .GlobalEnv with the same names !
    xx # no longer exp(1:3)
    rm(xx)
    attach("all.RData") # safer and will warn about masked objects w/ same name in .GlobalEnv
    ls(pos = 2)
    ##  also typically need to cleanup the search path:
    detach("file:all.RData")

    ## clean up (the example):
    unlink("all.RData")

    ## Not run:
    con <- url("http://some.where.net/R/data/example.rda")
    ## print the value to see what objects were created.
    print(load(con))
    close(con) # url() always opens the connection

    ## End(Not run)

[Package base version 3.3.2 Index]