Package 'learnr'

Description

Create options for users when used in question_checkbox() and question_radio() learnr questions. For question_text() and question_numeric(), the individual answers aren't directly presented to students, but their values can be used in determining if the student submitted the correct answer. For flexible feedback from checkbox, text, and numeric questions, answer_fn() can be used to provide a function that evaluates the student's submission and returns a custom result.

Usage

answer(text, correct = FALSE, message = NULL, label = text)

answer_fn(fn, label = NULL)

Arguments

Value

Returns a list with the "tutorial_question_answer" class.

Functions

• answer(): Create an answer option

• answer_fn(): Evaluate the student's submission to determine correctness and to return feedback.

Examples

answer(32, correct = FALSE)
answer(42, correct = TRUE, message = "The meaning of life.")

Description

List the tutorials that are currently available via installed R packages. Or list the specific tutorials that are contained within a given R package.

Usage

available_tutorials(package = NULL)

Arguments

Value

available_tutorials() returns a data.frame containing "package", "name", "title", "description", "package_dependencies", "private", and "yaml_front_matter".

Examples

available_tutorials(package = "learnr")

Description

Helper method to communicate that the user's submission was correct or incorrect. These functions were originally designed for developers to create question_is_correct() methods for custom question types, but they can also be called inside the functions created by answer_fn() to dynamically determine the result and message provided to the user.

Usage

correct(messages = NULL)

incorrect(messages = NULL)

mark_as(correct, messages = NULL)

Arguments

Value

Returns a list with class learnr_mark_as to be returned from the question_is_correct() method for the learnr question type.

See Also

answer_fn()

Examples

# Radio button question implementation of `question_is_correct`
question_is_correct.radio <- function(question, value, ...) {
  for (ans in question$answers) {
    if (as.character(ans$option) == value) {
      return(mark_as(ans$correct, ans$message))
    }
  }
  mark_as(FALSE, NULL)
}

Description

Method to disable all html tags to not allow users to interact with the html.

Usage

disable_all_tags(ele)

Arguments

Value

An htmltools HTML object with appended class = "disabled" and disabled attributes on all tags.

Examples

# add an href to all a tags
disable_all_tags(
  htmltools::tagList(
    htmltools::a(),
    htmltools::a()
  )
)

Description

Copy all items from the environment to a new environment. By default, the new environment will share the same parent environment.

Usage

duplicate_env(envir, parent = parent.env(envir))

Arguments

Value

A duplicated copy of envir whose parent env is parent.

Examples

# Make a new environment with the object 'key'
envir <- new.env()
envir$key <- "value"
"key" %in% ls() # FALSE
"key" %in% ls(envir = envir) # TRUE

# Duplicate the envir and show it contains 'key'
new_envir <- duplicate_env(envir)
"key" %in% ls(envir = new_envir) # TRUE

Description

Register an event handler on a per-tutorial basis. Handlers for an event will be fired in the order that they were registered.

Usage

event_register_handler(event, callback)

Arguments

Details

In most cases, this will be called within a learnr document. If that is the case, then the handler will exist as long as the document (that is, the Shiny application) is running.

If this function is called in a learnr .Rmd document, it should be in a chunk with context="server-start". If it is called with context="server", the handler will be registered at least two times (once for the application as a whole, and once per user session).

If this function is called outside of a learnr document, then the handler will persist until the learnr package is unloaded, typically when the R session is stopped.

Value

A function which, if invoked, will remove the callback.

Description

Lifecycle: experimental

Usage

external_evaluator(
  endpoint = getOption("tutorial.external.host",
    Sys.getenv("TUTORIAL_EXTERNAL_EVALUATOR_HOST", NA)),
  max_curl_conns = 50
)

Arguments

Value

A function that takes an expression (expr), timelimit, exercise and session.

Description

Tutorial state storage handler that uses the filesystem as a backing store. The directory will contain tutorial state data partitioned by user_id, tutorial_id, and tutorial_version (in that order)

Usage

filesystem_storage(dir, compress = TRUE)

Arguments

Value

Storage handler suitable for options(tutorial.storage = ...)

Description

Mark a question as finalized by adding a question-final class to the HTML output at the top level, in addition to disabling all tags with disable_all_tags().

