Importing from Packages

The most basic use case is to import a few functions from package (here the psych package):

import::from(psych, geometric.mean, harmonic.mean)
geometric.mean(trees$Volume)

The imported objects are placed in a separate entity in the search path which by default is named “imports”. It is therefore also easy to get rid of them again with detach("imports"). The main point is that it is clear which functions will be used and where they come from. It’s noteworthy that there is nothing special going on: the import::from function is only a convenient wrapper around getExportedValue (as is :: itself) and assign.

The import package itself should not to be attached (don’t include it via library, you will get a warning). Rather, it is designed to be expressive when using the colon syntax. To import non-exported objects one must use triple-colon syntax: import:::from(pkg, obj). If any of the import functions are called regularly, i.e. without preceding import:: or import:::, an error is raised. If import is attached, a startup message will inform that import should not be attached.

If one of the function names conflicts with an existing function (such as filter from the dplyr package) it is simple to rename it:

import::from(dplyr, select, arrange, keep_when = filter)
keep_when(mtcars, hp>250)

This does pretty much what it says: three functions are imported from dplyr, two of which will keep their original name, and one which is renamed, e.g. to avoid name clash with stats::filter.

You can use .all=TRUE to import all functions from a package, but rename one of them:

import::from(dplyr, keep_when = filter, .all=TRUE)

To omit a function from the import, use .except (which takes a character vector):

import::from(dplyr, .except=c("filter", "lag"))

Note that import tries to be smart about this and assumes that if you are using the .except parameter, you probably want to import everything you are not explicitly omitting, and sets the .all parameter to TRUE. You can override this in exceptional cases, but you seldom need to.

Finally, a more complex example, combining a few different import statements:

import::from(magrittr, "%>%")
import::from(dplyr, starwars, select, mutate, keep_when = filter)
import::from(tidyr, unnest)
import::from(broom, tidy)

ready_data <-
  starwars %>% 
  keep_when(mass < 100) %>% 
  select(name, height, mass, films) %>%
  unnest(films) %>%
  mutate( log_mass = log(mass), films=factor(films))

linear_model <- 
  lm(log_mass ~ height + films, data = ready_data) %>% 
  tidy

In the above, it is clear which package provides which functions (one could e.g. otherwise be tempted to think that tidy belonged to tidyr). Note that ordering is irrelevant, even if tidyr at some point exposes a function tidy after an update, as import is explicit about importing.

It also shows that one can import multiple objects in a single statement, and even rename objects if desired; for example, in the above one can imagine that filter from stats is needed later on, and so dplyr’s filter is renamed to avoid confusion. Sometimes, it is not at all clear what purpose a package has; e.g. the name magrittr does not immediately reveal that it’s main purpose is to provide the pipe operator, %>%.

import::from(sequence_module.R, fibonacci, square, triangular)

import::from(sequence_module.R, fib=fibonacci, .except="square")

## Do not use library() inside a module. This results in a warning, 
## and functions relying on ggplot2 will not work.
#library(ggplot2)

## This is also not recommended, because it is not clear wether recursively 
## imported functions should be available after the module is imported
#import::here(qplot, .from = ggplot2)

## This is the recommended way to recursively import functions on which
## module functions depend. The qplot function will be available to 
## module functions, but will not itself be available after import
import::here(qplot, .from = ggplot2)

## Note this operator overload is not something you want to `source`!
`+` <- function(e1, e2)
  paste(e1, e2)

## Some function relying on the above overload:
a <- function(s1, s2)
  s1 + rep(s2, 3)

## Another value.
b <- head(iris, 10)

## A value created using a recursively imported function
p <- qplot(Sepal.Length, Sepal.Width, data = iris, color = Species)

## A function relying on a function exposed through attachment:
plot_it <- function()
  qplot(Sepal.Length, Sepal.Width, data = iris, color = Species)

import::from(some_module.R, a, b, p, plot_it)

## Works:
a("cool", "import")

## The `+` is not affecting anything here, so this won't work:
# "cool" + "import"

# Works:
b
p
plot_it()

# File: foo.R
# Desc: Functionality related to foos.
# Imports from other_resources.R
# When recursively importing from another module or package for use by 
# your module functions, you should always use import::here() rather 
# than import::from() or library()
import::here(fun_a, fun_b, .from = "other_resources.R")

internal_fun <- function(...) ...

fun_c <- function(...) 
{
  ...
  a <- fun_a(...)
  i <- internal_fun(...)
  ...
}

fun_d <- function(...) ...

# File: bar.R
# Desc: Functionality related to bars. 
# Imports from foo.R
import::here(fun_c, .from = "foo.R")
...

import::from(magrittr, "%>%", "%$%", .into = "operators")
import::from(dplyr, arrange, .into = "datatools")
import::from(psych, describe, .into=month.name[1]) # Uses env: "January"

import::into("operators", "%>%", "%$%", .from = magrittr)
import::into("datatools", arrange, .from = dplyr)
import::into(month.name[1], describe, .from=psych)

