Ajshen at 03:13, 29 June 2026

2026-06-29T03:13:41Z

← Older revision		Revision as of 03:13, 29 June 2026
Line 1:		Line 1:

			[[Category:Package Development and Distribution]]

	This wiki presents a motivational example of a lot of properties of R packages and how to use them. Please see [[packages motivation]] for motivation about why you should utilize the package framework while doing research. The material in this page captures thoughts from lots of people and is a rewriting of a lecture Ben LeRoy presented while teaching 36-350 in the summer of 2019. Additionally, there are a lot of useful resources on the web to help you make an <code>R</code> package including:		This wiki presents a motivational example of a lot of properties of R packages and how to use them. Please see [[packages motivation]] for motivation about why you should utilize the package framework while doing research. The material in this page captures thoughts from lots of people and is a rewriting of a lecture Ben LeRoy presented while teaching 36-350 in the summer of 2019. Additionally, there are a lot of useful resources on the web to help you make an <code>R</code> package including:

Skipper at 01:49, 24 May 2024

2024-05-24T01:49:42Z

← Older revision		Revision as of 01:49, 24 May 2024
Line 294:		Line 294:
	and R will run all your associated test, and will return output like seen in the following image:		and R will run all your associated test, and will return output like seen in the following image:

	[[File:~~devtool_test_example~~.png\|~~frameless~~\|~~600px~~\|~~alt=output of testthat~~\|output of testthat]]		[[File:Devtool test example.png\|600px\|frame\|left\|output of testthat]]
	</li>		</li>
	</ol>		</ol>

Skipper at 01:48, 24 May 2024

2024-05-24T01:48:06Z

← Older revision		Revision as of 01:48, 24 May 2024
Line 73:		Line 73:
	and anything else you included from intializing your git repo (<code>.gitignore</code>, <code>LICENSE</code>, etc)		and anything else you included from intializing your git repo (<code>.gitignore</code>, <code>LICENSE</code>, etc)

	[[File:~~Tartan_folder~~.png\|frameless\|~~600px\|alt=initial directory items~~\|initial directory items]]		[[File:1200px-Tartan folder.png\|600px\|frameless\|left\|initial directory items]]

	==== Description file meta-data ====		==== Description file meta-data ====
Line 79:		Line 79:
	The first thing you should do is update a little bit of the meta-data in the <code>DESCRIPTION</code> file, an example of which is seen below. You don’t need to add lots, but you’ll probably want to at least add your name and a title.		The first thing you should do is update a little bit of the meta-data in the <code>DESCRIPTION</code> file, an example of which is seen below. You don’t need to add lots, but you’ll probably want to at least add your name and a title.

	[[File:~~tartan_description~~.png\|frameless\|~~600px\|alt=initialized description file~~\|initialized description file]]		[[File:Tartan description.png\|600px\|frameless\|left\|initialized description file]]

	=== Step 2: Writing a function ===		=== Step 2: Writing a function ===
Line 205:		Line 205:
	<syntaxhighlight lang="r">devtools::load_all()		<syntaxhighlight lang="r">devtools::load_all()
	?call_scotty_demo</syntaxhighlight>		?call_scotty_demo</syntaxhighlight>
	[[File:~~call_scotty_demo_doc~~.png\|frameless\|~~600px\|alt=example of help file~~\|example of help file]]		[[File:Call scotty demo doc.png\|600px\|frameless\|left\|example of help file]]

	=== Step 4: Testing ===		=== Step 4: Testing ===

Skipper: Created page with "This wiki presents a motivational example of a lot of properties of R packages and how to use them. Please see packages motivation for motivation about why you should util..."

2024-03-29T23:48:17Z

Created page with "This wiki presents a motivational example of a lot of properties of R packages and how to use them. Please see packages motivation for motivation about why you should util..."

New page

This wiki presents a motivational example of a lot of properties of R packages and how to use them. Please see [[packages motivation]] for motivation about why you should utilize the package framework while doing research. The material in this page captures thoughts from lots of people and is a rewriting of a lecture Ben LeRoy presented while teaching 36-350 in the summer of 2019. Additionally, there are a lot of useful resources on the web to help you make an <code>R</code> package including:

