{"id":12609,"date":"2020-01-03T11:22:02","date_gmt":"2020-01-03T16:22:02","guid":{"rendered":"https:\/\/rud.is\/b\/?p=12609"},"modified":"2020-01-02T16:49:11","modified_gmt":"2020-01-02T21:49:11","slug":"writing-frictionless-r-package-wrappers-building-a-basic-r-package","status":"publish","type":"post","link":"https:\/\/rud.is\/b\/2020\/01\/03\/writing-frictionless-r-package-wrappers-building-a-basic-r-package\/","title":{"rendered":"Writing Frictionless R Package Wrappers \u2014 Building A Basic R Package"},"content":{"rendered":"

Before we start wrapping foreign language code we need to make sure that basic R packages can be created. If you’ve followed along from the previous post<\/a> you have everything you need to get started here. Just to make sure<\/em>, you should be able to fire up a new RStudio session and execute the following R code and see similar output. If not, you’ll need to go through the steps and resources outlined there before continuing.<\/p>\n

pkgbuild::check_build_tools()\n### Your system is ready to build packages!\n<\/code><\/pre>\n
Also: the {bookdown} version should now always match the blog post (apart from some verbiage changes to denote it’s in a book vs a series of blog posts). You can refer to it at any time via \u2014 https:\/\/rud.is\/books\/writing-frictionless-r-package-wrappers\/<\/a>.<\/p>\n
Configuring {devtools}<\/h3>\n
We’re going to rely on the {devtools} package for many operations and the first thing you should do now is execute help(\"create\", \"devtools\")<\/code> in an RStudio R console to see the package documentation page where you’ll see guidance pointing you to devtools::use_description()<\/code> that lists some R session options()<\/code> that you can set to make your package development life much easier and quicker. Specifically, it lets you know that you can setup your ~\/.Rprofile<\/code> to include the certain options settings which will automatically fill in fields each time you create a new package vs you either specifying these fields manually in the package creation GUI or as parameters to devtools::create()<\/code>.<\/p>\n
A good, minimal setup would be something like:<\/p>\n
options(\n  usethis.description = list(\n    `Authors@R` = 'person(\"Some\", \"One\", email = \"someone@example.com\", role = c(\"aut\", \"cre\"),\n                          comment = c(ORCID = \"YOUR-ORCID-ID\"))',\n    License = \"MIT + file LICENSE\"\n  )\n)\n<\/code><\/pre>\n
NOTE: If you do not have an “ORCID” you really should get one (they’re free!) by heading over to
\n— https:\/\/orcid.org\/<\/a> — and filling in some basic information.<\/p>\n
Take a moment to edit your ~\/.Rprofile<\/code>. If you’re not sure about how to do that there is an excellent chapter in Efficient R Programming1<\/a><\/sup> which walks you through the process.<\/p>\n
Once you’ve added or verified these new options()<\/code> settings, restart your R session.<\/p>\n
Creating A Package<\/h3>\n
We’re almost<\/em> ready to create and build a basic R package. All R packages live in a package directory and I highly suggest creating a packages<\/code> directory right off your home directory (e.g. “~\/packages<\/code>“) or someplace where you’ll be able to keep them all organized and accessible. The rest of these posts will assume you’re using “~\/packages<\/code>” as the<\/p>\n
With {devtools} now pre-configured, use the RStudio R Console pane to execute the following code which should produce similar output and open up a new RStudio session with the new package directory:<\/p>\n
devtools::create(\"~\/packages\/myfirstpackage\") \n## \u2714 Creating '\/Users\/someuser\/packages\/myfirstpackage\/'\n## \u2714 Setting active project to '\/Users\/someuser\/packages\/myfirstpackage'\n## \u2714 Creating 'R\/'\n## \u2714 Writing 'DESCRIPTION'\n## Package: myfirstpackage\n## Title: What the Package Does (One Line, Title Case)\n## Version: 0.0.0.9000\n## Authors@R (parsed):\n##     * Bob Rudis <bob@rud.is> [aut, cre] (<https:\/\/orcid.org\/0000-0001-5670-2640>)\n## Description: What the package does (one paragraph).\n## License: MIT + file LICENSE\n## Encoding: UTF-8\n## LazyData: true\n## \u2714 Writing 'NAMESPACE'\n## \u2714 Writing 'myfirstpackage.Rproj'\n## \u2714 Adding '.Rproj.user' to '.gitignore'\n## \u2714 Adding '^myfirstpackage\\\\.Rproj$', '^\\\\.Rproj\\\\.user$' to '.Rbuildignore'\n## \u2714 Opening '\/Users\/someuser\/packages\/myfirstpackage\/' in new RStudio session\n## \u2714 Setting active project to '<no active project>'\n<\/code><\/pre>\n
The directory structure will look like this:<\/p>\n
.\n\u251c\u2500\u2500 DESCRIPTION\n\u251c\u2500\u2500 NAMESPACE\n\u251c\u2500\u2500 R\/\n\u2514\u2500\u2500 myfirstpackage.Rproj\n<\/code><\/pre>\n
At this point we still do not have a “perfect” R package. To prove this, use the R console to run devtools::check()<\/code> and — after some rather verbose output — you’ll see the following lines at the end:<\/p>\n
> checking DESCRIPTION meta-information ... WARNING\n  Invalid license file pointers: LICENSE\n\n0 errors \u2713 | 1 warning x | 0 notes \u2713\n<\/code><\/pre>\n
Since we’re saying that our package will be using the MIT license, we need to ensure there’s an associated LICENSE<\/code> file which we can do by executing usethis::use_mit_license()<\/code> which will create the necessary files and ensure the License<\/code> field in the DESCRIPTION<\/code> file is formatted properly.<\/p>\n
If you run devtools::check()<\/code> again, now, your final line should report:<\/p>\n
## 0 errors \u2713 | 0 warnings \u2713 | 0 notes \u2713\n<\/code><\/pre>\n
and the package directory tree should look like this:<\/p>\n
\u251c\u2500\u2500 DESCRIPTION\n\u251c\u2500\u2500 LICENSE\n\u251c\u2500\u2500 LICENSE.md\n\u251c\u2500\u2500 NAMESPACE\n\u251c\u2500\u2500 R\/\n\u2514\u2500\u2500 myfirstpackage.Rproj\n<\/code><\/pre>\n
Rounding Out The Corners<\/h3>\n
While we have a minimum viable package there are a few other steps we should take during this setup phase. First we’ll setup our package to use {roxygen2}<\/code>2<\/a><\/sup> for documenting functions, declaring NAMESPACE<\/code> imports, and other helper-features that will be introduced in later posts. We can do this via usethis::use_roxygen_md()<\/code>:<\/p>\n
usethis::use_roxygen_md()\n## \u2714 Setting Roxygen field in DESCRIPTION to 'list(markdown = TRUE)'\n## \u2714 Setting RoxygenNote field in DESCRIPTION to '7.0.2'\n## \u25cf Run `devtools::document()`\n<\/code><\/pre>\n
We won’t run devtools::document()<\/code> just yet<\/em>, though. Before we do that we’ll also create an R file where we can store top-level package introduction\/meta-information:<\/p>\n
usethis::use_package_doc()\n## \u2714 Writing 'R\/myfirstpackage-package.R'\n<\/code><\/pre>\n
Now, our directory tree should look like:<\/p>\n
.\n\u251c\u2500\u2500 DESCRIPTION\n\u251c\u2500\u2500 LICENSE\n\u251c\u2500\u2500 LICENSE.md\n\u251c\u2500\u2500 NAMESPACE\n\u251c\u2500\u2500 R\n\u2502   \u2514\u2500\u2500 myfirstpackage-package.R\n\u2514\u2500\u2500 myfirstpackage.Rproj\n<\/code><\/pre>\n
Now, run devtools::document()<\/code> which will translate the {roxygen2} comments into a properly-formatted R documentation file and regenerate the NAMESPACE<\/code> file (as we’ll be managing package imports and exports via {roxygen2} comments). The directory tree will now look like:<\/p>\n
.\n\u251c\u2500\u2500 DESCRIPTION\n\u251c\u2500\u2500 LICENSE\n\u251c\u2500\u2500 LICENSE.md\n\u251c\u2500\u2500 NAMESPACE\n\u251c\u2500\u2500 R\n\u2502   \u2514\u2500\u2500 myfirstpackage-package.R\n\u251c\u2500\u2500 man\n\u2502   \u2514\u2500\u2500 myfirstpackage-package.Rd\n\u2514\u2500\u2500 myfirstpackage.Rproj\n<\/code><\/pre>\n
and, we can now re-run devtools::check()<\/code> to make sure we have the three “0’s” we’re aiming for each time we check our package for errors.<\/p>\n
Passing The Test<\/h3>\n
We’re going to want to write and use tests to ensure our package works properly. There are many R package testing frameworks available. To ease the introduction into this process, we’ll use one of the frameworks that came along for the ride when you installed the various packages outlined in the previous post: {testthat}3<\/a><\/sup>. Setting up {testthat} is also pretty painless thanks to the {usethis} package we’ve been taking advantage of quite a bit so far. We’ll create the {testthat} overall infrastructure then add a placeholder test script since devtools::check()<\/code> will complain about no tests being available if we do not have at least a single script it can execute during the test phase of the package checking process.<\/p>\n
usethis::use_testthat()\n## \u2714 Adding 'testthat' to Suggests field in DESCRIPTION\n## \u2714 Creating 'tests\/testthat\/'\n## \u2714 Writing 'tests\/testthat.R'\n## \u25cf Call `use_test()` to initialize a basic test file and open it for editing.\n\nusethis::use_test(\"placeholder\")\n## \u2714 Increasing 'testthat' version to '>= 2.1.0' in DESCRIPTION\n## \u2714 Writing 'tests\/testthat\/test-placeholder.R'\n## \u25cf Modify 'tests\/testthat\/test-placeholder.R'\n<\/code><\/pre>\n
The directory tree will now look like this:<\/p>\n
.\n\u251c\u2500\u2500 DESCRIPTION\n\u251c\u2500\u2500 LICENSE\n\u251c\u2500\u2500 LICENSE.md\n\u251c\u2500\u2500 NAMESPACE\n\u251c\u2500\u2500 R\n\u2502   \u2514\u2500\u2500 myfirstpackage-package.R\n\u251c\u2500\u2500 man\n\u2502   \u2514\u2500\u2500 myfirstpackage-package.Rd\n\u251c\u2500\u2500 myfirstpackage.Rproj\n\u2514\u2500\u2500 tests\n    \u251c\u2500\u2500 testthat\n    \u2502   \u2514\u2500\u2500 test-placeholder.R\n    \u2514\u2500\u2500 testthat.R\n<\/code><\/pre>\n
Run devtools::check()<\/code> one more time to make sure we’ve got those precious 3 “0’s” one last time.<\/p>\n
Getting Things Under Control<\/h3>\n
We’re almost<\/em> done! One final step is to turn this directory into a git-managed directory so we can work a bit more safely and eventually share our development work with a broader audience. Provided you followed the outline in the previous post, setting up git is as straightforward as one {usethis} function call:<\/p>\n
usethis::use_git()\n## \u2714 Setting active project to '\/Users\/someuser\/packages\/myfirstpackage'\n## \u2714 Initialising Git repo\n## \u2714 Adding '.Rhistory', '.RData' to '.gitignore'\n## There are 10 uncommitted files:\n## * '.gitignore'\n## * '.Rbuildignore'\n## * 'DESCRIPTION'\n## * 'LICENSE'\n## * 'LICENSE.md'\n## * 'man\/'\n## * 'myfirstpackage.Rproj'\n## * 'NAMESPACE'\n## * 'R\/'\n## * 'tests\/'\n## Is it ok to commit them?\n## \n## 1: For sure\n## 2: Negative\n## 3: Not now\n## \n## Selection: 1\n## \u2714 Adding files\n## \u2714 Commit with message 'Initial commit'\n## \u25cf A restart of RStudio is required to activate the Git pane\n## Restart now?\n## \n## 1: Negative\n## 2: Not now\n## 3: Yup\n## \n## Selection: 3\n<\/code><\/pre>\n
RStudio should have been restarted (so it can add a “Git” pane in case you want to use the GUI to manage git) and the directory tree will now have a .git\/<\/code> subdirectory that you should (almost) never touch by hand.<\/p>\n
The last thing to do is to “vaccinate” your git setup so you don’t leak sensitive or unnecessary files when you (eventually) share your creation with the world:<\/p>\n
usethis::git_vaccinate()\n## \u2714 Adding '.Rproj.user', '.Rhistory', '.Rdata' to '\/Users\/someuser\/.gitignore'\n<\/code><\/pre>\n
We now have a basic, working R package that is devoid of any real functionality other than that of getting us familiar with the package setup and validation processes. We’ll be building upon this experience in most of the coming posts.<\/p>\n
Quick Reference<\/h3>\n
After ensuring you’ve got the recommended options()<\/code> in place, here are the steps to setup a new package:<\/p>\n
# in any RStudio R Console session\ndevtools::create(\"~\/packages\/THE-PACKAGE-NAME\")\n\n# in the newly created package RStudio R Console session:\nusethis::use_mit_license()       # need a LICENSE file\nusethis::use_roxygen_md()        # use {roxygen2} for documentation and configuration\nusethis::use_package_doc()       # setup a package-level manual page\nusethis::use_testthat()          # setup testing infrastructure\nusethis::use_test(\"placeholder\") # setup a placeholder test file\ndevtools::document()             # Let {roxygen2} create NAMESPACE entries, build manual pages (and, more later on)\ndevtools::check()                # looking for the three \"0's\" that tell us we're ready to roll!\nusethis::use_git()               # put the directory under git version control\nusethis::git_vaccinate()         # Prevent leaking credentials and other unnecessary filesystem cruft\n<\/code><\/pre>\n
Rather than re-type devtools::document()<\/code> (et al) whenever you need to run {roxygen2} or build\/check a package you can use RStudio keyboard shortcuts that are designed to seamlessly integrate with the {devtools} ecosystem:<\/p>\n\n\n\n\n\n\n\n\n\n\n
Operation<\/th>\nWindows & Linux<\/th>\nMac<\/th>\n{devtools} equivalent<\/th>\n<\/tr>\n<\/thead>\n
Install and Restart<\/td>\nCtrl+Shift+B<\/td>\nCmd+Shift+B<\/td>\ndevtools::install()<\/td>\n<\/tr>\n
Load All (devtools)<\/td>\nCtrl+Shift+L<\/td>\nCmd+Shift+L<\/td>\ndevtools::load_all()<\/td>\n<\/tr>\n
Test Package (Desktop)<\/td>\nCtrl+Shift+T<\/td>\nCmd+Shift+T<\/td>\ndevtools::test()<\/td>\n<\/tr>\n
Test Package (Web)<\/td>\nCtrl+Alt+F7<\/td>\nCmd+Alt+F7<\/td>\ndevtools::test()<\/td>\n<\/tr>\n
Check Package<\/td>\nCtrl+Shift+E<\/td>\nCmd+Shift+E<\/td>\ndevtools::check()<\/td>\n<\/tr>\n
Document Package<\/td>\nCtrl+Shift+D<\/td>\nCmd+Shift+D<\/td>\ndevtools::document()<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
We’ll refer to these operations as “install” (or “build”), “load all”, “test”, “check”, and “document” from now on so you can choose to use the console or the shortcuts as you prefer.<\/p>\n
Exercises<\/h3>\n
Our package may be kinda, well, useless<\/em> for the moment but that doesn’t mean you can’t show it some love and get some practice in at the same time while things are still relatively straightforward.<\/p>\n