1. What are formulas and when are they useful?
2. Writing a formula
   1. Setting the matcher type for a link
   2. Referring to other links and components
   3. Operators
   4. Return types
   5. Syntax-checking
3. Testing a formula
4. Formulas in hints and error feedback messages
5. Writing your own function

In this section, we introduce the concept and use of "formulas", powerful expressions that define the way CTAT example-tracing tutors match student input.

A formula is an expression you write for a step in an example-tracing tutor that enables the tutor to calculate a value (or set of values) it should use to test against the student's input.

Formula matching is an extension to existing matching methods. An example-tracing tutor works by comparing student-entered input to the input recorded in the steps of a behavior graph, which you create by demonstration. With the Edit Student Input Matching window, you can change this "exact" match to be more flexible: you can specify a range match (e.g., "1-10", which matches "6"), an "any" match (i.e., any input value will match), a wildcard match (e.g., "car*", which matches "cars" and "car"), or a regular expression match (e.g., "[THK]im", which matches "Tim", "Him", and "Kim"). With a formula match, the comparison is between the student-entered input and the evaluation of a formula, such as "link1.authorInput+5" (this equates to the value the author entered on Link 1 of the graph, plus 5).

A formula matcher is the most powerful type of matcher in CTAT because it can combine the values of inputs on other links, student-entered input, and the contents of interface components (such as text fields). Whenever you would like to evaluate correctness based on these characteristics, consider writing a formula.

Formulas are particularly useful in a few cases. When you need to specify a test (against a student action) that can only be determined at the time the student uses the tutor, a formula allows you to do so. For example, in the domain of fraction addition, you may have a set of common denominators that are valid for the current problem; but once the student uses one of those denominators in a converted fraction, he or she should use that same denominator in the other converted fractions and the unsimplified sum fraction. With a formula, you can check that the student chose a common denominator; then you can require the student to use that denominator in the other fractions.

Another benefit of formulas is that the tutor can be more general, with logic that works across similar problems (much like a cognitive tutor). Using the fraction addition example again, you might have a path in the behavior graph that represents finding and using a common denominator that is found by multiplying the two denominators of the given fractions. The formula for the links in that path of the graph would specify the product of multiplying the two denominators of the given fractions, which can be looked up by using variables that hold the value of components in the interface. Since the formula specifies a general logic, not hard-coded numbers, this graph is then on the way to becoming general enough to use with mass production.

You write a formula for a step in your behavior graph when you need to calculate a value to test against the student's input rather than just using a demonstrated value. Formulas can be simple expressions or more complex calculations that use functions provided by CTAT, as well as standard math and string functions.

For documentation on the functions supported by CTAT, see Formula Functions.

To get started writing a formula, view and edit the student input matching on a step (link) of your choice.

To set the formula matcher type for a link:

1. Open the Edit Student Input Matching dialog by clicking the link for which you'd like to specify a formula, and selecting Edit Student Input Matching... from the pop up menu.

2. Switch the matcher type from its current selection ("Exact Match" by default) to Formula Match.

   

   Figure: Edit Student Input Matching dialog with Input matcher set to Formula Match.

Notice that the text area for the input matcher setting changes to include a list of return types (e.g., "=", "<", and so on) when you set the matcher type to Formula Match. You can now enter a formula expression in the input text area.

Your formula will have access to variables, operators, and functions, which are described in the following sections.

Next, test your formula to see if it matches (or doesn't match) some student input by switching CTAT's Author Mode to Test Tutor and interacting with the tutor. Find out if the step you performed matched the formula (and if didn't match, why not) by opening the Edit Student Input Matching dialog again, and clicking the Last Evaluation button.

See section Testing a Formula for more help testing and debugging your formula.

CTAT provides the following predefined variables for use in formulas.

Tip

Link numbers are shown in link labels as the first number, followed by a period. You will need to reference link numbers if you intend to reference other steps in your formula.

Referring to student interface components

You can refer to the content of most CTAT user interface components by specifying the instance name of the component in a formula.

For example, to refer to the content of two CTATTextAreas, one called "givenDenom1" and the other called "givenDenom2", refer to their instance names in the formula:

givenDenom1*givenDenom2

These component variables are updated under a few conditions. If the component is configured in "Set Start State" mode, then its variable value is updated whenever the start state is loaded; otherwise, the component's variable value is updated when the content of the component is changed or the component is used (by either the student or the tutor).

For some components, it may not be obvious what value they will return when they are referenced. For example:

• CTATTextArea: returns the text
• CTATButton: returns the constant "-1"

To determine the format of a particular component's values:

1. Demonstrate a step with the component. A new link should appear in the behavior graph.
2. Open the Edit Student Input Matching dialog for the new link by double-clicking the link.
3. Examine the value in the "Input" field. The format of the value is the same as if you referenced it in a formula.

Referring to student-entered values

These variables are given their values whenever a student performs a step which is modeled in the graph.

• selection: the selection of the component the student has just used (ie, the current selection)
• action: the action the student has just performed (ie, the current action)
• input: the input the student has just entered (ie, the current input)
• linkN.selection: the selection the student interacted with that was traced in link N.
• linkN.action: the action the student performed that was traced in link N.
• linkN.input: the input the student entered that was matched by link N.
• linkN.actor: the actor who performed the action (either student or tutor) that was matched by link N.

Referring to author-specified values

These variables are given their values whenever a link is created or modified. You can see these values in the Edit Student Input Matching dialog of the various links in the graph.

• linkN.authorSelection: the selection specified for link N.
• linkN.authorAction: the action specified for link N.
• linkN.authorInput: the input specified for link N.
• linkN.authorActor: the actor who should perform the step (either Student, Tutor, or Any), specified for link N.

See also Testing a Formula, which explains how to compare expected and observed values.

In a formula, you have access to the following simple operators:

• +
• -
• *
• /

You can use these operators in your formulas to perform calculations involving numbers.

Note

The order of operations in formulas is the same as in the Java programming language and basic math: multiplication and division take precedence over (happen before) addition and subtraction. If two operators have the same precedence, they are evaluated left to right. You can override these rules by using parentheses.

A simple example using numbers and operators:

4*3/6-2+1

(Evaluates as 1.)

A more complex example: the quadratic formula could be expressed in a formula as follows:

Math.sqrt(link1.input * link1.input - 4 * link3.input) / -2

Each formula you write (and any functions that compose it) will return a value of a specific type (number or boolean) when it is evaluated. Set the expected return type to the left of the formula field.

Figure: Return type mismatch: the dialog specifies an equality test, but the formula returns a boolean value (true or false).

Your formula's return type should match the type set in the formula matcher. For example, if your formula returns a boolean (true or false), the formula matcher should be set to compare "boolean"; otherwise, the evaluation will not happen. In the screenshot above, the formula is set to evaluate with equals ("="), which is a comparison operator, but the formula and its function equals will return a boolean value (true or false). To fix this, set the return type to "boolean", or press Check, which will set the return type for you.

When you've written a formula that you want to try, first check that it's well-formed by clicking Check which will tell you 1) if the formula is valid, and 2) whether or not it can match the input that was demonstrated (shown to the left). If the formula is syntactically valid, you'll see a message like "OK". If the formula's syntax is invalid, you'll see a more specific error message.

