Reports API has built-in functionality to display, browse, visualize and compare results from an aggregated dataset. This section describes how to create interactive statistical reports and configure insightful visualizations for aggregate reports using Reports API.

This page uses an activity-summary-by-group dataset for its examples, but all the same configuration options are available for the sessions-summary-by-group as well.

Basic data display

Reports API can render the raw data from a dataset using the activity-summary-by-group and sessions-summary-by-group report types (corresponding to the two types of dataset of the same names).

To view a basic report of the statistical data in a dataset, initialise Reports API with the dataset_id and type of a generated dataset.

By default, Reports API will display all fields from the dataset in a tabular drill-down report, like this:

{
    "reports": [
        {
            "id": "basic-table-example",
            "type": "activity-summary-by-group",
            "dataset_id": "33285a4b-0e6e-47e4-bade-78999ada14db",
            "group_path": []
        }
    ]
}

Configuring columns

Use the columns parameter to configure which fields should be displayed in the report, and how they should be displayed. The columns parameter is an ordered list of ColumnDefinition objects. The report will display one column per object, and the properties of each ColumnDefinition will determine what to show in the column.

This example uses the columns configuration to show a subset of numeric fields from the above report.

{
    "reports": [
        {
            "id": "columns-example",
            "type": "activity-summary-by-group",
            "dataset_id": "33285a4b-0e6e-47e4-bade-78999ada14db",
            "group_path": [],
            "columns": [
                {
                    "type": "group_name"
                },
                {
                    "type": "numeric",
                    "field": "population"
                },
                {
                    "type": "numeric",
                    "field": "lowest_percent"
                },
                {
                    "type": "numeric",
                    "field": "median_percent"
                },
                {
                    "type": "numeric",
                    "field": "highest_percent"
                }
            ]
        }
    ]
}

Each ColumnDefinition object should conform to one of the types defined in the columns reference.

Visualizations using 1DPlot

1DPlot is a specialized column type for creating visual comparisons based on a dataset. Each cell in a 1DPlot column is treated as a chart with a horizontal scale that runs from 0% to 100%. One or more elements can be plotted onto the chart, and combined together to create useful visualizations.

Here's an example that combines a scale element, a box plot and a whisker plot to chart the results for schools and classes.

{
    "reports": [
        {
            "id": "box-whisker-example",
            "type": "activity-summary-by-group",
            "dataset_id": "33285a4b-0e6e-47e4-bade-78999ada14db",
            "group_path": [],
            "columns": [
                {
                    "type": "group_name"
                },
                {
                    "type": "numeric",
                    "field": "population"
                },
                {
                    "type": "1d_plot",
                    "label": "Results",
                    "elements": [
                        {
                            "type": "scale_bracket"
                        },
                        {
                            "type": "whisker_plot",
                            "source": "row",
                            "min": "lowest_percent",
                            "max": "highest_percent",
                            "labels": false
                        },
                        {
                            "type": "box_plot",
                            "source": "row",
                            "min": "p25_percent",
                            "middle": "median_percent",
                            "max": "p75_percent",
                            "labels": true
                        }
                    ]
                }
            ]
        }
    ]
}

The box and whisker chart for each row is drawn using the data values for the group represented by that row. The whisker element spans the minimum and maximum scores in the group, the inner box shows the lower and upper quartile scores in the group, and the vertical stroke shows the group median.

To display this box and whisker plot, our initialization options defined a 1DPlot with an elements array, specifying the elements we want to draw and the fields in the dataset that should be used to plot them. Each element object is called an ElementDefinition.

• The whisker_plot element will take its minimum and maximum bounds from the lowest_percent and highest_percent fields for each row.
• The box_plot element will take its minimum and maximum bounds from the p25_percent and p75_percent fields for each row. The box plot takes an optional middle property, which will plot a vertical line using data from the named field in the dataset.

ElementDefinition properties used for positioning, like min, max and score, can be specified as string names of fields in the dataset, or as hard-coded numeric values. This can be used to plot elements in fixed positions on the chart to help with comparisons or contextual information. The example below indicates a score of 50% using a fixed vertical line.

