Datasets: ibk-analysis-by-question Reference

Usage

The format of requests to Data API use the following syntax:

https://data.learnosity.com/[LTS_VERSION]/reports/datasets

For example, to use the 2023.3.LTS version and the 'Initialize Dataset' endpoint, you would create a request like so:

https://data.learnosity.com/v2023.3.LTS/reports/datasets

Initialize dataset

Initialize an "ibk-analysis-by-question" (Item bank analysis by Question) dataset via the SET reports/datasets endpoint.

To control which session data should be used for the Item bank analysis, choose from the following:

  • Specify file_count: 1 (or more) to upload an explicit list of sessions that should be considered for analysis. In this case, the endpoint returns URL(s) to which each input file must be uploaded before the data compilation job can commence. Read about the upload process for details.
  • Alternatively, specify file_count: 0 and provide any desired filter parameters. In this case, the data compilation job is queued immediately based on the given filters, and the endpoint response includes a corresponding job_reference for polling the job's progress.

Other parameters for the initialize request are described below:

Endpoint /[LTS_VERSION]/reports/datasets
HTTP Method POST
Action Type set
dataset_type
string

Specifies the type of dataset to initialize.

Must be ibk-analysis-by-question.

file_count
int

Number of input data files to upload containing specific session IDs to be analyzed. The response object will contain this many file URLs. Specify 0 to skip this step and analyze all sessions, or to filter sessions using the filters object instead. Specify 1 to upload all the session IDs in one file.

You would want to use this if your report is based on a large number of sessions, and prefer to split your data into a number of smaller files.

Note: Input files may not be used in combination with session filters specified in the filters object below. They are mutually exclusive.

organisation_id
int

The ID of the organization (Item bank) to analyze. If you are unsure of which ID to select, log in to the Learnosity Console to view your Item banks.

If not specified, the default organization of the requesting API consumer is used.

filters
object

Specifies a set of filters for the report.

You would want to use this to restrict the data returned based on a specific activity_id or date and time range.

See child attributes detailed below.

filters.activity_id
array

An array of string activity_id values.

Up to 100 activity_id values may be provided.

filters.mintime
string

Filter to exclude sessions submitted before mintime. Values can be provided in either RFC3339 section 5.6 “yyyy-mm-ddThh:mm:ssZ+” or Unix timestamp format.

filters.maxtime
string

Filter to exclude sessions submitted after maxtime. Values can be provided in either RFC3339 section 5.6 “yyyy-mm-ddThh:mm:ssZ+” or Unix timestamp format.

options
object

Object containing report configuration parameters, see child attributes detailed below.

options.default_sort_field
string

Define the default field used for sorting all group data in the dataset.

Note: the named field must be present in fields.

options.default_sort_order
string

Choose ascending or descending order for sorting group rows.

Possible values:

  • "desc": descending order.
  • "asc": ascending order.

Default: "desc"

options.fields
array[string]

The fields to be calculated for all Questions in the dataset.

See the list of available fields.

options.summary_fields
array[string]

The summary fields to be calculated. These fields will appear in the dataset summary file.

See the list of available fields.

Example

{
    "dataset_type": "ibk-analysis-by-question",
    "organisation_id": 6,
    "filters": {
        "activity_id": ["20230106b_ELA_comprehension"],
        "mintime": "2023-01-01",
        "maxtime": "2023-12-31"
    },
    "file_count": 0,
    "options": {
        "default_sort_field": "p_value",
        "default_sort_order": "asc",
        "fields": [
            "organisation_id",
            "item_reference",
            "question_number",
            "question_reference",
            "count_sessions",
            "count_attempted",
            "p_value",
            "p_value_if_attempted",
            "stddev_p_value",
            "stddev_p_value_if_attempted"
        ],
        "summary_fields": [
            "count_questions"
        ]
    }
}

/* Example response:
{
    "meta": {},
    "data": {
        "dataset_id": "686b89d5-2911-4721-a6fc-7b43f57772aa",
        "job_reference": "2c2e3d6d-d446-4850-8704-ccbf41e4d91c"
    }
}
*/

If specifying an explicit list of sessions for the "ibk-analysis-by-question" dataset, upload one or more NDJSON input files containing user_id and session_id properties. The datasets implementation guide provides details on the upload process.

