R Packages, 2nd Edition

R Packages, 2nd Edition

by Hadley Wickham, Jennifer Bryan
Released June 2023
Publisher(s): O'Reilly Media, Inc.
ISBN: 9781098134945

Read it now on the O’Reilly learning platform with a 10-day free trial.

O’Reilly members get unlimited access to books, live events, courses curated by job role, and more from O’Reilly and nearly 200 top publishers.

Buy on Amazon Buy on ebooks.com
Start your free trial

Book description

Turn your R code into packages that others can easily install and use. With this fully updated edition, developers and data scientists will learn how to bundle reusable R functions, sample data, and documentation together by applying the package development philosophy used by the team that maintains the "tidyverse" suite of packages. In the process, you'll learn how to automate common development tasks using a set of R packages, including devtools, usethis, testthat, and roxygen2.

Authors Hadley Wickham and Jennifer Bryan from Posit (formerly known as RStudio) help you create packages quickly, then teach you how to get better over time. You'll be able to focus on what you want your package to do as you progressively develop greater mastery of the structure of a package.

With this book, you will:

  • Learn the key components of an R package, including code, documentation, and tests
  • Streamline your development process with devtools and the RStudio IDE
  • Get tips on effective habits such as organizing functions into files
  • Get caught up on important new features in the devtools ecosystem
  • Learn about the art and science of unit testing, using features in the third edition of testthat
  • Turn your existing documentation into a beautiful and user friendly website with pkgdown
  • Gain an appreciation of the benefits of modern code hosting platforms, such as GitHub

Publisher resources

View/Submit Errata

