Improve encoding section

doc/user_guide/encoding.rst

@@ -38,7 +38,7 @@ Encoding Channels
 ~~~~~~~~~~~~~~~~~
 
 Altair provides a number of encoding channels that can be useful in different
-circumstances; the following table summarizes them:
+circumstances. The following tables summarize them:
 
 Position Channels
 ^^^^^^^^^^^^^^^^^
@@ -91,7 +91,6 @@ Text and Tooltip Channels
 Channel  Altair Class      Description               Example
 =======  ================  ========================  =========================================
 text     :class:`Text`     Text to use for the mark  :ref:`gallery_scatter_with_labels`
-key      :class:`Key`      --                        N/A
 tooltip  :class:`Tooltip`  The tooltip value         :ref:`gallery_scatter_tooltips`
 =======  ================  ========================  =========================================
 
@@ -107,12 +106,37 @@ href     :class:`Href`     Hyperlink for  points     :ref:`gallery_scatter_href`
 Level of Detail Channel
 ^^^^^^^^^^^^^^^^^^^^^^^
 
+Grouping data is an important operation in data visualization. For line and area marks,
+mapping an unaggregated data field to any
+non-position channel will group the lines and stacked areas by that field.
+For aggregated plots, all unaggregated fields encoded are used as grouping fields
+in the aggregation (similar to fields in ``GROUP BY`` in SQL).
+
+The ``detail`` channel specifies an additional grouping field (or fields) for grouping
+data without mapping the field(s) to any visual properties.
+
 =======  ================  ===============================  =========================================
 Channel  Altair Class      Description                      Example
 =======  ================  ===============================  =========================================
 detail   :class:`Detail`   Additional property to group by  :ref:`gallery_ranged_dot_plot`
 =======  ================  ===============================  =========================================
 
+For example here is a line chart showing stock prices of 5 tech companies over time.
+We map the ``symbol`` variable to ``detail`` to use them to group lines.
+
+.. altair-plot::
+
+    import altair as alt
+    from vega_datasets import data
+
+    source = data.stocks()
+    alt.Chart(source).mark_line().encode(
+        x="date:T",
+        y="price:Q",
+        detail="symbol:N"
+    )
+
+
 Order Channel
 ^^^^^^^^^^^^^
 
@@ -325,17 +349,17 @@ The :class:`Text` encoding accepts the following options:
 
 .. altair-object-table:: altair.FieldOrDatumDefWithConditionStringFieldDefText
 
-Description, Href, Tooltip, Url
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Href, Tooltip, Url
+^^^^^^^^^^^^^^^^^^
 
-The :class:`Description`, :class:`Href`, :class:`Tooltip`, and :class:`Url` encodings accept the following options:
+The :class:`Href`, :class:`Tooltip`, and :class:`Url` encodings accept the following options:
 
 .. altair-object-table:: altair.StringFieldDefWithCondition
 
-Detail and Key
-^^^^^^^^^^^^^^
+Detail
+^^^^^^
 
-The :class:`Detail` and :class:`Key` encodings accept the following options:
+The :class:`Detail` encoding accepts the following options:
 
 .. altair-object-table:: altair.FieldDefWithoutScale
 
@@ -677,3 +701,84 @@ While the above examples show sorting of axes by specifying ``sort`` in the
 
 Here the y-axis is sorted reverse-alphabetically, while the color legend is
 sorted in the specified order, beginning with ``'Morris'``.
+
+Datum and Value
+~~~~~~~~~~~~~~~
+
+So far we always mapped an encoding channel to a column in our dataset. However, sometimes
+it is also useful to map to a single constant value. In Altair, you can do this with
+
+* ``datum``, which describes a constant data value encoded via a scale
+* ``value``, which describes an encoded constant visual value
+
+``datum`` is particularly useful for annotating a specific data value. 
+For example, you can use it with a rule mark to highlight a 
+threshold value (e.g., 200 dollars stock price).
+
+.. altair-plot::
+
+    import altair as alt
+    from vega_datasets import data
+
+    source = data.stocks()
+    base = alt.Chart(source)
+    lines = base.mark_line().encode(
+        x="date:T",
+        y="price:Q",
+        color="symbol:N"
+    )
+    rule = base.mark_rule(strokeDash=[2, 2]).encode(
+        y=alt.datum(300)
+    )
+
+    lines + rule
+
+You can also use ``datum`` with :class:`DateTime`, for example, to highlight a certain year.
+In addition, we will set the color for the rule to the same one as the line for the symbol ``MSFT``
+with ``alt.datum("MSFT")``.
+
+.. altair-plot::
+
+    import altair as alt
+    from vega_datasets import data
+
+    source = data.stocks()
+    base = alt.Chart(source)
+    lines = base.mark_line().encode(
+        x="date:T",
+        y="price:Q",
+        color="symbol:N"
+    )
+    rule = base.mark_rule(strokeDash=[2, 2]).encode(
+        x=alt.datum(alt.DateTime(year=2006)),
+        color=alt.datum("MSFT")
+    )
+
+    lines + rule
+
+
+Similar to when mapping to a data column, when using ``datum`` different encoding channels 
+may support ``band``, ``scale``, ``axis``, ``legend``, ``format``, or ``condition`` properties.
+However, data transforms (e.g. ``aggregate``, ``bin``, ``timeUnit``, ``sort``) cannot be applied.
+
+Expanding on the example above, if you would want to color the ``rule`` mark regardless of 
+the color scale used for the lines, you can use ``value``, e.g. ``alt.value("red")``:
+
+.. altair-plot::
+
+    import altair as alt
+    from vega_datasets import data
+
+    source = data.stocks()
+    base = alt.Chart(source)
+    lines = base.mark_line().encode(
+        x="date:T",
+        y="price:Q",
+        color="symbol:N"
+    )
+    rule = base.mark_rule(strokeDash=[2, 2]).encode(
+        x=alt.datum(alt.DateTime(year=2006)),
+        color=alt.value("red")
+    )
+
+    lines + rule