Get Reading Forecast for Individuals

Overview

Given a prior student ability and uncertainty, this function forecasts the students performance on an assessment in the future. This calculation takes into consideration the number of days since the last student assessment and the future assessment. It also takes into consideration an uncertainty associated with the assessment.

Outputs include the students projected ability as measured by the assessment as well as an uncertainty measure associated with this forecast.

Also, this function takes as a parameter an array of cutLevels. These are in essence performance milestones, ranked from least to greatest. For each of these cut levels, this function will provide the probability that a student’s performance on the assessment will fall into that performance band.

URL

POST /api/forecast/reading

Request


Parameter	Type	Description
`priorAbility`	Integer	The student’s prior ability estimate.
`priorUncertainty`	Integer	Uncertainty associated with the student’s prior ability estimate.
`testUncertainty`	Number	Uncertainty of the difficulty of the test that student performance is to be forecasted for. MetaMetrics sends this information in spreadsheet format.
`elapsedDays`	Integer	Number of days from the date of the `priorAbility` to the date of the future test that is being forecasted.
`cutLevels`	Array	An array of performance levels based on expected future ability levels, measured in Lexile or Quantile. MetaMetrics sends this information in spreadsheet format.

Response


Parameter	Type	Description
`ability`	Integer	The student’s forecasted ability estimate.
`uncertainty`	Integer	Uncertainty associated with the student’s forecasted ability estimate.
`probabilities`	Array	The probabilities that the student will fall into each of the performance bands, as defined by the `cutLevels`.
`apiVersion`	String	The current version number for the API.
`framework`	String	Either Lexile or Quantile; framework used to produce the measure.

Code Examples

The following show an example of the request followed by an example of the response. The Python example is written for use with Python 3 and above.

import java.io.BufferedReader;
import java.io.IOException;
import java.io.InputStreamReader;
import java.util.List;
import java.util.ArrayList;
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;
import org.json.JSONArray;

public class ForecastReading {
    public static void main (String[] args) {
        try {
            // Authorization
            String baseURL = "https://forecast.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 = json.getString("accessToken");
            Integer expires = json.getInt("expiresIn");

            // Forecast Reading example
            HttpPost postForm = new HttpPost(baseURL + "/api/forecast/reading");

            JSONObject postData = new JSONObject();
            postData.put("priorAbility", 601);
            postData.put("priorUncertainty", 60);
            postData.put("elapsedDays", 45);
            postData.put("testUncertainty", 50.5);
            
            JSONArray cutLevels = new JSONArray();
            cutLevels.put(367.5);
            cutLevels.put(785.5);
            postData.put("cutLevels", cutLevels);

            StringEntity formInput = new StringEntity(postData.toString());
            postForm.setEntity(formInput);
            postForm.setHeader(HttpHeaders.AUTHORIZATION, "Bearer " + token);
            postForm.setHeader(HttpHeaders.CONTENT_TYPE, "application/json");
            response = client.execute(postForm); 
            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());
            
            Double ability = output.getDouble("ability");
            Double uncertainty = output.getDouble("uncertainty");

            List<Double> probabilities = new ArrayList<>();
            JSONArray probabilitiesJSON = output.getJSONArray("probabilities");
            for(int i = 0; i < probabilitiesJSON.length(); i++) {
                probabilities.add(probabilitiesJSON.getDouble(i));
            }

            String framework = output.getString("framework");
            String apiVersion = output.getString("apiVersion");
        } catch(IOException e) {
            e.printStackTrace();
        }
    }
}

# /authToken

import requests
import json

base_url = "https://forecast.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/forecast/reading

data = {
    "priorAbility": 500,
    "priorUncertainty": 100,
    "elapsedDays": 15,
    "testUncertainty": 50.5,
    "cutLevels": [387.5, 785.5],
}
response = requests.post(f"{base_url}/api/forecast/reading", headers=headers, json=data)
response.json()
# returns
# {
#    "ability": <float>,
#    "uncertainty": <float>
#    "probabilities": <list:float>
#    "framework": ["lexile" or "quantile"]
#    "apiVersion": <string>
# }