attach
Attach Set of R Objects to Search Path
The database is attached to the R search path. This means that the database is searched by R when evaluating a variable, so objects in the database can be accessed by simply giving their names.
- Keywords
- data
Usage
attach(what, pos = 2L, name = deparse(substitute(what)), warn.conflicts = TRUE)
Arguments
- what
- database. This can be a
data.frame
or alist
or a R data file created withsave
orNULL
or an environment. See also Details. - pos
- integer specifying position in
search()
where to attach. - name
- name to use for the attached database. Names starting with
package:
are reserved forlibrary
. - warn.conflicts
- logical. If
TRUE
, warnings are printed aboutconflicts
from attaching the database, unless that database contains an object.conflicts.OK
. A conflict is a function masking a function, or a non-function masking a non-function.
Details
When evaluating a variable or function name R searches for
that name in the databases listed by search
. The first
name of the appropriate type is used.
By attaching a data frame (or list) to the search path it is possible
to refer to the variables in the data frame by their names alone,
rather than as components of the data frame (e.g., in the example below,
height
rather than women$height
).
By default the database is attached in position 2 in the search path,
immediately after the user's workspace and before all previously
attached packages and previously attached databases. This can be
altered to attach later in the search path with the pos
option,
but you cannot attach at pos = 1
.
The database is not actually attached. Rather, a new environment is
created on the search path and the elements of a list (including
columns of a data frame) or objects in a save file or an environment
are copied into the new environment. If you use
<<-< a=""><-<>
or assign
to assign to an attached
database, you only alter the attached copy, not the original object.
(Normal assignment will place a modified version in the user's
workspace: see the examples.) For this reason attach
can lead
to confusion.
One useful trick is to use what = NULL
(or equivalently a
length-zero list) to create a new environment on the search path into
which objects can be assigned by assign
or
load
or sys.source
.
Names starting "package:"
are reserved for
library
and should not be used by end users. Attached
files are by default given the name file:what
. The
name
argument given for the attached environment will be used
by search
and can be used as the argument to
as.environment
.
There are hooks to attach user-defined table objects of class
"UserDefinedDatabase"
, supported by the Omegahat package
RObjectTables. See http://www.omegahat.net/RObjectTables/.
Value
-
The
environment
is returned invisibly with a
"name"
attribute.
Good practice
attach
has the side effect of altering the search path and this
can easily lead to the wrong object of a particular name being found.
People do often forget to detach
databases. In interactive use, with
is usually preferable to the
use of attach
/detach
, unless what
is a
save()
-produced file in which case
attach()
is a (safety) wrapper for load()
. In programming, functions should not change the search path unless
that is their purpose. Often with
can be used within a
function. If not, good practice is to
- Always use a distinctive
name
argument, and - To immediately follow the
attach
call by anon.exit
call todetach
using the distinctive name.
attach
call
changes the search path.
References
Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole.
See Also
Examples
library(base)
require(utils)
summary(women$height) # refers to variable 'height' in the data frame
attach(women)
summary(height) # The same variable now available by name
height <- height*2.54 # Don't do this. It creates a new variable
# in the user's workspace
find("height")
summary(height) # The new variable in the workspace
rm(height)
summary(height) # The original variable.
height <<- height*25.4 # Change the copy in the attached environment
find("height")
summary(height) # The changed copy
detach("women")
summary(women$height) # unchanged
## Not run: ## create an environment on the search path and populate it
# sys.source("myfuns.R", envir = attach(NULL, name = "myfuns"))
# ## End(Not run)