Attach Set of R Objects to Search Path

Description

The database is attached to theR search path. This means that thedatabase is searched byR when evaluating a variable, so objects inthe database can be accessed by simply giving their names.

Usage

attach(what, pos = 2L, name = deparse1(substitute(what), backtick=FALSE),       warn.conflicts = TRUE)

Arguments

Details

When evaluating a variable or function nameR searches forthat name in the databases listed bysearch. The firstname of the appropriate type is used.

By attaching a data frame (or list) to the search path it is possibleto 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 thanwomen$height).

By default the database is attached in position 2 in the search path,immediately after the user's workspace and before all previouslyattached packages and previously attached databases. This can bealtered to attach later in the search path with thepos option,but you cannot attach atpos = 1.

The database is not actually attached. Rather, a new environment iscreated on the search path and the elements of a list (includingcolumns of a data frame) or objects in a save file or an environmentarecopied into the new environment. If you use<<- orassign to assign to an attacheddatabase, you only alter the attached copy, not the original object.(Normal assignment will place a modified version in the user'sworkspace: see the examples.) For this reasonattach can leadto confusion.

One useful ‘trick’ is to usewhat = NULL (or equivalently alength-zero list) to create a new environment on the search path intowhich objects can be assigned byassign orload orsys.source.

Names starting"package:" are reserved forlibrary and should not be used by end users. Attachedfiles are by default given the namefile:what. Thename argument given for the attached environment will be usedbysearch and can be used as the argument toas.environment.

Value

Theenvironment is returned invisibly with a"name" attribute.

Good practice

attach has the side effect of altering the search path and thiscan easily lead to the wrong object of a particular name being found.People do often forget todetach databases.

In interactive use,with is usually preferable to theuse ofattach/detach, unlesswhat is asave()-produced file in which caseattach() is a (safety) wrapper forload().

In programming, functions should not change the search path unlessthat is their purpose. Oftenwith can be used within afunction. If not, good practice is to

• Always use a distinctivename argument, and

• To immediately follow theattach call by anon.exit call todetach using the distinctive name.

This ensures that the search path is left unchanged even if thefunction is interrupted or if code after theattach callchanges the search path.

References

Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988)The New S Language.Wadsworth & Brooks/Cole.

See Also

library,detach,search,objects,environment,with.

Examples

require(utils)summary(women$height)   # refers to variable 'height' in the data frameattach(women)summary(height)         # The same variable now available by nameheight <- height*2.54   # Don't do this. It creates a new variable                        # in the user's workspacefind("height")summary(height)         # The new variable in the workspacerm(height)summary(height)         # The original variable.height <<- height*25.4  # Change the copy in the attached environmentfind("height")summary(height)         # The changed copydetach("women")summary(women$height)   # unchanged## Not run: ## create an environment on the search path and populate itsys.source("myfuns.R", envir = attach(NULL, name = "myfuns"))## End(Not run)