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.1.LTS version and the 'Initialize Dataset' endpoint, you would create a request like so:

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

Initialize an "ibk-analysis-by-question" dataset via the SET reports/datasets endpoint.

To control which session data should be used for the itembank 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 /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. If your report is based on a large number of sessions, you may prefer to split your data into a number of smaller files.

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

organisation_id
int

Optional. The ID of the organisation (bank) to analyze. Discuss this with Learnosity Support if in doubt.

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

filters
object

Specifies a set of filters for the report.

filters.activity_id
array

An array of string activity_id values. Up to 100 activity_id values may be provided.

filters.mintime
string

Optional 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

Optional 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

String to determine the default sort field for data in the dataset. The datasets rows will be ordered using this field. The named field must be present in fields.

options.default_sort_order
string

String to determine sort order for rows. Valid values are:

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

Default: desc

options.fields
array

Array of strings, specifying the fields to be calculated for all questions in the dataset. See the list of available fields.

options.summary_fields
array

Array of strings, specifying 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": ["20170106b_ELA_comprehension"],
        "mintime": "2017-01-01",
        "maxtime": "2018-01-01"
    },
    "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"]}
{"user_id": "ANONYMIZED_USER_aeee19f9",           "session_id": ["0d51d05a-00b5-4406-902a-4ae4f8e813b0"]}
{"user_id": "ANONYMIZED_USER_aeee19fa",           "session_id": ["be914960-c6d6-4970-8037-2dcb0bcd1444"]}
{"user_id": "ANONYMIZED_USER_aeee19fb",           "session_id": ["2c0b9483-2838-4b4a-b151-e15ca1adb2b4"]}
{"user_id": "ANONYMIZED_USER_aeee19fc",           "session_id": ["d771d689-0278-4649-84f6-d8add3fa74de"]}
{"user_id": "ANONYMIZED_USER_aeee19fd",         "session_id": ["ffa7bf43-c400-4b3b-ac98-7d463f960fae"]}
{"user_id": "ANONYMIZED_USER_aeee19fe",           "session_id": ["d2c63728-2876-4ae8-bc9d-2be2781126f2"]}
{"user_id": "ANONYMIZED_USER_aeee19ff",     "session_id": ["fc160403-4cfc-4d3b-8933-08cd6f87bc0a"]}
{"user_id": "ANONYMIZED_USER_aeee1a00",            "session_id": ["4515e067-9f17-489f-8779-cbdde802ebe4"]}
{"user_id": "ANONYMIZED_USER_aeee1a01",         "session_id": ["a0f6c87d-7895-46d8-baa7-6359f35237c8"]}
{"user_id": "ANONYMIZED_USER_aeee1a02",             "session_id": ["e5e459c8-2b3f-4efb-ad76-3fc8e5400025"]}
{"user_id": "ANONYMIZED_USER_aeee1a03",           "session_id": ["1a31a6d5-bfe5-43ec-9314-8441e34abd9b"]}
{"user_id": "ANONYMIZED_USER_aeee1a04",          "session_id": ["ae8bd2bc-d2a4-450b-9e8a-3099ab9dc2a0"]}
{"user_id": "ANONYMIZED_USER_aeee1a05",         "session_id": ["d315ad51-7949-41d6-b443-aa9ec7142936"]}
{"user_id": "ANONYMIZED_USER_aeee1a06",              "session_id": ["543bfc08-5001-4f19-99d8-a05afda72bf5"]}
{"user_id": "ANONYMIZED_USER_aeee1a07",           "session_id": ["b867295a-174c-44ca-befa-de9f073575ca"]}
{"user_id": "ANONYMIZED_USER_aeee1a08",         "session_id": ["4b1659d4-8a61-4edc-a233-c49732f365ce"]}
{"user_id": "ANONYMIZED_USER_aeee1a09",          "session_id": ["1d71f74e-9037-4379-9c26-a9ba0aa8c63b"]}
{"user_id": "ANONYMIZED_USER_aeee1a0a",        "session_id": ["4737fb2d-90a4-4311-87db-e62d32f6705c"]}
{"user_id": "ANONYMIZED_USER_aeee1a0b",          "session_id": ["54dfb8d2-36b9-4e11-8ee2-c3075afb1b6b"]}
{"user_id": "ANONYMIZED_USER_aeee1a0c",           "session_id": ["e09062fc-3ded-449b-88c4-c7f8e596099b"]}
{"user_id": "ANONYMIZED_USER_aeee1a0d",          "session_id": ["5de28d47-0b23-4458-a039-9511cdb94851"]}
{"user_id": "ANONYMIZED_USER_aeee1a0e",           "session_id": ["5d0e2ca3-a916-4852-8817-0049690654ba"]}
{"user_id": "ANONYMIZED_USER_aeee1a0f",           "session_id": ["08fc872d-7f35-4852-8d2f-a09400060ae3"]}
{"user_id": "ANONYMIZED_USER_aeee1a10",          "session_id": ["51d09deb-0ea3-4eb7-9ef2-7d1eac8d2a97"]}
{"user_id": "ANONYMIZED_USER_aeee1a11",           "session_id": ["590065ac-0fb9-420b-92db-612d9d5702de"]}
{"user_id": "ANONYMIZED_USER_aeee1a12",           "session_id": ["d69c032b-516c-40de-8766-b48f57f492a6"]}
{"user_id": "ANONYMIZED_USER_aeee1a13",         "session_id": ["f354cf68-b12e-4b10-8d83-7f676b4e1b73"]}
{"user_id": "ANONYMIZED_USER_aeee1a14",          "session_id": ["77dd632c-b1a6-4c7b-b3db-a0beca4f2c87"]}
{"user_id": "ANONYMIZED_USER_aeee1a15",           "session_id": ["f4f72031-b9ed-41ce-bad3-12d1d6496ab7"]}
{"user_id": "ANONYMIZED_USER_aeee1a16",         "session_id": ["f3dff73f-01c0-455c-918d-4d16fec0c171"]}
{"user_id": "ANONYMIZED_USER_aeee1a17",           "session_id": ["8fc131b5-4fd8-4442-92f7-1226054b1776"]}
{"user_id": "ANONYMIZED_USER_aeee1a18",       "session_id": ["447909ec-624b-473c-8b2a-0dde5d76ba8b"]}
{"user_id": "ANONYMIZED_USER_aeee1a19",            "session_id": ["b8371baa-f490-481b-9de8-6ba69fac016c"]}
{"user_id": "ANONYMIZED_USER_aeee1a1a",            "session_id": ["d651a515-d2ee-4a86-9336-6ab06ca43a28"]}
{"user_id": "ANONYMIZED_USER_aeee1a1b",        "session_id": ["fb07fafe-18f4-4004-9897-6bd6e41b94b2"]}
{"user_id": "ANONYMIZED_USER_aeee1a1c",     "session_id": ["f4d59234-b6ed-448f-a0d9-1ed0e95d45ad"]}
{"user_id": "ANONYMIZED_USER_aeee1a1d",          "session_id": ["bcc6e913-be1d-41d3-9312-91e40ae9a933"]}
{"user_id": "ANONYMIZED_USER_aeee1a1e",           "session_id": ["26d778c4-71d9-496b-a66b-7cf261b77232"]}
{"user_id": "ANONYMIZED_USER_aeee1a1f",         "session_id": ["07625b61-5e2c-4b47-b858-09fd249770a3"]}
{"user_id": "ANONYMIZED_USER_aeee1a20",          "session_id": ["7acb38d3-4466-4188-a396-6a99f5f75d55"]}
{"user_id": "ANONYMIZED_USER_aeee1a21",       "session_id": ["19cb3b84-4eb2-4f75-a486-160b05e94c1f"]}
{"user_id": "ANONYMIZED_USER_aeee1a22",             "session_id": ["803287a4-91d7-47b1-b80f-8cd97627abbb"]}
{"user_id": "ANONYMIZED_USER_aeee1a23",            "session_id": ["f1df0d94-cc64-4c23-8c35-8715fac9b6d4"]}
{"user_id": "ANONYMIZED_USER_aeee1a24",          "session_id": ["bb4aef8e-b7cb-45f8-892c-34fa743aa9c6"]}
{"user_id": "ANONYMIZED_USER_aeee1a25",          "session_id": ["67cd2f49-ebb8-4fcb-9d2b-c524c81dd4d3"]}
{"user_id": "ANONYMIZED_USER_aeee1a26",         "session_id": ["30009061-c17d-4263-991c-007e1103fa8e"]}
{"user_id": "ANONYMIZED_USER_aeee1a27",          "session_id": ["f3662052-5212-41fe-8588-ccb3a493d7bb"]}
{"user_id": "ANONYMIZED_USER_aeee1a28",    "session_id": ["f1129577-f7b7-43e0-a23d-80c938bebe90"]}
{"user_id": "ANONYMIZED_USER_aeee1a29",       "session_id": ["8f8960a7-49e4-49a5-a632-0c317dd3b6a3"]}
{"user_id": "ANONYMIZED_USER_aeee1a2a",       "session_id": ["8a329305-957a-45ca-85aa-d303dad3c63c"]}
{"user_id": "ANONYMIZED_USER_aeee1a2b",         "session_id": ["bc2fe750-f80f-4176-9d25-c496b8a306f6"]}
{"user_id": "ANONYMIZED_USER_aeee1a2c",        "session_id": ["2c14f50f-c093-49c8-b629-f042231ff703"]}
{"user_id": "ANONYMIZED_USER_aeee1a2d",          "session_id": ["0c63f807-fc2b-4bc1-831c-7f592bdbc751"]}
{"user_id": "ANONYMIZED_USER_aeee1a2e",  "session_id": ["68b4fcd6-e117-425a-900a-39b5dcb4c986"]}
{"user_id": "ANONYMIZED_USER_aeee1a2f",            "session_id": ["520dbb37-a207-4265-9c2e-1ba87699c1c9"]}
{"user_id": "ANONYMIZED_USER_aeee1a30",        "session_id": ["0a3d4b79-9fcf-4264-9479-61c0a2539dc6"]}
{"user_id": "ANONYMIZED_USER_aeee1a31",          "session_id": ["b21fd23f-e25e-4680-bd0b-d69c4b9e289d"]}
{"user_id": "ANONYMIZED_USER_aeee1a32",           "session_id": ["3842f583-7de5-44fc-afc8-f57d4e33f3ce"]}
{"user_id": "ANONYMIZED_USER_aeee1a33",              "session_id": ["c068de8b-78df-4c74-820f-34d3dfbaea65"]}
{"user_id": "ANONYMIZED_USER_aeee1a34",          "session_id": ["3dfe9e36-445a-404a-a6ac-f2264628a0dc"]}
{"user_id": "ANONYMIZED_USER_aeee1a35",            "session_id": ["1b49259e-fa34-4c7e-896b-ae6714cd8992"]}
{"user_id": "ANONYMIZED_USER_aeee1a36",             "session_id": ["1a3e09dd-ad4a-4817-8421-f6a1cbe8f079"]}
{"user_id": "ANONYMIZED_USER_aeee1a37",         "session_id": ["199f4ca9-4e58-42e8-bf31-b1af768e2115"]}
{"user_id": "ANONYMIZED_USER_aeee1a38",           "session_id": ["a3cd3dcf-6ec2-4fc5-8cc6-d50154a443f2"]}
{"user_id": "ANONYMIZED_USER_aeee1a39",      "session_id": ["6f2768ef-bb85-4bf5-920a-ec30dcd743e6"]}
{"user_id": "ANONYMIZED_USER_aeee1a3a",     "session_id": ["64944e23-1f03-44c4-8cd4-c7bb0e7a4ed1"]}
{"user_id": "ANONYMIZED_USER_aeee1a3b",        "session_id": ["e184efb3-6a41-46b4-a52f-e07fa160bbaa"]}
{"user_id": "ANONYMIZED_USER_aeee1a3c",    "session_id": ["d855b9b5-6404-4e4f-95ac-364cc831e8f0"]}
{"user_id": "ANONYMIZED_USER_aeee1a3d",            "session_id": ["e52fe407-39a2-4069-8ad1-69f263117e7b"]}
{"user_id": "ANONYMIZED_USER_aeee1a3e",       "session_id": ["c592da55-df2b-42ee-b049-fd00d6870046"]}
{"user_id": "ANONYMIZED_USER_aeee1a3f",     "session_id": ["975809fa-1099-4a1c-a4b8-87eb56ee4364"]}
{"user_id": "ANONYMIZED_USER_aeee1a40",        "session_id": ["28d91a27-3a9a-4293-85c3-445e5a48f76e"]}
{"user_id": "ANONYMIZED_USER_aeee1a41",          "session_id": ["1c66b0ed-2a95-48c2-b227-a5ae327772ab"]}
{"user_id": "ANONYMIZED_USER_aeee1a42",        "session_id": ["30f121d8-33ec-4a7d-93d9-9ecc097f75b2"]}
{"user_id": "ANONYMIZED_USER_aeee1a43",      "session_id": ["5db92946-a16c-40af-a5ba-eac9b4d9189b"]}
{"user_id": "ANONYMIZED_USER_aeee1a44",           "session_id": ["872b9d97-bb6d-499f-822c-4af273fd42c6"]}
{"user_id": "ANONYMIZED_USER_aeee1a45",           "session_id": ["52dd502b-45be-4858-8cb5-be02f5530409"]}
{"user_id": "ANONYMIZED_USER_aeee1a46",          "session_id": ["70971a1b-252c-429a-b5bb-821bb7b385cf"]}
{"user_id": "ANONYMIZED_USER_aeee1a47",          "session_id": ["c5091057-794f-4d93-9264-097114463ef3"]}
{"user_id": "ANONYMIZED_USER_aeee1a48",           "session_id": ["c04b080f-8377-469e-b9b0-f0ae5cc0cf07"]}
{"user_id": "ANONYMIZED_USER_aeee1a49",            "session_id": ["8acf0101-d776-4262-ac8f-043fead2a6fd"]}
{"user_id": "ANONYMIZED_USER_aeee1a4a",        "session_id": ["022ed794-f75f-4293-be59-57acb8ea85db"]}
{"user_id": "ANONYMIZED_USER_aeee1a4b",             "session_id": ["329a40dd-30ea-48ac-9a05-d4a59f3d8dec"]}
{"user_id": "ANONYMIZED_USER_aeee1a4c",          "session_id": ["31689030-5fa1-44f2-8b6c-740d6e465ce5"]}
{"user_id": "ANONYMIZED_USER_aeee1a4d",       "session_id": ["fe2eb5ac-b8c7-4464-bdae-a5c284066668"]}
{"user_id":"ANONYMIZED_USER_aeee1a4e",           "session_id": ["d4ad04a5-e252-4d22-aba0-490319fd9d1a"]}
{"user_id":"ANONYMIZED_USER_aeee1a4f",          "session_id": ["95095fde-fdd7-44e9-ad0a-565ca285ab56"]}
{"user_id":"ANONYMIZED_USER_aeee1a50",           "session_id": ["a4c8b47f-93d8-4602-a732-18cfa57de30c"]}
{"user_id":"ANONYMIZED_USER_aeee1a51",        "session_id": ["623e2cee-4482-4cdf-be60-e17860f704fd"]}
{"user_id":"ANONYMIZED_USER_aeee1a52",             "session_id": ["1561b280-fe49-4da9-952b-70ea1830c82d"]}
{"user_id":"ANONYMIZED_USER_aeee1a53",        "session_id": ["18b2591f-fed2-4711-a4b3-9c48e76f7573"]}
{"user_id":"ANONYMIZED_USER_aeee1a54",           "session_id": ["2c1612c7-8fd2-4e0a-a105-cd6cdb431ca1"]}
{"user_id":"ANONYMIZED_USER_aeee1a55",         "session_id": ["69a379bb-669a-487c-9f43-51ffe3218079"]}
{"user_id":"ANONYMIZED_USER_aeee1a56",         "session_id": ["77d524f5-f608-420f-9afb-e93b1890ac5b"]}
{"user_id":"ANONYMIZED_USER_aeee1a57",            "session_id": ["14dfcdd3-890d-41fe-a1e4-95e5809c5383"]}
{"user_id":"ANONYMIZED_USER_aeee1a58",       "session_id": ["9e088b56-18e9-4c17-89e7-896cd2e0bffb"]}
{"user_id":"ANONYMIZED_USER_aeee1a59",         "session_id": ["582ce444-e518-4837-8d53-7a3fbe3f7734"]}
{"user_id":"ANONYMIZED_USER_aeee1a5a",           "session_id": ["8f0dd407-2250-4210-ba25-3ede7713a02a"]}
{"user_id":"ANONYMIZED_USER_aeee1a5b",           "session_id": ["312ff724-2b10-4f97-bd2b-a6d690201540"]}
{"user_id":"ANONYMIZED_USER_aeee1a5c",       "session_id": ["d25ef286-7062-4798-afcf-825193aee6f8"]}
{"user_id":"ANONYMIZED_USER_aeee1a5d",         "session_id": ["25910d68-7f6b-4d3c-a2e5-5320317400b4"]}

Retrieves the URL location 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 /reports/datasets
HTTP Method POST
Action Type get
dataset_id
string

String identifier of the dataset to retrieve.

dataset_type
string

The type of dataset identified by dataset_id. Must be ibk-analysis-by-question.

data[].type
string

String identifier of the type of output. Can be summary or dataset.

data[].format
string

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

data[].files
array

Array of pre-signed URLs. 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