Predicted Score

knAtom For ideas on how to implement predictive learner analytics in your product, start here. If you decide to use the Predicted Score metric, please review the relevant performance considerations.

In this section:

Request Predicted Score

Request Predicted Score

POST /accounts/metrics/predicted-score

Request predicted score for one or more accounts.

Authorization

This endpoint can be called any user that belongs to the same partner as the accounts being requested.

Request Body

Parameter	Type	Optional	Description
account_ids	uuid[]	No	ID(s) of the accounts for which to request predicted score.
graph_ids	string[]	No	Graph ID (gref) for the graph that contains all of the LOs being requested. Currently only supports a single graph ID.
grouped_learning_objectives	object[]	No	Array of objects, each containing group ID and the set of LOs in the group. See fields below for details.
grouped_learning_objectives[]. group_id	string	No	Unique string identifier for the group, i.e. “Chapter 1”
grouped_learning_objectives[]. learning_objectives	object[]	No	Array of learning objective objects containing optional weights for each LO. See fields below for details.
grouped_learning_objectives[]. learning_objectives[]. learning_objective_id	string	No	Learning objective ID (lref)
grouped_learning_objectives[]. learning_objectives[]. weight	integer	Yes	Weight for the learning objective. Must be a positive integer. If not specified, weight will be set to 1. For example: When requesting predicted score for an exam with 5 questions from LO A, 3 questions from LO B, and 1 question from LO C, assign the following weights: `{LO_A: 5, LO_B: 3, LO_C: 1}`
confidence_levels	integer[]	No	List of “confidence levels” for the predicted score that are being requested. Should be one or more values between 0 and 100.
get_overall_score	boolean	Yes	Whether to return an overall predicted score for all LOs across all of the groups. If not present, will default to `false`. Note: If there is only one group, then the overall score will be the same as the score for the group.
get_learning_objective_scores	boolean	Yes	Whether to return a predicted score for each LO in addition to the predicted score for each group. If not present, will default to `false`. Notes: Weights will not impact per-LO scores. If there is only one LO in a group, then the LO score will be the same as its group score.
learning_objective_coverage_requirement	integer	Yes	The number of questions a student must have answered on a learning objective across previous assignments for that learning objective to be considered fully “covered.” Defaults to 4.

Sample Request Body

{
  "account_ids": [
    "57466e95-6019-498d-9c42-9180aa663304"
  ],
  "graph_ids": [
    "gref-Knewton Statistics"
  ],
  "grouped_learning_objectives": [
    {
      "group_id": "Chapter 1",
      "learning_objectives": [
        {
          "learning_objective_id": "lref-lo56204"
        },
        {
          "learning_objective_id": "lref-lo99879",
          "weight": 2
        }
      ]
    },
    {
      "group_id": "Chapter 2",
      "learning_objectives": [
        {
          "learning_objective_id": "lref-lo34502"
        }
      ]
    }
  ],
  "confidence_levels": [20, 50, 80],
  "get_overall_score": true,
  "get_learning_objective_scores": true,
  "learning_objective_coverage_requirement": 4
}

Response Body

