Gradebook Formulas

 

Formulas are used to create advanced calculations for the assignment grade or the category average. The Gradebook supports the use of formula tokens in the “Formula” field on the settings screen for an assignment or category. This document first introduces how to add formula to categories and assignments using the Formula Editor and then describes all formula tokens that can be used in formulas along with several examples. Additional information for using Formula Editor is available in the Gradebook Manual of ANGEL Help.

 

 

Add a Formula to a Category

 

Category formulas are used to recalculate category averages of students. For example, you can weight the category average of exams or change the way how the assignments in a category are averaged to recalculate the category average using formulas. Note that formulas are not available for categories when in Points mode. If your gradebook is in Points mode, you can try to use formulas for your assignments to recalculate category average indirectly, or you can change them manually.

 

To add a formula to a category:

 

  1. On the main Gradebook menu, select the “Categories” link.
  2. Select the check box for an existing category in which you want to add a formula, then click the “Edit Selected” button. Alternately, to add a formula to a new category you wish to create, click the “Add New” button.
  3. In the “Category Editor” that displays at the bottom of the screen, select the Advanced radio button.
  4. Beneath the “Formula” box, select the “Formula Editor” link:


Screen capture.

Select the "Formula Editor" link.

 

  1. In the “Formula Editor” window, select the desired token from the pull-down menu at the lower left.
  2. Click the “Insert Token” button. The token will appear in the formula editor text box above. A list of tokens can be found at the end of this section.

 

The selected token appears in the text box.

 

  1. Enter the desired equation into the text box. (see the Examples)
  2. Under “Validate Formula,” click the “Go” button to validate that the formula is calculating properly. You should see a “Passed” message once validated. If your formula is not valid, you will see a “Failed” message. In this case, your formula cannot be saved and you are expected to edit your formula.

 

Screen capture.

The formula entered has been validated.

 

  1. To verify if the formula is correct and working you can safely test it on a student’s category average. Under “Test Formula,” select a student from the pull-down menu, then click the “Go” button to test the formula and verify the result.
  2. Click the “Save Formula” button to apply it to the category.
  3. When you are finished editing the category, click the “Save” button.

 

Add a Formula to an Assignment

 

Assignment formulas are used to recalculate the grades for an individual assignment in a category. For example, you can automatically add bonus points to each student’s homework assignment grade by using a formula for the assignment in your gradebook. The usage is very similar to that of category formulas; however, you can use formulas for assignments in both Percentage and Points mode unlike for categories. To add a formula to an assignment:

 

  1. On the main Gradebook menu, select the “Assignments” link.
  2. Select the check box for an existing assignment in which you want to add a formula, then click the “Edit Selected” button. Alternately, to add a formula to a new assignment you wish to create, click the “Add New” button.
  3. In the “Assignment Editor” that displays at the bottom of the screen, select the “Advanced” radio button.
  4. Beneath the “Formula” box, select the “Formula Editor” link.
  5. In the “Formula Editor” window, select the desired token from the pull-down menu at the lower left.
  6. Click the “Insert Token” button. Note: A list of tokens can be found at the end of this section.
  7. Enter the desired equation into the text box. (see the Examples)
  8. Under “Validate Formula,” click the “Go” button to validate that the formula is calculating properly. You should see a “Passed” message once validated.
  9. To verify if the formula is correct and working you can safely test it on a student’s assignment score. Under “Test Formula,” select a student from the pull-down menu, then click the “Go” button to test the formula and verify the result.
  10. Click the “Save Formula” button to apply it to the assignment.

 

 

Formula Tokens and Examples

 

Tokens can be used when you create a formula. You can use them in addition to entering the formula by hand. This section first describes how formulas work on a simple example and then presents the tokens that can be used in assignment and category formulas along with several examples.

 

Below you can see a sample Gradebook scenario to be used in the examples. It displays one homework category which has 25pts weight on the total score and is composed of two assignments which are worth 80pts and 100pts, respectively. It shows score and percentage together for each item and student.

 

Sample Gradebook scenario used in the examples.

 

NOTE: Formula for a category average or an assignment grade should always calculate a percentage, a value between 0 and 1. This is how the formula editor works and should not be confused with the gradebook modes Percentage and Points. After all, every grade in your gradebook can be displayed as a score or a percentage, and the formula editor simply recalculates grades based on percentage values of the scores. This becomes clearer in the following example.   

 

Example 1: The simplest form of a formula that can be used in the formula editor is to enter directly a percentage value in the formula editor. For instance, you want to give full credit (80 points) to everyone for Hw1 in our Gradebook scenario (though there are other ways to do that in ANGEL). You can directly type “1” in the formula editor of Hw1:

 

The formula for the scenario in Example 1.

 

 

The result of the formula is 1, which is 100%. Once the formula is saved, the Gradebook recalculates the hw1 score for each student using the result of the formula using the equation: “the value of the assignment * the percentage calculated by the formula”. Since the formula is always 1, the score for each student will be: “80pts*100% = 80pts”. After the formula is saved, the new HW1 scores can be seen below:

 

Recalculated Hw1 grades using the formula in Example 1.

 

In most other cases, you may want to recalculate the category average or the assignment score by using the current score of each user. To achieve this, the Gradebook provides you a variety of formula tokens which you can use in your formulas to access current information regarding items in the Gradebook, such as the student’s current score for an assignment or the number of assignments student has submitted for a category. You can think of a token as a variable in your formula whose value is automatically typed by the gradebook for each student. All the available tokens for your use in your formulas are described below.

 

Tokens available for assignments:

 

{ASSIGNMENT:USER:PERCENTAGE}

