In omkarakatta/firstpackage: Documents the development of an R package

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)

Creating up an R Package

Install necessary packages.

install.packages(c("devtools", "roxygen2", "testthat", "knitr"))

Configuration

library(devtools)

Create the package in the current working directory. Change the path if necessary within the argument of the function.

create_package("<PKG-NAME>")

To check the validity of PKG-NAME as a name for the package, call available::available("<PKG-NAME>").

Optionally, create a .Rprofile with the following text:

# from file.edit("~/.Rprofile") i.e. user-specific .Rprofile
.libPaths("/Library/Frameworks/R.framework/Versions/3.6/Resources/library") 

# local file
options(
  usethis.full_name = "Jane Doe",
  usethis.description = list(
    `Authors@R` = 'person("Jane", "Doe", email = "[e-mail]", role = c("aut", "cre"), 
    comment = c(ORCID = "YOUR-ORCID-ID"))',
    License = "MIT + file LICENSE",
    Version = "0.0.0.9000"
  ),
  usethis.protocol  = "ssh"  
)

See this section of Efficient R Programming, this post on Quick-R, and this section of R Packages.

use_git()

Make the directory of the package a Git repository.

use_git()

Or, initialize a git repo from the Terminal. Include .Rbuildignore in .gitignore.

Create a GitHub repository and configure as git remote to the local repo. Push all changes to the GitHub repo.

use_readme_rmd()

Create a README.Rmd file using use_readme_rmd(). Then, after editing the resulting README.Rmd, knit to "HTML" in RStudio to create README.md.

Edit the DESCRIPTION file

Create a license

Call use_mit_license("<NAME>").

Create functions

Add R functions to a script. One option is to have a .R file for each function. Alternatively, multiple functions can be defined in a single .R file. Be sure to add the #' @export tag.

Be sure to import functions from other packages in the DESCRIPTION file (as opposed to depend on them). Use the double-colon :: to call functions from other packages.

Add documentation to each function using the Roxygen2 format.

with devtools

The devtools package suggests the following workflow. First, create a script named after the function of interest.

use_r("<FUN>")

Then, write the definition of FUN into the resulting script R/FUN.R. When using functions from another package, call use_package("<EXT-PKG-NAME>") to use the external package of interest. Then use the double-colon approach to call this external function. To avoid the double-colon approach for commonly used functions, write @importFrom <EXT-PACK> <EXT-FUN> in the Roxygen2 documentation of the function. If a package is mentioned in NAMESPACE, then it must be mentioned in the Imports or Depends fields of DESCRIPTION. However, it is common for packages in DESCRIPTION not to be referenced in NAMESPACE.

Using Code > Insert roxygen skeleton in RStudio, edit the template to add documentation. Finally render the documentation with document().

use_testthat()

Create the framework for unit tests with use_testthat(). Then create a test file for the script R/FUN.R with use_test("<FUN>")

Run the tests using test() or more comprehensively via check().

check() & load_all()

All the while, using check() will help ensure everything is running properly. To test FUN in the console or in another script, call load_all(). Ultimately, writing unit tests are better than manually testing in the console.

Data

To make data available to the users, call usethis::use_data(<OBJ>). OBJ is an object that will then be saved as OBJ.Rdata in the folder data/. Likely, this object is the result of cleaning up other data. Call usethis::use_data_raw() and then store the original data file and the code used to produce OBJ inside use_data_raw. Here is the recommended workflow:

usethis::use_data_raw("<OBJ>")
# navigate to data-raw/OBJ.R, write down the code to create OBJ.R, and ensure the following is executed:
usethis::use_data(<OBJ>)

To document OBJ.Rdata, use use_r("<OBJ>") and then paste the Roxygen2 documentation in OBJ.R. Instead of writing a function definition below the documentation, write "OBJ" in the script.

#' @title OBJ
#' @description Dummy Dataset
#' @format A vector of integers
#' \describe{
#'   \item{\code{Time (s)}}{double COLUMN_DESCRIPTION}
#'   \item{\code{Acceleration - x (m/s²)}}{double COLUMN_DESCRIPTION}
#'   \item{\code{Acceleration - y (m/s²)}}{double COLUMN_DESCRIPTION}
#'   \item{\code{Acceleration - z (m/s²)}}{double COLUMN_DESCRIPTION}
#'   \item{\code{Acceleration - resultant (m/s²)}}{double COLUMN_DESCRIPTION}
#'}
#' @source \url{http://somewhere.important.com/}
"OBJ"

install()

At this point, we can call install() so the project is ready to be attached and loaded.

Final check() and install()

Make data available with use_data().

Make vignettes using use_vignette("<TITLE>") and fill out the template vignette.

Resources

• Fong Chun Chan's Blog
• Writing documentation with Roxygen2 by Karl Broman
• R packages by Hadley Wickham and Jennifer Bryan

To-Do

• create vignettes
• install package via github

omkarakatta/firstpackage documentation built on Sept. 8, 2020, 12:09 a.m.