Parameter	Type	Optional	Description
account_scores	object	No	Object mapping each account ID to the predicted-score object
account_scores[]. group_scores	object[]	No	Array of objects, each containing the group ID and the scores-at-confidence for the group. Always returned. Ordered by the order of the groups in the request.
account_scores[]. group_scores[]. group_id	string	No	Unique string identifier for the group, i.e. “Chapter 1”
account_scores[]. group_scores[]. scores	object	No	The scores-at-confidence for the group. See *scores[]. below for details
account_scores[]. group_scores[]. group_learning_objective_coverage	double	No	The average coverage across the LOs of the group, indicating the degree to which prior student work satisfies the requester’s threshold for minimum coverage. A value of 1.0 indicates the student has answered at least learning_objective_coverage_requirement questions on each LO of the group. For details on how this is computed see account_scores[].learning_objective_scores[].learning_objective_coverage
account_scores[]. learning_objective_scores	object[]	Yes	Array of objects, each containing the learning objective ID, its graph ID, and the scores-at-confidence for the learning objective. Returned if get_learning_objective_scores = `true`. Ordered by learning objective ID, then graph ID.
account_scores[]. learning_objective_scores[]. learning_objective_id	string	Yes	Learning objective ID (lref)
account_scores[]. learning_objective_scores[]. graph_id	string	Yes	Graph ID (gref) for the given learning objective
account_scores[]. learning_objective_scores[]. scores	object	Yes	The scores-at-confidence for the learning objective. See *scores[]. below for details
account_scores[]. learning_objective_scores[]. learning_objective_coverage	double	Yes	The fraction of learning_objective_coverage_requirement done for this learning objective, with a max of 1.0. If, for example, the student has answered 0, 1, 2, or 3 unique questions on the LO, the coverage will be 0.0, 0.25, 0.5, or 0.75, respectively. If they’ve answered 4 or more questions, it will be 1.0, indicating they have reached the requester’s threshold for fully “covering” the LO in previous assignment work.
account_scores[]. overall_score	object	Yes	The scores-at-confidence for all the groups combined. See *scores[]. below for details. Returned if get_overall_score = `true`.
account_scores[]. overall_learning_objective_coverage	double	Yes	The average coverage across the LOs of the exam, indicating the degree to which prior student work satisfies the requester’s threshold for minimum coverage. A value of 1.0 indicates the student has answered at least learning_objective_coverage_requirement questions on each LO. For details on how this is computed see account_scores[].learning_objective_scores[].learning_objective_coverage
*scores[]. confidence_level	integer	No	Confidence level requested
*scores[]. predicted_score	double	No	Predicted score for given confidence level. Will always be between 0.0 and 1.0

Sample Response Body

{
  "code": 200,
  "message": "",
  "error_id": "",
  "account_scores": {
    "57466e95-6019-498d-9c42-9180aa663304": {
      "overall_score": [
        {
          "confidence_level": 20,
          "predicted_score": 0.43
        },
        {
          "confidence_level": 50,
          "predicted_score": 0.67
        },
        {
          "confidence_level": 80,
          "predicted_score": 0.85
        }
      ],
      "overall_learning_objective_coverage": 0.77,
      "grouped_scores": [
        {
          "group_id": "Chapter 1",
          "scores": [
            {
              "confidence_level": 20,
              "predicted_score": 0.37
            },
            {
              "confidence_level": 50,
              "predicted_score": 0.53
            },
            {
              "confidence_level": 80,
              "predicted_score": 0.66
            }
          ],
          "group_learning_objective_coverage": 0.71
        },
        {
          "group_id": "Chapter 2",
          "scores": [
            {
              "confidence_level": 20,
              "predicted_score": 0.78
            },
            {
              "confidence_level": 50,
              "predicted_score": 0.83
            },
            {
              "confidence_level": 80,
              "predicted_score": 0.89
            }
          ],
          "group_learning_objective_coverage": 0.83
        }
      ],
      "learning_objective_scores": [
        {
          "learning_objective_id": "lref-lo56204",
          "graph_id": "gref-Knewton Statistics",
          "scores": [
            {
              "confidence_level": 20,
              "predicted_score": 0.37
            },
            {
              "confidence_level": 50,
              "predicted_score": 0.53
            },
            {
              "confidence_level": 80,
              "predicted_score": 0.66
            }
          ],
          "learning_objective_coverage": 0.75
        },
        {
          "learning_objective_id": "lref-lo99879",
          "graph_id": "gref-Knewton Statistics",
          "scores": [
            {
              "confidence_level": 20,
              "predicted_score": 0.78
            },
            {
              "confidence_level": 50,
              "predicted_score": 0.83
            },
            {
              "confidence_level": 80,
              "prediected_score": 0.89
            }
          ],
          "learning_objective_coverage": 1.0
        },
        {
          "learning_objective_id": "lref-lo34502",
          "graph_id": "gref-Knewton Statistics",
          "scores": [
            {
              "confidence_level": 20,
              "predicted_score": 0.78
            },
            {
              "confidence_level": 50,
              "predicted_score": 0.83
            },
            {
              "confidence_level": 80,
              "predicted_score": 0.89
            }
          ],
          "learning_objective_coverage": 0.5
        }
      ]
    }
  }
}