How R Searches and Finds Stuff

布满荆棘的人生 2022-06-17 06:37 104阅读 0赞

http://blog.obeautifulcode.com/R/How-R-Searches-And-Finds-Stuff/

Or…  
How to push oneself down the rabbit hole of environments, namespaces, exports, imports, frames, enclosures, parents, and function evaluation?

## Motivation ##

There are a few reasons to bother reading this post:

1.  Rabbit hole avoidance   
    You have avoided the above mentioned topics thus far, but now it’s time to dive in. Unfortunately you speak English, unlike the R help manuals which speak “Hairy C” (imagine a somewhat hairy native C coder from the 80s who’s really smart but grunts a lot…not the best communicator).
2.  R is acting a fool   
    Your function used to work, now it spits an error. Absolutely nothing about this particular function has changed. You vaguely remember installing a new package, but what does that matter? Unfortunately my friend, it does matter.
3.  R is finding the wrong thing   
    You attached the [matlab package][] and call `sum()` on a numeric matrix. The result is a vector of column sums, not a length 1 numeric. This messes up everything. What were you thinking trying to make R act like Matlab? Matlab is for losers (and rich people).
4.  You want R to [find something else][]   
    You like a package’s plotting function. If you could intercept one call within the function and use your own calculation, it would be perfect. This seems like black magic to you, but something is strange about maintaining a full copy of the function just to apply your little tweak. Welcome to the dark arts.
5.  Package authoring   
    You have authored a package. How does your kid plays with the other kids in the playground?

## Where does R put things? ##

Everything is R lives in an environment. Ultimately, we’re trying to figure out which environment something lives in, and how we get there (or how we got there). An environment, like everything else in R is an object. Objects hold stuff. Environments are specialized, they can only hold two things:

1.  A frame   
    This is just a collection of named objects. What’s a named object? Everything in R is an object, so it can be a function, a numeric, a character, a logical, etc. And these objects have names like myFunction, myNumeric , myCharacter, myLogical. When you type `myVar = "charlie"` at the command prompt you create a character object that holds the string `"charlie"` and you’re calling that object `myVar`. Since everything in R lives in an environment and the frame is the place where an environment holds objects, then the object you just created called `myVar` lives in a frame within some environment.
2.  The environment’s owner aka the enclosing environment.   
    This is just a reference to another environment.

![environment structure][]

As you can see from the visualization above, the chain of enclosing environments stops at a special environment called the Empty Environment. You can access this object by executing `emptyenv()` in R. And given an environment object, you can query the object for the two things that matter: the environment’s owner and the objects in the frame.

### A Fib About Owners and Pointers ###

Before you hit send on that flame mail I acknowledge a technical misdirection that I have and will continue to make. I use the concepts of ownership and containment loosely. I will say own or contain when I really mean pointer. If pointer means nothing to you then skip to the next section.

I will continue to talk about environments as owning objects, particularly functions. In truth functions are instructions stored somewhere in memory, and they are accessed by symbols in lookup tables that, when found, give a pointer to them. The core concepts of this article are agnostic to pointers and understanding pointers is unnecessary to achieve mastery of the search mechanism in R. In fact, R tries really hard to hide pointers. So yes it pains me to be technically imprecise, but I’m trying to keep things simple because most people can understand an ownership relationship and we have a lot of ground to cover.

## Play time with Environments (don’t skip me) ##

