Datasets: activity-summary-by-group Reference

You would want to use this dataset so that you can access raw data from Learnosity to perform your own custom data analysis and reporting.

See Implementing and Creating Datasets for Download or Reporting for more information about datasets.

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 v2023.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 "activity-summary-by-group" dataset via the SET reports/datasets endpoint. The following parameters are supported:
Endpoint /[LTS_VERSION]/reports/datasets
HTTP Method POST
Action Type set
dataset_type
string

Specifies the type of dataset to initialize.

Must be "activity-summary-by-group".
file_count
int

Number of group data files to accept during the upload step. The response object will contain this many file URLs. Specify 1 to upload all the user and groups data in one file.

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

Maximum value is: 100
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.
filters.activity_id
array

An array of string activity_id values. This will limit the returned data to the listed activity_id values.

Up to ten 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.
groups
array[object]

Define the group hierarchy that will format the presentation of report data.

You must build an array of objects. Each object contains a key and a label attribute and should be ordered from top to bottom by the defined key attributes. The label is the human readable label shown in the report. See example below for expected structure.
options
object

Configuration parameters for the report. 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]

List of fields to be calculated for all groups in the report.

See the list of available fields.
options.default_users_sort_field
string

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

Note: the named field must be present in user_fields.
options.default_users_sort_order
string

Choose ascending or descending order for sorting users.

Possible values:

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

Default: "desc"
options.user_fields
array[string]

List of data fields to show for each user in the report.

See the list of available user fields.

Example

{
    "dataset_type": "activity-summary-by-group",
    "file_count": 1,
    "filters": {
        "activity_id": [
            "20230106b_ELA_comprehension"
        ]
    },
    "options": {
        "default_sort_field": "mean_percent",
        "default_sort_order": "desc",
        "fields": [
            "group_count",
            "population",
            "lowest_score",
            "highest_score",
            "mean_seen_activities",
            "mean_attempted_percent",
            "mean_score",
            "median_score",
            "p25_score",
            "p75_score",
            "p90_score",
            "stddev_score",
            "lowest_percent",
            "highest_percent",
            "mean_percent",
            "median_percent",
            "p25_percent",
            "p75_percent",
            "p90_percent",
            "stddev_percent"
        ],
        "default_users_sort_field": "score",
        "default_users_sort_order": "desc",
        "user_fields": [
            "score",
            "attempted_max_score",
            "unscored_max_score",
            "max_score",
            "seen_activities"
        ]
    },
    "groups": [
        {
            "key": "district",
            "label": "District"
        },
        {
            "key": "school",
            "label": "School"
        },
        {
            "key": "class",
            "label": "Class"
        }
    ]
}

/* Example response:
{
  "meta": {
    "status": true,
    "timestamp": 1483585276
  },
  "data": {
    "dataset_id": "ce6c3842-5366-486d-a68f-ab9e6160e9de",
    "input_files": [
      "https://learnosity-reportdatasets-va.s3.amazonaws.com/reports/0034/activity-summary-by-group/ce6c3842-5366-486d-a68f-ab9e6160e9de/infiles/0.ndjson?AWSAccessKeyId=AKIAJB5XQL2VQTD4KG6Q&Expires=1483588877&Signature=QUXjR0beW83bB7l1OpiTMOKRsKc%3D"
    ]
  }
}
*/

For "activity-summary-by-group" datasets, upload one or more NDJSON input files containing user_id and group_path properties. The datasets implementation guide provides details on the upload process.

{"user_id":"ANONYMIZED_USER_001", "group_path":["Simpson","Hogwarts School","7_slytherin"]}
{"user_id":"ANONYMIZED_USER_002", "group_path":["Simpson","Hogwarts School","7_slytherin"]}
{"user_id":"ANONYMIZED_USER_003", "group_path":["Simpson","Hogwarts School","7_slytherin"]}
{"user_id":"ANONYMIZED_USER_004", "group_path":["Simpson","Hogwarts School","7_slytherin"]}
{"user_id":"ANONYMIZED_USER_005", "group_path":["Simpson","Hogwarts School","7_gryffindor"]}
{"user_id":"ANONYMIZED_USER_006", "group_path":["Simpson","Hogwarts School","7_gryffindor"]}
{"user_id":"ANONYMIZED_USER_007", "group_path":["Simpson","Hogwarts School","7_gryffindor"]}
{"user_id":"ANONYMIZED_USER_008", "group_path":["White","J. P. Wynne High School","7_broker"]}
{"user_id":"ANONYMIZED_USER_009", "group_path":["White","J. P. Wynne High School","7_broker"]}
{"user_id":"ANONYMIZED_USER_010", "group_path":["White","Shermer High School","7_vernon"]}
{"user_id":"ANONYMIZED_USER_011", "group_path":["White","Shermer High School","7_vernon"]}

