Documentation

assessVariableEqual

Perform multiple checks for variable presence and equality

Description

example

assessVariableEqual(variableName,expectedValue) determines whether the variable variableName is present, is the same datatype, the same size, and has the same value or values as the variable expectedValue. If the variable expectedValue is numeric, equality is determined using the default tolerances. If expectedValue is an array, equality is determined by applying the default tolerances to each element of the array.

assessVariableEqual(variableName,expectedValue,Name,Value) uses additional options specified by one or more Name,Value pair arguments.

If the assessment fails, the learner receives a feedback message, with text depending on the condition mismatch. You can also provide additional, customized feedback with the Feedback Name,Value pair.

Examples

collapse all

Compare learner submission variable avgX with reference solution variable avgX. The default tolerances are applied automatically.

assessVariableEqual('avgX',referenceVariables.avgX);

If the learner variable avgX is incorrect, the test fails and the learner receives the default feedback for an incorrect value:

Variable avgX has an incorrect value.

Compare learner submission array myArray=[1 1 4 4] with reference solution array myArray=[1 2 3 4]. The learner submission is accepted if the values in the array are within a 0.03 (3%) relative error tolerance.

assessVariableEqual('myArray', referenceVariables.myArray,'RelativeTolerance',0.03)

In this case, the tolerance is not satisfied because the absolute value of the expected values minus the actual values [0 1 1 0] are not equal to or less than the corresponding absolute product of the expected values and the relative tolerance: [0.03 0.06 0.09 0.12]. The function returns the default feedback message for an incorrect value.

Variable myArray has an incorrect value.

Compare learner submission array myArray=[1 1 4 4] with reference solution array myArray=[1 2 3 4]. The learner submission is accepted if the values in the array are within an absolute error tolerance of 1.

assessVariableEqual('myArray', referenceVariables.myArray,'AbsoluteTolerance',1)

In this case, the tolerance is satisfied because the absolute difference between the expected and actual values are all less than or equal to the corresponding absolute tolerance.

Compare learner submission variable avgX with reference solution variable avgX. If the submission variable is incorrect, provide additional custom feedback to guide the learner.

assessVariableEqual('avgX' referenceVariables.avgX,'Feedback','Refer to the Week 2 handout on Averages.')

If the learner submission has an incorrect value for avgX, the test fails and the learner receives the additional custom feedback along with the default feedback.

Variable avgX has an incorrect value.

Refer to the Week 2 handout on Averages.

Input Arguments

collapse all

The variable name the learner is supposed to use in solving the problem, specified as a char.

Example: 'learnerValue'

The correct value for the variable used in the solution, specified as any of the supported data types. Structures, tables and cells containing only the supported data types are also allowed. Data types datetime, duration, and calendarDuration ignore any applied formatting.

If you have created a reference solution, expectedValue can also be a variable in the reference solution by using the notation referenceVariables.variableName. For example, assessVariableEqual('X',referenceVariables.X) compares the value for X in the learner solution to the value of X in the reference solution.

The assessment is marked correct if a variable with the name variableName exists, and is the same data type, size, and value as expectedValue. If the assessment fails, the learner receives a feedback message, the exact message depending on the condition mismatch.

ConditionMessage

Variable does not exist in submitted solution.

The submission must contain a variable name <varname>.

Incorrect variable data type. It does not match the data type of expectedValue.

Variable <varname> must be of data type: <correct_type>. It is currently of <incorrect_type>. Check where the variable is assigned a value.

Incorrect variable size. It does not match the size of expectedValue.

Variable <varname> must be of size: <correct_size>.
It is currently of size <incorrect_size>. Check where the variable is assigned a value.

Incorrect variable value. It does not match expectedValue.

Variable <varname> has an incorrect value.

Note

When comparing a variable in the learner solution to another variable, those variables must have different names. For example, when comparing avgX in the learner solution to avgX in the reference solution, you format the reference variable as referenceVariables.avgX.

If expectedValue is a variable that is not in the reference solution, use a variable name that is different from the learner variable to avoid comparing against itself. For example:

assessVariableEqual('avgX',xSol)

Example: referenceVariables.xSol

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | logical | char | string | categorical | datetime | duration | calendarDuration | sym

Name-Value Pair Arguments

Specify optional comma-separated pairs of Name,Value arguments. Name is the argument name and Value is the corresponding value. Name must appear inside quotes. You can specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

Example: 'Feedback',’Refer to Week 1 video on Finding the Quadratic Polynomial'

Absolute tolerance, specified as the comma-separated pair consisting of 'AbsoluteTolerance' and a numeric array. The tolerance is applied only to numeric values of the same data type. The value can be a scalar or array the same size as expectedValue.

By default, absolute tolerance is 1e-4. For an absolute tolerance to be satisfied, the following condition must be true:

abs(expected-actual) <= AbsoluteTolerance

When no tolerance is specified, or if both Absolute and Relative tolerances are specified, the test passes if the application of either the absolute tolerance or the relative tolerance passes the equality check.

Relative tolerance is ignored when only absolute tolerance is specified.

Example: ’AbsoluteTolerance’,1.0

Relative tolerance, specified as the comma-separated pair consisting of ‘RelativeTolerance’ and a numeric array. The tolerance is applied only to numeric values of the same data type. The value can be a scalar or array the same size as expectedValue.

By default, relative tolerance is 0.001. For a relative tolerance to be satisfied, the following condition must be true:

abs(expected-actual) <= RelativeTolerance.*abs(expected)

When no tolerance is specified, or if both Absolute and Relative tolerances are specified, the test passes if the application of either the absolute tolerance or the relative tolerance passes the equality check.

Absolute tolerance is ignored when only relative tolerance is specified.

Example: ’RelativeTolerance’,0.05

Additional feedback to display to the learner if the assessment is marked incorrect, specified as the comma-separated pair consisting of 'Feedback' and a character array. Feedback should be used to provide learners with resources to make corrections to their code. Although you cannot know which condition was not satisfied, you can direct the learner to a particular lesson or reading that covers the material.

For example, assume the assessment includes the Feedback Name,Value pair:

'Feedback','See class resource for assigning variable values.'
When the learner submission has an incorrect value for the variable being compared, the test fails, and the learner receives the additional custom feedback along with the default feedback.

Variable myVariable has an incorrect value.

See class resource for assigning variable values.

Introduced in R2016a