# environments are just objects. lets create one. > myEnvironment = new.env() # print it out... > myEnvironment <environment: 0x0000000006ce0920> # every environment (except R_EmptyEnv) has an enclosure. # Who's myEnvironment's enclosure? It's "R_GlobalEnv" - find out using parent.env() > parent.env( myEnvironment ) <environment: R_GlobalEnv> # Who's R_GlobalEnv's enclosing environment? # Its the environment called "package:stats" (in my installation, might be different on yours) > parent.env( parent.env( myEnvironment ) ) <environment: package:stats> attr(,"name") [1] "package:stats" attr(,"path") [1] "C:/R/R-2.14.1/library/stats" # Here's two other ways to ask the same question. # This R_GlobalEnv must be special if it can retrieved using the identifier # .GlobalEnv AND a function globalenv(). We'll discuss R_GlobalEnv later. > parent.env( .GlobalEnv ) <environment: package:stats> attr(,"name") [1] "package:stats" attr(,"path") [1] "C:/R/R-2.14.1/library/stats" > parent.env( globalenv() ) <environment: package:stats> attr(,"name") [1] "package:stats" attr(,"path") [1] "C:/R/R-2.14.1/library/stats" # The empty environment is accessed using emptyenv() > emptyenv() <environment: R_EmptyEnv> # Why does myEnvironment have a funky name 0x0000000006ce0920? # That's just the location of the environment in memory. # We can add a friendly name by assigning a "name" attribute. # Unfortunately R doesn't replace the funky name with the friendly name when printing. # We can use the environmentName() function to verify our cool name > attr( myEnvironment , "name" ) = "Cool Name" > myEnvironment <environment: 0x0000000006ce0920> attr(,"name") [1] "Cool Name" > environmentName( myEnvironment ) [1] "Cool Name" # lets create a numeric object > myValue = 5 # Unless you try hard, when you create an object it is automatically placed in the # "current" or "local" environment, accessible using environment() > environment() <environment: R_GlobalEnv> # And we can query an environment for all objects in the frame using ls(). # Here we verify that objects myEnvironment and myValue are both placed in the local environment, R_GlobalEnv ls( envir = environment() ) [1] "myEnvironment" "myValue" # We can override the default behavior and create an object in an environment other than the local environment. # To do this use the assign() function. Here we create variable "myLogical" inside myEnvironment. # We use ls() to verify that there was nothing in myEnvironment before the assignment, # and again ls() verifies that "myLogical" is inside myEnvironment after the assignment > ls( envir = myEnvironment ) character(0) > assign( "myLogical" , c( FALSE , TRUE ) , envir = myEnvironment ) > ls( envir = myEnvironment ) [1] "myLogical" # We can retrieve any named object from any given environment using the get() function > get( "myLogical" , envir = myEnvironment ) [1] FALSE TRUE # How could I have known that myEnvironment's enclosure would be R_GlobalEnv before I created the object? # Once again, R uses the local environment as the default value. # You can change an environment's enclosure using the replacement form of parent.env(). > myEnvironment2 = new.env() > parent.env( myEnvironment2 ) <environment: R_GlobalEnv> > parent.env( myEnvironment2 ) = myEnvironment > parent.env( myEnvironment2 ) <environment: 0x0000000006ce0920> attr(,"name") [1] "Cool Name" # Here's another way to understand the "current" or "local" environment # We create a function that calls environment() to query for the local environment. # When R executes a function it automatically creates a new environment for that function. # This is useful - variables/objects created inside the function will live in the new local environment. # We call Test() to verify this. We can see that Test() does NOT print R_GlobalEnv. # We didn't created any objects within Test(). If we had, they would live in the "0x0000000006ce9b58" # environment while Test() is running. When the function completes executing, the environment dies. > Test = function() { print( environment() ) } > environment() <environment: R_GlobalEnv> > Test() <environment: 0x0000000006ce9b58> # And why not...who's the enclosing environment? # There's more than meets the eye here. We'll go deeper in a bit... > Test = function() { print( parent.env( environment() ) ) } > Test() <environment: R_GlobalEnv>

## Short Answer: How R Searches and Finds stuff ##

Have you followed along with the code above? It seems that environments are not just static repositories of objects. When R executes an expression, there is always one local or current environment. Maybe its easier to think of this as the active environment, in contrast to the other environments which are inactive. Or perhaps its more intuitive to think of an expression executing “within” a particular environment. The point here is that at any moment R can ask “hey, what’s the local environment.” R asks this questions a lot. In fact, it asks this question every time it needs to find a named object. We saw that R creates a new local environments every time it runs a function. So when we run any decently involved piece of code, functions call other function and environments spawn and die.

Imagine we just freeze the system at any one expression. When R goes searching for the names in that expression, it first looks at the objects within the local environment. If the object is not found by name in that environment, then R searches the enclosing environment of the local environment. If the object is not in the enclosure, then R searches the enclosure’s enclosure, and so on. That’s how R searches and finds stuff; it traverses the enclosing environments and stops at the first environment that contains the named object.

Satisfied? I didn’t think so. Lets roll…

## Map of the World (follow the purple line road) ##

