Get Measure Using Item Difficulty with Prior Student Information

Overview

This Bayesian function should be used when:

A passage and the associated item set has been administered to a student.
The items were generated with the Lexile Cloze API or a specific linking study was conducted.
The Lexile text measure of the passage is known.
There is prior information about a student. For example, a previously-computed ability (priorAbility) with uncertainty (priorUncertainty) and number of days since that assessment (elapsedDays).

URL

POST /api/score/items/difficulties/bayes

Request

The following parameters are required in the request. An example is provided in the Code Example section.


Parameter	Type	Description
`items`	Array	Array of item objects. Each item object is a dictionary with required parameters: `difficulty` Integer Array of integers representing measures of test items. `count` Array Number of items associated with each item difficulty in the `item_difficulties` list.
`numberCorrect`	Integer	Raw count of items answered correctly by the student.
`framework`	String	Either Lexile or Quantile; framework used to produce the measure.
`priorAbility`	Integer	The student’s prior ability estimate.
`priorUncertainty`	Integer	Uncertainty associated with the student’s prior ability estimate.
`elapsedDays`	Integer	Number of days since the student’s measure was last updated.

Response

This returns an object that contains the computed ability and uncertainty. See Scoring Service Response Codes for an explanation of error codes that might be returned. The Python example is written for use with Python 3 and above.


Parameter	Type	Description
`ability`	Integer	The student’s new ability estimate.
`uncertainty`	Integer	Uncertainty associated with the student’s new ability estimate.
`framework`	String	Either Lexile or Quantile; framework used to produce the measure.
`apiVersion`	String	The current version number for the API.

Code Examples

The following show examples of the request followed by the response.

import java.io.BufferedReader;
import java.io.IOException;
import java.io.InputStreamReader;
import java.util.HashMap;
import java.util.List;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.Map;
import org.apache.http.HttpHeaders;
import org.apache.http.HttpResponse;
import org.apache.http.client.HttpClient;
import org.apache.http.client.methods.HttpPost;
import org.apache.http.entity.StringEntity;
import org.apache.http.impl.client.HttpClientBuilder;

import org.json.JSONObject;


