How to create statistics

Introduction

Occasionally, it is helpful to extract statistical information from the students' submissions, so either teachers could find tendencies on their courses or a student could know their grades in a certain task in the course.

In this guide we explain how to extend the plugin statistics, adding new plots or doing modifications to it.

Plugin's general information

The statistics plugin is located in inginious/frontend/plugins/statistics. The plugin adds a new option in the course's menu (for all user roles) and in the course administration menu (only administrators). The statistics for students and administrators are organized with tabs. Because of efficiency, the statistics only are generated when the user clicks on the pertinent tab.

Create statistics

This process involve two main steps:

1. Creating an API that generates the information that will be shown to the user

   The statistics APIs are implemented as pages in the pages.py file (inside the plugin folder) that usually inherit from either UserStatisticsApi or StatisticsAdminApi; depending on the type: whether the statistics are aimed towards users or only towards administrators.

   In general, when you inherit from either class, you must to override the API_GET method. In both cases, the method has to return a tuple with the HTTP code state (generally is 200, that denotes exit) and the response object (that is transformable to JSON). Additionally, the APIs have to make a query to the Data Base (see Data base structure). To understand in overall the Data Base structure, the collections used to extract the data are user_tasks and submissions.

   Note: in the class StatisticsAdminApi, you can validate the administrator permissions when you get a course with get_course_and_check_rights method. Therefore, it is mandatory to call this method inside API_GET or in other case users without administrator permissions could use the API. Is a good idea to observe the already created statistics classes in order to guide yourself.

   The administrator statistics are very interactive: when you click on a element in the graph, the page will show a list of submissions related with the selected part. For this reason and for efficiency reasons, must also be created an API that offers "view the details" information. View the details receives as parameters the data related to the selected segment on the graph and returns the submissions. File utils.py contains the functions project_detail_user_tasks and project_submission which return the data from the Data Base with a certain standard. The detail views have not to return the whole documents from MongoDB as they could have a big size. That is why, you have to use the functions mentioned before or similar functions to reduce the payload. Also, the submissions must be returned in the order they were sent (descending order).

2. Consume the API from a web page and visualize the information.

   This visualization is done with JavaScript, mainly using plotly library. Bellow are described the main files:

   • course_admin_statistics.html: template for administrators statistics page.
   • user_statistics.html: template for no administrators statistics page.
   • static/js/statistics.js: script with common code for all statistics pages.
   • static/js/user_statistics.js: script with common code for all statistics pages for general users.
   • static/js/course_admin_statistics.js: script with common code for all statistics pages for administrators.

   Adding a new statistic to visualize it can be done following next steps:

   1. Create a new tab into the template corresponding to the page that will be modified.
   2. Create a class and its prototype is Statistic (Defined in statistics.js file) into the script corresponding to the page that will be modified. In overall, have to be overrode _plotData method (in charge to "draw" the information) and _fetchData (which obtains data through the API exposed into the server).
   3. Ensure you are calling plotAsync() method in the new statistic when the new tab is opened to load data asynchronously.
   4. For administrator statistics, add a new button that will allow to download a CSV with the corresponding statistics. This button have to call downloadCsvAsync method from the statistic.