We just said that R searches through the chain of enclosing environments to find named objects. Its sort of like a treasure hunt that is limited to a single direction. What we need for this treasure hunt is a map of the world! ![map of the world][]

This graphic shows the state of all environments when you first startup R. Each box represents a unique environment. The solid purple line represents the enclosing environment relationship. I’ll explain the dotted purple line in a bit. For now, consider it a relationship that’s similar to the enclosing environment.

## The Global Environment ##

I said that R\_GlobalEnv is a special environment and you can see that it is colored green in the map. Green means start. The global environment is precisely the environment that you start at when you launch R. It is your current or local environment when R launches. If you make an assignment at the prompt, the named object is stored in R\_GlobalEnv.

# the ls() function shows us all objects defined in a given environment. # In this case we're using the identifier .GlobalEnv to refer to the global environment # Here we can see that upon startup the global environment contains no objects # but after we assign myVariable, the global environment contains an object with that name > ls( envir = .GlobalEnv ) character(0) > myVariable = 0 > ls( envir = .GlobalEnv ) [1] "myVariable" # be careful with the environment() function. It might seem wrong that this returns NULL # but if you read the documentation you'll see that environment() takes a function as input. # myVariable is not a function, its a numeric. The purpose of environment() is not to tell you # an object's owner. More to come... > environment( myVariable )

## The Search List ##

In R, the “search list” is the chain of enclosing environments starting with R\_GlobalEnv and ending with R\_EmptyEnv. I like to think of it as the main highway on our map. This is the highway that R drives down when we start in R\_GlobalEnv. All roads in our world eventually lead to this highway. You can obtain the search list by typing `search()` at the prompt:

> search() [1] ".GlobalEnv" "package:stats" "package:graphics" "package:utils" "package:datasets" [6] "package:grDevices" "package:methods" "Autoloads" "package:base"

## Package v. Namespace v. Imports Environments ##

If you stare at our map above for enough time you might notice that every R package has 3 associated environments. If you think that this is confusing then you are blessed with common sense. This drove me crazy when I first encountered it. Trust me for now that the only tricky part about this is the naming convention, otherwise this trifecta is useful and well-designed.

![package namespace imports][]

Here’s a breakdown, left to right:

1.  package environment   
    This is where a package’s exported objects go. Simply put, these are the objects that the package author wants you to see. These are most likely functions. Typically a package is published that provides useful functions related to some topic or domain. In traditional Object Oriented Programming (OOP), this is analogous to a “public” class or method. If that means nothing to do you then ignore it.
2.  namespace environment   
    This is where all objects in a package go. This includes objects the package author wants you see. It also includes objects that are not meant to be accessed by the end-user. The latter, the “hidden” objects (they are not really hidden, you can access them if you’d like) facilitate the “visible” ones. For example, a function `HardCalculation()` might offload some complicated text formatting tasks to function `MakeResultsPretty()`. The author doesn’t want you to call `MakeResultsPretty()`, its sole purpose is to format the results that are idiosyncratic to `HardCalculation()`. In OOP this is analogous to a “private” or “internal” class or method.
    
    You might be thinking “wait, so objects the author wants me to see are in BOTH the package environment and the namespace environment?” Yes and No. Yes, both environments have a frame that lists objects of the same name, but no there is not two copies. Both environments have [pointers to the same function][]. If that makes no sense to you then think of it as two copies - it honestly doesn’t matter. This may seem like an odd arrangement (two pointers, two copies - your pick) but its use will become apparent shortly. This is also why there is no easy way to query an object for the environment that owns it. Its possible that two or more environments own the same object.
3.  imports environment   
    This environment contains objects from other packages that are explicitly stated requirements for a package to work properly. Most packages published on CRAN are not islands; they build on functionality provided in other packages. Take [ggplot2][] for example. You can see on the CRAN page in the “Imports” section that it requires `plyr` among other packages. I suggest using the screenshot below since the package could change in a way that breaks my example. The `imports:ggplot2` environment contains all objects in the `plyr`package. ![ggplot2 cran][]

## Imports v Depends ##

