DOCSP-2681 - Heatmap reference

Author: jeff-allen-mongo

source/chart-type-reference/heatmap.txt

@@ -0,0 +1,107 @@
+.. _heatmap-chart-ref:
+
+=================
+Heatmap Reference
+=================
+
+.. default-domain:: mongodb
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
+A heatmap represents data in a tabular format as a range of color. A
+darker, or more intense, color represents a larger aggregated value
+for a particular data point.
+
+Heatmap Encoding Channels
+-------------------------
+
+Heatmaps provide the following :ref:`encoding channels
+<encoding-channels>`:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 20 80
+
+   * - Encoding Channel
+     - Description
+
+   * - X Axis
+     - A :guilabel:`category` encoding channel that creates a category
+       along the X axis for each unique value in this field.
+
+   * - Y Axis
+     - A :guilabel:`category` encoding channel that creates a category
+       along the Y axis for each unique value in this field.
+
+   * - Intensity
+     - An :guilabel:`aggregation` encoding channel that changes the
+       shading of the matrix elements to reflect the aggregated value
+       of this field. Darker colors in the visualization reflect
+       greater aggregated values.
+
+.. note::
+
+   Heatmaps support :ref:`sorting <charts-sort-data>` and
+   :ref:`limiting <charts-limit-data>` for the
+   :guilabel:`X Axis` encoding channel, but not the
+   :guilabel:`Y Axis` channel.
+
+Use Cases
+---------
+
+Heatmaps reveal patterns or trends within your data. Use heatmaps
+when the exact data values are not as important as depicting
+higher-level trends and relationships between your data points. They
+can also highlight any significant outliers, or points which strongly
+go against the general direction of your data. A heatmap is a good
+choice to display:
+
+- A comparison of average room rental prices based on location and
+  property type.
+
+- Geographic data, such as election results across different districts
+  or population density.
+
+- The number of customer orders across various store locations by month
+  of the year.
+
+.. tip::
+
+   Heatmaps work especially well with :ref:`binned <charts-bin-data>`
+   data. With naturally ordered datasets, heatmaps highlight areas of
+   concentration within the data.
+
+Example
+-------
+
+The following chart visualizes data pertaining to movies. Each
+document in the collection represents a movie and contains general
+information about the film as well as ratings from critics. This
+heatmap shows the mean (average) `Metacritic
+<http://www.metacritic.com/>`_ rating for different movie genres
+(Y Axis) over time (X Axis):
+
+.. figure:: /images/charts/heatmap-example.png
+   :figwidth: 720px
+   :alt: Heatmap example
+
+We :ref:`bin <charts-bin-data>` the years along the X Axis into
+decades and aggregate to find the :guilabel:`mean` ``metacritic`` score
+of films from each genre released in each decade.
+
+The :guilabel:`intensity` field of ``metacritic`` shades each grid
+element based on the mean ``metacritic`` field of all of the
+intersecting documents based on the :guilabel:`X` and
+:guilabel:`Y axes` fields. Based on the chart, we see that
+from ``1930-1940`` there are a few genres with very high
+average Metacritic scores, and over time a more even distribution of
+film ratings begins to occur.
+
+.. note::
+
+   If the space is white, there are no movies from that decade of that
+   particular genre in the dataset.

source/chart-types.txt

@@ -17,3 +17,4 @@ Chart Types
 
       /chart-type-reference/column-bar-chart
       /chart-type-reference/line-area-chart
+      /chart-type-reference/heatmap

source/images/charts/heatmap-example.png

@@ -4,3 +4,5 @@ for each chart type in MongoDB Charts:
 - :ref:`Column and Bar Chart Reference <column-bar-chart-ref>`
 
 - :ref:`Line and Area Chart Reference <line-area-chart-ref>`
+
+- :ref:`Heatmap Reference <heatmap-chart-ref>`

source/includes/chart-type-ref-list.rst

@@ -46,7 +46,7 @@ administrator:
        granted to that user may authorize them to view, modify, or
        delete the shared resources. For more information, see
        :ref:`Data Source Permissions <permission-model>` and
-       :ref:`Dashboard Permissions <>`.
+       :ref:`Dashboard Permissions <dashboard-permissions>`.
 
    * - ``UserAdmin``
      - Includes all privileges from the ``User`` role and is authorized