R Language Using And Creating R Packages Complete Guide

Explaining the Use and Creation of R Packages

R is a language and environment for statistical computing and graphics. It offers extensive capabilities for data analysis and visualization, but its true power lies in its community-contributed packages. These packages extend R’s functionality by adding new functions, data, or transformations, simplifying complex analyses and promoting reproducibility. Below, we will delve into how to use existing R packages and how to create your own.

Using R Packages

Installing a Package

The first step in using R packages is installation. Most packages are available on Comprehensive R Archive Network (CRAN) but can also be found on GitHub and other platforms.

• CRAN Installation: To install a package from CRAN, use the install.packages() function. For example:

  install.packages("ggplot2")
  

• GitHub Installation: For packages hosted on GitHub, you can use the devtools package.

  install.packages("devtools")
  library(devtools)
  install_github("tidyverse/ggplot2")
  

Loading a Package

After installation, load the package using the library() or require() function in your R session to gain access to its functionalities.

library(ggplot2)
# or
require(ggplot2)

Accessing Package Docs

Packages come with documentation that you can access using help(), ?, and vignette() functions.

• Help Manual:

  help(ggplot)
  # or
  ?ggplot
  

• Package Vignettes:

  vignette(package = "ggplot2")
  

Functionality Overview

Packages often include various functions and datasets. You can explore them through the R console or online documentation.

• Functions: Use ls("package:packagename") to list all functions in the package.

  ls("package:ggplot2")
  

• Datasets: Many packages come with sample datasets for demonstration.

  data(package="ggplot2")
  

Creating an R Package

Creating an R package is a structured process that involves organizing your code, data, and documentation.

Setting Up Your Project

1. Install Required Tools: Ensure you have the devtools and usethis packages installed.

   install.packages("devtools")
   install.packages("usethis")
   

2. Create a Package Skeleton: Initialize a new project using create_package() within the usethis package.

   library(usethis)
   create_package("~/path/to/your/package")
   setwd("~/path/to/your/package")
   

3. Directory Structure: The package should have a standard structure like:

   • R/: Contains .R scripts with functions.
   • man/: Holds .Rd files (documentation).
   • data/: Stores datasets (in .rda or .csv formats).
   • DESCRIPTION: Metadata file for your package.
   • NAMESPACE: Defines which functions or data objects are exported.

Writing Functions

Write your functions in .R files within the R/ directory. Each function should be self-contained and ideally well-documented.

• Example Function:

  #' My Example Function
  #'
  #' This is a simple example function that adds two numbers.
  #' @param a Numeric value.
  #' @param b Numeric value.
  #' @return Sum of a and b.
  #' @export
  my_example_function <- function(a, b) {
    return(a + b)
  }
  

Documentation

Proper documentation is crucial for your package. Use roxygen2 tags to create .Rd files automatically.

• Add Roxygen Comments: The above function already includes basic roxygen comments. For more comprehensive documentation, consult the roxygen2 guide.

• Build Documentation: Generate .Rd files using the devtools::document() function.

  devtools::document()
  

Exporting Functions

To make functions accessible to users, they must be exported. Use the @export tag in roxygen comments or explicitly define exports in the NAMESPACE file.

• Roxygen Tag Method: As shown in the previous example using @export.

• NAMESPACE File Method: Add lines like export(sum_two_numbers) in the NAMESPACE.

Testing Your Package

Testing ensures your functions work as expected.

• Test Directory Setup: Create a tests/testthat/ directory for test scripts.

  usethis::use_testthat()
  

• Writing Tests: Use the testthat package to write tests. Here’s an example test script (tests/testthat/test-add.R):

  library(testthat)
  test_that("my_example_function should add two numbers", {
    expect_equal(my_example_function(1, 2), 3)
  })
  

• Run Tests: Execute the testing suite using devtools::test().

  devtools::test()
  

Building Your Package

Once your package is ready, build it to check for errors or issues.

• Build Check: Run the following command to perform thorough checks.

  devtools::check(build_args = c("--no-manual"))
  

Submitting Your Package to CRAN

If your package passes all checks, you might consider publishing it on CRAN.

• Prepare Package: Ensure all required fields are present in DESCRIPTION and follow CRAN policies.

• Tarball Creation: Build a tar.gz file for submission.

  R CMD build path/to/your/package
  

• Submission: Use BiocManager or the web interface to submit the tar.gz file.

  • Install BiocManager:

    installer::from_bioconductor("BiocManager")
    BiocManager::install()
    

Best Practices for Package Development

• Version Control (Git/GitHub): Maintain version control for your project using Git. Hosting on GitHub facilitates collaboration and distribution.
• Code Style: Follow consistent coding practices (e.g., Tidyverse style).
• Dependencies Management: Clearly define dependencies in DESCRIPTION.
• Namespace Cleanliness: Avoid exporting unnecessary functions and variables.
• Continuous Integration: Use CI tools like GitHub Actions to automate testing on push events.
• Documentation: Provide examples, explanations, and vignettes to enhance ease of use.

This comprehensive overview covers fundamental aspects of using and creating R packages, emphasizing key steps and best practices. Whether you're leveraging existing tools or contributing your own innovations, mastering R package development can significantly elevate your ability to conduct high-quality statistical analyses.