You might have been confused seeing a `Depends` and an `Imports` section. If `Imports` states a package’s requirements, then what does `Depends` do? This is a poor naming convention. The `Depends` section also lists packages that ggplot2 requires. The difference between `Imports` and `Depends` is where the requirement is placed on our map of the world. Because our map specifies the path R takes to find objects, there are consequences to specifying a requirement in `Imports` versus `Depends` in terms of how R finds the dependency.

If the package is specified in `Imports`, then the package contents will go into the “imports” environment. In the case of ggplot2, the objects in the `plyr` package will appear in the `imports:ggplot2` environment. Notice also that `plyr` does not have a package environment. Its nicely tucked away inside the environment `imports:ggplot2`. The dotted purple line will be explained later.

![imports depends plyr][]

If a package is specified in `Depends` (i.e. `reshape` package), then the package is loaded as it would be if you called `library()` or `require()` from the R prompt. That is, the package, namespace, and imports environments are created for the dependency and placed on our map. The reshape package is attached before `ggplot2` and the `package:reshape` environment becomes `package:ggplot2`’s enclosing environment.

![imports depends reshape][]

So who cares? Is the choice between Depends and Imports arbitrary? Its not. The `library()` command (or generally attaching a library) places the package environment under `R_Global`. More precisely, the package environment becomes `R_Global`’s enclosing environment.`R_Global`’s old enclosure now encloses the package environment. You can see this in the diagram below where we have loaded the package [reshape2][] which is a re-write/upgrade of the original `reshape` package.

Both `reshape` and `reshape2` contain the function `cast`. Lets say (I’m making this up) that `ggplot2` has a function called `FunctionThatCallsCast()`. As you can guess, this function calls the `cast()` function. Without knowing any details of how R finds stuff, lets just follow the “purple line road”. We travel from to 1 and 2 and find `FunctionThatCallsCast()`. Remember, the package and namespace environments both reference a package’s public-facing functions. We execute that function and now we need to find `cast`. We travel from 3 to 5 searching for `cast`. We find `cast` at 6 and stop. But this is the wrong `cast`. This is `cast` in package `reshape2`, but `ggplot` depends on the `cast` in `reshape`. This could have dire consequences depending on the differences between `cast` in `reshape` and `reshape2`.

![reshape reshape2 cast conflict][]

The better solution would have been to stuff `reshape`’s `cast()` function into `imports:ggplot2` using the `Imports` feature. In that case, we would have travelled from 2 to 3 and stopped. Now you can see why the choice between `Imports` and `Depends` is not arbitrary. With so many packages on CRAN and so many of us working in related disciplines its no surprise that same-named functions appear in multiple packages. `Depends` is less safe. `Depends` makes a package vulnerable to whatever other packages are loaded by the user.

## namespace:base ##

We haven’t mentioned the fact that all `imports:<name>` environments have `namespace:base` as their enclosure. Think of this a freebie for creating a package. Since the base functions are used frequently, they are most likely a dependency for any package (or a package’s imports). Without `namespace:base` where it is, R would have to go hunting quite far to find `package:base`. There’s a big risk that another package has a function of the same name as a base function. A package author cannot know a-prior when you intend to attach her package nor that you have decided to write your own version of a base function. So do as you like, a package author can expect that R will find the base functions immediately after `Imports`. There’s no chance of corruption.

## The Curveball (the dotted purple lines) ##

Functions, like all objects, are housed inside environments. However, functions themselves have a property which is a pointer to the environment in which they should run. When you create a function, that property is automatically set to the environment in which the function was created. So the environment that houses a function and the environment that the function will run in is one and the same.

![environment property][]

What do we mean by “the environment that a function will run in?” We said earlier that executing a function creates a new environment specifically for that function. We also said that all environments have an enclosing environment. So what environment is the enclosure of the function’s new environment? This is what is specified by the function’s environment property. This is “the environment that a function will run in.” Its not necessarily the environment that owns the function. It is controlled by the function’s environment property.

We can get a function object’s environment property using the `environment()` function. For example:

> MyFunction = function() {} > environment( MyFunction ) <environment: R_GlobalEnv>

And when we run `MyFunction()` and R is executing lines of codes inside that function, the environments look like this:

![environment execution][]

By default, R sets a function’s environment property equal to the environment where the function was created (the environment that owns the function). However, its not necessary that a function’s executing environment and the environment that owns the function are one and the same. In fact, we can change the environment to our liking:

