Aggregate
=========

A :doc:`Callable </Callables/Callable>` for returning aggregated values of columns. This is similar to the Group By operation in SQL queries.

Definition
----------

.. py:class:: controller.callable.transformer.Aggregate(self, group_by: list[ColumnReference], values: list[ColumnReference], aggregation_function: AggregationFunction, output_names: list[str])

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

    :param group_by: A list of column references where values in the columns are used to group the rows.
    :type group_by: list[ColumnReference]
    :param values: A list of column references where values in the columns are grouped according to the ``group_by`` columns.
    :type values: list[ColumnReference]
    :param aggregation_function: The function used to summarize the values.
    :type aggregation_function: AggregationFunction
    :param output_names: A list of output names for the columns of aggregated values to return.
    :type output_list: list[str]

Parameters
----------

.. py:attribute:: group_by

    A list of column references where values in the columns are used to group the rows.

    :type: list[ColumnReference]
    :required: True
    :choices: All columns in the target DataFrame

.. py:attribute:: values

    A list of column references where values in the columns are grouped according to the ``group_by`` columns.

    :type: list[ColumnReference]
    :required: True
    :choices: All columns in the target DataFrame

.. py:attribute:: aggregation_function

    The function used to summarize the values.

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

.. py:attribute:: output_names

    A list of output names for the columns of aggregated values to return.

    :type: list[str]
    :required: True

Output
------

A DataFrame is returned containing columns of aggregated (grouped) values.

- The names of the resulting columns are assigned by zipping the ``output_names`` parameter with the ``values`` parameter. That is, the first item in the ``output_names`` list is assigned to the first item in the ``values`` list, and so on.

.. note::

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

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

.. code-block:: javascript

    {
        "name": "foo",
        "callable": "aggregate",
        "params": {
            "group_by": ["$assignment1_answers.question.title"],
            "values": ["assignment1_answers.question_response.score"],
            "aggregation_function": "mean",
            "output_names": ["assignment1_mean_score"]
        }
    }