Usage

finalize_question(ele)

Arguments

Value

An htmltools HTML object with appropriately appended classes such that a tutorial question is marked as the final answer.

Examples

# finalize the question UI
finalize_question(
  htmltools::div(
    class = "custom-question",
    htmltools::div("answer 1"),
    htmltools::div("answer 2")
  )
)

Description

Notes:

• If custom question types are created, custom s3 formating methods may be implemented as well.

• Due to the shiny runtime of questions, a text representation of quizzes, questions, and answers will be presented.

Usage

## S3 method for class 'tutorial_question_answer'
format(x, ..., spacing = "")

## S3 method for class 'tutorial_question'
format(x, ..., spacing = "")

## S3 method for class 'tutorial_quiz'
format(x, ...)

## S3 method for class 'tutorial_question'
print(x, ...)

## S3 method for class 'tutorial_question_answer'
print(x, ...)

## S3 method for class 'tutorial_quiz'
print(x, ...)

Arguments

See Also

quiz, question, answer

Examples

ex_question <- question("What number is the letter A in the alphabet?",
  answer("8"),
  answer("14"),
  answer("1", correct = TRUE),
  answer("23"),
  incorrect = "See [here](https://en.wikipedia.org/wiki/English_alphabet) and try again.",
  allow_retry = TRUE
)
cat(format(ex_question), "\n")

Description

Returns information about the current tutorial. Ideally the function should be evaluated in a Shiny context, i.e. in a chunk with option context = "server". Note that the values of this function may change after the tutorial is completely initialized. If called in a non-reactive context, get_tutorial_info() will return default values that will most likely correspond to the current tutorial.

Usage

get_tutorial_info(
  tutorial_path = NULL,
  session = getDefaultReactiveDomain(),
  ...,
  encoding = "UTF-8"
)

Arguments

Value

Returns an ordinary list with the following elements:

• tutorial_id: The ID of the tutorial, auto-generated or from the tutorial$id key in the tutorial's YAML front matter.

• tutorial_version: The tutorial's version, auto-generated or from the tutorial$version key in the tutorial's YAML front matter.

• items: A data frame with columns order, label, type and data describing the items (questions and exercises) in the tutorial. This item is only available in the running tutorial, not during the static pre-render step.

• user_id: The current user.

• learnr_version: The current version of the running learnr package.

• language: The current language of the tutorial, either as chosen by the user or as specified in the language item of the YAML front matter.

See Also

get_tutorial_state()

Examples

if (rmarkdown::pandoc_available("1.4")) {
  tutorial_rmd <- local({
    # Use a temp copy of "Hello learnr" tutorial for this example
    src <- system.file(
      "tutorials", "hello", "hello.Rmd", package = "learnr"
    )
    dest <- tempfile(fileext = ".Rmd")
    file.copy(src, dest)
    dest
  })

  # ---- This is the example! ------------ #
  info <- get_tutorial_info(tutorial_rmd)
  # -------------------------------------- #

  # clean up the temporary Rmd used in this example
  unlink(tutorial_rmd)

  # This is the result of the example
  info
}

Description

As a student progresses through a learnr tutorial, their progress is stored in a Shiny reactive values list for their session (see shiny::reactiveValues()). Without arguments, get_tutorial_state() returns the full reactiveValues object that can be converted to a conventional list with shiny::reactiveValuesToList(). If the label argument is provided, the state of an individual question or exercise with that label is returned.

Calling get_tutorial_state() introduces a reactive dependency on the state of returned questions or exercises unless called within isolate(). Note that get_tutorial_state() will only work for the tutorial author and must be used in a reactive context, i.e. within shiny::observe(), shiny::observeEvent(), or shiny::reactive(). Any logic observing the user's tutorial state must be written inside a context="server" chunk in the tutorial's R Markdown source.

Usage

get_tutorial_state(label = NULL, session = getDefaultReactiveDomain())

Arguments

Value

A reactiveValues object or a single reactive value (if label is provided). The names of the full reactiveValues object correspond to the label of the question or exercise. Each item contains the following entries:

• type: One of "question" or "exercise".

• answer: A character vector containing the user's submitted answer(s).