* [http://r-pkgs.had.co.nz R Packages]. ~Hadley Wickham
* [https://link.springer.com/book/10.1007/978-0-387-75936-4 Software for Data Analysis: Programming with R.] ~John Chambers
* [https://cran.r-project.org/doc/manuals/r-release/R-exts.html Writing R Extensions] (the official documentation)

What’s nice about the <code>R</code> programming language how many easy-to-use resources there are to help you develop your own package. The following quote captures a notation that if you’re going to be working with R for long enough, package-driven development is going to happen - so why don’t you start now?

<blockquote>“… from user to programmer to contributor, in the gradual progress that R encourages.” ~ John Chambers (Software for Data Analysis: Programming with R)
</blockquote>

== Foundations (what tools will be used) ==

Currently, there are few very powerful packages to help you develop an <code>R</code> package as painlessly as possible.

* <code>devtools</code> and <code>usethis</code> packages provide a set of functions to automate higher level package details and repeative package development demands
* <code>Roxygen2</code> helps rapid and standardized documentation for your package
* <code>testthat</code> provides clean and standardized tools for testing

== Building an R package ==

=== Step 0: Setting up a Github repo and a Rstudio project directory ===

Version control (and discussed in Stat Computing) is a very useful tool to help streamline file management and provide piece of mind. Oftentimes, you will want to have a copy of the repository not just on your personal computer but online (to help with sharing, just in case your computer dies, it’s cool, etc.). As such these steps will walk you through how to set up a github repo for your new package and how to connect that repo to a new project in R studio.

<ol>
<li>'''In <code>GitHub</code>''', do the following:
<ul>
<li>go to the top-level directory (i.e., <code>github.com/<your user name></code>) </li>
<li>click on “+” at top right, and select “New repository” </li>
<li>name the repository (e.g., “tartan”) </li>
<li>provide a short description of the repository (don’t leave completely blank!) </li>
<li>keep the repository public (as students you have access to free private repos https://education.github.com/pack, but for purposes of this example we will keep the repo public) </li>
<li>click on “Initialize this repository with a README” and select the R option in “Add .gitignore”… there is no need to “Add a license” </li>
<li>click on “Create Repository” </li>
</ul></li>
<li>'''…then in RStudio''', do the following:
<ul>
<li>click on <code>File > New Project...</code> </li>
<li>click on “Version Control”, then on “Git” </li>
<li>provide the ''full'' address for the “Repository URL” (including the <code>https</code>, etc.; by default, this will provide the name of your local repository) </li>
<li>make sure “Create project as subdirectory of:” points to where you want to point it </li>
<li>click on “Create Project” (in this example we will be calling our package <code>tartan</code>) </li>
</ul>
</li>
</ol>

=== Step 1: Creating a minimal source package ===

An R (''source'') package just files in a directory, formatted in a specific way.

To create the bare bones R package, just type in your Rstudio console:

<syntaxhighlight lang="r">usethis::create_package("tartan")</syntaxhighlight>
<syntaxhighlight lang="r"># output of the above command
> usethis::create_package("tartan")
✔ Setting active project to './tartan'
✔ Creating 'R/'
✔ Creating 'man/'
✔ Writing 'DESCRIPTION'
✔ Writing 'NAMESPACE'
✔ Changing working directory to './tartan'</syntaxhighlight>
* if in the <code>tartan</code> project, may need to do <code>setwd("../")</code>, run the above line and then do <code>setwd("tartan")</code>.

This will create a <code>tartan</code> folder with the following items:

# Directory <code>R/</code> (where all the function source code goes)
# Directory <code>man/</code> (where all the <code>Roxygen</code> created documentation goes '''- auto generated''')
# <code>NAMESPACE</code> file (information about what functions you’re providing the user '''- auto generated''')
# <code>DESCRIPTION</code> file (information about your package)
# <code>tartan.Rproj</code> file (if using RStudio - just R project information '''- auto generated''')

and anything else you included from intializing your git repo (<code>.gitignore</code>, <code>LICENSE</code>, etc)

[[File:Tartan_folder.png|frameless|600px|alt=initial directory items|initial directory items]]

==== Description file meta-data ====

The first thing you should do is update a little bit of the meta-data in the <code>DESCRIPTION</code> file, an example of which is seen below. You don’t need to add lots, but you’ll probably want to at least add your name and a title.

[[File:tartan_description.png|frameless|600px|alt=initialized description file|initialized description file]]

=== Step 2: Writing a function ===

All of your R code needs to go in <code>.R</code> files in the <code>R/</code> directory. You can create these files yourself, but you can also automate this with

<syntaxhighlight lang="r">usethis::use_r("welcome") # opens up file (creates if need be)</syntaxhighlight>
With the previous line of code creating an empty <code>R/welcome.R</code> file. <br> Inside this file, let’s image we add the following function

<syntaxhighlight lang="r">call_scotty_demo <- function(your_name) {
if (nchar(your_name) > 30){
warning("your name is beyond 30 characters, and has been truncated")
your_name <- substr(your_name, 1, 30)
}

name_length <- nchar(your_name)

# Hiiiii
cat(paste("\n",
paste0(c("", rep("-", name_length + 8), "\n"), collapse = ""),
paste0(c("| Hi ", your_name, "! | \n"), collapse=""),
paste0(c("| ", rep("-", name_length + 4), "\n"), collapse = ""),
paste0(c("| /\n")))
)

# from Scotty.
cat(paste0(
" |/ |\\_/| \n",
" | |q p| /} \n",
" | ( 0 )\"\"\"\\ \n",
" \\ |\"-\"` | \n",
" || /=\\\\ | \n",
" \"'\" '\"\"\"'"))

}</syntaxhighlight>
To get access to this function we can locally load the package into memory (a weaker install than calling <code>library()</code>) by running:

<syntaxhighlight lang="r">devtools::load_all()</syntaxhighlight>
Note that <code>load_all()</code> can be called over and over if you keep updating your function files and will re-load the newest verion of all your functions.

==== Additional notes ====

Unlike writing code in an <code>.Rmd</code> or a <code>.R</code> file, we deal with library dependencies slightly differently. If you know functions need tools from a certain library we put that library in the <code>Imports:</code> section of your <code>DESCRIPTION</code> file. Additional to use functions from outside libraries in our functions we have to write them like <code>package_name::function_name</code>. For example in our function <code>call_scotty_demo</code> if we wanted to use <code>stringr</code>’s <code>str_sub</code> function we’d have to have our code look like:

<syntaxhighlight lang="r">call_scotty_demo <- function(your_name) {
if (nchar(your_name) > 30){
warning("your name is beyond 30 characters, and has been truncated")
your_name <- stringr::str_sub(your_name, 1, 30)
}

name_length <- nchar(your_name)

# Hiiiii
cat(paste("\n",
paste0(c("", rep("-", name_length + 8), "\n"), collapse = ""),
paste0(c("| Hi ", your_name, "! | \n"), collapse=""),
paste0(c("| ", rep("-", name_length + 4), "\n"), collapse = ""),
paste0(c("| /\n")))
)

# from Scotty.
cat(paste0(
" |/ |\\_/| \n",
" | |q p| /} \n",
" | ( 0 )\"\"\"\\ \n",
" \\ |\"-\"` | \n",
" || /=\\\\ | \n",
" \"'\" '\"\"\"'"))

}</syntaxhighlight>
and our <code>DESCRIPTION</code> file would need lines like

<syntaxhighlight lang="r">Imports:
stringr</syntaxhighlight>
=== Step 3: Documenting your functions ===

With <code>devtools</code> and a package it’s actually really easy to create local documentation for your own functions so that <code>?function_name</code> pops up documentation in the same way <code>?sum</code> does in Rstudio.

The easiest way to document your code is using <code>Roxygen2</code>’s helper tools. To start, make sure you’ve downloaded the package:

<syntaxhighlight lang="r">install.packages("roxygen2")
library(roxygen2)</syntaxhighlight>
Then at the first line of a function you’ve written (when you’re in Rstudio) use the short-cut <code>Command + Option + Shift + R</code> (Mac) or <code>Ctrl+ Alt + Shift + R</code> (Windows), this will auto-generate a documentation structure to fill in.

For example, if we had the function from above used the shortcut, we would then have:

<syntaxhighlight lang="r">#' Title
#'
#' @param your_name
#'
#' @return
#' @export
#'
#' @examples
call_scotty_demo <- function(your_name) {
...
}</syntaxhighlight>
which we could fill in with:

<syntaxhighlight lang="r">#' Meet Scotty, the Scottie Dog
#'
#' @param your_name string of your name (max length 30 characters)
#'
#' @return NULL. Though scotty appears on your screen and says Hi to you.
#' @export
#'
#' @examples
#' call_scotty_demo("Andrew Carnegie")
call_scotty_demo <- function(your_name) {
...
}</syntaxhighlight>
The basic structure of the documentation is decently straightforward (you can remove <code>@export</code> if you don’t want the function to export, and you can remove <code>@examples</code> if you don’t have any examples), but detailed guidance, documentation [https://r-pkgs.org/man.html?q=roxygen#man here] can be super helpful (with information on linking functions and other packages, adding math equations, code text, etc.)

'''Now''' to actually create a documentation file, we run

<syntaxhighlight lang="r">devtools::document()</syntaxhighlight>
The first time we do this we’ll create <code>man/</code> folder if one doesn’t always exist and also create / update a corresponding file named <code>man/call_scotty_demo.Rd</code> file that R uses to generate documentation. Additionally, the <code>document()</code> function also updates the <code>NAMESPACE</code> file so when you load your functions you get the desired documenation (need to have <code>@export</code> in the docstring).

The <code>man/call_scotty_demo.Rd</code> document file looks like the following. Notice how it says “do not edit by hand”.

<code>{r eval=F} % Generated by roxygen2: do not edit by hand % Please edit documentation in R/welcome.R \name{call_scotty_demo} \alias{call_scotty_demo} \title{Meet Scotty, the Scottie Dog} \usage{ call_scotty_demo(your_name) } \arguments{ \item{your_name}{string of your name (max length 30 characters)} } \value{ \code{NULL}. Though scotty appears on your screen and says Hi to you. } \description{ Meet Scotty, the Scottie Dog } \examples{ call_scotty_demo("Andrew Carnegie") }</code>

To actually view your documentation files we need to re-load the package and then use the standard <code>?</code> to get the help file:

<syntaxhighlight lang="r">devtools::load_all()
?call_scotty_demo</syntaxhighlight>
[[File:call_scotty_demo_doc.png|frameless|600px|alt=example of help file|example of help file]]

=== Step 4: Testing ===

Testing is critical to making sure your functions do what you expect. The easiest way to get started with testing is the <code>testthat</code> package, which also integrates with <code>devtools</code>. To start testing using <code>testthat</code> in your new R package do the following:

<code>{r eval = F} install.packages("testthat") usethis::use_testthat()</code>

This will set up the <code>tests/testthat</code> directory where we can store tests.

==== What’s the philosophy behind <code>testthat</code> ====

<code>testthat</code> functionality can be see as tools to do a range of needs, from low level testing all the way up to overall testing of all functions in a package.

<ol>
<li>On the low level, <code>testthat</code> provides functions to test your '''expectations'''. The most fundamental unit of testing is this low level. <code>testthat</code>’s <code>expect_...</code> functions provide the building blocks for testing. They describe what result is expected for your various computations and we can use these to make sure our functions are giving the expected output. For example:

<syntaxhighlight lang="r">library(testthat)
expect_equal(1, 1)
expect_equal(1, 2)</syntaxhighlight>
Returns:

<syntaxhighlight lang="r">## Error: 1 not equal to 2.
## 1/1 mismatches
## [1] 1 - 2 == -1</syntaxhighlight>
</li>
<li>'''Grouping expectations''' is the next level. We can group a set of expectations to examine more complex functionality with the wrapper <code>test_that</code> which takes in a string describing what you’re examining, and then a set of <code>expect_...</code>s that are wrapping in <code>{}</code>. For example:

<syntaxhighlight lang="r">test_that(paste("calling scotty works well (returns null",
"and provides warning nchar > 30)"), {
expect_equal(call_scotty_demo("Oski Bear"), NULL)
expect_warning(call_scotty_demo("Oski Bear, your a wonderful, but slightly creepy Berkeley Bear"))
expect_equal(1, 2)
}</syntaxhighlight>
Returns:

<syntaxhighlight lang="r">##
## -----------------
## | Hi Oski Bear! |
## | -------------
## | /
## |/ |\_/|
## | |q p| /}
## | ( 0 )"""\
## \ |"-"` |
## || /=\\ |
## "'" '"""'
## --------------------------------------
## | Hi Oski Bear, your a wonderful, b! |
## | ----------------------------------
## | /
## |/ |\_/|
## | |q p| /}
## | ( 0 )"""\
## \ |"-"` |
## || /=\\ |
## "'" '"""'

## Error: Test failed: 'calling scotty works well (returns null and provides warning nchar > 30)'
## * 1 not equal to 2.
## 1/1 mismatches
## [1] 1 - 2 == -1</syntaxhighlight>
</li>
<li>'''A set of grouped tests''' in single file. When building a package your functions will likely like in different <code>.R</code> files in the <code>R/</code> folder. To mirror this structure we put of our tests associated with a single <code>.R</code> file into 1 test file. These files sit in the <code>tests/testthat/</code> folder and must start with <code>test</code>. <code>devtools</code> and <code>usethis</code> provide a way to create these test in an automated fashion. For example, if we wanted to create a file <code>tests/testthat/test-welcome.R</code>, we could call

<syntaxhighlight lang="r">usethis::use_test("welcome")</syntaxhighlight>
which provides the message:

<syntaxhighlight lang="r">✔ Setting active project to './tartan'
✔ Adding 'testthat' to Suggests field in DESCRIPTION
✔ Creating 'tests/testthat/'
✔ Writing 'tests/testthat.R'
✔ Writing 'tests/testthat/test-welcome.R'
● Modify 'tests/testthat/test-welcome.R'</syntaxhighlight>
In these larger files (relative to group functions) we include group expectations as well as context information for the overall file using the <code>context()</code> function. And example can be see below:

<syntaxhighlight lang="r">context("test welcome from scotty")

test_that(paste("calling scotty works well (returns null",
"and provides warning nchar > 30)"), {
expect_equal(call_scotty_demo("Oski Bear"), NULL)
expect_warning(call_scotty_demo("Oski Bear, your a wonderful, but slightly creepy Berkeley Bear"))
expect_equal(1, 2)
})</syntaxhighlight>
Once you have a test file in your package all you need to do is run

<syntaxhighlight lang="r">devtools::test()</syntaxhighlight>
and R will run all your associated test, and will return output like seen in the following image:

[[File:devtool_test_example.png|frameless|600px|alt=output of testthat|output of testthat]]
</li>
</ol>

=== Step 5. Checking the full package ===

To understanding if your overall package is clean and able to be shared we can run

<pre>devtools::check()</pre>

This checks all your dependencies, syntax, and more that may have slipped through the cracks. Often times this is only necessary when you’re looking to share your package with others, but is a good step to include so you don’t have to change a lot of things right before sharing.

=== Step 6: Syncronizing with Github ===

As always, once you’ve completed a clean block of code you should push it to Github. When your code is on github other folks can download the package in a similar fashion to the standard <code>install.packages(...)</code>,

For example, to install the R package we just made we could use:

<code>{r eval = T, message=F, warning=F} devtools::install_github(repo = "benjaminleroy/tartan", force = F) # so making the sides does do it a ton of times library(tartan) #?call_scotty_demo call_scotty_demo("Big Bird")</code>

=== Step 7: And beyond! ===

In the above example we still didn’t cover a lot of things, including:

<ul>
<li> Including data in your package (that can be [http://r-pkgs.had.co.nz/data.html documented] too)
<code>r # suppose that I have a tarans dataset that I created - than I can save it this way usethis::use_data(tartans) # and document at usethis::use_r("data")</code> </li>
<li> Vignettes (long form documentation, knitr) </li>
<li> Compiled code (C, C++, Fortran…) </li>
<li> Creating a CRAN ready package </li>
<li> See [https://usethis.r-lib.org/reference/index.html <code>usethis</code>] to see all the package development steps that <code>usethis</code> automates. </li>
</ul>

Developing R packages - Revision history

Ajshen at 03:13, 29 June 2026

Skipper at 01:49, 24 May 2024

Skipper at 01:48, 24 May 2024

Skipper: Created page with "This wiki presents a motivational example of a lot of properties of R packages and how to use them. Please see packages motivation for motivation about why you should util..."