rostools / r-pkg-intro

An introductory course on building R packages

r-pkg-intro: An introductory course on building R packages

Description

Reproducibility and open scientific practices are increasingly being requested or required of scientists and researchers, but training on these practices has not kept pace. This course intends to help bridge that gap and covers the fundamentals and workflow of building an R package.

This repository contains the lesson, lecture, and assignment material for the course, including the website source files and other associated course administration files.

For more detail on the course, check out the welcome page.

Instructional Design

The lectures and lessons in this course and educational resource are designed to be presented primarily with a participatory live-coding approach. This involves an instructor typing and running code in RStudio in front of the class, while the class follows along using their own computers. Challenges are interspersed in the lesson material, allowing participants to collaboratively work on smaller coding problems for a few minutes. All lesson materials are provided ahead of time on the course website for participants to refer to during lectures.

Lesson content

The teaching material is found mainly in these locations:

• index.Rmd: Contains the overview of the course.
• preamble/ folder: Contains the files necessary for use before the course, for instance the syllabus, schedule, and pre-course tasks.
• sessions/ folder: Contains the files used during the course (e.g. code-along material).
• appendix/ folder: Contains the files used to support the course, such as pre-course tasks, code of conduct, resources, and instructions for instructors.
• slides/: The lecture slides are rendered into HTML slides from Markdown.

The website is generated from Quarto, so it follows the file and folder structure conventions from that package.

Contributing

If you are interested in contributing to the course material, please refer to the contributing guidelines. For guidelines on how to be a helper or instructor, check out the For Instructors page.

Please note that the project is released with a Contributor Code of Conduct. By contributing to or being involved in this project, you agree to abide by its terms.

Re-use

The course is largely designed to be taught in the order given, as each session builds off of the previous ones. The easiest way to use this material is to use it as-is, making use of the tips and instructions found throughout this page. The only thing you might want to make as your own would be the slides, however, they are also good enough to use on their own too.

But if you want to customize a bit more, the best approach is to fork the repository into your own GitHub account and modify it to fit your needs from there. The website is built automatically with GitHub Actions and then published as a website through Netlify. More detail on how to build your own website from the material is outside the scope of this document but you can find more information on Quarto's Publishing page.

To help with general admin tasks of running the course, there is the r3admin R package. For details of the license and acknowledgement of content used from sources, see the license document.

<!--
### How to cite the material

Please cite the material as:

> TODO: Update

Or as BibTeX:

TODO: Update
-->

r-pkg-intro's Issues

Draft of learning objectives for introduction session

Add CODEOWNERS so everyone gets tagged with PRs

Use the GitHub team, rather than individuals.

Add all contributors to rostools and in team for this repo

Draft of learning objectives for function documentation

Overall task tracking and roadmap

Check out the Project Board to have a bigger picture overview of what needs to be done, what needs to be reviewed, and who works on what.

Who does what

Person	Session
preamble/syllabus.qmd	@lwjohnst86
sessions/automated-testing.qmd	@signekb
sessions/creating-website.qmd	@omarsilverman
sessions/debugging.qmd	@Aastedet
sessions/documenting-functions.qmd	@AndersAskeland
sessions/function-development.qmd	@AndersAskeland
sessions/introduction.qmd	@lwjohnst86
sessions/package-setup.qmd	@lwjohnst86
sessions/testing.qmd	@signekb
sessions/what-next.qmd	@lwjohnst86
sessions/writing-guides.qmd	@rmj822
appendix/project.qmd	@lwjohnst86

General roadmap with estimated timeline

This timeline is assuming maybe 2-3 days of work a month, potentially less.

Month	Milestones
Jan-Feb	Reading through current session material, learning about your session's topic (starting with R Packages), learning to use Pull Requests to contribute, and write/revise a basic draft of session-specific learning objectives
Mar	Continue learning about your session's topic, get your learning objectives reviewed and then refine them
Apr	Start creating exercises that will achieve the learning objectives
May-June	Continue refining exercises, get them reviewed and refine them
Aug-Nov	Fill in all the prerequisite material needed to complete each exercise
Dec	Edit, revise, and review the entire course material
Jan 2025	Run the course somewhere?

Contributing tips

• In general, create a pull request for each milestone (e.g. after finishing your learning objective, submit a Pull Request). Fewer changes made per Pull Request (a "small PR") are easier to review, approve, and merge, so in general make fewer changes for every PR.