{
    "reports": [
        {
            "id": "element-constants-example",
            "type": "activity-summary-by-group",
            "dataset_id": "33285a4b-0e6e-47e4-bade-78999ada14db",
            "group_path": [],
            "columns": [
                {
                    "type": "group_name"
                },
                {
                    "type": "numeric",
                    "field": "population"
                },
                {
                    "type": "1d_plot",
                    "label": "Results",
                    "elements": [
                        {
                            "type": "line_plot",
                            "source": "row",
                            "score": 50,
                            "label": false
                        },
                        {
                            "type": "scale_bracket"
                        },
                        {
                            "type": "whisker_plot",
                            "source": "row",
                            "min": "lowest_percent",
                            "max": "highest_percent",
                            "labels": false
                        },
                        {
                            "type": "box_plot",
                            "source": "row",
                            "min": "p25_percent",
                            "middle": "median_percent",
                            "max": "p75_percent",
                            "labels": true
                        }
                    ]
                }
            ]
        }
    ]
}

The full set of supported element types are defined in the columns reference documentation.

Combining and comparing aggregated data

Elements in a 1DPlot can reference data from other groups in the dataset's group hierarchy, in order to visualize comparisons between groups. The source property of an ElementDefinition can specify that the data values for drawing that element should be supplied by its parent group, or another ancestor group in the hierarchy. The example below introduces a shaded area indicating the 25th-75th percentile range for the "parent" group of each row.

{
    "reports": [
        {
            "id": "school-context-example",
            "type": "activity-summary-by-group",
            "dataset_id": "33285a4b-0e6e-47e4-bade-78999ada14db",
            "group_path": [],
            "columns": [
                {
                    "type": "group_name"
                },
                {
                    "type": "numeric",
                    "field": "population"
                },
                {
                    "type": "1d_plot",
                    "label": "Results",
                    "elements": [
                        {
                            "type": "shading_plot",
                            "source": "parent",
                            "min": "p25_percent",
                            "max": "p75_percent"
                        },
                        {
                            "type": "line_plot",
                            "source": "row",
                            "score": 50,
                            "label": false
                        },
                        {
                            "type": "scale_bracket"
                        },
                        {
                            "type": "whisker_plot",
                            "source": "row",
                            "min": "lowest_percent",
                            "max": "highest_percent",
                            "labels": false
                        },
                        {
                            "type": "box_plot",
                            "source": "row",
                            "min": "p25_percent",
                            "middle": "median_percent",
                            "max": "p75_percent",
                            "labels": true
                        }
                    ]
                }
            ]
        }
    ]
}

The columns reference documentation has full details on the source property.

Visualizing student scores

The same ColumnDefinition options can be applied to user level rows in the report. Provide the desired column configuration via the user_columns parameter to the report. The 1d_plot column type can be used in the same way as for group rows; specify one or more elements and reference the string names of data fields that should be used to draw the elements for each row.

{
    "reports": [
        {
            "id": "user-columns-example",
            "type": "activity-summary-by-group",
            "dataset_id": "33285a4b-0e6e-47e4-bade-78999ada14db",
            "group_path": [],
            "columns": [
                {
                    "type": "group_name"
                },
                {
                    "type": "numeric",
                    "field": "population"
                },
                {
                    "type": "1d_plot",
                    "label": "Results",
                    "elements": [
                        {
                            "type": "shading_plot",
                            "source": "parent",
                            "min": "p25_percent",
                            "max": "p75_percent"
                        },
                        {
                            "type": "line_plot",
                            "source": "row",
                            "score": 50,
                            "label": false
                        },
                        {
                            "type": "scale_bracket"
                        },
                        {
                            "type": "whisker_plot",
                            "source": "row",
                            "min": "lowest_percent",
                            "max": "highest_percent",
                            "labels": false
                        },
                        {
                            "type": "box_plot",
                            "source": "row",
                            "min": "p25_percent",
                            "middle": "median_percent",
                            "max": "p75_percent",
                            "labels": true
                        }
                    ]
                }
            ],
            "user_columns": [
                {
                    "type": "user_id"
                },
                {
                    "type": "numeric",
                    "field": "score"
                },
                {
                    "type": "1d_plot",
                    "label": "Results",
                    "elements": [
                        {
                            "type": "shading_plot",
                            "source": "parent",
                            "min": "p25_percent",
                            "max": "p75_percent"
                        },
                        {
                            "type": "line_plot",
                            "source": "row",
                            "score": 50,
                            "label": false
                        },
                        {
                            "type": "score_plot",
                            "shape": "circle",
                            "source": "row",
                            "percent": ["score", "max_score"]
                        }
                    ]
                }
            ]
        }
    ]
}