# notice how environment(MyFunction) no longer returns R_GlobalEnv > MyFunction = function() { } > newEnvironment = new.env() > environment( MyFunction ) = newEnvironment > environment( MyFunction ) <environment: 0x000000000e895628> # Another way to see a function's environment property is to just print # the function. The environment will appear at the bottom of the printed function > MyFunction function() { } <environment: 0x000000000e895628> # Here we do the same for the standard deviation function > environment( sd ) <environment: namespace:stats> > sd function (x, na.rm = FALSE) { ... (removed for brevity) } <bytecode: 000000000E7F2EA0> <environment: namespace:stats> # Can you figure out what's going on here? # When run, FromLocal's enclosing environment is the MyFunction environment. That's where # FromLocal was created and that's what R does by default. # When R searches for the object "age" within FromLocal it looks to the MyFunction environment, # picks-up age = 22 and adds 1 to that. # - # When run, FromGlobal's enclosing environment is R_GlobalEnv because # we assigned the function's environment property to R_GlobalEnv. # When R searches for "age" within FromGlobal, it looks at the enclosing environment which is # The Global environment, and picks up age = 32 and adds 1 to that. # - # The environment of NoSearch() already has # the age object and does not need to search its enclosing environment(s). > age = 32 > MyFunction = function() + { + age = 22 + FromLocal = function() { print( age + 1 ) } + FromGlobal = function() { print( age + 1 ) } + NoSearch = function() { age = 11; print( age + 1 ) } + environment( FromGlobal ) = .GlobalEnv + FromLocal() + FromGlobal() + NoSearch() + } > MyFunction() [1] 23 [1] 33 [1] 12

This explains the dotted purple lines in our map. If you inspect the environment property of the functions within the `package:<name>`environments you’ll see that they all point to the `namespace:<name> environment`. Check it out:

# get the standard deviation function within package:stats and # inspect the function's environment property. # Notice that it points to the namespace:stats environment > statsPackageEnv = as.environment( "package:stats" ) > sdFunc = get( "sd" , envir = statsPackageEnv ) > environment( sdFunc ) <environment: namespace:stats> > statsNamespaceEnv = environment( sdFunc ) > sdFunc2 = get( "sd" , envir = statsNamespaceEnv ) > environment( sdFunc2 ) <environment: namespace:stats> # An easier way to get a namespace environment > statsNamespaceEnv = asNamespace( "stats" ) > statsNamespaceEnv <environment: namespace:stats>

So in essence, the package environment is just a pass-thru to the namespace environment. The package environment says “I don’t know what to do, ask my functions”. And when we ask the functions they all say “when you execute us create a new environment whose enclosure is the namespace environment.” More precisely, the functions are just offering up their environment property . We might as well make those dotted lines solid:

![map of the world complete][]

Incidentally, this is another explanation for why there’s no easy way to query an object for the environment that owns it. When we are executing in an environment, we are interested in the objects it owns because we might be looking for one of them. When we find a function we need to know which environment to execute it within. But its not important in our workflow to identify an arbitrary object’s owning environment.

If your head is spinning then I encourage you to pause and re-read this entire section. Function execution is the most complex piece of the puzzle.

## Passing Functions ##

Feel free to skip this section

Its because functions have an environment property that they can be passed around. Passing a function to another function is a mind-boggling (albeit powerful) feature. I’m not going to explore this too much. At a high level you can think of it as follows. If a function `FunctionA( someOtherFunction )` takes another function `someOtherFunction` as a parameter then `FunctionA` must have some variability in the way it runs. That variability is governed by the implementation of `someOtherFunction`. When we construct `someOtherFunction`, we expect it to run in a particular way. `someOtherFunction` should have access to the objects in the environment in which it was constructed. That expectation doesn’t change when the function is handed-off to `FunctionA` . But R creates a new environment for `FunctionA`. Thankfully that’s not a problem. When `someOtherFunction` is finally run R looks to the function’s environment property and executes within that environment, not within `FunctionA`’s environment. So the integrity of our expectation is upheld. In fact, `FunctionA` can pass `someOtherFunction` to `FunctionB` which in turn can pass the function to `FunctionC` and it has no consequence on how `someOtherFunction`will run. That’s the magic of a function’s environment property.

## That Creepy Caller ##