• correct: A logical indicating whether the user's answer was correct, or a logical NA if the submission was not checked for correctness.

• timestamp: The time at which the user's submission was completed, as a character string in UTC, formatted as "%F %H:%M:%OS3 %Z".

See Also

get_tutorial_info()

Description

One time initialization of R Markdown extensions required by the learnr package. This function is typically called automatically as a result of using exercises or questions.

Usage

initialize_tutorial()

Value

If not previously run, initializes knitr hooks and provides the required rmarkdown::shiny_prerendered_chunk()s to initialize learnr.

Description

knitr::knit_print methods for question and quiz

Usage

## S3 method for class 'tutorial_question'
knit_print(x, ...)

## S3 method for class 'tutorial_quiz'
knit_print(x, ...)

Arguments

Description

This wraps an expression so that it will be executed one time for a tutorial, based on some condition. The first time the condition is true, the expression will be executed; after that, the expression will not be evaluated again.

The execution state is stored so that if the expression is executed, then the user quits the tutorial and then returns to it, the expression will not be executed a second time.

A common use for one_time is to execute an expression when a section is viewed for the first time.

Usage

one_time(session, cond, expr, label = deparse(substitute(cond)))

Arguments

Value

The result of evaluating expr (one_time() is intended to be called within an event handler).

Examples

## Not run: 
# This goes in a {r context="server-start"} chunk

# The expression with message() will be executed the first time the user
# sees the section with ID "section-exercise-with-hint".
event_register_handler("section_viewed",
  function(session, event, data) {
    one_time(
      session,
      data$sectionId == "section-exercise-with-hint",
      {
        message("Seeing ", data$sectionId, " for the first time.")
      }
    )
  }
)



## End(Not run)

Description

Creates a checkbox group tutorial quiz question. The student may select one or more checkboxes before submitting their answer.

Usage

question_checkbox(
  text,
  ...,
  correct = "Correct!",
  incorrect = "Incorrect",
  try_again = "Incorrect. Be sure to select every correct answer.",
  allow_retry = FALSE,
  random_answer_order = FALSE
)

Arguments

Value

Returns a learnr question of type "learnr_checkbox".

See Also

Other Interactive Questions: question_numeric(), question_radio(), question_text(), quiz()

Examples

question_checkbox(
  "Select all the toppings that belong on a Margherita Pizza:",
  answer("tomato", correct = TRUE),
  answer("mozzarella", correct = TRUE),
  answer("basil", correct = TRUE),
  answer("extra virgin olive oil", correct = TRUE),
  answer("pepperoni", message = "Great topping! ... just not on a Margherita Pizza"),
  answer("onions"),
  answer("bacon"),
  answer("spinach"),
  random_answer_order = TRUE,
  allow_retry = TRUE,
  try_again = "Be sure to select all four toppings!"
)

# Set up a question where there's no wrong answer. The answer options are
# always shuffled, but the answer_fn() answer is always evaluated first.
question_checkbox(
  "Which of the tidyverse packages is your favorite?",
  answer("dplyr"),
  answer("tidyr"),
  answer("ggplot2"),
  answer("tibble"),
  answer("purrr"),
  answer("stringr"),
  answer("forcats"),
  answer("readr"),
  answer_fn(function(value) {
    if (length(value) == 1) {
      correct(paste(value, "is my favorite tidyverse package, too!"))
    } else {
      correct("Yeah, I can't pick just one favorite package either.")
    }
  }),
  random_answer_order = TRUE
)

Description

Creates a tutorial question asking the student to submit a number.

Usage

question_numeric(
  text,
  ...,
  correct = "Correct!",
  incorrect = "Incorrect",
  try_again = incorrect,
  allow_retry = FALSE,
  value = NULL,
  min = NA,
  max = NA,
  step = NA,
  options = list(),
  tolerance = 1.5e-08
)

Arguments

Value

Returns a learnr question of type "learnr_numeric".

See Also

Other Interactive Questions: question_checkbox(), question_radio(), question_text(), quiz()

Examples