Retrieve the dataset's raw files via the GET reports/datasets endpoint.

The endpoint returns pre-signed URLs for each group_path listed in the request. Send an HTTP GET request to the pre-signed URL to retrieve a JSON file of raw aggregation data corresponding to that group_path.

The ordering of the returned URLs corresponds to the ordering of the group_paths passed in the request.

Note: the endpoint will return URLs for each of the given group_paths even if the path does not exist within the dataset. However, accessing the URL for a non-existent path will return an HTTP status of 404.

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

The identifier of the dataset to retrieve.
dataset_type
string

The type of dataset identified by dataset_id.

Must be "activity-summary-by-group".
group_paths
array[array[string]]

You must create an array to specify the group paths. The group paths controls the presentation of data at each level of the report.

Each element of the array must be an array of strings containing group_path values. The group paths must represent a path through the dataset's group hierarchy.

See example structure below.

Example

{
    "dataset_type": "activity-summary-by-group",
    "dataset_id": "686b89d5-2911-4721-a6fc-7b43f57772aa",
    "group_paths": [
        [],
        ["Oregon"],
        ["Oregon", "Springfield Elementary"],
        ["Oregon", "Springfield Elementary", "Mrs Krabappel"],
        ["Oregon", "Springfield Elementary", "Ms Hoover"]
    ]
}

/* Example response:
{
  "meta": {
    "status": true,
    "timestamp": 1474431536,
    "records": 5
  },
  "data": [
    "https://learnosity-reportdatasets-va.s3.amazonaws.com/reports/0034/activity-summary-by-group/686b89d5-2911-4721-a6fc-7b43f57772aa/outfiles/d751713988987e9331980363e24189ce_1.json?AWSAccessKeyId=AKIAJUBLH5F2YDP6Z2QQ&Expires=1474435137&Signature=%2Bwgd77wOjBRFPQ41JohHb2hzLZU%3D",
    "https://learnosity-reportdatasets-va.s3.amazonaws.com/reports/0034/activity-summary-by-group/686b89d5-2911-4721-a6fc-7b43f57772aa/outfiles/8147ed71067cce9877dd043d5e98c1af_1.json?AWSAccessKeyId=AKIAJUBLH5F2YDP6Z2QQ&Expires=1474435137&Signature=l1GJ58bjT9yWWZIhFrKqRPYgoxI%3D",
    "https://learnosity-reportdatasets-va.s3.amazonaws.com/reports/0034/activity-summary-by-group/686b89d5-2911-4721-a6fc-7b43f57772aa/outfiles/8cea191c63343357ee28dcea89d80db2_1.json?AWSAccessKeyId=AKIAJUBLH5F2YDP6Z2QQ&Expires=1474435137&Signature=HeXt9M4ihps994zzc6L9C00Xg%2FI%3D",
    "https://learnosity-reportdatasets-va.s3.amazonaws.com/reports/0034/activity-summary-by-group/686b89d5-2911-4721-a6fc-7b43f57772aa/outfiles/25cebb8f9646cc5160decd7a04b57f68_1.json?AWSAccessKeyId=AKIAJUBLH5F2YDP6Z2QQ&Expires=1474435137&Signature=tTWr50j%2BlnDnNKrDFGkOZI3%2F7Ys%3D",
    "https://learnosity-reportdatasets-va.s3.amazonaws.com/reports/0034/activity-summary-by-group/686b89d5-2911-4721-a6fc-7b43f57772aa/outfiles/e065981af54ede481150c96e2ebfe79e_1.json?AWSAccessKeyId=AKIAJUBLH5F2YDP6Z2QQ&Expires=1474435137&Signature=q10lM9aSPYR%2B7q0GMz5q9f5MJFc%3D",
    ]
}
*/

