Pivot Table
===========

A :doc:`Callable </Callables/Callable>` for returning a pivot table generated from input data.

Definition
----------

.. py:class:: controller.callable.transformer.PivotTable(self, indexes: list[ColumnReference], columns: list[ColumnReference], values: list[ColumnReference], aggregation_function: str)

    :callable name: ``pivot_table``
    :callable type: :doc:`Transformer </Callables/Types/Transformer>`

    :param indexes: A list of column references where values in the columns are treated as indexes in the pivot table (group values into **rows**).
    :type indexes: list[ColumnReference]
    :param columns: A list of column references where values in the columns are treated as columns in the pivot table (group values into **columns**).
    :type columns: list[ColumnReference]
    :param values: A list of column references where values in the columns are summarized using ``aggregation_function``.
    :type values: list[ColumnReference]
    :param aggregation_function: The function used to summarize the values in the pivot table.
    :type aggregation_function: AggregationFunction

Parameters
----------

.. py:attribute:: indexes

    A list of column references where values in the columns are treated as indexes in the pivot table (group values into **rows**).

    :type: list[ColumnReference]
    :required: True
    :choices: All columns in the target DataFrame, except those selected in ``columns`` and ``values``

.. py:attribute:: columns

    A list of column references where values in the columns are treated as columns in the pivot table (group values into **columns**).

    :type: list[ColumnReference]
    :required: True
    :choices: All columns in the target DataFrame, except those selected in ``indexes`` and ``values``

.. py:attribute:: values

    A list of column references where values in the columns are summarized using ``aggregation_function``.

    :type: list[ColumnReference]
    :required: True
    :choices: All columns in the target DataFrame, except those selected in ``indexes`` and ``columns``

.. note::

    The list of columns referenced in ``indexes``, ``columns``, and ``values`` must be mutually exclusive.

.. py:attribute:: aggregation_function

    The function used to summarize the values in the pivot table.

    :type: AggregationFunction
    :required: True
    :choices: All available names of aggregation functions

Output
------

A DataFrame is returned containing the resulting pivot table. 

- A pivot table may contain indexes or columns of multiple levels. The output of PivotTable flattens multi-level indexes and columns. As an example:

    // TODO

.. note::

    The original input data is **not** preserved.

Example configuration
---------------------

.. code-block:: javascript

    {
        "name": "foo",
        "callable": "pivot_table",
        "params": {
            "indexes": ["$final_exam_submissions.student.program", "$final_exam_submissions.student.student_number"],
            "columns": ["$final_exam_submissions.question_response.question_id"],
            "values": ["$final_exam_submissions.question_response.score"],
            "aggregation_function": "mean"
        }
    }