question_numeric(
  "What is pi rounded to 2 digits?",
  answer(3, message = "Don't forget to use the digits argument"),
  answer(3.1, message = "Too few digits"),
  answer(3.142, message = "Too many digits"),
  answer(3.14, correct = TRUE),
  allow_retry = TRUE,
  min = 3,
  max = 4,
  step = 0.01
)

question_numeric(
  "Can you think of an even number?",
  answer_fn(function(value) {
    if (value %% 2 == 0) {
      correct("even")
    } else if (value %% 2 == 1) {
      incorrect("odd")
    }
  }, label = "Is the number even?"),
  step = 1
)

Description

Creates a radio button tutorial quiz question. The student can select only one radio button before submitting their answer. Note: Multiple correct answers are allowed.

Usage

question_radio(
  text,
  ...,
  correct = "Correct!",
  incorrect = "Incorrect",
  try_again = incorrect,
  allow_retry = FALSE,
  random_answer_order = FALSE
)

Arguments

Value

Returns a learnr question of type "learnr_radio".

See Also

Other Interactive Questions: question_checkbox(), question_numeric(), question_text(), quiz()

Examples

question_radio(
  "Pick the letter B",
  answer("A"),
  answer("B", correct = TRUE),
  answer("C"),
  answer("D"),
  allow_retry = TRUE,
  random_answer_order = TRUE
)

Description

Creates a tutorial question asking the student to enter text. The default text input is appropriate for short or single-line text entry. For longer text input, set the rows and/or cols argument to create a larger text area.

When used with answer(), the student's submission must match the answer exactly, minus whitespace trimming if enabled with trim = TRUE. For more complicated submission evaluation, use answer_fn() to provide a function that checks the student's submission. For example, you could provide a function that evaluates the user's submission using regular expressions.

Usage

question_text(
  text,
  ...,
  correct = "Correct!",
  incorrect = "Incorrect",
  try_again = incorrect,
  allow_retry = FALSE,
  random_answer_order = FALSE,
  placeholder = "Enter answer here...",
  trim = TRUE,
  rows = NULL,
  cols = NULL,
  options = list()
)

Arguments

Value

Returns a learnr question of type "learnr_text".

See Also

Other Interactive Questions: question_checkbox(), question_numeric(), question_radio(), quiz()

Examples

question_text(
  "Please enter the word 'C0rrect' below:",
  answer("correct", message = "Don't forget to capitalize"),
  answer("c0rrect", message = "Don't forget to capitalize"),
  answer("Correct", message = "Is it really an 'o'?"),
  answer("C0rrect ", message = "Make sure you do not have a trailing space"),
  answer("C0rrect", correct = TRUE),
  allow_retry = TRUE,
  trim = FALSE
)

# This question uses an answer_fn() to give a hint when we think the
# student is on the right track but hasn't found the value yet.
question_text(
  "What's the most popular programming interview question?",
  answer("fizz buzz", correct = TRUE, "That's right!"),
  answer_fn(function(value) {
    if (grepl("(fi|bu)zz", value)) {
      incorrect("You're on the right track!")
    }
  }, label = "fizz or buzz")
)

Description

There are five methods used to define a custom question. Each S3 method should correspond to the type = TYPE supplied to the question.

• question_ui_initialize.TYPE(question, value, ...)

  • Determines how the question is initially displayed to the users. This should return a shiny UI object that can be displayed using shiny::renderUI. For example, in the case of question_ui_initialize.radio, it returns a shiny::radioButtons object. This method will be re-executed if the question is attempted again.

• question_ui_completed.TYPE(question, ...)

  • Determines how the question is displayed after a submission. Just like question_ui_initialize, this method should return an shiny UI object that can be displayed using shiny::renderUI.

• question_is_valid.TYPE(question, value, ...)

  • This method should return a boolean that determines if the input answer is valid. Depending on the value, this function enables and disables the submission button.

• question_is_correct.TYPE(question, value, ...)

  • This function should return the output of correct, incorrect, or mark_as. Each method allows for custom messages in addition to the determination of an answer being correct. See correct, incorrect, or mark_as for more details.

• ⁠question_ui_try_again <- function(question, value, ...)⁠

  • Determines how the question is displayed to the users while the "Try again" screen is displayed. Usually this function will disable inputs to the question, i.e. prevent the student from changing the answer options. Similar to question_ui_initialize, this should should return a shiny UI object that can be displayed using shiny::renderUI.