• If using RStudio, use the usethis::pr_* helper workflow. See the instructions on the usethis package website. The functions to use would be:

  # Make sure to have a GitHub Token created:
  # usethis::create_github_token()
  
  # Add the token so R knows about it
  gitcreds::gitcreds_set()
  
  # Create a new branch
  pr_init("name-of-new-branch")
  
  # Make and commit changes
  
  # Push your changes to GitHub and make a Pull Request
  pr_push()
  
  # Fill in the details of the Pull Request page that opened up
  
  # Stop work on your local branch by moving back to the main branch
  pr_pause()
  
  # After your PR has been merged, run these two commands
  pr_resume() 
  # Select your branch that was just merged
  pr_finish()
  

Function Development - Brainstorm

Previous section

The preceding section is: sessions/package-setup.qmd.

During this section, participants learn about setting up and preparing the R environment for creating packages.

Learning outcome

Overarching goal

• Learn to create and structure functions that can be effectively utilized within R packages.

Sub goals

• Develop code interactively (exercise 1) and transform it into robust functions (exercise 2).
• Understand and apply function abstraction to enhance modularity and reusability (exercise 3).
• Master dependency management within package development (exercise 4).
• Implement process control and error handling to ensure function reliability (exercise 5).

Exercises

The following exercises are designed to develop a comprehensive understanding of function development in relation to R package creation. The order should be adjusted based on the flow of the course.

Exercise 1 - Write Code/Script

Objective: Write a script that addresses a specific problem, showcasing the practical application of R code.

• Provide a specific scenario or problem statement for participants to solve.
• Offer a ready script/code snippet if time is short.

Note: If previous sections create functions/code - use this.

Exercise 2 - Rewrite Code into a Function

Objective: Convert the given script into a function.

• Emphasize aspects such as function naming, argument structuring. Documentation comes later.
• Code should be hard coded

Exercise 3 - Abstractions

Objective: Evolve the function by abstracting the action of extracting elements, enhancing its flexibility and reusability.

• Use examples to demonstrate the transition from specific implementations to abstracted functionalities.
• Place function in utils?

Exercise 4 - Dependency Management

Objective: Learn to accurately declare and manage package dependencies.

• Introduce and explain the use of Imports, Depends, and Suggests in the DESCRIPTION file.
• Provide examples of how to manage dependencies correctly and the consequences of poor management.
• Attach package/function?

Exercise 5 - Error Handling/Control Flow

Objective: Incorporate error checking and control structures within functions.

• Detail the use of stop(), warning(), and message() for providing feedback at various levels.

For example:

• There is not title/author/etc.
• Input is not "correct"/text.

Extra Exercise - Extending Generic Functions

• Custom print method?
• Probably too complex.

Optional Reading

• Control flow - Loops. Are often needed in functions that interact with other systems (i.e. servers, http requests, etc.)

Next Section

Documentation

Add Action to build and deploy the website

Steps to creating teaching material

• Make (draft) overall learning outcome
• Decide on project/hypothetical example they could complete that demonstrates that they achieved the learning outcome (e.g. like the team project in the intro R course).
• Within each session, create an overall learning outcome along with a set of learning objectives that work toward the learning outcome (see Bloom's Taxonomy for helping write these)
• After the learning objectives are created, create a set of exercises (~1 per in-class hour) that support the learning objectives
• Finally, fill in all the content around the exercises with material that will allow the participants to complete the exercises

Draft of learning objectives for function development

Function documentation - Brainstorm

Previous section

The preceding section is: sessions/function-development.qmd.

In this section, participants learn how to create functions that can be incorporated into R package.

Learning outcome

Overarching goal

• Learn why and how one document R functions utilizing {roxygen2}.

Sub goals

• Understand why function documentation is crucial for a package (exercise 1).
• Learn to document functions using {roxygen2} (exercise 2).
• Learn how to write and create examples within documentation (exercise 3).
• Familiarize with and apply various Roxygen tags (exercise 4).

Exercises

During exercise, improve previously written functions with what is learned.

Exercise 1 - The Importance of Documentation

Discuss why detailed documentation is vital. Focus on its impact on code readability, maintenance, and collaboration.

Exercise 2 - Documenting Functions with {roxygen2}

• Introduce the basics of using Roxygen for function documentation, covering essential aspects like the function's purpose, parameters (@param), return values (@return), and how to make a function available to users (@export).
• Explain export and when to use it.

Exercise 3 - Writing Effective Examples

• Learn about creating examples
• I am unsure: Is this not also used in/as unit testing?

Exercise 4 - Additional Roxygen Tags to Know

• Learn about additional Rozygen tags (reading exercise?)
  • @seealso: For linking related documentation or resources.
  • @family: To group related functions within the documentation.
  • @references: For adding citations to external sources or literature.
  • @note: To provide additional context or information.
  • @warnings: To alert users about any potential caveats or issues.
  • @inheritParams

Next...

??? Is it debugging?

Draft of learning objectives for Package Setup session