How do I use the Formula Editor?
The Formula editor is a tool within Grades that you can use to create formulas for Formula grade items or for the Formula Grading System. In this article, you can read how to use the formula editor.
See here for a video on the Formula Editor.
Table of Contents
How does the Formula Editor work?
Use the Formula Editor to define a formula that calculates a grade item’s value based on other grade items. When you create a formula, you specify which grade items you want included in the formula and the relationships between them. An example of a simple formula is one that calculates the sum of a number of grade items. A more complicated formula is one that drops the minimum or maximum value from a set of grade items.
The Formula Editor is available on the pages of New Item, Edit Item for Formula items, Edit Calculated Final Grade, Edit Adjusted Final Grade and for the Formula grading system.
Access the Formula Editor
- On the Manage Grades page, click the name of a formula grade item you wish to edit.
- Click Edit Using the Formula Editor.
Key Grades Formula Editor components
1. Formula area
The Formula Area is where the formula text is displayed. The equals sign (=) at the start of the formula cannot be deleted. A cursor shows your position in the formula. Click in the formula area to position the cursor.
2. Cursor placement
The cursor placement icons are used to move the cursor forwards and backwards in the formula. You can also move the cursor by clicking on the new location with your mouse. There are four options:
- Move cursor to start of formula.
- Move cursor to end of formula.
- Move cursor back one element.
- Move cursor forward one element.
3. Grade item parameters
Use the Grade Item drop-down list to view what grade items you can insert as a parameter in your formula. You can insert Numeric, Pass/Fail, Selectbox, and Formula type grade items. You cannot reference the formula grade item you are defining (this avoids a circular reference) or a final grade.
Use the Grade Item Value drop-down list to view the values associated with the grade item you want to use in the formula. There are three options:
- Points Received: The grade the user achieved. E.g., 7 (out of 10 points).
- Max Points The maximum points available for the grade item. E.g., 10 points.
- Percent The percent grade the user achieved. E.g., 70%.
Click Insert to insert the selected grade parameter in the formula.
Insert a grade item parameter in a formula
- Select a Grade Item.
- Select the Grade Item Value you want to use in the calculation.
- Click Insert.
- For the weighted system, category and grade item weights are ignored in formula calculations.
- Dropped grade items and bonus grade items are calculated the same as other grade items.
4. Functions
The Function drop-down list contains a list of functions that you can use in your 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 for a set of values by adding all the values and dividing by the total number of values.
- IF Operates as a Boolean statement that returns either the value set as true or as false. You must define the condition (Boolean statement), true (then) value, and false (else) value.
- NOT Operates as a Boolean statement that returns the value set as true if the condition is false and as false if the condition is true.
- You can embed functions within functions.
- The Start, Next Term, and End options are used to define elements of a function:
- Start: Starts the function selected in the Function drop-down list with an opening bracket ({).
- Next Term: Inserts a comma to separate grade items or parts of a Boolean statement.
- End: Ends the function with a closing bracket (}).
Insert a function in a formula
- Select a Function.
- 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 are done adding parameters and conditions.
5. Numeric keys and operators
The right area of the Formula editor contains a number of operators and a numeric key pad to build your formula. These operators are usually used in conjunction with at least one grade item.
6. Backspace and clear
The Backspace and Clear options let you delete parts of your formula to make changes.
- Backspace Deletes the element to the left of the cursor.
- Clear Deletes the entire formula.
7. Cancel
The Cancel button exits the Formula Editor without saving your changes.
8. Insert
The Insert button validates your formula and applies it to the grade book item or final grade you are working on. If your formula is invalid, you receive an error message and your cursor moves to the point in the formula that caused the error. The error type displays in red above the formula.
9. Validate
The Validate option checks if your formula conforms to standard formula grammar. If your formula is valid, a confirmation message displays. If your formula is invalid, you receive an error message and your cursor moves to the point in the formula that caused the error. The error type displays in red above the formula. See Grades Formula Editor validation errors for a list of potential errors.
10. Preview
The Preview option lets you check how your formula will calculate grades for the first ten users in your user list. Click Close when you are finished viewing the grades. If your formula is invalid, you cannot preview grades.
Possible errors
The following are errors you might encounter while using the Formula Editor:
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 equation = 5/1 = (5+1)*2 |
Unbalanced parentheses |
The formula contains an opening or closing bracket without a corresponding bracket |
= 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 curly bracket add the end) SUM{[Item1.Points], [Item2.Points]} |
Unexpected function end |
The formula contains a closing bracket for a function that does not relate to a function |
= [Item1.Points]/2} |
Remove curly bracket = [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} |
Insert correct number of parameters. For SUM, at least 2 For IF, at least 3 |
Numeric value expected |
A Boolean statement or operator was entered in place 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 was not entered for a condition |
= IF {MIN{4,5},100,0} = NOT{4} |
Enter Boolean. = IF {MIN{4,5} > 5, 100, 0} |
Invalid terminal |
The formula contains an incorrectly used terminal |
= [Item1.Points] + 3.2.5 |
Remove the errors. = [Item1.Points] + 3.2 |
Example grade formulas
Scenario 1: Give users who achieved over 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]}}