• R Packages Book Club
  • Welcome
    • Book club meetings
    • Pace
    • Introductions
    • git and GitHub
    • Group Question 1
    • Group Question 2
    • Group Question 3
    • git and GitHub Resources
    • Learning objectives
    • Today’s learning objectives
    • What is an R package?
    • Installing and using packages
      • Installing packages
    • Why develop packages?
    • Philosophy behind the tools of R Package development
    • What if we need more detail?
    • What we won’t learn
    • A note
    • Meeting Videos
      • Cohort 1
      • Cohort 2
      • Cohort 3
      • Cohort 4
      • Cohort 5
  • I Getting started
  • 1 The whole game
    • Common features of packages
    • Install/update devtools
    • Create a folder for the package
    • Start git
    • Check that it worked
    • Create the first R file
    • Define the first function
    • Load all
    • Commit the changes
    • R CMD check
    • Update package metadata
    • Pick a license
    • Add document skeleton
    • Fill in documentation
    • Build documentation
    • View documentation
    • Set up test infrastructure
    • Write a test
    • Use functions from other packages
    • Rename files
    • Update function definition
    • Update tests
    • Re-check
    • Share the package on Github
    • Add a README
    • Update README
    • Summary
    • Meeting Videos
      • Cohort 1
      • Cohort 2
      • Cohort 3
      • Cohort 4
      • Cohort 5
  • 2 System setup
    • R version
    • RStudio Version
    • pak
    • devtools and friends
    • .Rprofile
    • Jon’s .Rprofile
    • RStudio hotkeys
    • RStudio hotkeys: Tests
    • R build toolchain
    • Developer setup situation report
    • Meeting Videos
      • Cohort 1
      • Cohort 2
      • Cohort 3
      • Cohort 4
  • 3 Package structure and state
    • Package states
    • Package state transitions
    • Source vs bundle
    • .Rbuildignore
    • Bundle vs binary
    • Installed packages
    • In-memory packages
    • Libraries, library(), require(), and packages
    • Meeting Videos
      • Cohort 1
      • Cohort 2
      • Cohort 3
      • Cohort 4
  • 4 Fundamental development workflows
    • 4.1 Survey the existing landscape
    • 4.2 Considerations
    • 4.3 Naming your package
    • 4.4 Creating a new package
      • 4.4.1 What does this do?
      • 4.4.2 Where to put this package?
    • 4.5 Using RStudio Projects
      • 4.5.1 Benefits of RStudio Projects
      • 4.5.2 Make an R Project for an existing package
      • 4.5.3 R Project tidbits
    • 4.6 RStudio, usethis and working directories
    • 4.7 Test driving a package
      • 4.7.1 Using load_all()
      • 4.7.2 Using test()
      • 4.7.3 Coping with being impatient
      • 4.7.4 (Previous speaker’s) bad habit
    • 4.8 Meeting Videos
      • 4.8.1 Cohort 1
      • 4.8.2 Cohort 2
      • 4.8.3 Cohort 3
      • 4.8.4 Cohort 4
  • 5 The package within
    • 5.1 Alfa: a script that works
    • 5.2 Bravo: a better script that works
    • 5.3 Charlie: external helpers
    • 5.4 Delta: an attempt at a package
    • 5.5 Echo: a working package
    • 5.6 Foxtrot: build time vs. run time
    • 5.7 Golf: side effects
    • 5.8 Meeting Videos
      • 5.8.1 Cohort 1
      • 5.8.2 Cohort 2
      • 5.8.3 Cohort 3
      • 5.8.4 Cohort 4
  • II Package components
  • 6 R code
    • 6.1 Mandatory conventions to organise functions
    • 6.2 Optional conventions to organise functions
    • 6.3 Rstudio ways to jump to a function
    • 6.4 Fast feedback via load_all()
    • 6.5 Code style
    • 6.6 Understanding when code is executed
    • 6.7 Aliasing a function recomendation
    • 6.8 Dynamic file path
    • 6.9 Respect the R landscape
    • 6.10 Sorting strings can be dangerous
    • 6.11 Restore state with base::on.exit()
    • 6.12 Restore state with withr::defer()
    • 6.13 base::on.exit() vs withr::defer()
    • 6.14 base::on.exit() vs withr::defer()
    • 6.15 base::on.exit() vs withr::defer()
    • 6.16 base::on.exit() vs withr::defer()
    • 6.17 withr pre-made helpers
    • 6.18 withr pre-made helpers
    • 6.19 withr::defer()can defer events on the global environment
    • 6.20 When you do need side-effects
    • 6.21 Constant health checks
    • 6.22 CRAN notes
    • 6.23 Meeting Videos
      • 6.23.1 Cohort 1
      • 6.23.2 Cohort 2
      • 6.23.3 Cohort 3
      • 6.23.4 Cohort 4
  • 7 Data
    • Why data?
    • Overview of main use cases and paths
    • 7.1 Exported data
    • 7.1 Exported data
    • 7.1 Exported data
    • 7.1 Exported data
    • 7.1.1 Preserve the origin story of package data
    • 7.1.2 Documenting datasets
    • 7.1.2 Documenting datasets
    • 7.1.3 Non-ASCII characters in data
    • 7.2 Internal data
    • 7.2 Internal data
    • 7.2 Internal data
    • 7.2 Internal data
    • 7.3 Raw data files
    • 7.3 Raw data files
    • 7.3.1 Filepaths
    • Summary of exported, internal, and raw data
    • 7.4 Internal state
    • 7.4 Internal state
    • 7.4 Internal state
    • 7.4 Internal state
    • 7.4 Internal state
    • 7.5 Persistent user data
    • 7.5 Persistent user data
    • 7.1 Meeting Videos
      • 7.1.1 Cohort 1
      • 7.1.2 Cohort 2
      • 7.1.3 Cohort 3
      • 7.1.4 Cohort 4
  • 8 Other components
    • 8.1 Other directories
    • 8.2 Installed filled
      • 8.2.1 Package citation:
    • 8.3 Congiguration tools : tools/
    • 8.4 Summary
    • 8.5 Meeting Videos
      • 8.5.1 Cohort 1
      • 8.5.2 Cohort 2
      • 8.5.3 Cohort 3
      • 8.5.4 Cohort 4
  • III Package metadata
  • 9 DESCRIPTION
    • DESCRIPTION File
    • Example DESCRIPTION File
    • Title
    • Description
    • Title & Description Example
    • On CRAN
    • Version
    • Author: who are you?
    • Authors@R in Practice
    • Multiple authors
    • URL and BugReports
    • License
    • Imports & Suggests
  • usethis::use_package()
    • Dependencies
    • Depends and Linking to
    • An R version gotcha
    • Other fields
    • Custom fields
    • What you edit vs. what other tools edit
    • Meeting Videos
      • Cohort 1
      • Cohort 2
      • Cohort 3
      • Cohort 4
  • 10 Dependencies: Mindset and Background
    • 10.1 When should you take a dependency?
      • 10.1.1 Dependencies are not equal
      • 10.1.2 Prefer a holistic, balanced, and quantitative approach
      • 10.1.3 Dependency thoughts specific to the tidyverse
      • 10.1.4 Whether to Import or Suggest
    • 10.2 Namespace
      • 10.2.1 Motivation
      • 10.2.2 The NAMESPACE file
    • 10.3 Search path
      • 10.3.1 Function lookup for user code
      • 10.3.2 Function lookup inside a package
    • 10.4 Attaching versus loading
      • 10.4.1 Whether to Import or Depend
    • 10.5 Meeting Videos
      • 10.5.1 Cohort 1
      • 10.5.2 Cohort 2
      • 10.5.3 Cohort 3
      • 10.5.4 Cohort 4
  • 11 Dependencies: In Practice
    • 11.1 Confusion about Imports
    • 11.2 NAMESPACE Workflow
      • 11.2.1 General Workflow
    • 11.3 Package is listed in Imports
      • 11.3.1 In code below R/
      • 11.3.2 How to not use a package in Imports
      • 11.3.3 In test code
      • 11.3.4 In examples and vignettes
    • 11.4 Package is listed in Suggests
      • 11.4.1 In code below R/
      • 11.4.2 In test code
      • 11.4.3 In examples and vignettes
    • 11.5 Package is listed in Depends
      • 11.5.1 In code below R/ and in test code
      • 11.5.2 In examples and vignettes
    • 11.6 Package is a nonstandard dependency
      • 11.6.1 Config/Needs/* field
    • 11.7 Export
      • 11.7.1 What to export
      • 11.7.2 What not to export
    • 11.8 Re-exporting
    • 11.9 Imports and exports related to S3
    • 11.10 Meeting Videos
      • 11.10.1 Cohort 1
      • 11.10.2 Cohort 2
      • 11.10.3 Cohort 3
      • 11.10.4 Cohort 4
  • 12 Licensing
    • Disclaimer
    • Default = copyright
    • Who is the copyright holder?
    • Major license categories
    • Survey of R licenses
    • By the numbers
    • Seek further guidance
    • Applying a license
    • Key Files
    • Relicensing
    • Code given to you
    • Code from websites
    • Code you bundle: Examples
    • Code you bundle: Giving credit
    • License compatibility
    • Meeting Videos
      • Cohort 1
      • Cohort 2
      • Cohort 3
  • IV Testing
  • 13 Testing basics
    • 13.1 Why Test?
    • 13.2 We already test
    • 13.3 Benefits of automated (unit) testing
    • 13.4 testthat package
    • 13.5 Workflow
    • 13.6 Setup
    • 13.7 Make a test
    • 13.8 Test file structure
    • 13.9 Expect functions
    • 13.10 Expect functions
    • 13.11 Snapshot tests
    • 13.12 Meeting Videos
      • 13.12.1 Cohort 1
      • 13.12.2 Cohort 2
      • 13.12.3 Cohort 3
      • 13.12.4 Cohort 4
  • 14 Designing your test suite
    • What to test?
    • What to test?
    • Direct your test writing efforts
    • Ways to use covr
    • High-level principles for testing
    • Self-sufficient tests
    • With code at top-level
    • Without code at top-level
    • Self-contained tests
    • testthat Limitations
    • Use withr
    • test_that options and environment variables
    • Plan for test failure
    • Create internal functions for testing
    • Testthat helper files
    • Testthat setup files
    • Storing test data
    • Where to write files during testing
    • 14.1 Meeting Videos
      • 14.1.1 Cohort 1
      • 14.1.2 Cohort 2
      • 14.1.3 Cohort 3
      • 14.1.4 Cohort 4
  • 15 Advanced testing techniques
    • Test Fixtures
    • Creating Helper Function
    • Creating Helper Function
    • Avoiding Side Effects
    • Using on.exit() to clean up
    • on.exit() Limitations
    • Using withr::defer() to Clean Up
    • withr::defer() benefits
    • Storing as a Static Test Fixture
    • Loading a Static Test Fixture
    • Helper Defined Inside a Test
    • Custom expectations
    • Skipping a Test
    • Creating your Own Skip Functions
    • Built-in skip() functions
    • Dangers of Skipping
    • skip() in Summary
    • Mocking
    • Tools for Mocking
    • Manage credentials
    • Special considerations for CRAN packages
    • 15.1 Meeting Videos
      • 15.1.1 Cohort 3
      • 15.1.2 Cohort 4
  • V Documentation
  • 16 Function documentation
    • 16.0.1 Why care about object documentation?
    • 16.0.2 roxygen2 advantages
    • 16.1 roxygen2 basics
      • 16.1.1 Documentation workflow
      • 16.1.2 roxygen2 comments, blocks, and tags
      • 16.1.3 Key markdown features
    • 16.2 Title, description, details
      • 16.2.1 Title recommendations
      • 16.2.2 Description recommendation
      • 16.2.3 Details recommendation
    • 16.3 Arguments
      • 16.3.1 Multiple Arguments
      • 16.3.2 Inheriting Arguments
    • 16.4 Return Value
    • 16.5 Examples
      • 16.5.1 Contents
      • 16.5.2 Leave the world as you found it
      • 16.5.3 Errors
      • 16.5.4 Dependencies and conditional execution
      • 16.5.5 Intermixing examples and text
    • 16.6 Re-using documentation
      • 16.6.1 Multiple functions
      • 16.6.2 Inheriting documentation
      • 16.6.3 Child documents
    • 16.7 Past edition notes:
    • 16.8 Object documentation defined
    • 16.9 Object documentation, an overview
    • 16.10 The documentation workflow
    • 16.11 Documenting functions
    • 16.12 Documenting datasets
    • 16.13 Documenting packages
    • 16.14 Documenting classes, generics, and methods
    • 16.15 A note about special characters
    • 16.16 Do repeat yourself
    • 16.17 Text formatting
    • 16.18 Meeting Videos
      • 16.18.1 Cohort 1
      • 16.18.2 Cohort 2
      • 16.18.3 Cohort 3
      • 16.18.4 Cohort 4
  • 17 Vignettes
    • 17.1 Introduction
    • 17.2 Workflow for writing a vignette
    • 17.3 Metadata
    • 17.4 Advice on writing vignettes
    • 17.5 Links
    • 17.6 Filepaths
    • 17.7 How many vignettes?
    • 17.8 Scientific publication
    • 17.9 Special considerations for vignette code
    • 17.10 Article instead of vignette
    • 17.11 How vignettes are built and checked
    • 17.12 R CMD build and vignettes
    • 17.13 R CMD check and vignettes
    • 17.14 Meeting Videos
      • 17.14.1 Cohort 1
      • 17.14.2 Cohort 2
      • 17.14.3 Cohort 3
      • 17.14.4 Cohort 4
  • 18 Other markdown files
    • 18.1 What other documentation should we include in our package?
    • 18.2 README.md
    • 18.3 .Rmd and .md
    • 18.4 usethis::use_readme_rmd()
    • 18.5 NEWS.md
    • 18.6 usethis::use_news_md()
    • 18.7 How to structure your NEWS file
    • 18.8 Get in the habit
    • 18.9 Meeting Videos
      • 18.9.1 Cohort 3
      • 18.9.2 Cohort 4
  • 19 Website
    • This is super easy!
    • We’re so close already!
    • It’s so easy!
    • It’s even easier!
    • Is that it?
    • Hex logos
    • Functions reference
    • Functions reference organisation
    • Functions reference example
    • Vignettes & articles
    • Vignettes & articles organisation
    • Non-vignette articles
    • Development Mode
    • Meeting Videos
      • Cohort 1
      • Cohort 2
      • Cohort 3
      • Cohort 4
  • VI Maintenance and distribution
  • 20 Software development practices
    • 20.1 Recommendations
    • 20.2 Git and Github
    • 20.3 CI/CD
    • 20.4 More GitHub Actions (GHA)
    • 20.5 More info and examples
    • 20.6 Meeting Videos
      • 20.6.1 Cohort 1
      • 20.6.2 Cohort 2
      • 20.6.3 Cohort 3
      • 20.6.4 Cohort 4
  • 21 Lifecycle
    • The challenge
    • Communicating the change
    • When do a package change?
    • Studying to prior versions
    • Package version number
    • Package version number
    • Package version number
    • Package version number
    • Tidyverse package version conventions
    • Changes type: backward compatible
    • Backward compatibility angles
    • Changes type: breaking change
    • Major vs minor vs patch release
    • Package version tools
    • Cons of breaking change
    • Cons resistance to breaking change
    • Package evolution approach
    • Lifecycle stages and badges
    • Setting badges up
    • Setting badges up
    • Setting badges up
    • Deprecating a function
    • Deprecating an argument
    • Deprecation helpers
    • Deprecation helpers
    • Dealing with change in a dependency
    • Dealing with change in a dependency
    • Dealing with change in a dependency
    • Superseding a function
    • Opt-in to the legacy behaviour
    • 21.1 Meeting Videos
      • 21.1.1 Cohort 1
      • 21.1.2 Cohort 2
      • 21.1.3 Cohort 3
      • 21.1.4 Cohort 3 Extra: Jenny Bryan
      • 21.1.5 Cohort 4
  • 22 Releasing to CRAN
    • Preparing for 1st submission
    • Preparing for update
    • Test environments
    • Check results
    • CRAN policies
    • Release
    • Failure
    • Success!
    • Meeting Videos
      • Cohort 1
      • Cohort 2
      • Cohort 3
      • Cohort 4
  • VII Appendices
  • 23 R CMD CHECK
    • 23.1 R CMD CHECK
      • 23.1.1 Results
    • 23.2 Checks
    • 23.3 Meeting Videos
      • 23.3.1 Cohort 3
      • 23.3.2 Cohort 4
  • Published with bookdown

R Packages Book Club

11.9 Imports and exports related to S3

R has multiple object-oriented programming (OOP) systems e.g. S3, S4, R6

If your package owns an S3 class, it makes sense to export a user-friendly constructor function