=======
Matchup
=======

.. include:: ../../incomplete.rst

.. contents::

A Matchup slice is used to present the user with a view of the data
separated compared against the average of those results with the highest
positive and separate differences displayed. It currently only has a default
flavor.

Matchup config
==============

Matchup slices support the :doc:`common_configuration`. Additional
options are:

scoreTitleTemplate
--------------------------

The template that will be evaluated to determine the score title

:Optional: Yes, default is "score"
:Values: Underscore.js template or plain text
:Example:
    .. code-block:: python

        config:
            scoreTitleTemplate: "<%= selection(\"lollipop\", {\"dimension\":
            \"metric\"}) %> score"

averageTitle
--------------------------

The text that indicates ``average``

:Optional: Yes, default is "industry average"
:Values: String
:Example:
    .. code-block:: python

        config:
            averageTitle: "Company average"

differenceThreshold
--------------------------

The statistical difference to group the values by. Values within this
threshold are considered to be "similar".

:Optional: Yes, default is 1
:Values: number
:Example:
    .. code-block:: python

        config:
            differenceThreshold: 2


displayModes
--------------------------

Togglable display modes (eg. show summary|all)

:Optional: Yes, default is ["summary", "all"]
:Values: Array of strings/mode names
:Example:
    .. code-block:: python

        config:
            displayModes: ["summary", "all"]

showCount (matchup)
--------------------------

Flag that indicates whether the count within the group should be shown

:Optional: Yes, default is ``true``
:Values: true|false
:Example:
    .. code-block:: python

        config:
            showCount: false

relatedItemsTitle
--------------------------

Each bar in matchup can have a list of related items. It is a list of strings
displayed when a bar is hovered/selected. The title name of this list is
defined here.

:Optional: Yes, default is empty string
:Values: String
:Example:
    .. code-block:: python

        config:
            relatedItemsTitle: "Related courses"

disableSort (matchup)
--------------------------

A boolean that controls if the data should be sorted. If set to ``true``,
sorting will be disabled and ``displayModes`` will be automatically set to
``["all"]``

:Optional: Yes, default is ``false``
:Values: true|false
:Example:
    .. code-block:: python

        config:
            disableSort: true

Flavors for Matchup
===================

Default (matchup)
-----------------

The first dimension in self.dimensions is the grouping dimension, and the
first metric is the value metric.

.. .. image:: images/matchup-default.png

The code for the default matchup flavor looks as follows:

.. code-block:: python

    class MatchupV3Service(CensusService):
        def build_response(self):
            self.metrics = ('popdiff', )
            self.dimensions = ('state',)

            recipe = self.recipe().metrics(*self.metrics).dimensions(
                *self.dimensions)

            self.response['responses'].append(recipe.render())

The slice in stack.yaml:

.. code-block:: yaml

    - slice_type: "matchup"
      slug: "matchup"
      title: "matchup"
      data_service: "censusv2service.MatchupV3Service"
      config:
        "differenceThreshold": 0.01
        "scoreTitleTemplate": "Population Change"
        "averageTitle": "Average Change"

Any additional dimensions and metrics are not included in the output in any
way.