This token returns the user’s percentage score for the assignment.

 

Example 2: The token “{ASSIGNMENT:USER:PERCENTAGE}” provides very simple way to weight the user’s score by some value. In our sample Gradebook scenario, to curve each student’s Hw1 score to be worth 110% of his actual score, you can use

 

The formula for the scenario in Example 2.

 

 

Note that once you save the formula, each user’s Hw1 score will automatically be calculated by the formula using his/her current score in the Gradebook. For instance, the student “Jane Learner” got 65 out of 80 for Hw1, which is 75%. After the Gradebook calculates the formula, her new percentage for Hw1 will be:

{ASSIGNMENT:USER:PERCENTAGE}*1.1 => 75% * 1.1 = 82.5%

Since the total points for HW1 is 80, her curved score will then be “80pts * 82.5% = 66pts”. After the formula is saved, the new HW1 scores can be seen below:

 

Recalculated Hw1 grades using the formula in Example 2.

 

 

{ASSIGNMENT:USER:SCORE}

This token returns user’s score for the assignment.

 

{ASSIGNMENT:OVERALL:POINTS-POSSIBLE}

This token returns number of points possible for the assignment.

 

 

Example 3: If you need to make calculations using actual scores, these two tokens can be useful. Similar to the previous example, to add “5 bonus pts” to each student’s Hw1 score, you can use the following formula:

 

The formula for the scenario in Example 3.

 

 

Note that simply using a formula “{ASSIGNMENT:USER:SCORE} + 5” is not complete because the formula result needs to be in percentage, thus we need to divide this score by the total possible score for the assignment. In our sample Gradebook scenario, the student Jane Learner’s new percentage is calculated as “(60 + 5)/80 = 81.25%”. Thus her score will be “80*81.25% = 65 (81.25%)”. After the formula is saved, the new HW1 scores can be seen below:

 

Recalculated Hw1 grades using the formula in Example 3.

 

 

 

{ASSIGNMENT:OVERALL:AVERAGE-PERCENTAGE}

This token returns the overall class average (in percent) for the assignment. In the sample Gradebook scenario, the value of this token is “81.67%”.

 

{ASSIGNMENT:CATEGORY:OVERALL-NUMBER-OF-ASSIGNMENTS}

This token returns number of assignments associated with the category the assignment is associated with. In the sample Gradebook scenario, the value of this token is “2”.

 

{ASSIGNMENT:CATEGORY:OVERALL-SUM-OF-ALL-ASSIGNMENT-POINTS-POSSIBLE}

This token returns total points possible for the category the assignment is associated with. In the sample Gradebook scenario, the value of this token is “180”.

 

{ASSIGNMENT:CATEGORY:OVERALL-WEIGHT}

Weight for the category the assignment is associated with. In the sample Gradebook scenario, the value of this token is “25”.

 

 

 

Tokens available for categories:

 

{CATEGORY:USER:AVERAGE-ASSIGNMENT-PERCENTAGE}
This token returns the user's percentage average for the category based on weighting all category assignments equally (Weight All Items Equally).

Example 4: In the Gradebook scenario, Hw2 has more weight (100pts) than Hw1 does (which is out of 80pts) on the category average since the result is calculated over out of total possible points of all assignment. For instance, the student “Raphael Learner” got 80/80 for Hw1 and 50/100 for Hw2. Thus the category average for this student is calculated as “(Hw1+Hw2)/(80+100)  =  (80+50)/180 = 72.22%” by default. However if you want each assignment in the category to be regarded equally, you can use the following formula for the category:

 

The formula for the scenario in Example 4.

Note that the token itself returns the average percentage by weighting all assignments in the category equally so you do not need any other term in the formula. Now the category average for the same student will be calculated as “(100% + 50%)/2 = 75%”. After the formula is saved, the new Homework category average for each student can be seen below:

Recalculated category average using the formula in Example 4.

{CATEGORY:OVERALL:AVERAGE-PERCENTAGE}
This token returns the overall category average multiplied by the points possible, divided by the maximum number of points in the category. In the sample Gradebook scenario, the value of this token is “74.81”.

 

{CATEGORY:OVERALL:NUMBER-OF-ASSIGNMENTS}
This token returns overall number of assignments in the category. In the sample Gradebook scenario, the value of this token is “2”.

 

{CATEGORY:OVERALL:SUM-OF-ALL-ASSIGNMENT-POINTS-POSSIBLE}
This token returns sum of user’s points possible of all assignments in the category. In the sample Gradebook scenario, the value of this token is “180”.

 

{CATEGORY:OVERALL:WEIGHT}
This token returns overall weight of the category. In the sample Gradebook scenario, the value of this token is “25”.

{CATEGORY:USER:PERCENTAGE}
This token returns the user's percentage average for the category. As in example 2, the category average for each user can easily be curved by weighting this token.

{CATEGORY:USER:SCORE}
This token returns the user's score for the category.

{CATEGORY:USER:SUM-OF-ALL-ASSIGNMENT-POINTS-POSSIBLE}
This token returns sum of user's points possible based on the number of assignments that have been graded.

{CATEGORY:USER:NUMBER-OF-ASSIGNMENTS}
This token returns number of user's assignments (in the category) that have been graded.

{CATEGORY:USER:SUM-OF-ALL-ASSIGNMENT-POINTS}
This token returns sum of user points earned in the category.

Example 5:  Suppose you want to give negative points to students who did not submit one or more assignments. The penalty will be “-1%” on the total homework category percentage for each missing assignment. To achieve this, you can use the following formula:

 

The formula for the scenario in Example 5.