======
Sankey
======

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

.. contents::


A Sankey slice is used to present the user with a view of the data and how it
changes or flows over some dimensions or time periods. It does not have a
default render flavor.


Sankey config
================================

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

colorMap
--------------------------

Color map for each of the node names (eg. better|same|worse)

:Optional: Yes, will generate colors dynamically for each nodes defined in
    data (colors are coming from either ``config.colors`` or will be
    auto-generated
:Values: A map with node names as keys and colors as values
:Example:
    .. code-block:: python

        config:
            colorMap:
                "better": "#f00"
                "same": "#00f"
                "worse": "#fff"

colors (sankey)
---------------

Predefined array of colors to be assigned to the node

:Optional: Yes, will use ``d3.scale.category10().range()`` colors
:Values: Array of colors
:Example:
    .. code-block:: python

        config:
            colors: ["#f00", "#fff", "#CCC"]

linkHoverTextTemplateName
--------------------------

Template name whose content will be rendered when link is hovered

:Optional: Yes, see SankeySliceView for default
:Values: CSS selector
:Example:
    .. code-block:: python

        config:
            linkHoverTextTemplateName: #sankey-link-hover

nodeHoverTextTemplateName
--------------------------

Template name whose content will be rendered when node is hovered

:Optional: Yes, see SankeySliceView for default
:Values: CSS selector
:Example:
    .. code-block:: python

        config:
            nodeHoverTextTemplateName: #sankey-node-hover

nodeTitleTemplateName
--------------------------

Template name whose content is displayed right next to the node (node title)

:Optional: Yes, see SankeySliceView for default
:Values: CSS selector
:Example:
    .. code-block:: python

        config:
            nodeTitleTemplateName: #sankey-node-title

timePoints
--------------------------

The labels used as a title in the Start/End of the the Sankey flow

:Optional: Yes, default is ``["Start", "End"]``
:Values: An array of length two, containing strings
:Example:
    .. code-block:: python

        config:
            timePoints: ["Begin", "Finish"]


Flavors of Sankey
=================

bi-level
--------

The bi-level flavor requires two dimensions that the values will be mapped
between, and a single metric represents the value of the connection between the
dimensions.

.. image:: images/sankey-bilevel.png

The code for the Sankey bi-level flavor looks as follows (Note: Lists of keys
for the first and second dimensions must be supplied via the render
configuration. Also, you can include additional metadata as well.)

.. code-block:: python

    class SankeyService(NotredameQuarterlyService):

        def build_response(self):
            division_case_expression, singular='division')
            sponsors = ['National Institute...', 'Other']
            divisions = ['College of Science', 'Other']

            extra_metadata = {'sankey': {'format': '', 'label_plural': 'Colleges',
                                         'label_singular': 'College'}
                              }

            render_config = {'first_dimension_list': sponsors,
                             'second_dimension_list': divisions,
                             'metadata': extra_metadata}
            recipe = self.recipe()\
                .metrics(query_metric)\
                .dimensions(top3_sponsor_dim, top3_division_dim)\
                .filters(Filter(calendar_begindate >= self.start_date),
                         Filter(calendar_enddate <= self.end_date))

            self.response['responses'].append(
                recipe.render('Sankey', flavor='bi-level',
                              render_config=render_config))

The slice in stack.yaml:

.. code-block:: yaml

    - slice_type: "sankey"
      slug: "sankey"
      title: "What is the flow of <strong><%= optionChooser1.selectionDisplay() %></strong> between\
        \ Top Colleges and Top Sponsors?"
      config:
        "timePoints":
        - "Colleges"
        - "Sponsors"
      data_service: "dataservice.SankeyService"

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