-
Notifications
You must be signed in to change notification settings - Fork 14
/
README.Rmd
213 lines (160 loc) · 8.48 KB
/
README.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
---
output: github_document
---
# import <a href="https://import.rticulate.org"><img src="man/figures/logo.png" align="right" height="138" /></a>
<!-- badges: start -->
[](https://CRAN.R-project.org/package=import)
[ `-success)](https://github.com/rticulate/import)
[](https://github.com/rticulate/import/actions)
<!-- badges: end -->
# An Import Mechanism For R
The import package is intended to simplify the way in which functions from external
packages or modules are made available for use in R scripts. Learn more on
the [package website](https://import.rticulate.org/), by reading
[`vignette("import")`](https://import.rticulate.org/articles/import.html),
or using the help (`?import::from`).
## Introduction
The typical way of using functionality exposed by a package in R scripts is to
load (and attach) the entire package with `library()` (or `require()`). This can
have the **undesirable effect of masking objects** in the user's search path
and can also make it difficult and **confusing to identify** what functionality
comes from which package when using several `library` statements.
The `import` package provides a simple alternative, allowing the user specify in
a concise way exactly which objects. For example, the `Hmisc` package exposes over
four hundred functions. Instead of exposing all of those functions, someone who only needs
access to, say the `impute()` and the `nomiss()` functions, can import those functions only:
```R
import::from(Hmisc, impute, nomiss)
```
For more on the motivation behind the package, see
[vignette("import")](https://import.rticulate.org/articles/import.html)
## Installation
To install `import` from CRAN:
```R
install.packages("import")
```
You can also install the development version of `import` from GitHub using `devtools`:
```R
devtools::install_github("rticulate/import")
```
## Usage
### Importing functions from R packages
The most basic use case is to import a few functions from package
(here the `psych` package):
```R
import::from(psych, geometric.mean, harmonic.mean)
geometric.mean(trees$Volume)
```
If one of the function names conflicts with an existing function (such as `filter`
from the `dplyr` package) it is simple to rename it:
```R
import::from(dplyr, select, arrange, keep_when = filter)
keep_when(mtcars, hp>250)
```
Use `.all=TRUE` to import all functions from a package. If you want to rename one
of them, you can still do that:
```R
import::from(dplyr, keep_when = filter, .all=TRUE)
```
To omit a function from the import, use `.except` (which takes a character vector):
```R
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 still override this in exceptional cases,
but you seldom need to.
These and other examples are discussed in more detail in the
[Importing from Packages](https://import.rticulate.org/articles/import.html#importing-from-packages) section of the
package vignette.
### Importing Functions from "Module" Scripts
The `import` package allows R files to be used as "modules" from which functions are loaded.
For example, the file
[sequence_module.R](https://raw.githubusercontent.com/rticulate/import/master/man/examples/sequence_module.R)
contains several functions calculating terms of mathematical sequences. It is
possible to import from such files, just as one imports from packages:
```R
import::from(sequence_module.R, fibonacci, square, triangular)
```
Renaming, as well as the `.all` and `.except` parameters, work in the same way as for packages:
```R
import::from(sequence_module.R, fib=fibonacci, .except="square")
```
These and other examples are discussed in more detail in the
[Importing from Modules](https://import.rticulate.org/articles/import.html#importing-functions-from-module-scripts)
section of the package vignette.
### Choosing where import looks for packages or modules
The `import` package will by default use the current set of library paths, i.e.
the result of `.libPaths()`. It is, however, possible to specify a different set
of library paths using the `.library` argument in any of the `import` functions,
for example to import packages installed in a custom location, or to remove any
ambiguity as to where imports come from.
Note that in versions up to and including `1.3.0` this defaulted to use only the
*first* entry in the library paths, i.e. `.library=.libPaths()[1L]`. We believe
the new default is applicable in a broader set of circumstances, but if this
change causes any issues, we would very much appreciate hearing about it.
When importing from a module (.R file), the directory where `import` looks for
the module script can be specified with the with `.directory` parameter.
The default is `.` (the current working directory).
### Choosing where the imported functions are placed
By default, imported objects are placed in a separate entity in the search
path called "imports". One can also specify which names to use in the search
path and use several to group imports:
```R
import::from(magrittr, "%>%", "%$%", .into = "operators")
import::from(dplyr, arrange, .into = "datatools")
```
If using custom search path entities actively, one might prefer the
alternative syntax (which does the same but reverses the argument order):
```R
import::into("operators", "%>%", "%$%", .from = magrittr)
import::into("datatools", arrange, .from = dplyr)
```
If it is desired to place imported objects in the current environment,
use `import::here()`:
### More advanced usage
The `import` package is designed to be simple to use for basic cases, so it uses
symbolic evaluation to allow the names of packages, modules and functions to be
entered without quotes (except for operators, such as `"%>%"` which must be quoted).
However, this means that it calling a variable containing the name of a module, or a
vector of functions to import, will not work. For this use case, you can use the
`.character_only` parameter:
```R
module_name <- "../utils/my_module.R"
# Will not work (import will look for a package called "module_name")
import::from(module_name, foo, bar)
# This will correctly import the foo() and bar() functions from "../utils/my_module.R"
import::from(module_name, foo, bar, .character_only=TRUE)
```
The `.character_only` parameter is covered in more detail in the
[Advanced Usage](https://import.rticulate.org/articles/import.html#advanced-usage) section of the package vignette,
which also describes how you can import from module scripts stored online with the
help of the `pins` package, or achieve python-like imports with the help of `{}`
notation for environments in the `.into` parameter.
# Contributing
Contributions to this project are welcome. Please start by opening an issue or
discussion thread. New features are added conservatively based on supply (is
anyone willing to contribute an implementation of the feature?), demand (how many
people seem to need a new feature?), and last, but not least, by whether a
feature can be implemented without breaking backwards compatibility.
* Created and authored by [@smbache](https://github.com/smbache)
* Currently maintained by [@torfason](https://github.com/torfason)
* Code contributions by
[@awong234](https://github.com/awong234),
[@brshallo](https://github.com/brshallo),
[@flying-sheep](https://github.com/flying-sheep),
[@hutch3232](https://github.com/hutch3232),
[@J-Moravec](https://github.com/J-Moravec),
[@klmr](https://github.com/klmr),
[@mschilli87](https://github.com/mschilli87),
[@olivroy](https://github.com/olivroy)
*(Did we forget to add you? If so, please let us know!)*
# See also:
* Some of the use cases for `import` can now be handled directly in base R using the
new `exclude` and `include.only` arguments of `library()` and `require()`
* For an interesting but slightly different idea of Python-like modules for R, see the
[box](https://klmr.me/box/) package by [@klmr](https://github.com/klmr) (previously
called [modules](https://github.com/klmr/modules)).
* Another approach, focused on treating the use of functions with naming conflicts as
explicit errors is the [conflicted](https://github.com/r-lib/conflicted)
package by [@hadley](https://github.com/hadley).