How do I use the Formula Editor?
The Formula Editor is a tool within Grades that can be used to create formulas for Formula Grade Items or for the Formula Grading System. This article explains how the Formula Editor works.
Contents
- How does the Formula Editor work?
- Create a Formula Grade Item
- Key components of the Grades Formula Editor
- Possible error messages
- Example grade formulas
How the Formula Editor works
Use the Formula Editor to define a formula that calculates the value of a grade item based on other grade items. When creating a formula, you need to specify which grade items to include and the relationships between them. An example of a simple formula is one that calculates the sum of several grade items. A more complex example is a formula that excludes the minimum or maximum value from a series of grade items.
Create a Formula Grade Item Type
Click on ‘Grades’ in the navigation bar. Then click on ‘Manage Grades’.
A new item is created by clicking on ‘New’ and then selecting ‘Item’.
Choose ‘Formula’.
On the page that appears, scroll down and click on ‘Edit Using the Formula Editor’ under the section Points Received.
Key Components of the Grades Formula Editor
On the Formula Editor page, many elements are displayed:
- Formula Area
The formula area is where the formula text is displayed. The equals sign (=) at the start of the formula cannot be removed. A cursor indicates your position within the formula. Click inside the formula area to place the cursor.
- Cursor Placement
The cursor placement icons are used to move the cursor forward or backward within the formula. You can also click on the desired location in the formula using your mouse. There are four options:
- << Move the cursor to the beginning of the formula.
- >> Move the cursor to the end of the formula.
- < Move the cursor one element backward.
- > Move the cursor one element forward.
- Grade Item Parameters
Use the Grade Item drop-down list t o see which grade items you can insert as parameters into your formula. The options include: Numeric, Pass/Fail, Selectbox, and Formula type grade items. You cannot reference the formula grade item you are currently defining (this avoids circular references or loops) or a final grade.
Use the Grade Item Value drop-down list to view the values associated with the grade item you want to include in your formula. These include:
- Points Received: The grade a student has achieved, e.g., 7 out of 10 points.
- Max Points: The maximum available points for the grade item, e.g., 10 points.
- Percent: The percentage the student has achieved, e.g., 70%.
To insert the selected grade parameter into the formula:
Select a Grade Item and choose the Grade Item Value you wish to use in the calculation. Then click on ‘Insert’.
Note:
- For weighted systems, Category and Grade Item weights are ignored in the formula’s calculations.
- Dropped grade items and bonus grade items are calculated in the same way as other grade items.
- Functions
The Function drop-down list contains functions that can be used in the calculation formula.
- MAX: Calculates the maximum (largest) value in a set of values.
- MIN: Calculates the minimum (smallest) value in a set of values.
- SUM: Calculates the sum (total) of a set of values.
- AVG: Calculates the average of a set of values by summing all values and dividing by the total number of values.
- IF: Acts as a Boolean statement, returning a value set for true or false. You need to define the condition (Boolean statement), the true (then) value, and the false (else) value.
- NOT: Acts as a Boolean statement, returning true if the condition is false, and false if the condition is true.
Note:
It is possible to nest functions within other functions.
The Start, Next Term, and End options are used to define the elements of a function:
- Start: Initiates the selected function from the Function drop-down list with an opening brace ({).
- Next Term: Adds a comma to separate grade items or parts of a Boolean statement.
- End: Closes the function with a closing brace (}).
Add a Function to a Formula
Select a Function and click ‘Start’. Enter a parameter. Click ‘Next Term’ to add another parameter or use the numeric keys and operators to define a condition. Click ‘End’ when you have finished adding parameters and conditions.
- Numeric Keys and Operators
The right-hand section of the formula editor contains several operators and a numeric keypad to help construct your formula. These operators are usually used in combination with at least one Grade Item.
- Backspace and Clear
The Backspace and Clear options allow you to edit or remove parts of your formula:
- Backspace: Deletes the element to the left of the cursor.
- Clear: Removes the entire formula.
- Cancel
The ‘Cancel’ button exits the Formula Editor without saving your changes.
- Insert
The ‘Insert’ button validates the formula and applies it to the Grade Item or final grade you are working on. If the formula is invalid, an error message will appear, and the cursor will move to the point in the formula where the error occurred. The error type will be displayed in red above the formula.
- Validate
The ‘Validate’ option checks whether the formula conforms to the grammar of the standard formula. If the formula is valid, a confirmation message will appear. If the formula is invalid, an error message will appear, and the cursor will move to the point in the formula where the error occurred. The error type will be displayed in red above the formula. Refer to the section Possible Error Messages for a list of potential issues.
- Preview
The ‘Preview’ option allows you to verify how the formula calculates grades for the first ten users in the User List. Click Close when you are done reviewing the grades. If the formula is invalid, grade previews will not be available.
Possible Error Messages
| Error | Description | Example | Correction |
| Unexpected [token_type]
For Example, Unexpected operator |
The formula contains a function component in an unexpected location | = 5=/1
= (5+1)2 |
Correct the formula
= 5/1 |
| Unbalanced parentheses | The formula contains an opening or closing bracket without a matching counterpart | = 5+1) | Remove bracket
= 5+ 1 |
| Missing end of function | The formula contains an unclosed function | = SUM{[Item1.Points], [Item2.Points] | Close the function (add a curly brace, add the end)
SUM{[Item1.Points], [Item2.Points]} |
| Unexpected function end | The formula contains a closing brace for a function that does not correspond to a function | = [Item1.Points]/2} | Remove curly brace
= [Item1.Points]/2 |
| Invalid number of operator parameters | The formula contains an invalid number of operator parameters | = [Item1.Points] + | Add parameters or remove operator
= [Item1.Points] + [Item2.Points] |
| Invalid number of function parameters | The formula contains an invalid number of function parameters | = SUM{}
= IF{[Item1.Points]<2,5} |
Enter the correct number of parameters. For SUM, at least 3. For IF, exactly 3. |
| Numeric value expected | A Boolean statement or operator has been enterd instead of a numeric value | = IF{5<2,1 OR 1,4}
= SUM{1 = 2,3,4} |
Correct parameters
= IF {BOOLEAN, TRUE, FALSE} = SUM {only numeric values} |
| Boolean value expected | A Boolean statement has not been entered for a condition | = IF {MIN{4,5},100,0}
= NOT{4} |
Enter a Boolean. = IF {MIN{4,5} > 5, 100, 0} |
| Invalid terminal | The formula contains an incorrectly used terminal | = [Item1.Points] + 3.2.5 | Remove the mistake = [Item1.Points] + 3.2 |
Example Grade Formulas
Scenario 1: Award users who have scored more than 75% on all grade items in a category 100% for the category.
= IF {MIN{[Week1.Percent],[Week2.Percent],[Week3.Percent]} < 75, 0, 100}
Scenario 2: Drop the lowest two grades in a set of three grades.
= SUM{[G1.PointsReceived],[G2.Points Received], [G3Points Received]} – MIN{[G1.PointsReceived],[G2.Points Received]} – IF{MIN{[G2.Points Received], [G3Points Received]} = MIN{[G1.PointsReceived],[G2.Points Received]}, MIN{[G1.PointsReceived],[G3.Points Received]}, MIN {[G2.PointsReceived],[G3.Points Received]}}