Tip

If you see an error message, look for the ^ character, which should point to the first piece of the formula that is invalid.

To determine if a formula matches a student's input on a step, you can do a few things from the Edit Student Input Matching dialog:

• Check your formula against the input that you demonstrated when creating the graph.
• Enter input in the student interface, then see how the formula was evaluated (Last Evaluation)

To test your formula against the input that you demonstrated:

1. Open the Edit Student Input Matching dialog on the step for which you've written your formula.

2. Click Check. Diagnostic text appears in the space above the button (see figure below).

   Note

   Pressing Check both checks the formula's syntax and, if it's valid, compares it against the demonstrated value.

   

   Figure: Results of checking a formula against demonstrated input.

To test your formula against input you enter in the student interface:

1. Switch CTAT's Author Mode to Test Tutor.

2. Perform a step in the student interface that you'd expect to be matched by your formula. As with other matchers, green outlining and text signifies a match on a correct action link, while red outlining and text signifies either a match on an incorrect action link, a suboptimal action link, or no match at all.

   Tip

   You can see which link matched by looking for a bold link label, although this is difficult if not impossible on larger graphs or steps that occur late in a sequence.

3. Open the Edit Student Input Matching dialog on the step for which you've written your formula.

4. Click Last Evaluation. Diagnostic text will appear in the space above the button, describing how CTAT interpreted the formula.

   

   Figure: Results of testing a formula against input entered in the student interface

On any step, the result of a formula will be one of the following:

• The formula was not evaluated/used for the step
• The formula was evaluated but didn't match the student's step.
• The formula was evaluated and matched the student's step.

If the formula was not used to evaluate the step, the following message should appear:

This expression has not been evaluated.

Possible reasons for no evaluation are generally the same for any non-formula-match link in an example-tracing tutor: the selection or action might not have matched, so input was not evaluated; or a constraint such as ordering or min/max traversals precluded a comparison with the formula-match link.

If the formula was evaluated but didn't match, you might see something like the following:

 Last evaluation (3:14:18 PM):

 Observed input (student): 2
 Expected input (formula): 1.0

 No match!

If the formula was evaluated and matched successfully, you might see something like the following:

 Last evaluation (3:15:10 PM):

 Observed input (student): 2
 Expected input (formula): 2.0

 Match!

During an attempt at evaluating a formula, Java errors can occur. Some possible errors are:

• java.lang.IllegalStateException -- can occur for a variety of reasons.
• java.lang.ClassNotFoundException -- CTAT was unable to find a function you named in the formula. The function might be spelled incorrectly, or the arguments might be of the wrong type.

Try testing your formula with varied input. Before testing the formula again, remember to click on the start state or the state preceding the step you're testing,

To use the value of a variable in a hint or feedback message, use the following syntax in the hint message:

<%=variableName%>

For example, to reference component variables in a hint message:

What is the smallest number that both <%=givenDenom1%> and <%=givenDenom2%> go into?

You can use this same syntax to insert the result of a formula in a hint or feedback message. The following example uses the sum function to find the sum of two numbers, and prints the result:

The sum of the two numbers is <%=sum(givenDenom1,givenDenom2)%>.

When the formula functions defined by CTAT don't provide the functionality that you need, you can write your own functions in JavaScript. With the JavaScript example tracer, any global functions (or methods of global objects) that authors define in their own scripts should be recognized in formulas.

You can define your function in the .html file or in a separate .js file. For example, a very simple function that returns the student input value doubled could be defined as follows in the .html file:

<script>
function doubleMe(value) {
    var result = value+value;
    return result;
}
</script>

Your function would be specified in the Edit Student Input Matching dialog as a Formula Match on the input:

Figure: Edit Student Input Matching dialog with Input matcher set to Formula Match.

Note

For the current release of CTAT, custom functions defined in JavaScript are not recognized in the authoring tools. You can specify your function in a formula in the Edit Student Input Matching dialog, but you will not be able to test your function in the authoring tools; it can only be tested in a tutor that has been deployed. (Authors can provide a Java version of the same function and add it to ctat.jar if they want it to work in the authoring tools as well as in deployed tutors.) See also: Dynamic Interfaces.

Back to top

Next >> Formula Functions