:py:mod:`oioioi.statistics.controllers`
=======================================

.. py:module:: oioioi.statistics.controllers


Module Contents
---------------

Classes
~~~~~~~

.. autoapisummary::

   oioioi.statistics.controllers.StatisticsMixinForContestController
   oioioi.statistics.controllers.StatisticsMixinForProgrammingContestController




Attributes
~~~~~~~~~~

.. autoapisummary::

   oioioi.statistics.controllers.statistics_categories
   oioioi.statistics.controllers.statistics_plot_kinds


.. py:data:: statistics_categories
   

   

.. py:data:: statistics_plot_kinds
   

   

.. py:class:: StatisticsMixinForContestController

   Bases: :py:obj:`object`

   The basic unit of statistics module is a plot group. It is a group of
   plots. A plot group is calculated for an object. The object can be a
   contest or a problem.

   Example plot groups are:

   1. Contest -- Data is calculated for a whole contest.
   1. Problem XYZ -- Data is calculated for a XYZ problem.

   A cluster of plot groups for a certain type of object is a category.

   A plot group is represented by a category identifier and an object
   name. The name is identifying an object for which statistics will be
   calculated. The type of the object depends on the category. It can be
   a contest or a problem. The meaning of the name also depends on
   category. For a problem it is a short name. In some cases the string
   is not necessary (for example for current contest), so an empty string
   is also possible.

   A plot is a graphical representation of some data. For example:
   a histogram of results for a contest, a pie chart of AC and WA for
   a problem, a table with lengths of the shortest solutions for problems
   or even some text with the total number of submissions.

   Plot kind tells what information we want to get. For example:
   a distribution of points for a problem, length of the shortest solution
   for a problem, numbers of solution for each problem in a contest. It
   also defines the type of object for which data will be calculated.

   Example plot kinds for a problem:

   1. Number of submissions.
   1. Histogram of points.
   1. Structure of results -- how many AC, WA or TLE were reported.

   Example plot kinds for a contest:

   1. Number of accepted solutions.
   1. Time of the first AC for every problem.
   1. Number of accepted solutions for each problem.
   1. Size of the shortest solution for each problem.
   1. Structure of the results -- how many AC, WA or TLE were reported.

   Plot data is a portion of information sufficient to render a plot.
   To get plot data we need two pieces of information. One is the desired
   kind of plot. The other is the name of the object. The meaning of the
   name depends on the object type. For problem, the name is short_name.

   .. _plot-data-representation:
   Plot data is represented as a dict containing several entries:

   1. ``plot_name`` -- Title of the plot.
   1. ``plot_type`` -- An object of
      :class:`~oioioi.statistics.plottypes.PlotType`. It determines a way
      to render data. For example a histogram, plain text or x-y plot.

   Additional dict entries depend on ``plot_type``. Look at
   :class:`~oioioi.statistics.plottypes.PlotType` implementations.

   Plot kind is represented as a pair of an enum entry and a string.

   .. py:method:: statistics_available_plot_groups(request)
      :abstractmethod:

      Returns a list of available plot groups.

      Each entry of output describes a plot group. It contains
      a category identifier, an object name and a description of plot
      group. The description should be translated.

      :rtype: List of tuples ``(key from statistics_categories,
         string, unicode)``


   .. py:method:: statistics_available_plots(request, plot_category, object_name)
      :abstractmethod:

      Returns a list of available plots for the plot group.
      Determines which plots the requesting user is allowed to see.

      Each entry of the output contains a plot kind identifier and an
      object name.

      :param plot_category: A key form ``statistics_categories``.
      :rtype: list of (enum entry from statistics_plot_kinds, string)


   .. py:method:: statistics_data(request, plot_kind, object_name)
      :abstractmethod:

      Returns data needed to render statistics for the ``plot_kind``.

      :return: A dict describing plot. See
         :ref:`plot-data-representation`.
      :rtype: Dict.


   .. py:method:: render_statistics(request, data, plot_id)
      :abstractmethod:

      Renders the given plots to HTML.

      :param data: A dict describing plots, as returned
         by :meth:`statistics_data`
      :type data: Dict.
      :param plot_id: Look at
          :class:`~oioioi.statistics.plottypes.PlotType`.
      :return: Unicode containing HTML.


   .. py:method:: can_see_stats(request)

      Determines if statistics should be shown



.. py:class:: StatisticsMixinForProgrammingContestController

   Bases: :py:obj:`object`

   .. py:method:: can_see_problem_statistics(request, pi)


   .. py:method:: statistics_available_plot_groups(request)


   .. py:method:: statistics_available_plots(request, category, object)

      Available plots for given object in given category.
      Does not check user's permission for viewing those statistics.


   .. py:method:: statistics_data(request, plot_kind, object)


   .. py:method:: render_statistics(request, data, plot_id)