{"user_id": "ANONYMIZED_USER_aeee19f1", "session_id": ["f77b6600-dfd7-4a58-a461-4e5d9e667e43"]}
{"user_id": "ANONYMIZED_USER_aeee19f2", "session_id": ["46b0dc55-bb79-45c3-8d09-2c99cc4e7b39"]}
{"user_id": "ANONYMIZED_USER_aeee19f3", "session_id": ["3bd372ae-b302-4078-88e6-39436b7c5bad"]}
{"user_id": "ANONYMIZED_USER_aeee19f4", "session_id": ["3457ec0f-7126-4e9c-8ccb-9f955353e14f"]}
{"user_id": "ANONYMIZED_USER_aeee19f5", "session_id": ["ae92be44-8769-4a70-9503-8954c1a7bca8"]}
{"user_id": "ANONYMIZED_USER_aeee19f6", "session_id": ["1ee32517-2ec2-4690-a9b0-cc69b9b0e30c"]}
{"user_id": "ANONYMIZED_USER_aeee19f7", "session_id": ["6cb15b97-2757-4cc8-bfa0-75200b7534df"]}
{"user_id": "ANONYMIZED_USER_aeee19f8", "session_id": ["fc870d98-719b-4af3-825a-5a27cd5993ee"]}

Retrieves the URL of raw data files for a specified dataset. The endpoint returns an array of output file objects containing pre-signed URLs. Send an HTTP GET request to the pre-signed URL to retrieve the file.

Endpoint /[LTS_VERSION]/reports/datasets
HTTP Method POST
Action Type get
dataset_id
string

The dataset to retrieve.

dataset_type
string

The type of dataset identified by dataset_id.

Must be "ibk-analysis-by-question".

data[].type
string

The output type. Can be either "summary" or "dataset".

data[].format
string

The file format of the output file. Can be returned as either "json" or "csv.gz" (compressed CSV).

data[].files
array

List of pre-signed URLs for downloading the files. In most cases there will be a single URL, but we allow for particularly large datasets to be split across multiple files.

Example

{
    "dataset_type": "ibk-analysis-by-question",
    "dataset_id": "686b89d5-2911-4721-a6fc-7b43f57772aa"
}

/* Example response:
{
    "meta": {},
    "data": [
        {
            "type": "summary",
            "format": "json",
            "files": [
                "https://learnosity-reportdatasets-va.s3.amazonaws.com/reports/0034/ibk-analysis-by-question/686b89d5-2911-4721-a6fc-7b43f57772aa/2017-08-02_iabq_686b89d5_summary.json?AWSAccessKeyId=AKIAxxx"
            ]
        },
        {
            "type": "dataset",
            "format": "csv.gz",
            "files": [
                "https://learnosity-reportdatasets-va.s3.amazonaws.com/reports/0034/ibk-analysis-by-question/686b89d5-2911-4721-a6fc-7b43f57772aa/2017-08-02_iabq_686b89d5_result_1.csv.gz?AWSAccessKeyId=AKIAxxx",
                "https://learnosity-reportdatasets-va.s3.amazonaws.com/reports/0034/ibk-analysis-by-question/686b89d5-2911-4721-a6fc-7b43f57772aa/2017-08-02_iabq_686b89d5_result_2.csv.gz?AWSAccessKeyId=AKIAxxx"
            ]
        }
    ]
}
*/

The contents of the different kinds of output files are described below.

Type Format Description
summary json A JSON summary of your dataset. Contains summary_fields data.

 

{
    "summary": {
        "count_questions": 12323
    },
    "fields": [
        "item_reference",
        "question_number",
        "question_reference",
        "count_sessions",
        "count_attempted",
        "p_value",
        "p_value_if_attempted",
        "stddev_p_value",
        "stddev_p_value_if_attempted"
    ],
    "sort_field": "p_value",
    "sort_order": "asc"
}

 

Type Format Description
dataset csv.gz The full dataset containing fields data for all Questions. 

 

organisation_id,item_reference,question_number,question_reference,count_sessions,count_attempted,p_value,stddev_p_value,p_value_if_attempted,stddev_p_value_if_attempted
6,item_3,1,question_3,13719,12169,0.431,0.495,0.486,0.495
6,item_2,1,question_2,7111,6550,0.447,0.497,0.485,0.497
6,item_7,1,question_7,8534,8205,0.479,0.5,0.498,0.5
6,item_6,1,question_6,7111,6650,0.488,0.5,0.522,0.5
6,item_9,1,question_9,7350,6679,0.493,0.5,0.542,0.5
6,item_10,1,question_10,8746,8139,0.505,0.5,0.543,0.5
6,item_8,1,question_8,10508,9618,0.508,0.5,0.555,0.5
6,item_2,1,question_2,13836,13330,0.513,0.5,0.532,0.5
6,item_1,1,question_1,12855,11124,0.522,0.499,0.603,0.499

 

Was this article helpful?

Did you arrive here by accident? If so, learn more about Learnosity.