Skip to main content

Set up course infrastructure

1 Initialize the course with init_course()

The init_course() function is the first step to creating a course. It creates a new R project for the course, saves some metadata about the course in a .csv (metadata_course.csv) for later reference, installs the Quarto website structure and theme template, and (by default) sets up Git/GitHub and automatic publishing. This function has eleven arguments. The course information can be supplied either as individual arguments or all at once in a single object, course_info (see Supplying course info as a table or list). When using individual arguments, only course_proj is mandatory:

  • course_proj is the desired name for the course project repository, and will also drive the course’s eventual home on the interwebs. We recommend a format like yyyy-mm-<course type>, such as 2024-10-coreR or 2024-06-delta. Characters other than letters, numbers, _ and - are replaced with _ (with a warning).
  • course_org is the GitHub organization (or GH user) where the course project will live. Defaults to "nceas-learning-hub".
  • course_title is a brief, descriptive title for the course. If left blank, defaults to the same as course_proj.
  • course_desc is a brief (~ 1 sentence) description of the course content. This is stored in the course metadata but currently not otherwise used. If left blank, defaults to the same as course_title.
  • course_dates is a text field containing the dates of the course, in whatever format. If left blank, no dates will be recorded.
  • setup_github (default TRUE) initializes the course as a Git-tracked project, makes an initial commit, creates a GitHub repository named course_proj in the organization course_org, and sets up publishing (see Publish the course). Set to FALSE to skip these steps and handle Git/GitHub yourself.
  • template selects the stylistic template, which defines the default index page, banner colors, hex logo, etc.: "lh" (default) for Learning Hub; "adc" for Arctic Data Center; "delta" for Delta Stewardship Council; "corer" for coreR.
  • package is the lessons package that supplies the Quarto structure and index page files. Defaults to "lhLessons"; currently a placeholder for potential future custom lesson packages.
  • loc is the desired location where the new course will be created. Defaults to the current working directory. The location must not be inside an existing Git repository - this is checked before anything is created, and if it is, init_course() stops with an error. If you are currently working in an existing Git-tracked R project, some options:
    • Close the current project; this should leave you in the default location for projects you’ve set in RStudio. Then it should be fine to use loc = '.' (default).
    • Keep the current project open, but set loc = '..' to create the new course one level up, parallel to your current project.
    • Define some custom location and set loc to that directory.
  • quiet (default TRUE) controls whether progress and diagnostic messages are shown. Set quiet = FALSE to see details.
  • course_info (optional) is an object holding all of the course information, to be used instead of the individual arguments above: either a one-row data frame whose column names match the argument names, or a named list whose names match the argument names. See below for details.

The function invisibly returns the full path to the new course project. With the default quiet = TRUE, the new project is activated automatically; with quiet = FALSE the instructor is instead prompted (y/n) whether to open the new project. Either way, the instructor is advised to close the current project and open or activate the new course project directly.

After this step, the course has structure but no lessons. We’ll fix that in the next step!

1.1 Supplying course info as a table or list

Instead of typing each argument, you can pass all of the course information in the course_info argument, e.g., a table you maintain as a .csv and read in with your preferred function. The rules:

  • course_info must be a one-row data frame whose column names match the argument names, or a named list whose names match the argument names.
  • course_proj is required. Any other argument that is missing from course_info, or NA in course_info (e.g., a blank .csv cell), gets its default value.
  • Names in course_info that are not arguments of init_course() cause an error.
  • Supplying individual arguments alongside course_info also causes an error - use one approach or the other.
  • setup_github and quiet may be given as TRUE/FALSE or as text such as "TRUE" (handy when reading from a .csv).
ExampleExample

From a data frame (or a one-row .csv read in with, e.g., read.csv() or readr::read_csv()):

course_df <- data.frame(course_proj  = '2024-10-coreR',
                        course_title = 'CoreR',
                        course_desc  = 'CoreR course offered at NCEAS in Oct 2024',
                        course_dates = 'Oct. 6 - 10, 2024')