Sending an HTTP GET request to a pre-signed URL from the response above will retrieve a JSON file with this structure:

{
    "group_id": "c82cd9e95eddcb4f050257791cd73d97",
    "group_name": "Springfield Elementary",
    "group_path": [
        "Oregon",
        "Springfield Elementary"
    ],
    "fields": [
        "group_id",
        "group_path",
        "group_name",
        "population",
        "lowest_score",
        "highest_score",
        "mean_score",
        "median_score",
        "mean_percent",
        "median_percent"
    ],
    "sort_field": "population",
    "sort_order": "desc",
    "rows_per_page": 1000,
    "rows_total": 2,
    "self": [
        "c82cd9e95eddcb4f050257791cd73d97",
        [
            "Oregon",
            "Springfield Elementary"
        ],
        "Springfield Elementary",
        16,
        2,
        20,
        11.37,
        11,
        56.875,
        55
    ],
    "rows": [
        [
            "d4130a365bfd812fcecdda69a1c81c2f",
            [
                "Oregon",
                "Springfield Elementary",
                "7_krabappel"
            ],
            "7_krabappel",
            9,
            9,
            20,
            14.88,
            14,
            74.44444444444,
            70
        ],
        [
            "84dea322f8946625a1b4e00fbfa10fb5",
            [
                "Oregon",
                "Springfield Elementary",
                "7_hoover"
            ],
            "7_hoover",
            7,
            2,
            17,
            6.85,
            6,
            34.28571428571,
            30
        ]
    ]
}

The contents of the JSON file are described below:

Attribute Description

group_id

string

Autogenerated unique identifier for this group.

group_name

string

User friendly name for the group.

group_path

array[string]

 An array of group names identifying the path of this group through the group hierarchy, starting with the top-level group name.

fields

array[string]

 Array of field names calculated for this group and for all groups in the dataset.

self

array

Summary row data for this group, containing an array of calculated aggregate values based on all users within this group. The values are ordered based on the fields array. 

rows

array[array]

 Array of arrays. Each sub-array contains the calculated aggregate values for each child group of this group. The values in each sub-array are ordered based on the fields array.

rows_total

int

Total number of rows calculated for this group.

Note: the actual size of rows may be less if rows_per_page is less than rows_total.

rows_per_page

int

The number of rows returned in this page of the request.

Note: the actual size of rows may be less depending on the dataset.

sort_field

string

The field used to sort the data.

The sort_field can be specified during dataset initialization with default_sort_field.

sort_order

string

The order of sorting that was applied to the data which can be either ascending ("asc") or descending ("desc").

The sort_order can be specified during dataset initialization with default_sort_order.

Initialize Reports API with an activity-summary-by-group report object to explore the dataset via our interactive GUI, including drill down functionality. See the API documentation for the activity-summary-by-group report type.

An example PHP implementation of Reports API using the Learnosity SDK:

<?php
include_once __DIR__ . "/vendor/autoload.php";
use LearnositySdk\Request\Init;

$domain = $_SERVER["SERVER_NAME"];
$security = [
    "consumer_key" => CONSUMER_KEY,
    "domain"       => $domain,
    "timestamp"    => gmdate("Ymd-Hi"),
];

// build request
$request = [
    "reports" => [
        [
            "id"          => "report-01",
            "type"        => "activity-summary-by-group",
            "dataset_id"  => "fb254347-23c3-40b4-b4e4-f79bda201109",
            "group_path"  => []
        ]
    ];
$Init = new Init("reports", $security, CONSUMER_SECRET, $request);
$signedRequest = $Init->generate();
?>

<html>
    <head>
        <title>Group Activity Reports</title>
    </head>
    <body>
        <div id="report-01"></div>
        <script src="//reports.learnosity.com/?[LTS_VERSION]"></script>

        <script>
            var initOptions = "<?php echo $signedRequest ?>";
            var eventOptions = {};
            var reportsApp = LearnosityReports.init(initOptions, eventOptions);
        </script>
    </body>
</html>
 
Was this article helpful?

Related articles


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