import::here("%>%", "%$%", .from = magrittr)
import::here(arrange, .from = dplyr)

# Import into the local environment
import::into(environment(), "%>%", .from = magrittr)

# Import into the global environment, curlies are optional
import::into({.GlobalEnv}, "%>%", "%$%", .from = magrittr)

# Import into a new environment, mainly useful for python-style imports
# (see below)
x = import::into(new.env(), "%<>%", .from = magrittr)

Advanced usage and the .character_only parameter

The import package uses non-standard evaluation (NSE) on the .from and ... parameters, allowing the names of packages and functions to be listed without quoting them. This makes some common use-cases very straightforward, but can get in the way of more programmatic usages.

This is where the .character_only parameter comes in handy. By setting .character_only=TRUE, the non-standard evaluation of the .from and the ... parameters is disabled. Instead, the parameters are processed as character vectors containing the relevant values.

(Previously, NSE was also applied to the .into parameter, but as of version 1.3.0 this is no longer the case, and all parameters except .from and ... are always evaluated in a standard way.)

It is useful to examine some examples of how specifying .character_only=TRUE can be helpful.

Programmatic selection of objects to import

It is not always know in advance which objects to import from a given package. For example, assume we have a list of objects from the broom package that we need to import, we can do it as follows:

objects <- c("tidy", "glance", "augment")
import::from("broom", objects, .character_only=TRUE)

This will import the three functions specified in the objects vector. It is worth noting that because .character_only disables non-standard evaluation on all parameters, the name of the package must now be quoted.

One common use case is when one wants to import all objects except one or a few, because of conflicts with other packages. Should one, for example, want to use the stats versions of the filter() and lag() functions, but import all the other functions in the dplyr package, one could do it like this:

objects <- setdiff(getNamespaceExports("dplyr"), c("filter","lag"))
import::from("dplyr", objects, .character_only=TRUE)

Programmatic selection of module location

The same approach can be used when the directory of the source file for a module is not known in advance. This can be useful when the original source file is not always run with the original working directory, but one still does not want to specify a hard-coded absolute path, but to determine it at run time:

mymodule <- file.path(mypath, "module.R")
import::from(mymodule, "myfunction", .character_only=TRUE)

Again, note that now the name of the function must be quoted because non-standard evaluation is disabled on all parameters.

The here package is useful in many circumstances like this; it allows the setting of a “root” directory for a project and by using the here::here() function to figure out the correct directory, regardless of the working directory.

import::from(here::here("src/utils/module.R")), "myfunction", .character_only=TRUE)

Alternatively, if the file name is always the same and it is only the directory that differs, you could use the .directory parameter, which always expects standard evaluation arguments.

import::from(module.R, "myfunction", here::here("src/utils"))

Note that here::here() has no relation to import::here() despite the similarity in names.

Importing from a URL

Another case where .character_only comes in handy is when one wants to import some functions from a URL. While import does not allow direct importing from a URL (because of difficult questions about when a URL target has changes, whether to download a file and other things), it easy to achieve the desired result by using the pins package (whose main purpose is to resolve such difficult questions). A simple example follows, which directly imports the myfunc() function, which is defined in the plusone_module.R:

url <- "https://raw.githubusercontent.com/rticulate/import/master/man/examples/plusone_module.R"
import::from(pins::pin(url), "myfunc", .character_only=TRUE)
myfunc(3)
#> [1] 4

Python-like imports

A frequent pattern in python imports packages under an alias; all subsequent use of the imported objects then explicitly includes the alias:

import pandas as pd
import numpy as np
import math as m

print(m.pi)
print(m.e)

In order to achieve this functionality with the import package, use .into={new.env()} which assign to a new environment without attaching it. import::from() returns this environment, so it can be assigned to a variable:

# Import into a new namespace, use $ to access
td <- import::from(tidyr, spread, pivot_wider, .into={new.env()})
dp <- import::from(dplyr, .all=TRUE, .into={new.env()})
dp$select(head(cars),dist)
#>   dist
#> 1    2
#> 2   10
#> 3    4
#> 4   22
#> 5   16
#> 6   10

# Note that functions are not visible without dp$ prefix
select(head(cars),dist)
#> Error in select(head(cars), dist): could not find function "select"

Importing S3 methods

S3 methods work well in local context, but when the method is called from a different environment, it must be registered (in packages, this is done in the NAMESPACE file). import can now register methods of form generic.class or generic.class.name automatically using the new .S3 argument. By specifying .S3=TRUE, import will automatically detect methods for existing or new generics. No need to export and/or register them manually!

Consider following script foo.r with a generic and two methods:

# foo.r
# functions with great foonctionality
foo = function(x){
  UseMethod("foo", x)
}

foo.numeric <- function(x){
  x + 1
}

foo.character <- function(x){
  paste0("_", x, "_")
}

Now, all we need is to import the foo generic:

import::from("foo.r", foo, .S3=TRUE)

foo(0) # 1
foo("bar") # _bar_

This is an experimental feature. We think it should work well and you are encouraged to use it and report back – but the syntax and semantics may change in the future to improve the feature.