Skip to main content

The {lhCore} package

Course development with {lhCore}

The {lhCore} package and its sister package, {lhLessons}, were developed to make it easy for a course designer/instructor to set up a course using materials from the NCEAS Learning Hub.

NoteTo install:

You will need to install both {lhCore} (for functionality) and {lhLessons} (for content):

remotes::install_github('nceas-learning-hub/lhCore')
remotes::install_github('nceas-learning-hub/lhLessons')

1 What does {lhCore} do?

The {lhCore} package has a few key functions:

  • init_course() initializes a course by setting up a new repository, including a style template and Quarto website structure, sets up the repository for Git/GitHub functionality, and sets up automatic publication to GitHub Pages.
  • setup_lessons() copies selected lessons from the {lhLessons} package into the course repository and sets up the structure of the course as a Quarto website.
Note

The {lhCore} functions that create or change a course (init_course(), setup_lessons(), update_lessons(), checkin_lessons()) are designed to be run interactively, from the R console, because they ask for confirmation along the way. Running them from a script or other non-interactive session produces an error (unless the option lhCore.allow_noninteractive is set to TRUE).

Additional functions to help with setting up a course:

  • update_lessons() will update lessons (or revert to older ones) based on instructor selection of a version of the {lhLessons} package.
  • search_lessons() provides available lesson names (searchable by name or by topic tag) based on the installed version of the {lhLessons} package.
  • compare_diffs() identifies differences between the course versions of lessons and the parent lessons in the lhLessons repository, e.g., edits made while teaching the course or new lessons created for the course.
  • checkin_lessons() allows the instructor to push edited and new lessons back to the lhLessons repository, in a branch specific to the instructor’s course. The updates in the branch can then be merged with the main branch through a code review process.

2 What does {lhLessons} do?

The {lhLessons} package has essentially no user-facing functionality (just a couple of minor helper functions), but instead houses lessons as Quarto documents, along with templates and support files to construct a course. Why is this separate from {lhCore}?

  • First, it seemed like a good idea to allow the course lesson content to be version-controlled separately from the package containing the functions.
  • Second, this allows for other instructors or organizations to create their own lesson content or structure that can play nicely with the {lhCore} functionality - for example, if the curriculum for the Delta Stewardship Council diverged from the {lhCore} curriculum, we could create a {deltaLessons} package to contain different content, and even a different style or format.
  • Third, it allows an instructor to choose different versions of the content and perhaps update an old course, if the materials for the old course are significantly out of date, using GitHub release tags that refer to different versions of the content related to specific points in time.

3 Why {lhCore}?

3.1 Where we’re at

For years NCEAS has been offering courses through the Learning Hub, the Arctic Data Center, the Delta Stewardship Council, and working group workshops, among other efforts. The course offerings include lessons on collaboration with Git and GitHub, reproducibility with R and RStudio, and fundamental techniques of working with all kinds of data. As of October 2024, these courses have been built in the nceas-training repository of the NCEAS GitHub organization, with each course built on a separate branch. These courses are rendered by GitHub actions set up in the repro-research-course repository, where the courses are linked to an NCEAS URL, and archived in the repo.

This system has worked for years, and the lesson offerings have grown organically over time to over a hundred different .Rmds and .qmds. But setting up a new course is tricky - after establishing a desired curriculum, an instructor needs to manually identify relevant lessons from a long list of files with inconsistent file naming, and then needs to manually set up files to link to these lessons, all within a new branch to avoid affecting other lessons (and to work with the Github actions to publish the course). The lesson catalog contains duplicates, updated versions, deprecated lessons, etc. The instructor then frequently has to make edits to the lessons, on that separate branch. As of this writing, there are 43 separate branches, each likely holding improvements and valuable edits, with no well defined process to thoughtfully incorporate the best of those ideas into the latest and greatest versions of each lesson.

3.2 Where we’re going

By setting up a new NCEAS Learning Hub organization, and designing the {lhCore} and {lhLessons} packages, we can accomplish a few things:

  1. Make it far easier to set up a typical Learning Hub training by automating and streamlining many of the setup steps.
  2. Curate the course offerings and try to outline some standards for adding additional course offerings, for consistency.
  3. Use distinct repositories to host each course, rather than branches all held within a single repository. This seems more in line with how we teach the use of Git and GitHub.
  4. Update course lessons so that old course offerings can be brought into line with current course offerings (or lessons can be reverted to old versions).
  5. Use GitHub Pages to easily and automatically publish courses to the web.
  6. Facilitate post-course review of edits and updates to course materials, to better share wisdom and ideas across the various spokes of the NCEAS Learning Hub.

4 Acknowledgments

Lesson style upgrades: Nick J. Lyon, Casey O’Hara, Jim Regetz

Custom callouts and style tips: Tavares, H., van Rongen, M., Cardona, A. (2024). Course Development Guidelines. https://cambiotraining.github.io/quarto-course-template/

O’Hara, C. (2026). lhCore: Resources and Functions to Build a Learning Hub Course. R package version 0.1.0. https://github.com/nceas-learning-hub/lhCore.

NCEAS Learning Hub (2026). lhLessons: NCEAS Learning Hub Lessons Package. https://nceas-learning-hub.github.io/lh_packages.

Ben Bolker, Julien Brun, Amber E. Budden, Angel Chen, S. Jeanette Clark, Samantha Csik, Halina Do-Linh, Stephanie Hampton, Natasha Haycock-Chavez, Allison Horst, Matt Jones, Samantha Katz, Julie Lowndes, Nick J. Lyon, Erin McLean, Bryce Mecum, Casey O’Hara, Deanna Pennington, Karthik Ram, Jim Regetz, Tracy Teal, Camila Vargas Poulsen, Daphne Virlar-Knight, Leah Wasser