Usage

question_ui_initialize(question, value, ...)

question_ui_try_again(question, value, ...)

question_ui_completed(question, value, ...)

question_is_valid(question, value, ...)

question_is_correct(question, value, ...)

## Default S3 method:
question_ui_initialize(question, value, ...)

## Default S3 method:
question_ui_try_again(question, value, ...)

## Default S3 method:
question_ui_completed(question, value, ...)

## Default S3 method:
question_is_valid(question, value, ...)

## Default S3 method:
question_is_correct(question, value, ...)

Arguments

Value

learnr question objects, UI elements, results or server methods.

See Also

For more information and question type extension examples, please see the Custom Question Types section of the quiz_question tutorial: learnr::run_tutorial("quiz_question", "learnr").

Examples

q <- question(
  "Which package helps you teach programming skills?",
  answer("dplyr"),
  answer("learnr", correct = TRUE),
  answer("base")
)
question_is_correct(q, "dplyr")
question_is_correct(q, "learnr")

Description

Add interactive quiz questions to a tutorial. Each quiz question is executed within a shiny runtime to provide more flexibility in the types of questions offered. There are four default types of quiz questions:

learnr_radio

Radio button question. This question type will only allow for a single answer submission by the user. An answer must be marked for the user to submit their answer.

learnr_checkbox

Check box question. This question type will allow for one or more answers to be submitted by the user. At least one answer must be marked for the user to submit their answer.

learnr_text

Text box question. This question type will allow for free form text to be submitted by the user. At least one non-whitespace character must be added for the user to submit their answer.

learnr_numeric

Numeric question. This question type will allow for a number to be submitted by the user. At least one number must be added for the user to submit their answer.

Note, the print behavior has changed as the runtime is now Shiny based. If questions and quizes are printed in the console, the S3 structure and information will be displayed.

Usage

quiz(..., caption = rlang::missing_arg())

question(
  text,
  ...,
  type = c("auto", "single", "multiple", "learnr_radio", "learnr_checkbox",
    "learnr_text", "learnr_numeric"),
  correct = "Correct!",
  incorrect = "Incorrect",
  try_again = NULL,
  message = NULL,
  post_message = NULL,
  loading = NULL,
  submit_button = rlang::missing_arg(),
  try_again_button = rlang::missing_arg(),
  allow_retry = FALSE,
  random_answer_order = FALSE,
  options = list()
)

Arguments

Value

A learnr quiz, or collection of questions.

See Also

random_praise(), random_encouragement()

For more information and question type extension examples, please see the help documentation for question_methods and view the question_type tutorial: learnr::run_tutorial("question_type", "learnr").

Other Interactive Questions: question_checkbox(), question_numeric(), question_radio(), question_text()

Examples

quiz(
  question("What number is the letter A in the alphabet?",
    answer("8"),
    answer("14"),
    answer("1", correct = TRUE),
    answer("23"),
    incorrect = "See [here](https://en.wikipedia.org/wiki/English_alphabet) and try again.",
    allow_retry = TRUE
  ),

  question("Where are you right now? (select ALL that apply)",
    answer("Planet Earth", correct = TRUE),
    answer("Pluto"),
    answer("At a computing device", correct = TRUE),
    answer("In the Milky Way", correct = TRUE),
    incorrect = paste0("Incorrect. You're on Earth, ",
                       "in the Milky Way, at a computer.")
  )
)

Description

Augment the random phrases available in random_praise() and random_encouragement() with phrases of your own. Note that these phrases are added to the existing phrases, rather than overwriting them.

Usage

random_phrases_add(language = "en", praise = NULL, encouragement = NULL)

Arguments

Value

Returns the previous custom phrases invisibly when called in the global setup chunk or interactively. Otherwise, it returns a shiny pre- rendered chunk.

Usage in learnr tutorials

To add random phrases in a learnr tutorial, you can either include one or more calls to random_phrases_add() in your global setup chunk:

```{r setup, include = FALSE}`r ''`
library(learnr)
random_phrases_add(
  language = "en",
  praise = "Great work!",
  encouragement = "I believe in you."
)
```