Table of contents

  1. Preface
    1. Welcome!
    2. Introduction
      1. Philosophy
      2. In This Book
      3. What’s Not Here
    3. Conventions Used in This Book
    4. Colophon
    5. O’Reilly Online Learning
    6. How to Contact Us
    7. Acknowledgments
  2. I. Getting Started
    1. 1. The Whole Game
      1. Load devtools and Friends
      2. Toy Package: regexcite
      3. Preview the Finished Product
      4. create_package()
      5. use_git()
      6. Write the First Function
      7. use_r()
      8. load_all()
        1. Commit strsplit1()
      9. check()
      10. Edit DESCRIPTION
      11. use_mit_license()
      12. document()
        1. NAMESPACE Changes
      13. check() Again
      14. install()
      15. use_testthat()
      16. use_package()
      17. use_github()
      18. use_readme_rmd()
      19. The End: check() and install()
      20. Review
    2. 2. System Setup
      1. devtools, usethis, and You
        1. Personal Startup Configuration
      2. R Build Toolchain
        1. Windows
        2. macOS
        3. Linux
      3. Verify System Prep
    3. 3. Package Structure and State
      1. Package States
      2. Source Package
      3. Bundled Package
        1. .Rbuildignore
      4. Binary Package
      5. Installed Package
      6. In-Memory Package
      7. Package Libraries
    4. 4. Fundamental Development Workflows
      1. Create a Package
        1. Survey the Existing Landscape
        2. Name Your Package
        3. Package Creation
        4. Where Should You create_package()?
      2. RStudio Projects
        1. Benefits of RStudio Projects
        2. How to Get an RStudio Project
        3. What Makes an RStudio Project?
        4. How to Launch an RStudio Project
        5. RStudio Project Versus Active usethis Project
      3. Working Directory and Filepath Discipline
      4. Test Drive with load_all()
        1. Benefits of load_all()
        2. Other Ways to Call load_all()
      5. check() and R CMD check
        1. Workflow
        2. Background on R CMD check
    5. 5. The Package Within
      1. Alfa: A Script That Works
      2. Bravo: A Better Script That Works
      3. Charlie: A Separate File for Helper Functions
      4. Delta: A Failed Attempt at Making a Package
      5. Echo: A Working Package
      6. Foxtrot: Build Time Versus Run Time
      7. Golf: Side Effects
      8. Concluding Thoughts
        1. Script Versus Package
        2. Finding the Package Within
        3. Package Code Is Different
  3. II. Package Components
    1. 6. R Code
      1. Organize Functions Into Files
      2. Fast Feedback via load_all()
      3. Code Style
      4. Understand When Code Is Executed
        1. Example: A Path Returned by system.file()
        2. Example: Available Colors
        3. Example: Aliasing a Function
      5. Respect the R Landscape
        1. Manage State with withr
        2. Restore State with base::on.exit()
        3. Isolate Side Effects
        4. When You Do Need Side Effects
      6. Constant Health Checks
    2. 7. Data
      1. Exported Data
        1. Preserve the Origin Story of Package Data
        2. Documenting Datasets
        3. Non-ASCII Characters in Data
      2. Internal Data
      3. Raw Data File
        1. Filepaths
        2. pkg_example() Path Helpers
      4. Internal State
      5. Persistent User Data
    3. 8. Other Components
      1. Other Directories
      2. Installed Files
        1. Package Citation
      3. Configuration Tools
  4. III. Package Metadata
    1. 9. DESCRIPTION
      1. The DESCRIPTION File
      2. Title and Description: What Does Your Package Do?
      3. Author: Who Are You?
      4. URL and BugReports
      5. The License Field
      6. Imports, Suggests, and Friends
        1. Minimum Versions
        2. Depends and LinkingTo
        3. An R Version Gotcha
      7. Other Fields
      8. Custom Fields
    2. 10. Dependencies: Mindset and Background
      1. When Should You Take a Dependency?
        1. Dependencies Are Not Equal
        2. Prefer a Holistic, Balanced, and Quantitative Approach
        3. Dependency Thoughts Specific to the tidyverse
        4. Whether to Import or Suggest
      2. Namespace
        1. Motivation
        2. The NAMESPACE File
      3. Search Path
        1. Function Lookup for User Code
        2. Function Lookup Inside a Package
      4. Attaching Versus Loading
        1. Whether to Import or Depend
    3. 11. Dependencies: In Practice
      1. Confusion About Imports
      2. Conventions for This Chapter
      3. NAMESPACE Workflow
      4. Package Is Listed in Imports
        1. In Code Below R/
        2. In Test Code
        3. In Examples and Vignettes
      5. Package Is Listed in Suggests
        1. In Code Below R/
        2. In Test Code
        3. In Examples and Vignettes
      6. Package Is Listed in Depends
        1. In Code Below R/ and in Test Code
        2. In Examples and Vignettes
      7. Package Is a Nonstandard Dependency
        1. Depending on the Development Version of a Package
        2. Config/Needs/* Field
      8. Exports
        1. What to Export
        2. Re-exporting
      9. Imports and Exports Related to S3
    4. 12. Licensing
      1. Big Picture
      2. Code You Write
        1. Key Files
        2. More Licenses for Code
        3. Licenses for Data
        4. Relicensing
      3. Code Given to You
      4. Code You Bundle
        1. License Compatibility
        2. How to Include
      5. Code You Use
  5. IV. Testing
    1. 13. Testing Basics
      1. Why Is Formal Testing Worth the Trouble?
      2. Introducing testthat
      3. Test Mechanics and Workflow
        1. Initial Setup
        2. Create a Test
        3. Run Tests
      4. Test Organization
      5. Expectations
        1. Testing for Equality
        2. Testing Errors
        3. Snapshot Tests
        4. Shortcuts for Other Common Patterns
    2. 14. Designing Your Test Suite
      1. What to Test
        1. Test Coverage
      2. High-Level Principles for Testing
        1. Self-Sufficient Tests
        2. Self-Contained Tests
        3. Plan for Test Failure
        4. Repetition Is OK
        5. Remove Tension Between Interactive and Automated Testing
      3. Files Relevant to Testing
        1. Hiding in Plain Sight: Files Below R/
        2. tests/testthat.R
        3. testthat Helper Files
        4. testthat Setup Files
        5. Files Ignored by testthat
        6. Storing Test Data
        7. Where to Write Files During Testing
    3. 15. Advanced Testing Techniques
      1. Test Fixtures
        1. Create useful_things with a Helper Function
        2. Create (and Destroy) a Local useful_thing
        3. Store a Concrete useful_thing Persistently
      2. Building Your Own Testing Tools
        1. Helper Defined Inside a Test
        2. Custom Expectations
      3. When Testing Gets Hard
        1. Skipping a Test
        2. Mocking
        3. Secrets
      4. Special Considerations for CRAN Packages
        1. Skip a Test
        2. Speed
        3. Reproducibility
        4. Flaky Tests
        5. Process and Filesystem Hygiene
  6. V. Documentation
    1. 16. Function Documentation
      1. roxygen2 Basics
        1. The Documentation Workflow
        2. roxygen2 Comments, Blocks, and Tags
        3. Key Markdown Features
      2. Title, Description, Details
        1. Title
        2. Description
        3. Details
      3. Arguments
        1. Multiple Arguments
        2. Inheriting Arguments
      4. Return Value
      5. Examples
        1. Contents
        2. Leave the World as You Found It
        3. Errors
        4. Dependencies and Conditional Execution
        5. Intermixing Examples and Text
      6. Reusing Documentation
        1. Multiple Functions in One Topic
        2. Inheriting Documentation
        3. Child Documents
      7. Help Topic for the Package
    2. 17. Vignettes
      1. Workflow for Writing a Vignette
      2. Metadata
      3. Advice on Writing Vignettes
        1. Diagrams
        2. Links
        3. Filepaths
        4. How Many Vignettes?
        5. Scientific Publication
      4. Special Considerations for Vignette Code
        1. Article Instead of Vignette
      5. How Vignettes Are Built and Checked
        1. R CMD build and Vignettes
        2. R CMD check and Vignettes
    3. 18. Other Markdown Files
      1. README
        1. README.Rmd and README.md
      2. NEWS
    4. 19. Website
      1. Initiate a Site
      2. Deployment
      3. Now What?
      4. Logo
      5. Reference Index
        1. Rendered Examples
        2. Linking
        3. Index Organization
      6. Vignettes and Articles
        1. Linking
        2. Index Organization
        3. NonVignette Articles
      7. Development Mode
  7. VI. Maintenance and Distribution
    1. 20. Software Development Practices
      1. Git and GitHub
        1. Standard Practice
      2. Continuous Integration
        1. GitHub Actions
        2. R CMD check via GHA
        3. Other Uses for GHA
    2. 21. Lifecycle
      1. Package Evolution
      2. Package Version Number
      3. Tidyverse Package Version Conventions
      4. Backward Compatibility and Breaking Change
      5. Major Versus Minor Versus Patch Release
        1. Package Version Mechanics
      6. Pros and Cons of Breaking Change
      7. Lifecycle Stages and Supporting Tools
        1. Lifecycle Stages and Badges
        2. Deprecating a Function
        3. Deprecating an Argument
        4. Deprecation Helpers
        5. Dealing with Change in a Dependency
        6. Superseding a Function
    3. 22. Releasing to CRAN
      1. Decide the Release Type
      2. Initial CRAN Release: Special Considerations
        1. CRAN Policies
      3. Keeping Up with Change
      4. Double R CMD Checking
        1. CRAN Check Flavors and Related Services
      5. Reverse Dependency Checks
        1. Revdeps and Breaking Changes
      6. Update Comments for CRAN
      7. The Submission Process
      8. Failure Modes
      9. Celebrating Success
  8. Index
  9. About the Authors

Product information

  • Title: R Packages, 2nd Edition
  • Author(s): Hadley Wickham, Jennifer Bryan
  • Release date: June 2023
  • Publisher(s): O'Reilly Media, Inc.
  • ISBN: 9781098134945