The Dovetail #10: Updates from The Carpentries Workbench

R for Social Scientists and R for Geospatial Data have entered the Beta Phase

This is the tenth post in a series that we are calling “The Dovetail”, about the transition to The Carpentries Workbench. In this series, we aim to keep members of The Carpentries community abreast of the current news about the Workbench.

If you are interested in participating in discussions around The Carpentries Workbench, head over to our GitHub Discussions forum:

If you have used the workbench and would like to provide feedback, please tell us about your experience.

Beta Phase Updates

Lessons Currently In the Beta Phase

R for Social Scientists and Introduction to Geospatial Raster and Vector Data with R have both entered into the Workbench Beta Phase. The table below shows the status of lessons that are currently in the Beta Phase:

Lesson Stage1 Workbench URL Next Transition Date
Data Analysis and Visualisation in R for Ecologists pre-beta 2022-11-14
R for Social Scientists pre-beta 2022-11-28
Introduction to Geospatial Raster and Vector Data with R pre-beta 2022-11-28

When you visit these pages, if you want to go back to the original lesson, you can click on the workbench beta alert icon at the top of the page:

screencapture of pre-beta alert box on a Workbench site with a yellow caution icon followed by the text "Workbench Beta | Give Feedback | Learn More". The "give feedback" and "learn more" are links in bold.

Alert banner displayed for lessons in Workbench pre-beta stage

For Instructors, here is a video showing what you can expect to see when you go to teach a lesson that is entering the beta phase:

Upcoming Lessons

In the next two weeks, we will see the following lessons enter the beta phase:

During the beta phase, there will be two parallel sites available for 12 weeks, one that is live and will continue to recieve updates and the other that serves as a snapshot as demonstrated in this table:

phase live site snapshot snapshot editable?
pre-beta yes
beta no

A recent question from the Workbench GitHub Discussions asks:

If learners/trainees are presented with a “snapshot” version of a lesson, will clicking that button send them to the snapshot repo? If so, will there be any messaging (banners etc) to redirect them to the correct repo for making contributions?

We value all contributions and do not want the beta phase to introduce a barrier that could prevent a community member from improving a lesson. If someone clicks on a link, makes a suggested change, and opens a pull request, it would be demotivating to find out that the contribution was made to a temporary or frozen version of the lesson. Thus, the answer to this question is that clicking on the “improve this page” or “edit this page” buttons will lead contributors to a landing page that briefly explains the purpose of the phase they entered the lesson through and provides a link to follow to make their suggestion to the lesson.

For example, if the contributor clicks on a link from a snapshot in pre-beta stage where it is editable, but not permanent, they would find the following page:

screenshot of a portion of the workbench lesson episode "Before we Start" that shows it was Last updated on 2022-10-31 with a link that says "Edit this page" screenshot that shows the landing page for the pre-beta stage. Text with a link at the bottom says "You may continue to propose changes to the temporary snapshot of this lesson"

When the reader clicks on the link that says “Edit this page”, the will they would find the pre-beta snapshot page

If a lesson is in the beta stage, where the snapshot is not editable, they would find the following page:

screenshot of a button that says "Improve this page" screenshot that shows the landing page for the beta stage. Text with a link at the bottom says "You may continue to propose changes to the live lesson"

When the reader clicks on the link that says “Improve this page”, the will they would find the beta snapshot page

Updates to The Carpentries Workbench

Since 2022-10-19,

  • {sandpaper} version 0.10.4 -> 0.10.6
    • The move_episode() and set_ family of functions will now print the command to use if the user calls the function without write = TRUE
  • {pegboard} 0.3.2
    • no updates :)
  • {varnish} 0.2.6 -> 0.2.8
    • Bugs in the Workbench beta phase links have been fixed
    • Links to edit pages on GitHub are now directed to a page that first explains the purpose of the beta phase.

To update your local Workbench installation, open R and use the following code:

# Enable repository from carpentries
options(repos = c(
  ropensci = '',
  CRAN = ''))
# Download and install sandpaper in R
install.packages(c('tinkr', 'pegboard', 'sandpaper', 'varnish'))

Upcoming and Current Lessons in Workbench Beta

List of Lessons to enter Workbench Beta in 2022

Lesson Pre-Beta Beta Pre-release
datacarpentry/R-ecology-lesson—Data Analysis and Visualization in R for Ecologists (✅ approved by maintainers) 2022-10-17 2022-11-14 2023-01-23
datacarpentry/r-socialsci—R for Social Scientists (✅ approved by maintainer) 2022-10-31 2022-11-28 2023-02-06
datacarpentry/r-raster-vector-geospatial—Introduction to Geospatial Raster and Vector Data with R (✅ approved by maintainers) 2022-10-31 2022-11-28 2023-02-06
datacarpentry/OpenRefine-ecology-lesson—Data Cleaning with OpenRefine for Ecologists (✅ approved by maintainer) 2022-11-07 2022-12-05 2023-02-13
librarycarpentry/lc-shell—Library Carpentry: The UNIX Shell (✅ approved by maintainers) 2022-11-14 2022-12-12 2023-02-20
carpentries/instructor-training—Instructor Training (✅ approved by maintainers) 2022-11-28 2023-01-09 2023-03-06
datacarpentry/python-ecology-lesson-es—Análisis y visualización de datos usando Python (✅ approved by maintainers) 2022-12-05 2023-01-16 2023-03-13

Community Lessons


Tips and Tricks for Using The Workbench

This tip is for folks who are working on lessons that use R Markdown.

This tip will show you how to use the package cache to debug a problem in your lesson without changing your default R package library.

Lessons that use the Workbench automatically use the {renv} package to manage lesson dependencies without modifying the state of your default R package library. This is different than the styles version of the lessons where you would be forced to update the packages in your global package library. In a lesson, the lockfile for this package cache lives in renv/profiles/lesson-requirements/renv.lock.

Now imagine that there is a mysterious error in your lesson. Take for example PR#378 for one of the lessons that was released into pre-beta today. This error happened because there was a change in a package that was used. This led to a problem with some of the plotting commands where there would be an error that looked something like this:

Error in FUN(X[[i]], ...): object 'HARV_RGB_Ortho.3' not found

There are two ways to diagnose the error:

Solution 1: copy files and use renv

You can create a new folder outside of your lesson and copy the renv.lock file into that folder along with the data and files from the episodes/ folder. When you open R inside that folder type:


Once you have that, you can run through the commands until you get to the error.

Solution 2: use work_with_cache()

I wrote the work_with_cache() function in the {sandpaper} package to temporarily allow me to use the versions in the package cache while I was working on the transition workflow. It allowed me to quickly access packages to build the lesson without having to reinstall them to my default library.

To debug, I open the R Markdown file that was giving me trouble and set my working directory to site/built where all of the intermediate Markdown output is rendered. After that I call work_with_cache() placing the output in a variable called “done”.

done <- work_with_cache() # loads the lesson-requirements profile

Once I do this, My prompt looks like this:

* (lesson-requirements) Project '/path/to/r-raster-vector-geospatial' loaded. [renv 0.16.0]
ℹ call `done()` when you are finished with the session.


And then I can walk through the R Markdown document until I hit the error and begin exploring. When I find the solution, I can fix it in the document and then restore my session by calling done(), which is a function that work_with_cache() created to finalise the session and return you to your previous state.

done() # detaches the lesson-requirements profile, allowe me to access my default library
  1. The Workbench Beta Phase is divided into three distinct stages, read more at

Dialogue & Discussion

Comments must follow our Code of Conduct.

Edit this page on Github