Datasets: activity-summary-by-group Reference – Learnosity Product & Developer Help

Initialize dataset

Initialize an "activity-summary-by-group" dataset via the SET reports/datasets endpoint. The following parameters are supported:

Endpoint	v1/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 upload step. The response object will contain this many file URLs. Specify `1` to upload all the user and groups data in one file. If your report is based on a large number of users, you may 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.
filters.activity_id array	An array of string `activity_id` values. Up to 10 `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 group data in the dataset. The report's group 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 group rows. Valid values are: `desc`: descending order. `asc`: ascending order. Default: desc
options.fields array	Array of string, of aggregate fields to be calculated for all groups in the report. See the list of available fields.
options.user_fields array	Array of string, of user fields to be retrieved for each user in the report. See the list of available user fields.
options.default_users_sort_field string	String to determine the default sort field for user data in the dataset. The report's user rows will be ordered using this field. The named field must be specified in `user_fields`.
options.default_users_sort_order string	String to determine sort order for group rows. Valid values are: `desc`: descending order. `asc`: ascending order. Default: desc
groups array	Array of objects defining the group key and group label for each level of the group hierarchy. Each object contains a `key` and a `label` attribute. The objects should be ordered from the top level group key to the bottom level group key.

Example

{
    "dataset_type": "activity-summary-by-group",
    "file_count": 1,
    "filters": {
        "activity_id": [
            "20170106b_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"
    ]
  }
}
*/

Input file

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":"bart_simpson",           "group_path":["Simpson","Springfield High","7_krabappel"]}
{"user_id":"milhouse_vanhouten",     "group_path":["Simpson","Springfield High","7_krabappel"]}
{"user_id":"nelson_muntz",           "group_path":["Simpson","Springfield High","7_krabappel"]}
{"user_id":"martin_prince",          "group_path":["Simpson","Springfield High","7_krabappel"]}
{"user_id":"wendell_borton",         "group_path":["Simpson","Springfield High","7_krabappel"]}
{"user_id":"lewis_clark",            "group_path":["Simpson","Springfield High","7_krabappel"]}
{"user_id":"sherri_mackleberry",     "group_path":["Simpson","Springfield High","7_krabappel"]}
{"user_id":"terri_mackleberry",      "group_path":["Simpson","Springfield High","7_krabappel"]}
{"user_id":"adrian_belew",           "group_path":["Simpson","Springfield High","7_krabappel"]}
{"user_id":"lisa_simpson",           "group_path":["Simpson","Springfield High","7_hoover"]}
{"user_id":"ralph_wiggum",           "group_path":["Simpson","Springfield High","7_hoover"]}
{"user_id":"janey_powell",           "group_path":["Simpson","Springfield High","7_hoover"]}
{"user_id":"allison_taylor",         "group_path":["Simpson","Springfield High","7_hoover"]}
{"user_id":"alex_whitney",           "group_path":["Simpson","Springfield High","7_hoover"]}
{"user_id":"francine_rhenquist",     "group_path":["Simpson","Springfield High","7_hoover"]}
{"user_id":"hubert_wong",            "group_path":["Simpson","Springfield High","7_hoover"]}
{"user_id":"maggie_simpson",         "group_path":["Simpson","Cypress Creek College","7_doyle"]}
{"user_id":"dot_warner",             "group_path":["Simpson","Cypress Creek College","7_doyle"]}
{"user_id":"gordy_scribe",           "group_path":["Simpson","Cypress Creek College","7_doyle"]}
{"user_id":"warren_watson",          "group_path":["Simpson","Cypress Creek College","7_doyle"]}
{"user_id":"melvin_earnest",         "group_path":["Simpson","Cypress Creek College","7_doyle"]}
{"user_id":"gary_gray",              "group_path":["Simpson","Cypress Creek College","7_doyle"]}
{"user_id":"draco_malfoy",           "group_path":["Simpson","Hogwarts School","7_slytherin"]}
{"user_id":"vincent_crabbe",         "group_path":["Simpson","Hogwarts School","7_slytherin"]}
{"user_id":"gregory_goyle",          "group_path":["Simpson","Hogwarts School","7_slytherin"]}
{"user_id":"pansy_parkinson",        "group_path":["Simpson","Hogwarts School","7_slytherin"]}
{"user_id":"blaise_zabini",          "group_path":["Simpson","Hogwarts School","7_slytherin"]}
{"user_id":"marcus_flint",           "group_path":["Simpson","Hogwarts School","7_slytherin"]}
{"user_id":"terence_higgs",          "group_path":["Simpson","Hogwarts School","7_slytherin"]}
{"user_id":"adrian_pucey",           "group_path":["Simpson","Hogwarts School","7_slytherin"]}
{"user_id":"tracey_davis",           "group_path":["Simpson","Hogwarts School","7_slytherin"]}
{"user_id":"hestia_carrow",          "group_path":["Simpson","Hogwarts School","7_slytherin"]}
{"user_id":"flora_carrow",           "group_path":["Simpson","Hogwarts School","7_slytherin"]}
{"user_id":"zubeida_khan",           "group_path":["Simpson","Hogwarts School","7_slytherin"]}
{"user_id":"zoe_accrington",         "group_path":["Simpson","Hogwarts School","7_slytherin"]}
{"user_id":"yurika_haneda",          "group_path":["Simpson","Hogwarts School","7_slytherin"]}
{"user_id":"yatin_bhagat",           "group_path":["Simpson","Hogwarts School","7_slytherin"]}
{"user_id":"viola_richmond",         "group_path":["Simpson","Hogwarts School","7_slytherin"]}
{"user_id":"harry_potter",           "group_path":["Simpson","Hogwarts School","7_gryffindor"]}
{"user_id":"hermione_granger",       "group_path":["Simpson","Hogwarts School","7_gryffindor"]}
{"user_id":"ron_weasley",            "group_path":["Simpson","Hogwarts School","7_gryffindor"]}
{"user_id":"dean_thomas",            "group_path":["Simpson","Hogwarts School","7_gryffindor"]}
{"user_id":"seamus_finnagin",        "group_path":["Simpson","Hogwarts School","7_gryffindor"]}
{"user_id":"neville_longbottom",     "group_path":["Simpson","Hogwarts School","7_gryffindor"]}
{"user_id":"parvati_patil",          "group_path":["Simpson","Hogwarts School","7_gryffindor"]}
{"user_id":"fred_weasley",           "group_path":["Simpson","Hogwarts School","7_gryffindor"]}
{"user_id":"george_weasley",         "group_path":["Simpson","Hogwarts School","7_gryffindor"]}
{"user_id":"ginny_weasley",          "group_path":["Simpson","Hogwarts School","7_gryffindor"]}
{"user_id":"angelina_johnson",       "group_path":["Simpson","Hogwarts School","7_gryffindor"]}
{"user_id":"katie_bell",             "group_path":["Simpson","Hogwarts School","7_gryffindor"]}
{"user_id":"oliver_wood",            "group_path":["Simpson","Hogwarts School","7_gryffindor"]}
{"user_id":"collin_creevy",          "group_path":["Simpson","Hogwarts School","7_gryffindor"]}
{"user_id":"dennis_creevy",          "group_path":["Simpson","Hogwarts School","7_gryffindor"]}
{"user_id":"percey_weasley",         "group_path":["Simpson","Hogwarts School","7_gryffindor"]}
{"user_id":"pomona_sprout",          "group_path":["Simpson","Hogwarts School","7_hufflepuff"]}
{"user_id":"silvanus_kettleburn",    "group_path":["Simpson","Hogwarts School","7_hufflepuff"]}
{"user_id":"newton_scamander",       "group_path":["Simpson","Hogwarts School","7_hufflepuff"]}
{"user_id":"nymphadora_tonks",       "group_path":["Simpson","Hogwarts School","7_hufflepuff"]}
{"user_id":"cedric_diggory",         "group_path":["Simpson","Hogwarts School","7_hufflepuff"]}
{"user_id":"ernie_macmillan",        "group_path":["Simpson","Hogwarts School","7_hufflepuff"]}
{"user_id":"hannah_abbott",          "group_path":["Simpson","Hogwarts School","7_hufflepuff"]}
{"user_id":"justin_finchfletchley",  "group_path":["Simpson","Hogwarts School","7_hufflepuff"]}
{"user_id":"susan_bones",            "group_path":["Simpson","Hogwarts School","7_hufflepuff"]}
{"user_id":"zacharias_smith",        "group_path":["Simpson","Hogwarts School","7_hufflepuff"]}
{"user_id":"luna_lovegood",          "group_path":["Simpson","Hogwarts School","7_ravenclaw"]}
{"user_id":"marcus_belby",           "group_path":["Simpson","Hogwarts School","7_ravenclaw"]}
{"user_id":"cho_chang",              "group_path":["Simpson","Hogwarts School","7_ravenclaw"]}
{"user_id":"myrtle_warren",          "group_path":["Simpson","Hogwarts School","7_ravenclaw"]}
{"user_id":"padma_patil",            "group_path":["Simpson","Hogwarts School","7_ravenclaw"]}
{"user_id":"terry_boot",             "group_path":["Simpson","Hogwarts School","7_ravenclaw"]}
{"user_id":"michael_corner",         "group_path":["Simpson","Hogwarts School","7_ravenclaw"]}
{"user_id":"roger_davies",           "group_path":["Simpson","Hogwarts School","7_ravenclaw"]}
{"user_id":"anthony_goldstein",      "group_path":["Simpson","Hogwarts School","7_ravenclaw"]}
{"user_id":"marietta_edgecombe",     "group_path":["Simpson","Hogwarts School","7_ravenclaw"]}
{"user_id":"robert_hilliard",        "group_path":["Simpson","Hogwarts School","7_ravenclaw"]}
{"user_id":"penelope_clearwater",    "group_path":["Simpson","Hogwarts School","7_ravenclaw"]}
{"user_id":"lisa_turpin",            "group_path":["Simpson","Hogwarts School","7_ravenclaw"]}
{"user_id":"isobel_macdougal",       "group_path":["Simpson","Hogwarts School","7_ravenclaw"]}
{"user_id":"mandy_brocklehurst",     "group_path":["Simpson","Hogwarts School","7_ravenclaw"]}
{"user_id":"nanette_desford",        "group_path":["Simpson","Hogwarts School","7_ravenclaw"]}
{"user_id":"maria_glossop",          "group_path":["Simpson","Hogwarts School","7_ravenclaw"]}
{"user_id":"filius_flitwick",        "group_path":["Simpson","Hogwarts School","7_ravenclaw"]}
{"user_id":"millicent_bagnold",      "group_path":["Simpson","Hogwarts School","7_ravenclaw"]}
{"user_id":"walter_white",           "group_path":["Walter","J. P. Wynne High School","7_broker"]}
{"user_id":"skyler_white",           "group_path":["Walter","J. P. Wynne High School","7_broker"]}
{"user_id":"jesse_pinkman",          "group_path":["Walter","J. P. Wynne High School","7_broker"]}
{"user_id":"hank_schrader",          "group_path":["Walter","J. P. Wynne High School","7_broker"]}
{"user_id":"saul_goodman",           "group_path":["Walter","J. P. Wynne High School","7_broker"]}
{"user_id":"john_bender",            "group_path":["Walter","Shermer High School","7_vernon"]}
{"user_id":"claire_standish",        "group_path":["Walter","Shermer High School","7_vernon"]}
{"user_id":"andy_clark",             "group_path":["Walter","Shermer High School","7_vernon"]}
{"user_id":"brian_johnson",          "group_path":["Walter","Shermer High School","7_vernon"]}
{"user_id":"allison_reynolds",       "group_path":["Walter","Shermer High School","7_vernon"]}
{"user_id":"kat_stratford",          "group_path":["Walter","Padua High School","7_morgan"]}
{"user_id":"patrick_verona",         "group_path":["Walter","Padua High School","7_morgan"]}
{"user_id":"cameron_james",          "group_path":["Walter","Padua High School","7_morgan"]}
{"user_id":"bianca_stratford",       "group_path":["Walter","Padua High School","7_morgan"]}
{"user_id":"joey_donner",            "group_path":["Walter","Padua High School","7_morgan"]}
{"user_id":"katherina_minola",       "group_path":["Walter","Padua High School","7_morgan"]}
{"user_id":"bianca_minola",          "group_path":["Walter","Padua High School","7_morgan"]}
{"user_id":"baptista_minola",        "group_path":["Walter","Padua High School","7_morgan"]}
{"user_id":"petruchio_smith",        "group_path":["Walter","Padua High School","7_morgan"]}
{"user_id":"gremio_jones",           "group_path":["Walter","Padua High School","7_morgan"]}
{"user_id":"lucentio_williams",      "group_path":["Walter","Padua High School","7_morgan"]}
{"user_id":"hortensio_brown",        "group_path":["Walter","Padua High School","7_morgan"]}
{"user_id":"grumio_wilson",          "group_path":["Walter","Padua High School","7_morgan"]}
{"user_id":"tranio_taylor",          "group_path":["Walter","Padua High School","7_morgan"]}
{"user_id":"biondello_johnson",      "group_path":["Walter","Padua High School","7_morgan"]}
{"user_id":"vincentio_white",        "group_path":["Walter","Padua High School","7_morgan"]}

Get dataset

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.

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	v1/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 `activity-summary-by-group`.
group_paths array	Array of group path arrays. Each group path array contains the group_path strings identifying a valid path through the dataset's group hierarchy.

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",
    ]
}
*/

Sample data file

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	Machine-generated unique identifier for the group to which this JSON data corresponds.
group_name	The string group name to which this JSON data corresponds.
group_path	Array of string group names identifying the path of this group through the group hierarchy, starting with the top-level group name.
fields	Array of fields calculated for this group (and for all groups in the dataset).
self	Array of calculated aggregate values based on all users within this group. The values are ordered to correspond to the order of fields specified within the `fields` array. `self` constitutes the summary row for this group.
rows	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 to correspond to the order of fields specified within the `fields` array.
rows_total	Total number of rows calculated for this group. The actual size of `rows` may be less if `rows_per_page` < `rows_total`
rows_per_page	Maximum number of rows contained in this JSON file. The actual size of `rows` may be less.
sort_field	String denoting the field by which `rows` is sorted. Corresponds to one of the calculated `fields`. The `sort_field` can be specified during dataset initialisation.
sort_order	String denoting the order by which rows is sorted; either `desc` or `asc`. The `sort_order` can be specified during dataset initialisation.

Reports API

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.

Here's an example PHP implementation 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?[VERSION]"></script>

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

Initialize dataset

Input file

Get dataset

Example

Sample data file

Reports API

Related articles