init_course(course_info = course_df)

The {lhCore} package includes an example table, lhCore::test_course, showing the expected layout: one row, one column per argument. Any column can be left out, or set to NA, to use that argument’s default.

lhCore::test_course
  course_proj         course_org course_title                               course_desc
1 test_course nceas-learning-hub        CoreR CoreR course offered at NCEAS in Oct 2024
  course_dates setup_github template   package loc quiet
1 October 2024         TRUE    corer lhLessons   .  TRUE

Note that the example has setup_github = "TRUE", which will create a GitHub repository. To try it out locally, change that to "FALSE" first:

test_df <- lhCore::test_course
test_df$setup_github <- "FALSE"
init_course(course_info = test_df)

Or from a named list:

init_course(course_info = list(course_proj = '2024-10-coreR', template = 'corer'))
Warning

The course files will be pulled from the version of {lhLessons} package that the instructor currently has installed. We recommend reinstalling the package (remotes::install_github('nceas-learning-hub/lhLessons')) before running this function to make sure you have the latest version!

ExampleExample
init_course(course_proj = '2024-06-delta', 
            course_title = 'NCEAS coreR for Delta Science Program', 
            course_desc = 'As part of a collaboration between NCEAS and the 
                           Delta Science Program, this course has been adapted 
                           from NCEAS coreR course, an in-person immersion in R 
                           programming for environmental data science.',
            course_dates = 'June 10 - 13, 2024', 
            template = 'delta',
            loc = '..')

With quiet = FALSE, the instructor will see messages outlining the steps and the resulting metadata, and recommended next steps such as:

To render the course book, restart RStudio to activate the Build tab.
Recommended next steps: 
  • Edit the index.qmd to ensure it accurately describes the course
  • Use `search_lessons()` to see the lesson catalog from the lesson package
  • Use `setup_lessons(<lessons>)` to install the lessons in the course

2 What init_course() installs

Course structure is set up internally by init_course() (the helper setup_course_structure() is not exported, so it is not called directly by the instructor). Here’s what gets installed:

  • metadata_course.csv, holding the course project name, organization, title, description, and dates.
  • A _quarto.yml file that creates the structure of the course site, populated with course info from the metadata. It contains placeholders (# START SESSIONS, # SESSION_LINKS, # END SESSIONS) where setup_lessons() will later insert the lesson sequence.
  • An index.qmd file with boilerplate text based on the selected template. This can (and should) be edited to provide specific info on the new course.
  • An _extensions folder with CSS information and image files to control the appearance of the site according to the selected template, such as the header bar at the top, font faces, sizes, colors…
  • Other miscellaneous course files from the lessons package (e.g., a 404.qmd).
  • If setup_github = TRUE: a .gitignore and a .github folder with a GitHub Actions workflow to auto-publish the site whenever a new commit is pushed to GitHub (see Publish the course).

2.1 Editing the index.qmd

Edit this file to your heart’s content. You can modify the title in the YAML header, but leave the rest of the header in place. The text of the page is specific to this course. Some boilerplate text is already in place, but you may wish to edit specific learning objectives, schedule, and details about the course book to reflect the needs of the course.

2.2 Linking to Git and GitHub

With the default setup_github = TRUE, init_course() handles the Git and GitHub setup. This requires that your Git user.name and user.email are already configured (the function stops with an error otherwise), and that you have write privileges to the GitHub organization.

If Git/GitHub are not (fully) set up - e.g., setup_github = FALSE - the function checks and prints reminders such as:

This project does not seem to be a Git repository.  You might want to:
  • Use `usethis::use_git()` to set up your project as a Git-tracked project, and then...
  • Use `usethis::use_github(organisation = 'nceas-learning-hub')` to connect the project with Github!

Follow those directions, answering the prompts after each function call. Don’t overlook the organisation = 'nceas-learning-hub' argument (note the British spelling), otherwise it will be linked to your user account.