Alternatively, you can call random_phrases_add() in a separate, standard R chunk (with echo = FALSE):

```{r setup-phrases, echo = FALSE}`r ''`
random_phrases_add(
  language = "en",
  praise = c("Great work!", "You're awesome!"),
  encouragement = c("I believe in you.", "Yes we can!")
)
```

Examples

random_phrases_add("demo", praise = "Great!", encouragement = "Try again.")
random_praise(language = "demo")
random_encouragement(language = "demo")

Description

Random praises and encouragements sayings to compliment your question and quiz experience.

Usage

random_praise(language = NULL)

random_encouragement(language = NULL)

Arguments

Value

Character string with a random saying

Examples

random_praise()
random_praise()

random_encouragement()
random_encouragement()

Description

Run a tutorial provided by an installed R package.

Usage

run_tutorial(
  name = NULL,
  package = NULL,
  ...,
  shiny_args = NULL,
  clean = FALSE,
  as_rstudio_job = NULL
)

Arguments

Value

Starts a Shiny server running the learnr tutorial.

See Also

safe and available_tutorials

Examples

# display all "learnr" tutorials
available_tutorials("learnr")

# run basic example within learnr
## Not run: 
run_tutorial("hello", "learnr")

## End(Not run)

Description

When rendering (or running) a document with R markdown, it inherits the current R Global environment. This will produce unexpected behaviors, such as poisoning the R Global environment with existing variables. By rendering the document in a new, safe R environment, a vanilla, rendered document is produced.

Usage

safe(expr, ..., show = TRUE, env = safe_env())

Arguments

Details

The environment variable LEARNR_INTERACTIVE will be set to "1" or "0" depending on if the calling session is interactive or not.

Using safe should only be necessary when locally deployed.

Value

The result of expr.

Examples

## Not run: 
# Direct usage
safe(run_tutorial("hello", package = "learnr"))

# Programmatic usage
library(rlang)

expr <- quote(run_tutorial("hello", package = "learnr"))
safe(!!expr)

tutorial <- "hello"
safe(run_tutorial(!!tutorial, package = "learnr"))

## End(Not run)

Description

Long-form tutorial which includes narrative, figures, videos, exercises, and questions.

Usage

tutorial(
  fig_width = 6.5,
  fig_height = 4,
  fig_retina = 2,
  fig_caption = TRUE,
  progressive = FALSE,
  allow_skip = FALSE,
  dev = "png",
  df_print = "paged",
  smart = TRUE,
  theme = "rstudio",
  highlight = "textmate",
  ace_theme = "textmate",
  mathjax = "default",
  extra_dependencies = NULL,
  css = NULL,
  includes = NULL,
  md_extensions = NULL,
  pandoc_args = NULL,
  language = "en",
  lib_dir = NULL,
  ...
)

Arguments

Value

An rmarkdown::output_format() for learnr tutorials.

Examples

tutorial()

Description

HTML dependency for core tutorial JS and CSS. This should be included as a dependency for custom tutorial formats that wish to ensure that that tutorial.js and tutorial.css are loaded prior their own scripts and stylesheets.

Usage

tutorial_html_dependency()

Value

learnr's HTML dependencies

Description

Set various tutorial options that control the display and evaluation of exercises.

Usage

tutorial_options(
  exercise.cap = NULL,
  exercise.eval = FALSE,
  exercise.timelimit = 30,
  exercise.lines = NULL,
  exercise.pipe = NULL,
  exercise.blanks = NULL,
  exercise.checker = NULL,
  exercise.error.check.code = NULL,
  exercise.completion = TRUE,
  exercise.diagnostics = TRUE,
  exercise.startover = TRUE,
  exercise.reveal_solution = TRUE
)

Arguments

Value

Nothing. Invisibly sets knitr::opts_chunk settings.

Examples

if (interactive()) {
  tutorial_options(exercise.eval = TRUE, exercise.timelimt = 10)
}

Description

List the R packages required to run a particular tutorial.

Usage

tutorial_package_dependencies(name = NULL, package = NULL)

Arguments

Value

A character vector of package names that are required for execution.

Examples

tutorial_package_dependencies(package = "learnr")