public class ItemDifficultiesBayes {
	public static void main( String[] args )
    {
    	try
    	{
			// Call 6

    		String baseURL = "https://scoring.lexile.com";
    		String clientId = "your_client_id";
    		String clientSecret = "your_client_secret";
    			
			HttpClient client = HttpClientBuilder.create().build();
			HttpPost authPost = new HttpPost(baseURL + "/authToken");
			JSONObject jsonInput = new JSONObject();
			jsonInput.put("clientId", clientId);
			jsonInput.put("clientSecret", clientSecret);
			StringEntity input = new StringEntity(jsonInput.toString());
			authPost.setEntity(input);
			authPost.setHeader(HttpHeaders.CONTENT_TYPE, "application/json");
			HttpResponse response = client.execute(authPost); 
			StringBuilder stringBuilder = new StringBuilder();
			BufferedReader rd = new BufferedReader(new InputStreamReader(response.getEntity().getContent()));
			String line;
			while ((line = rd.readLine()) != null) 
			{
			    stringBuilder.append(line);
			}
			JSONObject json = new JSONObject(stringBuilder.toString());
			String token = (String) json.get("accessToken");
			Integer expires = (Integer) json.get("expiresIn");

			// 1) Basic Example
			
			HttpPost postDifficutly = new HttpPost(baseURL + "/api/score/items/difficulties/bayes");
			JSONObject postData = new JSONObject();
			postData.put("numberCorrect", 2);
			postData.put("framework", "lexile");
			postData.put("priorAbility", 500);
			postData.put("priorUncertainty", 100);
			postData.put("elapsedDays", 50);
			
			JSONArray itemList = new JSONArray();
			for(int i=0; i < 3; i++) {
			    JSONObject item = new JSONObject();
			    item.put("difficulty", (i+1)*100);
			    itemList.put(item);
			}

            postData.put("items", itemList);
			
			StringEntity difficultyInput = new StringEntity(postData.toString());
			postDifficutly.setEntity(difficultyInput);
			postDifficutly.setHeader(HttpHeaders.AUTHORIZATION, "Bearer " + token);
			postDifficutly.setHeader(HttpHeaders.CONTENT_TYPE, "application/json");
			response = client.execute(postDifficutly); 
			stringBuilder = new StringBuilder();
			rd = new BufferedReader(new InputStreamReader(response.getEntity().getContent()));
			while ((line = rd.readLine()) != null) 
			{
			    stringBuilder.append(line);
			}
			
			JSONObject output = new JSONObject(stringBuilder.toString());
			Integer ability = (Integer) output.get("ability");
			Integer uncertainty = (Integer) output.get("uncertainty");
			String framework = (String) output.get("framework");
			String apiVersion = (String) output.get("apiVersion");

			
			// 2) Using Item Counts

			HttpPost postDifficutly2 = new HttpPost(baseURL + "/api/score/items/difficulties/bayes");
			JSONObject postData2 = new JSONObject();
			postData2.put("numberCorrect", 2);
			postData2.put("framework", "lexile");
			postData2.put("priorAbility", 500);
			postData2.put("priorUncertainty", 100);
			postData2.put("elapsedDays", 50);

			JSONArray itemList2 = new JSONArray();
			for(int i=0; i < 3; i++) {
			    JSONObject item = new JSONObject();
			    item.put("difficulty", (i+1)*100);
			    item.put("count",2);
			    itemList2.put(item);
			}

            postData2.put("items", itemList2);
			
			StringEntity difficultyInput2 = new StringEntity(postData2.toString());
			input.setContentType("application/json");
			postDifficutly2.setEntity(difficultyInput2);
			postDifficutly2.setHeader(HttpHeaders.AUTHORIZATION, "Bearer " + token);
			postDifficutly2.setHeader(HttpHeaders.CONTENT_TYPE, "application/json");
			response = client.execute(postDifficutly2); 
			stringBuilder = new StringBuilder();
			rd = new BufferedReader(new InputStreamReader(response.getEntity().getContent()));
			while ((line = rd.readLine()) != null) 
			{
			    stringBuilder.append(line);
			}
			JSONObject output2 = new JSONObject(stringBuilder.toString());
			Integer ability2 = (Integer) output2.get("ability");
			Integer uncertainty2 = (Integer) output2.get("uncertainty");
			String framework2 = (String) output2.get("framework");
			String apiVersion2 = (String) output2.get("apiVersion");
    	}
    	catch(IOException e) 
    	{
            e.printStackTrace();
        }
    }
}

# Call 6

# /authToken

import requests
import json

base_url = "https://scoring.lexile.com"
client_id = "your_client_id"  # replace with your provided client ID
client_secret = "your_client_secret"  # replace with your provided client secret
response = requests.post(
    f"{base_url}/authToken",
    data={"clientId": client_id, "clientSecret": client_secret},
)
access_token = response.json()["accessToken"]  # use in Authorization header

# use these headers to make requests
headers = {
    "Authorization": f"Bearer {access_token}",
    "Content-Type": "application/json",
}


# /api/score/items/difficulties/bayes

# 1) Basic Example
data = {
    "priorAbility": 500,
    "priorUncertainty": 100,
    "elapsedDays": 15,
    "numberCorrect": 2,
    "framework": "lexile",
    "items": [{"difficulty": 100}, {"difficulty": 300}, {"difficulty": 500}],
}
response = requests.post(
    f"{base_url}/api/score/items/difficulties/bayes", headers=headers, json=data
)
response.json()
# returns
# {
#    "ability": <int>,
#    "uncertainty": <int>
#    "framework": ["lexile" or "quantile"]
#    "apiVersion": <string>
# }


# 2) Using Counts
data = {
    "priorAbility": 500,
    "priorUncertainty": 100,
    "elapsedDays": 15,
    "numberCorrect": 2,
    "framework": "lexile",
    "items": [
        {"difficulty": 100, "count": 2},
        {"difficulty": 300, "count": 1},
        {"difficulty": 500, "count": 2},
    ],
}
response = requests.post(
    f"{base_url}/api/score/items/difficulties/bayes", headers=headers, json=data
)
response.json()
# returns
# {
#    "ability": <int>,
#    "uncertainty": <int>
#    "framework": ["lexile" or "quantile"]
#    "apiVersion": <string>
# }