Creating a local R package using RStudio

If there’s one thing I love about R, it’s visualizations. And if there’s one thing I love about visualizations, it’s getting to choose the colors. But if there’s one thing I hate about getting to choose the colors, it’s forgetting which colors I like and having to look up color names or hex codes and saving new lists of colors of varying lengths each time I want to generate a new chart or graph. I’ve suspected for a while that it would pay to make a package to save color combinations, but it always felt like too much of a chore. Then I got Omicron.

I was faced with a week’s worth of abyss, quarantined in a single room in my family’s home after flying to California for the holidays. After a healthy amount of grimacing, I decided enough was enough, I would do something with the meager tools at my disposal and finally take on the task of creating a package to save and display color combinations. I spent a few days putting palettes together and writing functions to display, shuffle, and return the color codes based on user input. I’ll write another post just about the contents of the package, because I like it and think it’s a lot of fun.

For now I want to document how I was able to convert functions and data into a package that can be called at any time. This is definitely not the only way to save code as a package, but this is the easiest way to do it that worked for me. Because I already made the color package, I will make a new package for the sake of this post called michiganjfrog.

Step 1: Open a new project in RStudio

In RStudio, navigate to File -> New Project… you will then be prompted to save the current workspace, and do so if you like. The project wizard will pop up. Choose New Directory -> Package. You’ll get a form that looks like this:

Here you will pick the package name, where the package will be saved, and whether to create a git repository. My package uses only base R so I didn’t worry about checking “Use renv with this project,” but for future reference, checking that box could be useful for dependency management. I checked “Create a git repository” because I wanted to track changes to my package on GitHub.

Once the package is created, you’ll get something that looks like this:

The wizard already comes with a sample R script with a function called “hello.”

Step 2: Save a function

To save more functions, select File -> New File -> R Script and write your function. It is generally best practice to save functions in their own R scripts, or to save related functions together.

When you save your R script, RStudio will automatically suggest you save it to the “R” folder within your package. That is exactly where it should be saved. Don’t change that. Name your file either the same name as your function or a short, easy to remember name for your related functions.

Step 3: Build your package with the new function

This step doesn’t have to take place necessarily right after you save your first function, but I think it’s useful down the road to rebuild your package as often as possible and before creating the documentation file for your function for reasons that will become clear in step 4. To build (basically, save) your package, navigate to the top right corner of RStudio and select the “Build” tab. Then click “Install and Restart”

Step 4: Document your function

Go to File -> New File -> R Documentation… A dialog box will pop up that looks like this:

If you’ve already built the package with a function by the same name as the “Topic name,” RStudio will recognize this and automatically fill in some of the fields in the documentation template when you press OK:

You can fill in the other fields with any relevant information, then press “preview” to view the html rendering of the documentation file:

To save the documentation, follow step 3 to rebuild the package.

Step 5: Add data

Adding data such as lists or tables to a package is relatively easy. Just open a new script, define your data and use the use_data() function to save the data within the package. It should look like this:

frogfacts <- c("green","yellow","top hat","shy","eternal","ragtime")

use_data(frogfacts)

Make sure you run the code and rebuild the package to save your changes.

Step 6: Connect to GitHub

After creating a new directory in GitHub, open a terminal window and type the following:

cd desktop/michiganjfrog (or wherever the package is saved)
git remote add origin https://github.com/szaidman22/michiganjfrog.git
git branch -M main
git add -A
git commit -m "adding package contents"
git push --set-upstream origin main

This will connect the package directory to the GitHub directory and add everything to the main branch. To push and commit changes from RStudio, navigate to the “Git” tab at the top right of the RStudio window:

Check any of the documents/directories within the package with changes that you want to push to GitHub, then press the “Commit” button, close the dialog box that pops up, and press the “Push” button:

To check that the changes were pushed properly, go to the GitHub directory and look for commits.

Step 7: Check the package

There are many ways to check that the package does what it’s supposed to, but in my opinion the easiest is just to open a new project and try to use it. Because the package is saved on your own machine and already installed, there is no need to install it. All you have to do is call the package from the library:

It looks like the package and descriptions work! Stay tuned to hear more about the color palette package I made last month.