How to create statistics

How to create statistics

Introduction

Occasionally, it is helpful to extract statistical information from the submissions submitted by the students, in that way, either teachers could find tendencies on their courses or a student could know her/his grades in a certain task in the course.

INGInious original version does not offer a module for statistics, it just offers some tables to see the submissions. For this reason, in this version for the National University of Colombia, we built this module or plugin that extracts relevant information related to the submissions.

In this page you will find general information about how to add new statistics to the plugin.

Module's general information

The statistics module's code is located into the folder:

inginious/frontend/webapp/plugins/statistics

This module is implemented as an INGInious plugin, this in order to have the module decoupled from the base code (this make easier the maintenance as in the base code as in the module). 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 click on the pertinent tab.

Create statistics

This process involve two main steps:

1. Create an API that generates the information that will be showed to the user.
2. Consume the API from a web page and visualize the information.

• Create API:

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

  In general, the APIs have to make a query to the Data Base (MongoDB). To understand in overall the Data Base structure, the collections where are 'extracted' the statistics are user_tasks (which stores information summing up all the submissions from a student, including the final grade for that task) and submissions (all the submissions with the corresponding grade).

  If your class inherit from UserStatisticsAPI, you must to implement the statistics method (in some cases override validate_parameters), and for the case if you inherit from StatisticsAdminApi 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).er UserStatisticsApi or StatisticsAdminApi; depending on the type if the statistics are aimed towards users or only towards administrators.

  In general, the APIs have to make a query to the Data Base (MongoDB). To understand in overall the Data Base structure, the collections where are 'extracted' the statistics are user_tasks (which stores information summing up all the submissions from a student, including the final grade for that task) and submissions (all the submissions with the corresponding grade).

  If your class inherit from UserStatisticsAPI, you must to implement the statistics method (in some cases override validate_parameters), and for the case if you inherit from StatisticsAdminApi 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).

  ​

  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 method 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 you.

  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 be created an API that offers "view the details". 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 (they include the output from the grader for every submission). That is why, you have to use the functions mentioned before or similar functions. Also, the submissions must be returned in the order they were sent (descending order).

• 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.
  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.