The search mechanism does not use the call stack. The call stack is the sequence of function calls that has gotten you to wherever you currently are in the calculation. For example, `FunctionA` calls `FunctionB` which in turn calls `FunctionC`. The call stack just places each of those functions on top of one another in the order in which they were called. Lets say `FunctionC` needs to execute `FunctionD`. The wrong way to think about the search mechanism is to follow the callers. That is, if `FunctionD` is not defined in `FunctionC`’s executing environment, then look at `FunctionB`’s executing environment and if not found there then look at `FunctionA`’s executing environment. The right way to think about the search mechanism is to ask “who owns Function C?” If the owner knows nothing about `FunctionD`, then maybe the owner’s owner does, and so on.

Unfortunately, the call stack is more intuitive than the chain of enclosing environments. Just remember, whenever R is evaluating a statement the system is simultaneously at the top (or bottom if it’s easier to visualize that way) of two important chains of environments. One is the chain of enclosing environments which is involved in the task of scoping (i.e. where to look next for variable names not found in the frame of the current environment). This is the chain we care about. The other chain is the call stack, which is produced by the sequence of function calls. You can ignore this chain. There are scenarios where it’s necessary to look for a variable via the call stack, but to accomplish that you have to use some special functions in R. Those scenarios are beyond the scope of this article.

A word of caution: R (and some R literature) uses the term “parent” in context of both chains. There’s the function `parent.env()` which we already know and `parent.frame()` which is used to interrogate the call stack. This is certainly confusing and its a historic slip-up. The term “parent” should not be used as a substitute for enclosing environments. It should only be used with the call stack.

## Finally, How R searches and finds stuff ##

So, finally, how does R search and find stuff? R just follows the purple line road in our map above. Lets follow along with an example

Lets say we’re looking for function `ggplot`. We start at `R_GlobalEnv`. If `ggplot` is not in the global environment, then it must be in a package. So R travels down the search list looking for `ggplot`. This is simply the chain of enclosing environments starting with `R_Global`. R ultimately find the function in one of the package environments. Although `ggplot` is found within the `package` environment, R executes `ggplot` within the `namespace` environment as described in the prior section. In this case, we’ve found `ggplot` in `package:ggplot2` and we execute the function within `namespace:ggplot2`.

Lets say `ggplot` calls another function `MyFunction`. A few things can happen:

1.  If `MyFunction` is defined within `ggplot`, then we find it immediately since R checks the local environment first. In this case the local environment is the environment created to run `ggplot`
2.  If not found, then R looks to the enclosing environment of `MyFunction`’s executing environment which is `namespace:ggplot2`. If we find `MyFunction` here, then it’s a case of a package function calling another function in the same package.
3.  If `MyFunction` is not in the `namespace:ggplot2`, then R checks the enclosing environment of the namespace environment which is the imports environment. This gives `ggplot` an opportunity to find `MyFunction` within a set of explicitly defined package dependencies. This is like ggplot finding a plyr function in our example above.
4.  If `MyFunction` is not in the imports environment, then we check the enclosing environment of the imports environment which is `namespace:base`. A base function (i.e. sd() for standard deviation) would be found here and the search would be complete.
5.  If `MyFunction` is not found in `namespace:base`, then we are back to the search list. We start by checking `R_GlobalEnv`. Its unlikely that `MyFunction` is in `R_GlobalEnv`. It would be poor practice for a package to expect the user to define some function in the global environment. However, the user could take this as an opportunity to intercept the search by defining her own version of `MyFunction` in the global environment.
6.  If `MyFunction` is within a package that’s a dependency of `ggplot2` and that dependency is specified in` Depends` rather than `Imports`, then the search list is where we would find `MyFunction`. This is like `ggplot` looking for a function in the `reshape` package in our example above. We would hope that no other package has defined the same function and is attached closer to the global environment (as in our `reshape2` example above)

All-in-all you just have to determine what the “current” or “local” environment is and following the enclosing environments (the purple arrows) until you find the object you are looking for. Rinse and repeat.

## Qualitative Comments ##

