Write your own R package and share it on GitHub

• Collection of code, data, documentation developed by R community
• Addresses particular problem with specialized statistical technique, graphical device, etc.
• Core set of packages come with base R
• >15,000 Additional packages available from CRAN, Bioconductor, Omegahat, GitHub, etc.
• Popular R packages
  • dplyr
  • ggplot2

• Website that hosts software development and version control using Git
• Free basic services
• Truly open source
• “Facebook for programmers”

For yourself

• Save time
  • Keep track of your functions
  • Have all your functions in one place
• Document your work
• For publishing papers
  • Increasingly, (bio)statistical journals ask for R package development of a novel method

For others

• If the package is useful to you, it is also useful to someone else
• Readers of your paper can use the proposed method
• Advance science!

• Reproducibility
• Accessibility
• Collaboration
• Back-up method
• Version-control using Git (more on this later)

• R Studio (https://rstudio.com/)
• devtools & roxygen2 & usethis packages
• Git (install from https://git-scm.com/)
• GitHub account (https://github.com/)
• Rtools package (https://cran.r-project.org/bin/windows/Rtools/)
  • Not necessary if you stick to base R and add-on packages on CRAN
  • Good idea to install it eventually

Some other useful packages

• here
• available

1. Open R Studio
   • New Project > New Directory > R Package > Enter info > Create Project
2. Edit your package
   • Each function should be saved in its own file
   • Write the package description and document functions
   • Include some data
   • Write a vignette
3. Create a new repository in GitHub
   • Repo name \( = \) package name
4. Connect to GitHub
5. Pull + Commit + Push
6. Use/share package with install_github()

There is more than one way!

Some tips

• Make it simple & short
• Make it unique (use available package – see next slide)
• Must start with a letter & cannot end with a period
• Do not use special characters
• Trend towards using all lower case
• Hadley's book has more information

Check to see if the name is unique, especially if you plan to submit your package to CRAN

install.packages("available")
library(available)
available("ayapack", browse = FALSE)

• New Project > New Directory > R Package
  • Enter “Package name”
  • Optional: Select R scripts that include your functions (if you leave it blank, a default function is included)
  • Select a subdirectory where you want to save the package (this location is not too important since the final product will be saved on GitHub)
  • Check “Create a git repository”

• packagename.Rproj: This indicates that the directory is a project
• DESCRIPTION: This is where all the meta-data about your package goes – you can edit this file manually
• NAMESPACE: This file indicates what needs to be exposed to users for your R package – we will recreate this file using document() (see next slide)
• R: This is where all your R code goes for your package
• man: This is where the manuals for your functions will be saved
• Don't worry too much about the rest (.gitignore, .Rbuildingore)

• Next, load the packages

library(devtools)
library(roxygen2)
library(usethis)

• Then, delete the NAMESPACE file
• Document your function by adding roxygen2 comments (see next slide)
  • Comment lines begin with #’
  • Place comment lines directly above the function
  • Place @ tag after #’ to supply a specific section
  • Untagged lines will be used to generate a title, description, and details section (in that order)

#' @title inverse logistic link function
#' @description a function that returns the inverse of the logistic link function
#' @param x numeric vector
#' @return y
#' @author Aya Mitani
#' @examples
#' expit(2)
#' @export

expit <- function(x){
  y <- exp(x) / (1 + exp(x))
  return(y)
}

When you are finished with the comments, use document() to convert roxygen2 comments into documentation

devtools::document()

This will create

• myexpit.Rd inside the man direcotory
  
• NAPESPACE

Both are read only – NEVER edit these files by hand!

View the help file

?myexpit

Your package information

The DESCRIPTION file is pre-generated by roxygen2

Package: ayapack
Type: Package
Title: What the Package Does (Title Case)
Version: 0.1.0
Author: Who wrote it
Maintainer: The package maintainer <yourself@somewhere.net>
Description: More about what it does (maybe more than one line)
    Use four spaces when indenting paragraphs within the Description.
License: What license is it under?
Encoding: UTF-8
LazyData: true
RoxygenNote: 7.1.1

You can edit the DESCRIPTION file by hand

Dependencies

If your package depends on other packages or you want to suggest other packages, then include them in the DESCRIPTION file

For example, if you require survival and suggest ggplot2, then

usethis::use_package("survival")
usethis::use_package("ggplot2", "suggests")

will add survival under Imports and ggplot2 under Suggests

Imports: 
    survival
Suggests: 
    ggplot2

Example data sets are very useful for demonstrating your functions

• Create a subdirectory data/
• Import existing data or generate your own data

# I like to use the here package to locate my files
library(here)
exdata <- read.table(here("exdata.txt"), header = TRUE)
# Alternatively, you can specify the exact location to your file by writing out the full path

• Save with .rda extension in data/

use_data(exdata)

Every data set should come with a description

• Create a .R file and add roxygen2 comments
• Write the name of the data at the end (see next slide)
• Save the file in R/ subdirectory with the name exdata.R
• devtools::document() to convert the comments to documentation
• See the documentation by ?exdata

Quick example

#' Example data
#'
#' Data from a toxicology study blah blah blah
#'
#' @docType data
#' @format A data frame with 1028 rows and 4 variables:
#' \describe{
#'   \item{LitID}{Litter ID}
#'   \item{Dose}{Dose of ethylene glycol (EG) administered}
#'   \item{FetalWt}{Fetal weight}
#'   \item{FetalMal}{Indicator for fetal malformation}
#' }
#' @source https://content.sph.harvard.edu/fitzmaur/ala2e/
#' @references Price, C.J., Kimmel, C.A., Tyl, R.W. and Marr, M.C. (1985).
#' The developmental toxicity of ethylene glycol in rats and mice.
#' Toxicological Applications in Pharmacology, 81, 113-127.
"exdata" 

Vignettes are very popular now – they are like tutorials for your package

Use R Markdown to write your vignette

Resources for writing vignettes

• https://r-pkgs.org/vignettes.html
• https://kbroman.org/pkg_primer/pages/vignettes.html

Example of a vignette

• Source code
• In action

This is easy to do

devtools::check()

Fix any errors that come up and rerun until no errors are detected

You can also perform a spell check by

devtools::spell_check()

• Download Git
  • Set your username in Git
  • Set your commit email address in Git
• Create a GitHub account
  • Create a new repository

Set your username and commit email address in Git

Open Git Bash (in Windows) or Terminal (in Macs) and type

git config --global user.name "My Name"
git config --global user.email "myemail@email.com"

To confirm

git config --global user.name
git config --global user.email

Or use R

library(usethis) 
use_git_config(user.name = "My Name", user.email = "myemail@email.com")

# to confirm, generate a git situation-report, your user name and email should appear under Git config (global)
git_sitrep()

• Repository name should equal the package name
• Make it public
• Don't create a README yet
• Copy the URL of your repository

• Open Terminal in RStudio (Tools > Terminal > New Terminal)

git remote add origin https://github.com/username/reponame.git
git init
git add .
git commit -m "initial commit"
git push -u origin master

• Go to your GitHub Repo page and refresh the browser to see the contents of your package

• Add a README – you can include

  • Name of your package
  • Short description of your package
  • Instructions for installation
  • Quick example
  • References
  • Short vignette

• You now have a package that you can share with others!

Installing your R package from GitHub is easy with devtools

install.packages("devtools")
library(devtools)
devtools::install_github("github_username/yourpackage")
library(yourpackage)

• Once your package is live on GitHub, archive (or even delete) the original project on your machine
• After your initial commit, any updates you make should be done using version control
• I like to create a “Version control” folder on my local machine
• When you want to make any changes, copy the HTTPS from your GitHub Repo page

Open RStudio

• New Project > Version Control > Git
• Paste HTTPS in Repository URL
• Give a name to the project
  • I like to just use the original package name, but you can give it other names, e.g. “yourpackage_update2021”
• Enter the directory where you want to put your project

Make your edits

• Remember to check() before pushing the new edits back onto GitHub

• Book by Hadley Wickham and Jenny Bryan
• Happy Git and GitHub for the useR
• devtools cheatsheet
• Blog post by MZES Social Science Data La
• Tutorial by Karl Broman
• Writing R Extensions