Submit a request
Submit a request

 

 

Datasets: activity-summary-by-group Reference

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

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"]}

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

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.

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>
 

Related articles


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