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.
`abilityDisplay`	String	A formatted, reader-friendly version of the forecasted ability score (e.g. "105L"). Use this value when displaying results to teachers, parents, or students.
`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 build version of the API that processed the request (e.g. "3dd0523b-master").
`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>,
                    #    "abilityDisplay": <string>,
                    #    "uncertainty": <float>
                    #    "probabilities": <list:float>
                    #    "framework": ["lexile" or "quantile"]
                    #    "apiVersion": <string>
                    # }