Signal a passing or failing grade if two values are equal

pass_if_equal() and fail_if_equal() are two graded() helper functions that signal a passing or a failing grade if two values are equal. They are designed to easily compare the returned value of the student's submitted code with the value returned by the solution or another known value:

Both functions find and use .result as the default for x, the first item in the comparison. .result is the last value returned from the user's submitted code.
pass_if_equal() additionally finds and uses .solution as the default expected value y.

See graded() for more information on gradethis grade-signaling functions.

Usage

pass_if_equal(
  y = .solution,
  message = getOption("gradethis.pass", "Correct!"),
  x = .result,
  ...,
  env = parent.frame(),
  tolerance = sqrt(.Machine$double.eps),
  praise = getOption("gradethis.pass.praise", FALSE)
)

fail_if_equal(
  y,
  message = getOption("gradethis.fail", "Incorrect"),
  x = .result,
  ...,
  env = parent.frame(),
  tolerance = sqrt(.Machine$double.eps),
  hint = getOption("gradethis.fail.hint", FALSE),
  encourage = getOption("gradethis.fail.encourage", FALSE)
)

Arguments

y

The expected value against which x is compared using waldo::compare(x, y).

In pass_if_equal(), if no value is provided, the exercise .solution (i.e. the result of evaluating the code in the exercise's *-solution chunk) will be used for the comparison.

If the exercise uses multiple solutions with different results, set y = .solution_all. In this case, pass_if_equal() will test each of the solutions and provide a passing grade if x matches any values contained in y. Note that if the exercise has multiple solutions but they all return the same result, it will be faster to use the default value of y = .solution.

message

A character string of the message to be displayed. In all grading helper functions other than graded(), message is a template string that will be processed with glue::glue().

x

First item in the comparison. By default, when used inside grade_this(), x is automatically assigned the value of .result — in other words the result of running the student's submitted code. x is not the first argument since you will often want to compare the final value of the student's submission against a specific value, y.

...

Additional arguments passed to graded()

env

environment to evaluate the glue message. Most users of gradethis will not need to use this argument.

tolerance

If non-NULL, used as threshold for ignoring small floating point difference when comparing numeric vectors. Setting to any non-NULL value will cause integer and double vectors to be compared based on their values, rather than their types.

It uses the same algorithm as all.equal(), i.e., first we generate x_diff and y_diff by subsetting x and y to look only locations with differences. Then we check that mean(abs(x_diff - y_diff)) / mean(abs(y_diff)) (or just mean(abs(x_diff - y_diff)) if y_diff is small) is less than tolerance.

praise

Include a random praising phrase with random_praise()? The default value of praise can be set using gradethis_setup() or the gradethis.pass.praise option.

hint

Include a code feedback hint with the failing message? This argument only applies to fail() and fail_if_equal() and the message is added using the default options of give_code_feedback() and maybe_code_feedback(). The default value of hint can be set using gradethis_setup() or the gradethis.fail.hint option.

encourage

Include a random encouraging phrase with random_encouragement()? The default value of encourage can be set using gradethis_setup() or the gradethis.fail.encourage option.

Value

Returns a passing or failing grade if x and y are equal.

Functions

pass_if_equal: Signal a passing grade only if x and y are equal.
fail_if_equal: Signal a failing grade only if x and y are equal.

Examples

# Suppose our prompt is to find the cars in `mtcars` with 6 cylinders...

grader <-
  # ```{r example-check}
  grade_this({
    # Automatically pass if .result equal to .solution
    pass_if_equal()

    fail_if_equal(mtcars[mtcars$cyl == 4, ], message = "Not four cylinders")
    fail_if_equal(mtcars[mtcars$cyl == 8, ], message = "Not eight cylinders")

    # Default to failing grade with feedback
    fail()
  })
# ```

.solution <-
  # ```{r example-solution}
  mtcars[mtcars$cyl == 6, ]
# ```

# Correct!
grader(mock_this_exercise(mtcars[mtcars$cyl == 6, ], !!.solution))
#> <gradethis_graded: [Correct] You rock! Correct!>

# These fail with specific messages
grader(mock_this_exercise(mtcars[mtcars$cyl == 4, ], !!.solution))
#> <gradethis_graded: [Incorrect] Not four cylinders>
grader(mock_this_exercise(mtcars[mtcars$cyl == 8, ], !!.solution))
#> <gradethis_graded: [Incorrect] Not eight cylinders>

# This fails with default feedback message
grader(mock_this_exercise(mtcars[mtcars$mpg == 8, ], !!.solution))
#> <gradethis_graded: [Incorrect]
#>   Incorrect. I expected you to call `structure()` where you
#>   called `[`. Try it again. Perseverence is the key to success.
#> >