Create R Package

From Idea to Implementation

Creating an R package is a rewarding project that allows you to organize, share, and reuse your R code in a structured, efficient way. Whether you’re developing a library for personal use or preparing to share it with the broader R community, building a package will help you improve your coding practices and make your functions more portable and maintainable. In this blog post, we’ll walk through the essential steps of creating your first R package, from setting up the package structure to documenting your functions using roxygen2.

1. Setting Up the Package Structure

Before you start coding, it’s essential to set up a proper package structure. The best way to get started is by using the devtools package, which simplifies the process of creating, testing, and documenting your package.

Installing Required Packages

To begin, you need to install devtools and usethis—two powerful packages that help streamline package development.

r
Copy code
install.packages("devtools")
install.packages("usethis")

Once the packages are installed, load them into your session:

r
Copy code
library(devtools)
library(usethis)

Creating a New Package

To create a new package, use the create_package() function from the usethis package. This function sets up the basic directory structure for your package:

r
Copy code
usethis::create_package("path/to/your/package")

This will create a new folder with the necessary subdirectories such as R/, man/, and DESCRIPTION file. The R/ directory is where your R functions will go, and the man/ directory will hold the documentation files.

Package Structure Overview

DESCRIPTION: Contains metadata about your package, such as name, version, description, dependencies, and authorship.
R/: This folder contains the R code for the package (i.e., your functions).
man/: This folder contains documentation files for each function in the package.
NAMESPACE: Defines the functions that are exported by your package.
tests/: (optional) Contains tests for your functions, typically using the testthat package.

The basic structure after running create_package() should look like this:

go
Copy code
your-package/
├── DESCRIPTION
├── NAMESPACE
├── R/
│   └── your_function.R
└── man/
    └── your_function.Rd

2. Writing Functions for Your Package

Now that your package structure is set up, you can start writing functions. Let’s create a simple function for demonstration purposes.

Writing the First Function

Inside the R/ folder, create a new R file called add_numbers.R and write your first function. For example, a function to add two numbers:

r
Copy code
#' Add two numbers
#'
#' This function takes two numeric values and returns their sum.
#'
#' @param x A numeric value.
#' @param y A numeric value.
#' @return The sum of \code{x} and \code{y}.
#' @export
add_numbers <- function(x, y) {
  return(x + y)
}

In this code:

The @param tags describe the function’s arguments.
The @return tag explains what the function returns.
The @export tag marks this function for export, making it accessible to users of your package.

Saving the Function

Save the file in the R/ directory with a .R extension (e.g., add_numbers.R). You can add more functions in the same directory, each function stored in its own file or grouped together in a single file, depending on their functionality.

3. Documenting Functions with `roxygen2`

Documenting your functions properly is an important aspect of creating a package. The roxygen2 package provides a streamlined way to generate documentation for your functions directly from the comments in your R code.

Installing and Using `roxygen2`

First, install the roxygen2 package if you haven’t already:

r
Copy code
install.packages("roxygen2")

Next, load the package:

r
Copy code
library(roxygen2)

Documenting with `roxygen2`

Notice in the function we created earlier, we included special comments above the function. These comments follow the roxygen2 syntax. Here’s a breakdown of the key elements:

@param: Describes the arguments of the function.
@return: Describes the output of the function.
@export: Marks the function for export so that it becomes available to users of the package.
@examples: Provides example usage of the function.

To generate the documentation files, you will run the roxygen2::roxygenize() function. This will read your function files, extract the comments, and automatically generate .Rd files in the man/ directory, which R uses for help files.

r
Copy code
roxygen2::roxygenize("path/to/your/package")

This command will create a .Rd file for each function in the man/ directory. For example, the add_numbers function will have an associated add_numbers.Rd file in the man/ directory, which can be accessed via the help() function in R:

r
Copy code
help(add_numbers)

NAMESPACE and Exporting Functions

roxygen2 also helps manage your NAMESPACE file. When you use the @export tag in your function’s documentation, roxygen2 automatically updates the NAMESPACE file to export that function.

For instance, after running roxygen2::roxygenize(), your NAMESPACE file will include a line like this:

scss
Copy code
export(add_numbers)

This tells R that add_numbers should be available for users of the package.

4. Testing Your Package

Before distributing your package, it’s important to test it to ensure that everything works as expected. You can use the testthat package for unit testing.

Setting Up Tests with `testthat`

First, install testthat if you haven’t already:

r
Copy code
install.packages("testthat")

To set up tests, create a tests/testthat/ folder in your package directory. Inside, create a file like test-add_numbers.R and write tests for your function:

r
Copy code
test_that("add_numbers adds correctly", {
  expect_equal(add_numbers(2, 3), 5)
  expect_equal(add_numbers(-1, 1), 0)
  expect_equal(add_numbers(0, 0), 0)
})

Then, you can run the tests using the following command:

r
Copy code
devtools::test()

This will run all tests in the tests/testthat/ folder and check that your package functions as expected.

5. Building and Installing Your Package

Once you have written your functions and documented them, it’s time to build and install your package.

Building the Package

To build your package into a .tar.gz file, use the following command:

r
Copy code
devtools::build("path/to/your/package")

Installing the Package

To install your package locally for testing, run:

r
Copy code
devtools::install("path/to/your/package")

You can now load your package and use it like any other R package:

r
Copy code
library(yourPackageName)
add_numbers(1, 2)

6. Sharing Your Package

Once your package is complete, you can share it with others. The most common way to distribute R packages is via CRAN, but you can also share them on GitHub for more flexibility.

To push your package to GitHub, follow these steps:

Create a GitHub repository for your package.
Initialize Git in your package directory (git init).
Commit your files and push them to GitHub.

You can also use the usethis package to automate parts of this process:

r
Copy code
usethis::use_github()

Conclusion

Creating an R package is an essential skill for any advanced R user, as it allows you to organize and share your code effectively. In this post, we’ve covered the key steps to building your first R package—from setting up the package structure and writing functions to documenting them using roxygen2 and testing with testthat.