I believe that the search and find mechanism is an adequate design given that R is an interpreted, weakly typed language that supports attaching multiple packages at-will. If we are executing outside of a package (as in `R_GlobalEnv`) it enables us to find functions inside packages. If we are inside a package it allows the package functions to find the specified dependencies. If we are inside a package or a package’s imports (dependencies), then we have a buffer of base functions before we plunging into the search list. Also, the design ensures that we terminate at `R_EmptyEnv` if a named object cannot be found, no matter where on the map we are.

All of that said, its still complicated. When I’m debugging a search-and-find issue it takes a lot of brainpower to figure out what’s going on. Don’t beat yourself up if the same is happening to you.

## Skip the search-and-find ##

If you know exactly which package contains the object desired then you can reference it directly using the `::` operator. Simply place the package name before the operator and the name of the object after the operator to retrieve it.

# use :: to get sd > stats::sd function (x, na.rm = FALSE) { ... ( omitted for brevity ) } <bytecode: 000000000511D608> <environment: namespace:stats>

If the object is not exported or you are unsure, then you can use the `:::` operator (notice the extra colon).

# use ::: to get Wilks > Wilks Error: object 'Wilks' not found > stats:::Wilks function (eig, q, df.res) { ... ( omitted for brevity ) } <bytecode: 00000000050FE280> <environment: namespace:stats>

This operator searches the namespace environment for the given object (as we discussed, non-exported objects do not appear in the package environment, only in the namespace environment). You can validate that by looking at the definition of `:::` (remember to include the backticks).

# view the ::: operator function > `:::` function (pkg, name) { pkg <- as.character(substitute(pkg)) name <- as.character(substitute(name)) get(name, envir = asNamespace(pkg), inherits = FALSE) } <bytecode: 00000000073BAEA8> <environment: namespace:base>

## Thanks ##

I’d like to thank [Josh O’Brien][Josh O_Brien] who reviewed a draft version of this post and provided solid feedback. His comments and challenges directly improved the quality of this article. In some cases I lifted text verbatim from his emails (with his permission of course). I am grateful to him for being so generous with his time. I’d also like to thank the R community on [StackOverflow][] for being patient with numerous questions that I’ve posted about topics herein discussed. That community continues to be the absolute best way to get answers about R. Finally, I thank John Chambers for writing the R programmer’s must-have book [Software for Data Analysis][].

[matlab package]: http://cran.r-project.org/web/packages/matlab/index.html
[find something else]: http://stackoverflow.com/questions/8204008/redirect-intercept-function-calls-within-a-package-function
[environment structure]: http://blog.obeautifulcode.com/img/how-r-searches-and-finds-stuff/environment-structure.png
[map of the world]: http://blog.obeautifulcode.com/img/how-r-searches-and-finds-stuff/map-of-the-world.png
[package namespace imports]: http://blog.obeautifulcode.com/img/how-r-searches-and-finds-stuff/package-namespace-imports.png
[pointers to the same function]: http://stackoverflow.com/questions/9278715/value-reference-equality-for-same-named-function-in-package-namespace-environmen
[ggplot2]: http://cran.r-project.org/web/packages/ggplot2/index.html
[ggplot2 cran]: http://blog.obeautifulcode.com/img/how-r-searches-and-finds-stuff/ggplot2.png
[imports depends plyr]: http://blog.obeautifulcode.com/img/how-r-searches-and-finds-stuff/imports-depends-plyr.png
[imports depends reshape]: http://blog.obeautifulcode.com/img/how-r-searches-and-finds-stuff/imports-depends-reshape.png
[reshape2]: http://cran.r-project.org/web/packages/reshape2/index.html
[reshape reshape2 cast conflict]: http://blog.obeautifulcode.com/img/how-r-searches-and-finds-stuff/reshape-reshape2-cast-conflict.png
[environment property]: http://blog.obeautifulcode.com/img/how-r-searches-and-finds-stuff/environment-property.png
[environment execution]: http://blog.obeautifulcode.com/img/how-r-searches-and-finds-stuff/environment-execution.png
[map of the world complete]: http://blog.obeautifulcode.com/img/how-r-searches-and-finds-stuff/map-of-the-world-complete.png
[Josh O_Brien]: http://stackexchange.com/users/955440/josh-obrien
[StackOverflow]: http://stackoverflow.com/questions/tagged/r
[Software for Data Analysis]: http://www.amazon.com/Software-Data-Analysis-Programming-Statistics/dp/0387759352