#CRAN packages
install.packages(c("devtools", "roxygen2", "renv"))Contributing to R packages on GitHub
Overview
This document covers our process for contributing to R packages on GitHub. It assumes working knowledge of R and git.
0. Setup
Software
This pipeline should be completed in R and RStudio. You should also install the following packages.
And load them into your current R session.
library(devtools)
library(roxygen2)
library(renv)Example package
In this tutorial, we demonstrate adding and updating a function a fake package called testPackage. This package is available at
1. Copy the package repo
1.1 If you are a member of our organization
As a member of UWISDOM (formerly BIGslu), you may have write privileges to the package repo. If you do, you will create a new repo branch for your edits. Then, clone the repo to your local computer and switch to your branch in your git software of choice.
If you need write privileges, contact Kim.
1.2 If you are an outside contributer
As an outside member, you do not have write privileges to our GitHub repos. Thus, you need to make fork of the package repo e.g. create a copy of the repo under your GitHub account. Then, clone your repo fork to your local computer.
2. Make changes to the repo
2.1 Add a new function
2.1.1 Gather your information
Prior to incorporating your function into an existing package, you must have a working function. This must include:
- R script with the function
- Text describing each parameter, its options, and its default
- Test data, either a minimal reproducible example or using example data
2.1.2. Create a script for your function within the package
Open the Rproject within the package repo. Create a script for your function using usethis functionality. The name of this file must be the same as the name of you function.
use_r("my_fxn")✔ Setting active project to
"/Users/kadm/Documents/GitHub/BIGslu/R_packages/testPackage".
☐ Modify R/my_fxn.R.Copy-paste your function into this script. Do not include any example data, test code, etc. Just the function. For example,
my_fxn <- function(language = "english"){
if(language == "english"){ print("Hello!") }
if(language == "spanish"){ print("Hola!") }
if(language == "french"){ print("Bonjour!") }
}Save the script.
2.1.3 Declare and update packages
Within your function script, you need to explicitly declare every non-base R package function. For example, dplyr::select( ). We do not usually code like this because we have library load packages. So go through your function and add package calls as needed.
If you use a new package, add it to the package dependencies like so.
use_package("PACKAGE_NAME")2.1.4 Create a roxygen header
Place you cursor within your function. Go to the top menu Code > Insert Roxygen skeleton.
You will see a skeleton in your R function.
#' Title
#'
#' @param language
#'
#' @return
#' @export
#'
#' @examplesBased on your function, fill out the title, param, and export options. Parameters should be given in the form @param param_nam Parm class, description. Default. Include any necessary requirements in the description. For example,
#' Print hello in various languages
#'
#' @param language Character string of language to use. Must be lowercase. Default is 'english'
#'
#' @return Character string
#' @export
#'
#' @examples2.1.5 Create examples
Using minimal reproducible data or even better, example data from within the package, write the simplest possible example for your function. Please use full parameter names in examples for clarity. For example,
#' @examples
#' my_fxn(language = "english")If desired, add additional examples to showcase different settings.
2.1.6 Create documentation
Using devtools, load all the functions in the package.
load_all()ℹ Loading testPackageThen, create/update documentation for functions.
document()ℹ Updating testPackage documentation
ℹ Loading testPackage
Writing NAMESPACE2.2 Modify an existing function
2.2.1 Make changes to the function
Open the Rproject within the package repo. Open the script in the R/ directory for the function you want to edit. Make the necessary changes, and be sure to update the roxygen header and examples if parameters are altered.
2.2.2 Declare and update packages
Within the function, you need to explicitly declare every non-base R package function. For example, dplyr::select( ). We do not usually code like this because we have library load packages. So go through your edits and add package calls as needed.
If you use a new package, add it to the package dependencies like so.
use_package("PACKAGE_NAME")2.2.3 Update documenation
Using devtools, load all the functions in the package.
load_all()ℹ Loading testPackageThen, update documentation for functions.
document()ℹ Updating testPackage documentation
ℹ Loading testPackage
Writing NAMESPACE2.2.4 Check dependencies
If your edits impact outputs used in other packages, like kmFit results used in BIGpicture, load that dependent package using library and check that examples for the relevant functions run without error using the new outputs.
2.3 Add example data
2.3.1 Create example data
The usethis package has a number of functions to codify data in packages. To create your example data, run the following function in the R package project.
use_data_raw()This creates/opens data-raw/DATASET.R where you can perform any coding needed to create, modify, and save your example data. Users who install this R package do not have access to this directory, so you can treat it as a contained working space. However, the GitHub repo is PUBLIC so assume anything included here is also PUBLIC. Thus, do not include primary or identifiable patient data in any objects.
2.3.2 Add new example data
Once you have your final example data, end the data-raw/DATASET.R script with the following to save the object to data/. Note that you need to modify the call to include your data object name and run this function for each individual data object to be included.
use_data(example.data, overwrite = TRUE)✔ Adding R to Depends field in DESCRIPTION.
✔ Creating data/.
✔ Saving "example.data" to "data/example.data.rda".
☐ Document your data (see <https://r-pkgs.org/data.html>).2.3.3 Create data documentation
Unfortunately document does not automatically create documentation for data. Instead, create an R script in R/ that is named the same as the data object like R/example.data.R. Fill out the information relevant to your example data. The required pieces include docType, name, keywords, and the data set name at the end. For example,
#' testPackage example data
#'
#' @format A data frame with 3 rows and 2 variables:
#' \describe{
#' \item{x}{integer. Value 1-3}
#' \item{y}{integer. Value 4-6}
#' }
#'
#' @source \url{Add_url_here}
#' @references Add citation here
#' @description A small example data frame
#' @docType data
#' @name example.data
#' @keywords datasets
"example.data"Then run document to create the help page.
load_all()
document()3. Test package build
Once you have completed your additions/edits, run check to build and test the package. In general, it is a good idea to run load_all, document, and check all together to make sure everything is up-to-date before check.
load_all()
document()
check()Your goal it to see no errors, warnings, and comments like so.
── R CMD check results ───────────────────────────────────── testPackage 0.1.0 ────
Duration: 12.8s
0 errors ✔ | 0 warnings ✔ | 0 notes ✔If you have errors, warnings, or notes, see the final section of this document for common fixes.
4. Create a pull request
From your branch or fork, create a pull request to the main branch of the original repo. Tag Kim for review and she will do (or delegate) final checks before merging into the main, public package.
Common check issues
Errors
One or more examples fail
Go to the associated function’s R script. Load all current functions with load_all() and then try running each line of the example until you recapitulate the error. Modify your examples until they work. Note you may need to load packages with library within the examples section if you are using functions outside of base R or the current package.
Warnings
Non-standard license specification
Delete you LICENSE file if it exists. Then, run ONE of the following to add a license correctly.
use_mit_license()
use_gpl3_license()checking dependencies in R code
This warning will list packages not defined as dependencies in your code. Add each as dependency like so.
use_package("PACKAGE_NAME")Notes
no visible binding for global variable
This means you reference a variable or object that is not defined within the function itself. This can cause issues if your local and function environments have objects with the same name. To fix this note, set these variables to NULL at the start of your function.
my_fxn <- function(language = "english"){
SOMETHING <- NULL
...
}You can string together multiple variables like so.
SOMETHING <- SOMETHING_ELSE <- NULLno visible global function definition
This means you use a function that is not defined within the current function’s environment. To fix this note, make sure every time you use a function not in base R, you include the package path. For example,
package::FUNCTION()